Merge tag 'docs-5.9' of git://git.lwn.net/linux

+9

.mailmap

··· 18 18 Aleksandar Markovic <aleksandar.markovic@mips.com> <aleksandar.markovic@imgtec.com> 19 19 Alex Shi <alex.shi@linux.alibaba.com> <alex.shi@intel.com> 20 20 Alex Shi <alex.shi@linux.alibaba.com> <alex.shi@linaro.org> 21 + Alexander Lobakin <alobakin@pm.me> <alobakin@dlink.ru> 22 + Alexander Lobakin <alobakin@pm.me> <alobakin@marvell.com> 23 + Alexander Lobakin <alobakin@pm.me> <bloodyreaper@yandex.ru> 21 24 Alexandre Belloni <alexandre.belloni@bootlin.com> <alexandre.belloni@free-electrons.com> 22 25 Alexei Starovoitov <ast@kernel.org> <ast@plumgrid.com> 23 26 Alexei Starovoitov <ast@kernel.org> <alexei.starovoitov@gmail.com> ··· 137 134 Jeff Layton <jlayton@kernel.org> <jlayton@primarydata.com> 138 135 Jens Axboe <axboe@suse.de> 139 136 Jens Osterkamp <Jens.Osterkamp@de.ibm.com> 137 + Jiri Slaby <jirislaby@kernel.org> <jirislaby@gmail.com> 138 + Jiri Slaby <jirislaby@kernel.org> <jslaby@novell.com> 139 + Jiri Slaby <jirislaby@kernel.org> <jslaby@suse.com> 140 + Jiri Slaby <jirislaby@kernel.org> <jslaby@suse.cz> 141 + Jiri Slaby <jirislaby@kernel.org> <xslaby@fi.muni.cz> 140 142 Johan Hovold <johan@kernel.org> <jhovold@gmail.com> 141 143 Johan Hovold <johan@kernel.org> <johan@hovoldconsulting.com> 142 144 John Paul Adrian Glaubitz <glaubitz@physik.fu-berlin.de> ··· 159 151 Kay Sievers <kay.sievers@vrfy.org> 160 152 Kenneth W Chen <kenneth.w.chen@intel.com> 161 153 Konstantin Khlebnikov <koct9i@gmail.com> <k.khlebnikov@samsung.com> 154 + Konstantin Khlebnikov <koct9i@gmail.com> <khlebnikov@yandex-team.ru> 162 155 Koushik <raghavendra.koushik@neterion.com> 163 156 Krzysztof Kozlowski <krzk@kernel.org> <k.kozlowski@samsung.com> 164 157 Krzysztof Kozlowski <krzk@kernel.org> <k.kozlowski.k@gmail.com>

+36 -36

CREDITS

··· 34 34 35 35 N: Mark Adler 36 36 E: madler@alumni.caltech.edu 37 - W: http://alumnus.caltech.edu/~madler/ 37 + W: https://alumnus.caltech.edu/~madler/ 38 38 D: zlib decompression 39 39 40 40 N: Monalisa Agrawal ··· 62 62 63 63 N: Werner Almesberger 64 64 E: werner@almesberger.net 65 - W: http://www.almesberger.net/ 65 + W: https://www.almesberger.net/ 66 66 D: dosfs, LILO, some fd features, ATM, various other hacks here and there 67 67 S: Buenos Aires 68 68 S: Argentina ··· 96 96 97 97 N: Erik Andersen 98 98 E: andersen@codepoet.org 99 - W: http://www.codepoet.org/ 99 + W: https://www.codepoet.org/ 100 100 P: 1024D/30D39057 1BC4 2742 E885 E4DE 9301 0C82 5F9B 643E 30D3 9057 101 101 D: Maintainer of ide-cd and Uniform CD-ROM driver, 102 102 D: ATAPI CD-Changer support, Major 2.1.x CD-ROM update. ··· 114 114 115 115 N: H. Peter Anvin 116 116 E: hpa@zytor.com 117 - W: http://www.zytor.com/~hpa/ 117 + W: https://www.zytor.com/~hpa/ 118 118 P: 2047/2A960705 BA 03 D3 2C 14 A8 A8 BD 1E DF FE 69 EE 35 BD 74 119 119 D: Author of the SYSLINUX boot loader, maintainer of the linux.* news 120 120 D: hierarchy and the Linux Device List; various kernel hacks ··· 124 124 125 125 N: Andrea Arcangeli 126 126 E: andrea@suse.de 127 - W: http://www.kernel.org/pub/linux/kernel/people/andrea/ 127 + W: https://www.kernel.org/pub/linux/kernel/people/andrea/ 128 128 P: 1024D/68B9CB43 13D9 8355 295F 4823 7C49 C012 DFA1 686E 68B9 CB43 129 129 P: 1024R/CB4660B9 CC A0 71 81 F4 A0 63 AC C0 4B 81 1D 8C 15 C8 E5 130 130 D: Parport hacker ··· 339 339 340 340 N: Johannes Berg 341 341 E: johannes@sipsolutions.net 342 - W: http://johannes.sipsolutions.net/ 342 + W: https://johannes.sipsolutions.net/ 343 343 P: 4096R/7BF9099A C0EB C440 F6DA 091C 884D 8532 E0F3 73F3 7BF9 099A 344 344 D: powerpc & 802.11 hacker 345 345 ··· 376 376 377 377 N: Anton Blanchard 378 378 E: anton@samba.org 379 - W: http://samba.org/~anton/ 379 + W: https://samba.org/~anton/ 380 380 P: 1024/8462A731 4C 55 86 34 44 59 A7 99 2B 97 88 4A 88 9A 0D 97 381 381 D: sun4 port, Sparc hacker 382 382 ··· 509 509 510 510 N: Paul Bristow 511 511 E: paul@paulbristow.net 512 - W: http://paulbristow.net/linux/idefloppy.html 512 + W: https://paulbristow.net/linux/idefloppy.html 513 513 D: Maintainer of IDE/ATAPI floppy driver 514 514 515 515 N: Stefano Brivio ··· 518 518 519 519 N: Dominik Brodowski 520 520 E: linux@brodo.de 521 - W: http://www.brodo.de/ 521 + W: https://www.brodo.de/ 522 522 P: 1024D/725B37C6 190F 3E77 9C89 3B6D BECD 46EE 67C3 0308 725B 37C6 523 523 D: parts of CPUFreq code, ACPI bugfixes, PCMCIA rewrite, cpufrequtils 524 524 S: Tuebingen, Germany ··· 865 865 866 866 N: Todd J. Derr 867 867 E: tjd@fore.com 868 - W: http://www.wordsmith.org/~tjd 868 + W: https://www.wordsmith.org/~tjd 869 869 D: Random console hacks and other miscellaneous stuff 870 870 S: 3000 FORE Drive 871 871 S: Warrendale, Pennsylvania 15086 ··· 894 894 895 895 N: Matt Domsch 896 896 E: Matt_Domsch@dell.com 897 - W: http://www.dell.com/linux 898 - W: http://domsch.com/linux 897 + W: https://www.dell.com/linux 898 + W: https://domsch.com/linux 899 899 D: Linux/IA-64 900 900 D: Dell PowerEdge server, SCSI layer, misc drivers, and other patches 901 901 S: Dell Inc. ··· 992 992 993 993 N: Randy Dunlap 994 994 E: rdunlap@infradead.org 995 - W: http://www.infradead.org/~rdunlap/ 995 + W: https://www.infradead.org/~rdunlap/ 996 996 D: Linux-USB subsystem, USB core/UHCI/printer/storage drivers 997 997 D: x86 SMP, ACPI, bootflag hacking 998 998 D: documentation, builds ··· 1157 1157 1158 1158 N: Jeremy Fitzhardinge 1159 1159 E: jeremy@goop.org 1160 - W: http://www.goop.org/~jeremy 1160 + W: https://www.goop.org/~jeremy 1161 1161 D: author of userfs filesystem 1162 1162 D: Improved mmap and munmap handling 1163 1163 D: General mm minor tidyups ··· 1460 1460 1461 1461 N: Oliver Hartkopp 1462 1462 E: oliver.hartkopp@volkswagen.de 1463 - W: http://www.volkswagen.de 1463 + W: https://www.volkswagen.de 1464 1464 D: Controller Area Network (network layer core) 1465 1465 S: Brieffach 1776 1466 1466 S: 38436 Wolfsburg ··· 1599 1599 1600 1600 N: Kenji Hollis 1601 1601 E: kenji@bitgate.com 1602 - W: http://www.bitgate.com/ 1602 + W: https://www.bitgate.com/ 1603 1603 D: Berkshire PC Watchdog Driver 1604 1604 D: Small/Industrial Driver Project 1605 1605 1606 1606 N: Nick Holloway 1607 1607 E: Nick.Holloway@pyrites.org.uk 1608 - W: http://www.pyrites.org.uk/ 1608 + W: https://www.pyrites.org.uk/ 1609 1609 P: 1024/36115A04 F4E1 3384 FCFD C055 15D6 BA4C AB03 FBF8 3611 5A04 1610 1610 D: Occasional Linux hacker... 1611 1611 S: (ask for current address) ··· 1655 1655 1656 1656 N: Harald Hoyer 1657 1657 E: harald@redhat.com 1658 - W: http://www.harald-hoyer.de 1658 + W: https://www.harald-hoyer.de 1659 1659 D: ip_masq_quake 1660 1660 D: md boot support 1661 1661 S: Am Strand 5 ··· 1856 1856 D: Author of the COSA/SRP sync serial board driver. 1857 1857 D: Port of the syncppp.c from the 2.0 to the 2.1 kernel. 1858 1858 P: 1024/D3498839 0D 99 A7 FB 20 66 05 D7 8B 35 FC DE 05 B1 8A 5E 1859 - W: http://www.fi.muni.cz/~kas/ 1859 + W: https://www.fi.muni.cz/~kas/ 1860 1860 S: c/o Faculty of Informatics, Masaryk University 1861 1861 S: Botanicka' 68a 1862 1862 S: 602 00 Brno ··· 2017 2017 2018 2018 N: Gene Kozin 2019 2019 E: 74604.152@compuserve.com 2020 - W: http://www.sangoma.com 2020 + W: https://www.sangoma.com 2021 2021 D: WAN Router & Sangoma WAN drivers 2022 2022 S: Sangoma Technologies Inc. 2023 2023 S: 7170 Warden Avenue, Unit 2 ··· 2112 2112 2113 2113 N: Jaroslav Kysela 2114 2114 E: perex@perex.cz 2115 - W: http://www.perex.cz 2115 + W: https://www.perex.cz 2116 2116 D: Original Author and Maintainer for HP 10/100 Mbit Network Adapters 2117 2117 D: ISA PnP 2118 2118 S: Sindlovy Dvory 117 ··· 2316 2316 2317 2317 N: Daniel J. Maas 2318 2318 E: dmaas@dcine.com 2319 - W: http://www.maasdigital.com 2319 + W: https://www.maasdigital.com 2320 2320 D: dv1394 2321 2321 2322 2322 N: Hamish Macdonald ··· 2647 2647 2648 2648 N: Paul Moore 2649 2649 E: paul@paul-moore.com 2650 - W: http://www.paul-moore.com 2650 + W: https://www.paul-moore.com 2651 2651 D: NetLabel, SELinux, audit 2652 2652 2653 2653 N: James Morris ··· 2786 2786 E: niemi@tux.org 2787 2787 W: http://www.tux.org/~niemi/ 2788 2788 D: Assistant maintainer of Mtools, fdutils, and floppy driver 2789 - D: Administrator of Tux.Org Linux Server, http://www.tux.org 2789 + D: Administrator of Tux.Org Linux Server, https://www.tux.org 2790 2790 S: 2364 Old Trail Drive 2791 2791 S: Reston, Virginia 20191 2792 2792 S: USA ··· 2850 2850 2851 2851 N: Mikulas Patocka 2852 2852 E: mikulas@artax.karlin.mff.cuni.cz 2853 - W: http://artax.karlin.mff.cuni.cz/~mikulas/ 2853 + W: https://artax.karlin.mff.cuni.cz/~mikulas/ 2854 2854 P: 1024/BB11D2D5 A0 F1 28 4A C4 14 1E CF 92 58 7A 8F 69 BC A4 D3 2855 2855 D: Read/write HPFS filesystem 2856 2856 S: Weissova 8 ··· 2872 2872 2873 2873 N: Barak A. Pearlmutter 2874 2874 E: bap@cs.unm.edu 2875 - W: http://www.cs.unm.edu/~bap/ 2875 + W: https://www.cs.unm.edu/~bap/ 2876 2876 P: 512/602D785D 9B A1 83 CD EE CB AD 93 20 C6 4C B7 F5 E9 60 D4 2877 2877 D: Author of mark-and-sweep GC integrated by Alan Cox 2878 2878 S: Computer Science Department ··· 3035 3035 3036 3036 N: Daniel Quinlan 3037 3037 E: quinlan@pathname.com 3038 - W: http://www.pathname.com/~quinlan/ 3038 + W: https://www.pathname.com/~quinlan/ 3039 3039 D: FSSTND coordinator; FHS editor 3040 3040 D: random Linux documentation, patches, and hacks 3041 3041 S: 4390 Albany Drive #41A ··· 3130 3130 3131 3131 N: Rik van Riel 3132 3132 E: riel@redhat.com 3133 - W: http://www.surriel.com/ 3133 + W: https://www.surriel.com/ 3134 3134 D: Linux-MM site, Documentation/admin-guide/sysctl/*, swap/mm readaround 3135 3135 D: kswapd fixes, random kernel hacker, rmap VM, 3136 3136 D: nl.linux.org administrator, minor scheduler additions ··· 3246 3246 3247 3247 N: Paul `Rusty' Russell 3248 3248 E: rusty@rustcorp.com.au 3249 - W: http://ozlabs.org/~rusty 3249 + W: https://ozlabs.org/~rusty 3250 3250 D: Ruggedly handsome. 3251 3251 D: netfilter, ipchains with Michael Neuling. 3252 3252 S: 52 Moore St ··· 3369 3369 3370 3370 N: Robert Schwebel 3371 3371 E: robert@schwebel.de 3372 - W: http://www.schwebel.de 3372 + W: https://www.schwebel.de 3373 3373 D: Embedded hacker and book author, 3374 3374 D: AMD Elan support for Linux 3375 3375 S: Pengutronix ··· 3545 3545 N: Henrik Storner 3546 3546 E: storner@image.dk 3547 3547 W: http://www.image.dk/~storner/ 3548 - W: http://www.sslug.dk/ 3548 + W: https://www.sslug.dk/ 3549 3549 D: Configure script: Invented tristate for module-configuration 3550 3550 D: vfat/msdos integration, kerneld docs, Linux promotion 3551 3551 D: Miscellaneous bug-fixes ··· 3579 3579 3580 3580 N: Eugene Surovegin 3581 3581 E: ebs@ebshome.net 3582 - W: http://kernel.ebshome.net/ 3582 + W: https://kernel.ebshome.net/ 3583 3583 P: 1024D/AE5467F1 FF22 39F1 6728 89F6 6E6C 2365 7602 F33D AE54 67F1 3584 3584 D: Embedded PowerPC 4xx: EMAC, I2C, PIC and random hacks/fixes 3585 3585 S: Sunnyvale, California 94085 ··· 3609 3609 3610 3610 N: Urs Thuermann 3611 3611 E: urs.thuermann@volkswagen.de 3612 - W: http://www.volkswagen.de 3612 + W: https://www.volkswagen.de 3613 3613 D: Controller Area Network (network layer core) 3614 3614 S: Brieffach 1776 3615 3615 S: 38436 Wolfsburg ··· 3656 3656 3657 3657 N: Andrew Tridgell 3658 3658 E: tridge@samba.org 3659 - W: http://samba.org/tridge/ 3659 + W: https://samba.org/tridge/ 3660 3660 D: dosemu, networking, samba 3661 3661 S: 3 Ballow Crescent 3662 3662 S: MacGregor A.C.T 2615 ··· 3894 3894 N: David Weinehall 3895 3895 E: tao@acc.umu.se 3896 3896 P: 1024D/DC47CA16 7ACE 0FB0 7A74 F994 9B36 E1D1 D14E 8526 DC47 CA16 3897 - W: http://www.acc.umu.se/~tao/ 3897 + W: https://www.acc.umu.se/~tao/ 3898 3898 D: v2.0 kernel maintainer 3899 3899 D: Fixes for the NE/2-driver 3900 3900 D: Miscellaneous MCA-support ··· 3919 3919 N: Harald Welte 3920 3920 E: laforge@netfilter.org 3921 3921 P: 1024D/30F48BFF DBDE 6912 8831 9A53 879B 9190 5DA5 C655 30F4 8BFF 3922 - W: http://gnumonks.org/users/laforge 3922 + W: https://gnumonks.org/users/laforge 3923 3923 D: netfilter: new nat helper infrastructure 3924 3924 D: netfilter: ULOG, ECN, DSCP target 3925 3925 D: netfilter: TTL match

+1 -1

Documentation/ABI/testing/sysfs-driver-w1_therm

··· 8 8 to device min/max capabilities. Values are integer as they are 9 9 stored in a 8bit register in the device. Lowest value is 10 10 automatically put to TL. Once set, alarms could be search at 11 - master level, refer to Documentation/w1/w1_generic.rst for 11 + master level, refer to Documentation/w1/w1-generic.rst for 12 12 detailed information 13 13 Users: any user space application which wants to communicate with 14 14 w1_term device

+26

Documentation/PCI/endpoint/function/binding/pci-test.rst

··· 1 + .. SPDX-License-Identifier: GPL-2.0 2 + 3 + ========================== 4 + PCI Test Endpoint Function 5 + ========================== 6 + 7 + name: Should be "pci_epf_test" to bind to the pci_epf_test driver. 8 + 9 + Configurable Fields: 10 + 11 + ================ =========================================================== 12 + vendorid should be 0x104c 13 + deviceid should be 0xb500 for DRA74x and 0xb501 for DRA72x 14 + revid don't care 15 + progif_code don't care 16 + subclass_code don't care 17 + baseclass_code should be 0xff 18 + cache_line_size don't care 19 + subsys_vendor_id don't care 20 + subsys_id don't care 21 + interrupt_pin Should be 1 - INTA, 2 - INTB, 3 - INTC, 4 -INTD 22 + msi_interrupts Should be 1 to 32 depending on the number of MSI interrupts 23 + to test 24 + msix_interrupts Should be 1 to 2048 depending on the number of MSI-X 25 + interrupts to test 26 + ================ ===========================================================

-19

Documentation/PCI/endpoint/function/binding/pci-test.txt

··· 1 - PCI TEST ENDPOINT FUNCTION 2 - 3 - name: Should be "pci_epf_test" to bind to the pci_epf_test driver. 4 - 5 - Configurable Fields: 6 - vendorid : should be 0x104c 7 - deviceid : should be 0xb500 for DRA74x and 0xb501 for DRA72x 8 - revid : don't care 9 - progif_code : don't care 10 - subclass_code : don't care 11 - baseclass_code : should be 0xff 12 - cache_line_size : don't care 13 - subsys_vendor_id : don't care 14 - subsys_id : don't care 15 - interrupt_pin : Should be 1 - INTA, 2 - INTB, 3 - INTC, 4 -INTD 16 - msi_interrupts : Should be 1 to 32 depending on the number of MSI interrupts 17 - to test 18 - msix_interrupts : Should be 1 to 2048 depending on the number of MSI-X 19 - interrupts to test

+2

Documentation/PCI/endpoint/index.rst

··· 11 11 pci-endpoint-cfs 12 12 pci-test-function 13 13 pci-test-howto 14 + 15 + function/binding/pci-test

+1 -1

Documentation/PCI/endpoint/pci-endpoint-cfs.rst

··· 24 24 25 25 The pci_ep configfs has two directories at its root: controllers and 26 26 functions. Every EPC device present in the system will have an entry in 27 - the *controllers* directory and and every EPF driver present in the system 27 + the *controllers* directory and every EPF driver present in the system 28 28 will have an entry in the *functions* directory. 29 29 :: 30 30

+1 -1

Documentation/PCI/endpoint/pci-endpoint.rst

··· 214 214 * pci_epf_create() 215 215 216 216 Create a new PCI EPF device by passing the name of the PCI EPF device. 217 - This name will be used to bind the the EPF device to a EPF driver. 217 + This name will be used to bind the EPF device to a EPF driver. 218 218 219 219 * pci_epf_destroy() 220 220

+1 -1

Documentation/PCI/pci-error-recovery.rst

··· 248 248 ------------------ 249 249 250 250 In response to a return value of PCI_ERS_RESULT_NEED_RESET, the 251 - the platform will perform a slot reset on the requesting PCI device(s). 251 + platform will perform a slot reset on the requesting PCI device(s). 252 252 The actual steps taken by a platform to perform a slot reset 253 253 will be platform-dependent. Upon completion of slot reset, the 254 254 platform will call the device slot_reset() callback.

+4 -4

Documentation/PCI/pci.rst

··· 209 209 OS BUG: we don't check resource allocations before enabling those 210 210 resources. The sequence would make more sense if we called 211 211 pci_request_resources() before calling pci_enable_device(). 212 - Currently, the device drivers can't detect the bug when when two 212 + Currently, the device drivers can't detect the bug when two 213 213 devices have been allocated the same range. This is not a common 214 214 problem and unlikely to get fixed soon. 215 215 ··· 265 265 --------------------- 266 266 .. note:: 267 267 If anything below doesn't make sense, please refer to 268 - Documentation/DMA-API.txt. This section is just a reminder that 268 + :doc:`/core-api/dma-api`. This section is just a reminder that 269 269 drivers need to indicate DMA capabilities of the device and is not 270 270 an authoritative source for DMA interfaces. 271 271 ··· 291 291 Setup shared control data 292 292 ------------------------- 293 293 Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared) 294 - memory. See Documentation/DMA-API.txt for a full description of 294 + memory. See :doc:`/core-api/dma-api` for a full description of 295 295 the DMA APIs. This section is just a reminder that it needs to be done 296 296 before enabling DMA on the device. 297 297 ··· 421 421 422 422 Then clean up "consistent" buffers which contain the control data. 423 423 424 - See Documentation/DMA-API.txt for details on unmapping interfaces. 424 + See :doc:`/core-api/dma-api` for details on unmapping interfaces. 425 425 426 426 427 427 Unregister from other subsystems

+4 -3

Documentation/admin-guide/LSM/Yama.rst

··· 19 19 etc) to extract additional credentials and continue to expand the scope 20 20 of their attack without resorting to user-assisted phishing. 21 21 22 - This is not a theoretical problem. SSH session hijacking 23 - (http://www.storm.net.nz/projects/7) and arbitrary code injection 24 - (http://c-skills.blogspot.com/2007/05/injectso.html) attacks already 22 + This is not a theoretical problem. `SSH session hijacking 23 + <https://www.blackhat.com/presentations/bh-usa-05/bh-us-05-boileau.pdf>`_ 24 + and `arbitrary code injection 25 + <https://c-skills.blogspot.com/2007/05/injectso.html>`_ attacks already 25 26 exist and remain possible if ptrace is allowed to operate as before. 26 27 Since ptrace is not commonly used by non-developers and non-admins, system 27 28 builders should be allowed the option to disable this debugging system.

+1 -1

Documentation/admin-guide/blockdev/drbd/index.rst

··· 10 10 clusters and in this context, is a "drop-in" replacement for shared 11 11 storage. Simplistically, you could see it as a network RAID 1. 12 12 13 - Please visit http://www.drbd.org to find out more. 13 + Please visit https://www.drbd.org to find out more. 14 14 15 15 .. toctree:: 16 16 :maxdepth: 1

+3 -3

Documentation/admin-guide/blockdev/floppy.rst

··· 6 6 ========= 7 7 8 8 A FAQ list may be found in the fdutils package (see below), and also 9 - at <http://fdutils.linux.lu/faq.html>. 9 + at <https://fdutils.linux.lu/faq.html>. 10 10 11 11 12 12 LILO configuration options (Thinkpad users, read this) ··· 220 220 221 221 The latest version can be found at fdutils homepage: 222 222 223 - http://fdutils.linux.lu 223 + https://fdutils.linux.lu 224 224 225 225 The fdutils releases can be found at: 226 226 227 - http://fdutils.linux.lu/download.html 227 + https://fdutils.linux.lu/download.html 228 228 229 229 http://www.tux.org/pub/knaff/fdutils/ 230 230

+1 -1

Documentation/admin-guide/cgroup-v1/rdma.rst

··· 114 114 115 115 (d) Delete resource limit:: 116 116 117 - echo echo mlx4_0 hca_handle=max hca_object=max > /sys/fs/cgroup/rdma/1/rdma.max 117 + echo mlx4_0 hca_handle=max hca_object=max > /sys/fs/cgroup/rdma/1/rdma.max

+4 -4

Documentation/admin-guide/cgroup-v2.rst

··· 1683 1683 of the two is enforced. 1684 1684 1685 1685 cgroup writeback requires explicit support from the underlying 1686 - filesystem. Currently, cgroup writeback is implemented on ext2, ext4 1687 - and btrfs. On other filesystems, all writeback IOs are attributed to 1688 - the root cgroup. 1686 + filesystem. Currently, cgroup writeback is implemented on ext2, ext4, 1687 + btrfs, f2fs, and xfs. On other filesystems, all writeback IOs are 1688 + attributed to the root cgroup. 1689 1689 1690 1690 There are inherent differences in memory and writeback management 1691 1691 which affects how cgroup ownership is tracked. Memory is tracked per ··· 2042 2042 ---- 2043 2043 2044 2044 The "rdma" controller regulates the distribution and accounting of 2045 - of RDMA resources. 2045 + RDMA resources. 2046 2046 2047 2047 RDMA Interface Files 2048 2048 ~~~~~~~~~~~~~~~~~~~~

+1 -1

Documentation/admin-guide/cifs/todo.rst

··· 98 98 Known Bugs 99 99 ========== 100 100 101 - See http://bugzilla.samba.org - search on product "CifsVFS" for 101 + See https://bugzilla.samba.org - search on product "CifsVFS" for 102 102 current bug list. Also check http://bugzilla.kernel.org (Product = File System, Component = CIFS) 103 103 104 104 1) existing symbolic links (Windows reparse points) are recognized but

+3 -4

Documentation/admin-guide/cifs/usage.rst

··· 16 16 17 17 Please see 18 18 MS-SMB2 (for detailed SMB2/SMB3/SMB3.1.1 protocol specification) 19 - http://protocolfreedom.org/ and 20 - http://samba.org/samba/PFIF/ 19 + or https://samba.org/samba/PFIF/ 21 20 for more details. 22 21 23 22 ··· 31 32 32 33 For Linux: 33 34 34 - 1) Download the kernel (e.g. from http://www.kernel.org) 35 + 1) Download the kernel (e.g. from https://www.kernel.org) 35 36 and change directory into the top of the kernel directory tree 36 37 (e.g. /usr/src/linux-2.5.73) 37 38 2) make menuconfig (or make xconfig) ··· 830 831 Enabling Kerberos (extended security) works but requires version 1.2 or later 831 832 of the helper program cifs.upcall to be present and to be configured in the 832 833 /etc/request-key.conf file. The cifs.upcall helper program is from the Samba 833 - project(http://www.samba.org). NTLM and NTLMv2 and LANMAN support do not 834 + project(https://www.samba.org). NTLM and NTLMv2 and LANMAN support do not 834 835 require this helper. Note that NTLMv2 security (which does not require the 835 836 cifs.upcall helper program), instead of using Kerberos, is sufficient for 836 837 some use cases.

+1 -1

Documentation/admin-guide/cifs/winucase_convert.pl

··· 16 16 # GNU General Public License for more details. 17 17 # 18 18 # You should have received a copy of the GNU General Public License 19 - # along with this program. If not, see <http://www.gnu.org/licenses/>. 19 + # along with this program. If not, see <https://www.gnu.org/licenses/>. 20 20 # 21 21 22 22 while(<>) {

+1 -1

Documentation/admin-guide/dell_rbu.rst

··· 26 26 OpenManage and Dell Update packages (DUP). 27 27 28 28 Libsmbios can also be used to update BIOS on Dell systems go to 29 - http://linux.dell.com/libsmbios/ for details. 29 + https://linux.dell.com/libsmbios/ for details. 30 30 31 31 Dell_RBU driver supports BIOS update using the monolithic image and packetized 32 32 image methods. In case of monolithic the driver allocates a contiguous chunk

+2 -2

Documentation/admin-guide/device-mapper/dm-integrity.rst

··· 45 45 will format the device 46 46 3. unload the dm-integrity target 47 47 4. read the "provided_data_sectors" value from the superblock 48 - 5. load the dm-integrity target with the the target size 48 + 5. load the dm-integrity target with the target size 49 49 "provided_data_sectors" 50 50 6. if you want to use dm-integrity with dm-crypt, load the dm-crypt target 51 51 with the size "provided_data_sectors" ··· 99 99 the superblock is used. 100 100 101 101 meta_device:device 102 - Don't interleave the data and metadata on on device. Use a 102 + Don't interleave the data and metadata on the device. Use a 103 103 separate device for metadata. 104 104 105 105 buffer_sectors:number

+1 -1

Documentation/admin-guide/device-mapper/dm-raid.rst

··· 71 71 ============= =============================================================== 72 72 73 73 Reference: Chapter 4 of 74 - http://www.snia.org/sites/default/files/SNIA_DDF_Technical_Position_v2.0.pdf 74 + https://www.snia.org/sites/default/files/SNIA_DDF_Technical_Position_v2.0.pdf 75 75 76 76 <#raid_params>: The number of parameters that follow. 77 77

+1 -1

Documentation/admin-guide/device-mapper/dm-zoned.rst

··· 14 14 For a more detailed description of the zoned block device models and 15 15 their constraints see (for SCSI devices): 16 16 17 - http://www.t10.org/drafts.htm#ZBC_Family 17 + https://www.t10.org/drafts.htm#ZBC_Family 18 18 19 19 and (for ATA devices): 20 20

+5 -4

Documentation/admin-guide/devices.txt

··· 375 375 239 = /dev/uhid User-space I/O driver support for HID subsystem 376 376 240 = /dev/userio Serio driver testing device 377 377 241 = /dev/vhost-vsock Host kernel driver for virtio vsock 378 + 242 = /dev/rfkill Turning off radio transmissions (rfkill) 378 379 379 - 242-254 Reserved for local use 380 + 243-254 Reserved for local use 380 381 255 Reserved for MISC_DYNAMIC_MINOR 381 382 382 383 11 char Raw keyboard device (Linux/SPARC only) ··· 1443 1442 ... 1444 1443 1445 1444 The driver and documentation may be obtained from 1446 - http://www.winradio.com/ 1445 + https://www.winradio.com/ 1447 1446 1448 1447 82 block I2O hard disk 1449 1448 0 = /dev/i2o/hdag 33rd I2O hard disk, whole disk ··· 1657 1656 dynamically, so there is no fixed mapping from subdevice 1658 1657 pathnames to minor numbers. 1659 1658 1660 - See http://www.comedi.org/ for information about the Comedi 1659 + See https://www.comedi.org/ for information about the Comedi 1661 1660 project. 1662 1661 1663 1662 98 block User-mode virtual block device ··· 1724 1723 implementations a kernel presence for caching and easy 1725 1724 mounting. For more information about the project, 1726 1725 write to <arla-drinkers@stacken.kth.se> or see 1727 - http://www.stacken.kth.se/project/arla/ 1726 + https://www.stacken.kth.se/project/arla/ 1728 1727 1729 1728 103 block Audit device 1730 1729 0 = /dev/audit Audit device

+2 -2

Documentation/admin-guide/ext4.rst

··· 618 618 619 619 programs: http://e2fsprogs.sourceforge.net/ 620 620 621 - useful links: http://fedoraproject.org/wiki/ext3-devel 621 + useful links: https://fedoraproject.org/wiki/ext3-devel 622 622 http://www.bullopensource.org/ext4/ 623 623 http://ext4.wiki.kernel.org/index.php/Main_Page 624 - http://fedoraproject.org/wiki/Features/Ext4 624 + https://fedoraproject.org/wiki/Features/Ext4

+3 -3

Documentation/admin-guide/hw-vuln/special-register-buffer-data-sampling.rst

··· 14 14 to MDS attacks. 15 15 16 16 Affected processors 17 - -------------------- 17 + ------------------- 18 18 Core models (desktop, mobile, Xeon-E3) that implement RDRAND and/or RDSEED may 19 19 be affected. 20 20 ··· 59 59 60 60 61 61 Mitigation mechanism 62 - ------------------- 62 + -------------------- 63 63 Intel will release microcode updates that modify the RDRAND, RDSEED, and 64 64 EGETKEY instructions to overwrite secret special register data in the shared 65 65 staging buffer before the secret data can be accessed by another logical ··· 118 118 ============= ============================================================= 119 119 120 120 SRBDS System Information 121 - ----------------------- 121 + ------------------------ 122 122 The Linux kernel provides vulnerability status information through sysfs. For 123 123 SRBDS this can be accessed by the following sysfs file: 124 124 /sys/devices/system/cpu/vulnerabilities/srbds

+1

Documentation/admin-guide/index.rst

··· 41 41 init 42 42 kdump/index 43 43 perf/index 44 + pstore-blk 44 45 45 46 This is the beginning of a section with information of interest to 46 47 application developers. Documents covering various aspects of the kernel

+11 -9

Documentation/admin-guide/kernel-parameters.txt

··· 1212 1212 Format: {"off" | "on" | "skip[mbr]"} 1213 1213 1214 1214 efi= [EFI] 1215 - Format: { "old_map", "nochunk", "noruntime", "debug", 1216 - "nosoftreserve", "disable_early_pci_dma", 1217 - "no_disable_early_pci_dma" } 1218 - old_map [X86-64]: switch to the old ioremap-based EFI 1219 - runtime services mapping. [Needs CONFIG_X86_UV=y] 1215 + Format: { "debug", "disable_early_pci_dma", 1216 + "nochunk", "noruntime", "nosoftreserve", 1217 + "novamap", "no_disable_early_pci_dma", 1218 + "old_map" } 1219 + debug: enable misc debug output. 1220 + disable_early_pci_dma: disable the busmaster bit on all 1221 + PCI bridges while in the EFI boot stub. 1220 1222 nochunk: disable reading files in "chunks" in the EFI 1221 1223 boot stub, as chunking can cause problems with some 1222 1224 firmware implementations. 1223 1225 noruntime : disable EFI runtime services support 1224 - debug: enable misc debug output 1225 1226 nosoftreserve: The EFI_MEMORY_SP (Specific Purpose) 1226 1227 attribute may cause the kernel to reserve the 1227 1228 memory range for a memory mapping driver to 1228 1229 claim. Specify efi=nosoftreserve to disable this 1229 1230 reservation and treat the memory by its base type 1230 1231 (i.e. EFI_CONVENTIONAL_MEMORY / "System RAM"). 1231 - disable_early_pci_dma: Disable the busmaster bit on all 1232 - PCI bridges while in the EFI boot stub 1232 + novamap: do not call SetVirtualAddressMap(). 1233 1233 no_disable_early_pci_dma: Leave the busmaster bit set 1234 1234 on all PCI bridges while in the EFI boot stub 1235 + old_map [X86-64]: switch to the old ioremap-based EFI 1236 + runtime services mapping. [Needs CONFIG_X86_UV=y] 1235 1237 1236 1238 efi_no_storage_paranoia [EFI; X86] 1237 1239 Using this parameter you can use more than 50% of ··· 2793 2791 touchscreen support is not enabled in the mainstream 2794 2792 kernel as of 2.6.30, a preliminary port can be found 2795 2793 in the "bleeding edge" mini2440 support kernel at 2796 - http://repo.or.cz/w/linux-2.6/mini2440.git 2794 + https://repo.or.cz/w/linux-2.6/mini2440.git 2797 2795 2798 2796 mitigations= 2799 2797 [X86,PPC,S390,ARM64] Control optional mitigations for

+1 -1

Documentation/admin-guide/laptops/disk-shock-protection.rst

··· 135 135 for use. Please feel free to add projects that have been the victims 136 136 of my ignorance. 137 137 138 - - http://www.thinkwiki.org/wiki/HDAPS 138 + - https://www.thinkwiki.org/wiki/HDAPS 139 139 140 140 See this page for information about Linux support of the hard disk 141 141 active protection system as implemented in IBM/Lenovo Thinkpads.

+1 -1

Documentation/admin-guide/laptops/sonypi.rst

··· 151 151 different way to adjust the backlighting of the screen. There 152 152 is a userspace utility to adjust the brightness on those models, 153 153 which can be downloaded from 154 - http://www.acc.umu.se/~erikw/program/smartdimmer-0.1.tar.bz2 154 + https://www.acc.umu.se/~erikw/program/smartdimmer-0.1.tar.bz2 155 155 156 156 - since all development was done by reverse engineering, there is 157 157 *absolutely no guarantee* that this driver will not crash your

+3 -3

Documentation/admin-guide/laptops/thinkpad-acpi.rst

··· 905 905 The mapping of thermal sensors to physical locations varies depending on 906 906 system-board model (and thus, on ThinkPad model). 907 907 908 - http://thinkwiki.org/wiki/Thermal_Sensors is a public wiki page that 908 + https://thinkwiki.org/wiki/Thermal_Sensors is a public wiki page that 909 909 tries to track down these locations for various models. 910 910 911 911 Most (newer?) models seem to follow this pattern: ··· 926 926 - 3: Internal HDD 927 927 928 928 For the T43, T43/p (source: Shmidoax/Thinkwiki.org) 929 - http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_T43.2C_T43p 929 + https://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_T43.2C_T43p 930 930 931 931 - 2: System board, left side (near PCMCIA slot), reported as HDAPS temp 932 932 - 3: PCMCIA slot ··· 936 936 - 11: Power regulator, underside of system board, below F2 key 937 937 938 938 The A31 has a very atypical layout for the thermal sensors 939 - (source: Milos Popovic, http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_A31) 939 + (source: Milos Popovic, https://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_A31) 940 940 941 941 - 1: CPU 942 942 - 2: Main Battery: main sensor

+2 -2

Documentation/admin-guide/media/building.rst

··· 90 90 Those GPU-specific drivers are selected via the ``Graphics support`` 91 91 menu, under ``Device Drivers``. 92 92 93 - When a GPU driver supports supports HDMI CEC, it will automatically 93 + When a GPU driver supports HDMI CEC, it will automatically 94 94 enable the CEC core support at the media subsystem. 95 95 96 96 Media dependencies ··· 244 244 If you have an hybrid card, you may need to enable both ``Analog TV`` 245 245 and ``Digital TV`` at the menu. 246 246 247 - When using this option, the defaults for the the media support core 247 + When using this option, the defaults for the media support core 248 248 functionality are usually good enough to provide the basic functionality 249 249 for the driver. Yet, you could manually enable some desired extra (optional) 250 250 functionality using the settings under each of the following

+1 -1

Documentation/admin-guide/mm/concepts.rst

··· 35 35 protection and controlled sharing of data between processes. 36 36 37 37 With virtual memory, each and every memory access uses a virtual 38 - address. When the CPU decodes the an instruction that reads (or 38 + address. When the CPU decodes an instruction that reads (or 39 39 writes) from (or to) the system memory, it translates the `virtual` 40 40 address encoded in that instruction to a `physical` address that the 41 41 memory controller can understand.

+17 -6

Documentation/admin-guide/mm/hugetlbpage.rst

··· 101 101 page size may be selected with the "default_hugepagesz=<size>" boot parameter. 102 102 103 103 Hugetlb boot command line parameter semantics 104 - hugepagesz - Specify a huge page size. Used in conjunction with hugepages 104 + 105 + hugepagesz 106 + Specify a huge page size. Used in conjunction with hugepages 105 107 parameter to preallocate a number of huge pages of the specified 106 108 size. Hence, hugepagesz and hugepages are typically specified in 107 - pairs such as: 109 + pairs such as:: 110 + 108 111 hugepagesz=2M hugepages=512 112 + 109 113 hugepagesz can only be specified once on the command line for a 110 114 specific huge page size. Valid huge page sizes are architecture 111 115 dependent. 112 - hugepages - Specify the number of huge pages to preallocate. This typically 116 + hugepages 117 + Specify the number of huge pages to preallocate. This typically 113 118 follows a valid hugepagesz or default_hugepagesz parameter. However, 114 119 if hugepages is the first or only hugetlb command line parameter it 115 120 implicitly specifies the number of huge pages of default size to 116 121 allocate. If the number of huge pages of default size is implicitly 117 122 specified, it can not be overwritten by a hugepagesz,hugepages 118 123 parameter pair for the default size. 119 - For example, on an architecture with 2M default huge page size: 124 + 125 + For example, on an architecture with 2M default huge page size:: 126 + 120 127 hugepages=256 hugepagesz=2M hugepages=512 128 + 121 129 will result in 256 2M huge pages being allocated and a warning message 122 130 indicating that the hugepages=512 parameter is ignored. If a hugepages 123 131 parameter is preceded by an invalid hugepagesz parameter, it will 124 132 be ignored. 125 - default_hugepagesz - Specify the default huge page size. This parameter can 133 + default_hugepagesz 134 + pecify the default huge page size. This parameter can 126 135 only be specified once on the command line. default_hugepagesz can 127 136 optionally be followed by the hugepages parameter to preallocate a 128 137 specific number of huge pages of default size. The number of default 129 138 sized huge pages to preallocate can also be implicitly specified as 130 139 mentioned in the hugepages section above. Therefore, on an 131 - architecture with 2M default huge page size: 140 + architecture with 2M default huge page size:: 141 + 132 142 hugepages=256 133 143 default_hugepagesz=2M hugepages=256 134 144 hugepages=256 default_hugepagesz=2M 145 + 135 146 will all result in 256 2M huge pages being allocated. Valid default 136 147 huge page size is architecture dependent. 137 148

+1

Documentation/admin-guide/mm/index.rst

··· 31 31 idle_page_tracking 32 32 ksm 33 33 memory-hotplug 34 + nommu-mmap 34 35 numa_memory_policy 35 36 numaperf 36 37 pagemap

+2 -2

Documentation/admin-guide/mm/ksm.rst

··· 9 9 10 10 KSM is a memory-saving de-duplication feature, enabled by CONFIG_KSM=y, 11 11 added to the Linux kernel in 2.6.32. See ``mm/ksm.c`` for its implementation, 12 - and http://lwn.net/Articles/306704/ and http://lwn.net/Articles/330589/ 12 + and http://lwn.net/Articles/306704/ and https://lwn.net/Articles/330589/ 13 13 14 14 KSM was originally developed for use with KVM (where it was known as 15 15 Kernel Shared Memory), to fit more virtual machines into physical memory, ··· 52 52 If KSM is not configured into the running kernel, madvise MADV_MERGEABLE 53 53 and MADV_UNMERGEABLE simply fail with EINVAL. If the running kernel was 54 54 built with CONFIG_KSM=y, those calls will normally succeed: even if the 55 - the KSM daemon is not currently running, MADV_MERGEABLE still registers 55 + KSM daemon is not currently running, MADV_MERGEABLE still registers 56 56 the range for whenever the KSM daemon is started; even if the range 57 57 cannot contain any pages which KSM could actually merge; even if 58 58 MADV_UNMERGEABLE is applied to a range which was never MADV_MERGEABLE.

+1 -1

Documentation/admin-guide/mm/numaperf.rst

··· 129 129 130 130 /sys/devices/system/node/nodeX/memory_side_cache/ 131 131 132 - If that directory is not present, the system either does not not provide 132 + If that directory is not present, the system either does not provide 133 133 a memory-side cache, or that information is not accessible to the kernel. 134 134 135 135 The attributes for each level of cache is provided under its cache

+2 -2

Documentation/admin-guide/nfs/nfs-client.rst

··· 65 65 attribute. See `RFC3530 Section 6: Filesystem Migration and Replication`_ and 66 66 `Implementation Guide for Referrals in NFSv4`_. 67 67 68 - .. _RFC3530 Section 6\: Filesystem Migration and Replication: http://tools.ietf.org/html/rfc3530#section-6 69 - .. _Implementation Guide for Referrals in NFSv4: http://tools.ietf.org/html/draft-ietf-nfsv4-referrals-00 68 + .. _RFC3530 Section 6\: Filesystem Migration and Replication: https://tools.ietf.org/html/rfc3530#section-6 69 + .. _Implementation Guide for Referrals in NFSv4: https://tools.ietf.org/html/draft-ietf-nfsv4-referrals-00 70 70 71 71 The fs_locations information can take the form of either an ip address and 72 72 a path, or a DNS hostname and a path. The latter requires the NFS client to

+1 -1

Documentation/admin-guide/nfs/nfs-rdma.rst

··· 65 65 If the version is less than 1.1.2 or the command does not exist, 66 66 you should install the latest version of nfs-utils. 67 67 68 - Download the latest package from: http://www.kernel.org/pub/linux/utils/nfs 68 + Download the latest package from: https://www.kernel.org/pub/linux/utils/nfs 69 69 70 70 Uncompress the package and follow the installation instructions. 71 71

+3 -3

Documentation/admin-guide/nfs/nfsroot.rst

··· 264 264 access to the floppy drive device, /dev/fd0 265 265 266 266 For more information on syslinux, including how to create bootdisks 267 - for prebuilt kernels, see http://syslinux.zytor.com/ 267 + for prebuilt kernels, see https://syslinux.zytor.com/ 268 268 269 269 .. note:: 270 270 Previously it was possible to write a kernel directly to ··· 292 292 cdrecord dev=ATAPI:1,0,0 arch/x86/boot/image.iso 293 293 294 294 For more information on isolinux, including how to create bootdisks 295 - for prebuilt kernels, see http://syslinux.zytor.com/ 295 + for prebuilt kernels, see https://syslinux.zytor.com/ 296 296 297 297 - Using LILO 298 298 ··· 346 346 see Documentation/admin-guide/serial-console.rst for more information. 347 347 348 348 For more information on isolinux, including how to create bootdisks 349 - for prebuilt kernels, see http://syslinux.zytor.com/ 349 + for prebuilt kernels, see https://syslinux.zytor.com/ 350 350 351 351 352 352

+1 -1

Documentation/admin-guide/nfs/pnfs-block-server.rst

··· 8 8 to the clients to directly access the underlying block devices that are 9 9 shared with the client. 10 10 11 - To use pNFS block layouts with with the Linux NFS server the exported file 11 + To use pNFS block layouts with the Linux NFS server the exported file 12 12 system needs to support the pNFS block layouts (currently just XFS), and the 13 13 file system must sit on shared storage (typically iSCSI) that is accessible 14 14 to the clients in addition to the MDS. As of now the file system needs to

+1 -1

Documentation/admin-guide/nfs/pnfs-scsi-server.rst

··· 9 9 also hands out layouts to the clients so that they can directly access the 10 10 underlying SCSI LUNs that are shared with the client. 11 11 12 - To use pNFS SCSI layouts with with the Linux NFS server, the exported file 12 + To use pNFS SCSI layouts with the Linux NFS server, the exported file 13 13 system needs to support the pNFS SCSI layouts (currently just XFS), and the 14 14 file system must sit on a SCSI LUN that is accessible to the clients in 15 15 addition to the MDS. As of now the file system needs to sit directly on the

+1 -1

Documentation/admin-guide/perf/arm-ccn.rst

··· 27 27 and "vc" (virtual channel ID). 28 28 29 29 Crosspoint watchpoint-based events (special "event" value 0xfe) 30 - require "xp" and "vc" as as above plus "port" (device port index), 30 + require "xp" and "vc" as above plus "port" (device port index), 31 31 "dir" (transmit/receive direction), comparator values ("cmp_l" 32 32 and "cmp_h") and "mask", being index of the comparator mask. 33 33

+2 -2

Documentation/admin-guide/pm/intel-speed-select.rst

··· 114 114 Lock/Unlock status 115 115 ~~~~~~~~~~~~~~~~~~ 116 116 117 - Even if there are multiple performance profiles, it is possible that that they 117 + Even if there are multiple performance profiles, it is possible that they 118 118 are locked. If they are locked, users cannot issue a command to change the 119 119 performance state. It is possible that there is a BIOS setup to unlock or check 120 120 with your system vendor. ··· 883 883 enable:success 884 884 885 885 In this case, the option "-a" is optional. If set, it enables Intel(R) SST-TF 886 - feature and also sets the CPUs to high and and low priority using Intel Speed 886 + feature and also sets the CPUs to high and low priority using Intel Speed 887 887 Select Technology Core Power (Intel(R) SST-CP) features. The CPU numbers passed 888 888 with "-c" arguments are marked as high priority, including its siblings. 889 889

+1 -1

Documentation/admin-guide/pm/intel_pstate.rst

··· 723 723 724 724 The ``ftrace`` interface can be used for low-level diagnostics of 725 725 ``intel_pstate``. For example, to check how often the function to set a 726 - P-state is called, the ``ftrace`` filter can be set to to 726 + P-state is called, the ``ftrace`` filter can be set to 727 727 :c:func:`intel_pstate_set_pstate`:: 728 728 729 729 # cd /sys/kernel/debug/tracing/

+8 -1

Documentation/admin-guide/security-bugs.rst

··· 21 21 22 22 As it is with any bug, the more information provided the easier it 23 23 will be to diagnose and fix. Please review the procedure outlined in 24 - admin-guide/reporting-bugs.rst if you are unclear about what 24 + :doc:`reporting-bugs` if you are unclear about what 25 25 information is helpful. Any exploit code is very helpful and will not 26 26 be released without consent from the reporter unless it has already been 27 27 made public. 28 + 29 + Please send plain text emails without attachments where possible. 30 + It is much harder to have a context-quoted discussion about a complex 31 + issue if all the details are hidden away in attachments. Think of it like a 32 + :doc:`regular patch submission <../process/submitting-patches>` 33 + (even if you don't have a patch yet): describe the problem and impact, list 34 + reproduction steps, and follow it with a proposed fix, all in plain text. 28 35 29 36 Disclosure and embargoed information 30 37 ------------------------------------

+1 -1

Documentation/admin-guide/sysctl/fs.rst

··· 261 261 is to cross privilege boundaries when following a given symlink (i.e. a 262 262 root process follows a symlink belonging to another user). For a likely 263 263 incomplete list of hundreds of examples across the years, please see: 264 - http://cve.mitre.org/cgi-bin/cvekey.cgi?keyword=/tmp 264 + https://cve.mitre.org/cgi-bin/cvekey.cgi?keyword=/tmp 265 265 266 266 When set to "0", symlink following behavior is unrestricted. 267 267

+37 -5

Documentation/admin-guide/sysctl/kernel.rst

··· 235 235 from using ``dmesg(8)`` to view messages from the kernel's log 236 236 buffer. 237 237 When ``dmesg_restrict`` is set to 0 there are no restrictions. 238 - When ``dmesg_restrict`` is set set to 1, users must have 238 + When ``dmesg_restrict`` is set to 1, users must have 239 239 ``CAP_SYSLOG`` to use ``dmesg(8)``. 240 240 241 241 The kernel config option ``CONFIG_SECURITY_DMESG_RESTRICT`` sets the ··· 335 335 Default value is "``/sbin/hotplug``". 336 336 337 337 338 - hung_task_all_cpu_backtrace: 339 - ================ 338 + hung_task_all_cpu_backtrace 339 + =========================== 340 340 341 341 If this option is set, the kernel will send an NMI to all CPUs to dump 342 342 their backtraces when a hung task is detected. This file shows up if ··· 646 646 scanned for a given scan. 647 647 648 648 649 - oops_all_cpu_backtrace: 650 - ================ 649 + oops_all_cpu_backtrace 650 + ====================== 651 651 652 652 If this option is set, the kernel will send an NMI to all CPUs to dump 653 653 their backtraces when an oops event occurs. It should be used as a last ··· 994 994 === 995 995 996 996 See Documentation/filesystems/devpts.rst. 997 + 998 + 999 + random 1000 + ====== 1001 + 1002 + This is a directory, with the following entries: 1003 + 1004 + * ``boot_id``: a UUID generated the first time this is retrieved, and 1005 + unvarying after that; 1006 + 1007 + * ``entropy_avail``: the pool's entropy count, in bits; 1008 + 1009 + * ``poolsize``: the entropy pool size, in bits; 1010 + 1011 + * ``urandom_min_reseed_secs``: obsolete (used to determine the minimum 1012 + number of seconds between urandom pool reseeding). 1013 + 1014 + * ``uuid``: a UUID generated every time this is retrieved (this can 1015 + thus be used to generate UUIDs at will); 1016 + 1017 + * ``write_wakeup_threshold``: when the entropy count drops below this 1018 + (as a number of bits), processes waiting to write to ``/dev/random`` 1019 + are woken up. 1020 + 1021 + If ``drivers/char/random.c`` is built with ``ADD_INTERRUPT_BENCH`` 1022 + defined, these additional entries are present: 1023 + 1024 + * ``add_interrupt_avg_cycles``: the average number of cycles between 1025 + interrupts used to feed the pool; 1026 + 1027 + * ``add_interrupt_avg_deviation``: the standard deviation seen on the 1028 + number of cycles between interrupts used to feed the pool. 997 1029 998 1030 999 1031 randomize_va_space

+1 -1

Documentation/admin-guide/sysctl/vm.rst

··· 583 583 584 584 The default value is 1. 585 585 586 - See Documentation/nommu-mmap.txt for more information. 586 + See Documentation/admin-guide/mm/nommu-mmap.rst for more information. 587 587 588 588 589 589 numa_zonelist_order

+2 -2

Documentation/admin-guide/tainted-kernels.rst

··· 38 38 39 39 Tainted: P W O 40 40 41 - The meaning of those characters is explained in the table below. In tis case 41 + The meaning of those characters is explained in the table below. In this case 42 42 the kernel got tainted earlier because a proprietary Module (``P``) was loaded, 43 43 a warning occurred (``W``), and an externally-built module was loaded (``O``). 44 44 To decode other letters use the table below. ··· 61 61 * Proprietary module was loaded (#0) 62 62 * Kernel issued warning (#9) 63 63 * Externally-built ('out-of-tree') module was loaded (#12) 64 - See Documentation/admin-guide/tainted-kernels.rst in the the Linux kernel or 64 + See Documentation/admin-guide/tainted-kernels.rst in the Linux kernel or 65 65 https://www.kernel.org/doc/html/latest/admin-guide/tainted-kernels.html for 66 66 a more details explanation of the various taint flags. 67 67 Raw taint value as int/string: 4609/'P W O '

+1 -1

Documentation/admin-guide/xfs.rst

··· 133 133 logbsize must be an integer multiple of the log 134 134 stripe unit configured at **mkfs(8)** time. 135 135 136 - The default value for for version 1 logs is 32768, while the 136 + The default value for version 1 logs is 32768, while the 137 137 default value for version 2 logs is MAX(32768, log_sunit). 138 138 139 139 logdev=device and rtdev=device

+1 -1

Documentation/arm/booting.rst

··· 128 128 129 129 The boot loader must load a device tree image (dtb) into system ram 130 130 at a 64bit aligned address and initialize it with the boot data. The 131 - dtb format is documented in Documentation/devicetree/booting-without-of.txt. 131 + dtb format is documented in Documentation/devicetree/booting-without-of.rst. 132 132 The kernel will look for the dtb magic value of 0xd00dfeed at the dtb 133 133 physical address to determine if a dtb has been passed instead of a 134 134 tagged list.

+1 -1

Documentation/arm64/acpi_object_usage.rst

··· 220 220 x86 only table as of ACPI 5.1; starting with ACPI 6.0, processor 221 221 descriptions and power states on ARM platforms should use the DSDT 222 222 and define processor container devices (_HID ACPI0010, Section 8.4, 223 - and more specifically 8.4.3 and and 8.4.4). 223 + and more specifically 8.4.3 and 8.4.4). 224 224 225 225 MADT Section 5.2.12 (signature == "APIC") 226 226

+2 -2

Documentation/arm64/arm-acpi.rst

··· 273 273 274 274 - UUID: daffd814-6eba-4d8c-8a91-bc9bbf4aa301 275 275 276 - - http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf 276 + - https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf 277 277 278 278 The UEFI Forum provides a mechanism for registering device properties [4] 279 279 so that they may be used across all operating systems supporting ACPI. ··· 470 470 471 471 Linux Code 472 472 ---------- 473 - Individual items specific to Linux on ARM, contained in the the Linux 473 + Individual items specific to Linux on ARM, contained in the Linux 474 474 source code, are in the list that follows: 475 475 476 476 ACPI_OS_NAME

+1

Documentation/arm64/index.rst

··· 14 14 hugetlbpage 15 15 legacy_instructions 16 16 memory 17 + perf 17 18 pointer-authentication 18 19 silicon-errata 19 20 sve

+5 -2

Documentation/arm64/perf.txt Documentation/arm64/perf.rst

··· 1 + .. SPDX-License-Identifier: GPL-2.0 2 + 3 + ===================== 1 4 Perf Event Attributes 2 5 ===================== 3 6 4 - Author: Andrew Murray <andrew.murray@arm.com> 5 - Date: 2019-03-06 7 + :Author: Andrew Murray <andrew.murray@arm.com> 8 + :Date: 2019-03-06 6 9 7 10 exclude_user 8 11 ------------

+1 -1

Documentation/arm64/sve.rst

··· 494 494 Note: This section is for information only and not intended to be complete or 495 495 to replace any architectural specification. 496 496 497 - Refer to [4] for for more information. 497 + Refer to [4] for more information. 498 498 499 499 ARMv8-A defines the following floating-point / SIMD register state: 500 500

+1 -1

Documentation/block/biodoc.rst

··· 196 196 do not have a corresponding kernel virtual address space mapping) and 197 197 low-memory pages. 198 198 199 - Note: Please refer to Documentation/DMA-API-HOWTO.txt for a discussion 199 + Note: Please refer to :doc:`/core-api/dma-api-howto` for a discussion 200 200 on PCI high mem DMA aspects and mapping of scatter gather lists, and support 201 201 for 64 bit PCI. 202 202

+153

Documentation/block/blk-mq.rst

··· 1 + .. SPDX-License-Identifier: GPL-2.0 2 + 3 + ================================================ 4 + Multi-Queue Block IO Queueing Mechanism (blk-mq) 5 + ================================================ 6 + 7 + The Multi-Queue Block IO Queueing Mechanism is an API to enable fast storage 8 + devices to achieve a huge number of input/output operations per second (IOPS) 9 + through queueing and submitting IO requests to block devices simultaneously, 10 + benefiting from the parallelism offered by modern storage devices. 11 + 12 + Introduction 13 + ============ 14 + 15 + Background 16 + ---------- 17 + 18 + Magnetic hard disks have been the de facto standard from the beginning of the 19 + development of the kernel. The Block IO subsystem aimed to achieve the best 20 + performance possible for those devices with a high penalty when doing random 21 + access, and the bottleneck was the mechanical moving parts, a lot slower than 22 + any layer on the storage stack. One example of such optimization technique 23 + involves ordering read/write requests according to the current position of the 24 + hard disk head. 25 + 26 + However, with the development of Solid State Drives and Non-Volatile Memories 27 + without mechanical parts nor random access penalty and capable of performing 28 + high parallel access, the bottleneck of the stack had moved from the storage 29 + device to the operating system. In order to take advantage of the parallelism 30 + in those devices' design, the multi-queue mechanism was introduced. 31 + 32 + The former design had a single queue to store block IO requests with a single 33 + lock. That did not scale well in SMP systems due to dirty data in cache and the 34 + bottleneck of having a single lock for multiple processors. This setup also 35 + suffered with congestion when different processes (or the same process, moving 36 + to different CPUs) wanted to perform block IO. Instead of this, the blk-mq API 37 + spawns multiple queues with individual entry points local to the CPU, removing 38 + the need for a lock. A deeper explanation on how this works is covered in the 39 + following section (`Operation`_). 40 + 41 + Operation 42 + --------- 43 + 44 + When the userspace performs IO to a block device (reading or writing a file, 45 + for instance), blk-mq takes action: it will store and manage IO requests to 46 + the block device, acting as middleware between the userspace (and a file 47 + system, if present) and the block device driver. 48 + 49 + blk-mq has two group of queues: software staging queues and hardware dispatch 50 + queues. When the request arrives at the block layer, it will try the shortest 51 + path possible: send it directly to the hardware queue. However, there are two 52 + cases that it might not do that: if there's an IO scheduler attached at the 53 + layer or if we want to try to merge requests. In both cases, requests will be 54 + sent to the software queue. 55 + 56 + Then, after the requests are processed by software queues, they will be placed 57 + at the hardware queue, a second stage queue were the hardware has direct access 58 + to process those requests. However, if the hardware does not have enough 59 + resources to accept more requests, blk-mq will places requests on a temporary 60 + queue, to be sent in the future, when the hardware is able. 61 + 62 + Software staging queues 63 + ~~~~~~~~~~~~~~~~~~~~~~~ 64 + 65 + The block IO subsystem adds requests in the software staging queues 66 + (represented by struct :c:type:`blk_mq_ctx`) in case that they weren't sent 67 + directly to the driver. A request is one or more BIOs. They arrived at the 68 + block layer through the data structure struct :c:type:`bio`. The block layer 69 + will then build a new structure from it, the struct :c:type:`request` that will 70 + be used to communicate with the device driver. Each queue has its own lock and 71 + the number of queues is defined by a per-CPU or per-node basis. 72 + 73 + The staging queue can be used to merge requests for adjacent sectors. For 74 + instance, requests for sector 3-6, 6-7, 7-9 can become one request for 3-9. 75 + Even if random access to SSDs and NVMs have the same time of response compared 76 + to sequential access, grouped requests for sequential access decreases the 77 + number of individual requests. This technique of merging requests is called 78 + plugging. 79 + 80 + Along with that, the requests can be reordered to ensure fairness of system 81 + resources (e.g. to ensure that no application suffers from starvation) and/or to 82 + improve IO performance, by an IO scheduler. 83 + 84 + IO Schedulers 85 + ^^^^^^^^^^^^^ 86 + 87 + There are several schedulers implemented by the block layer, each one following 88 + a heuristic to improve the IO performance. They are "pluggable" (as in plug 89 + and play), in the sense of they can be selected at run time using sysfs. You 90 + can read more about Linux's IO schedulers `here 91 + <https://www.kernel.org/doc/html/latest/block/index.html>`_. The scheduling 92 + happens only between requests in the same queue, so it is not possible to merge 93 + requests from different queues, otherwise there would be cache trashing and a 94 + need to have a lock for each queue. After the scheduling, the requests are 95 + eligible to be sent to the hardware. One of the possible schedulers to be 96 + selected is the NONE scheduler, the most straightforward one. It will just 97 + place requests on whatever software queue the process is running on, without 98 + any reordering. When the device starts processing requests in the hardware 99 + queue (a.k.a. run the hardware queue), the software queues mapped to that 100 + hardware queue will be drained in sequence according to their mapping. 101 + 102 + Hardware dispatch queues 103 + ~~~~~~~~~~~~~~~~~~~~~~~~ 104 + 105 + The hardware queue (represented by struct :c:type:`blk_mq_hw_ctx`) is a struct 106 + used by device drivers to map the device submission queues (or device DMA ring 107 + buffer), and are the last step of the block layer submission code before the 108 + low level device driver taking ownership of the request. To run this queue, the 109 + block layer removes requests from the associated software queues and tries to 110 + dispatch to the hardware. 111 + 112 + If it's not possible to send the requests directly to hardware, they will be 113 + added to a linked list (:c:type:`hctx->dispatch`) of requests. Then, 114 + next time the block layer runs a queue, it will send the requests laying at the 115 + :c:type:`dispatch` list first, to ensure a fairness dispatch with those 116 + requests that were ready to be sent first. The number of hardware queues 117 + depends on the number of hardware contexts supported by the hardware and its 118 + device driver, but it will not be more than the number of cores of the system. 119 + There is no reordering at this stage, and each software queue has a set of 120 + hardware queues to send requests for. 121 + 122 + .. note:: 123 + 124 + Neither the block layer nor the device protocols guarantee 125 + the order of completion of requests. This must be handled by 126 + higher layers, like the filesystem. 127 + 128 + Tag-based completion 129 + ~~~~~~~~~~~~~~~~~~~~ 130 + 131 + In order to indicate which request has been completed, every request is 132 + identified by an integer, ranging from 0 to the dispatch queue size. This tag 133 + is generated by the block layer and later reused by the device driver, removing 134 + the need to create a redundant identifier. When a request is completed in the 135 + drive, the tag is sent back to the block layer to notify it of the finalization. 136 + This removes the need to do a linear search to find out which IO has been 137 + completed. 138 + 139 + Further reading 140 + --------------- 141 + 142 + - `Linux Block IO: Introducing Multi-queue SSD Access on Multi-core Systems <http://kernel.dk/blk-mq.pdf>`_ 143 + 144 + - `NOOP scheduler <https://en.wikipedia.org/wiki/Noop_scheduler>`_ 145 + 146 + - `Null block device driver <https://www.kernel.org/doc/html/latest/block/null_blk.html>`_ 147 + 148 + Source code documentation 149 + ========================= 150 + 151 + .. kernel-doc:: include/linux/blk-mq.h 152 + 153 + .. kernel-doc:: block/blk-mq.c

+1

Documentation/block/index.rst

··· 10 10 bfq-iosched 11 11 biodoc 12 12 biovecs 13 + blk-mq 13 14 capability 14 15 cmdline-partition 15 16 data-integrity

+1 -1

Documentation/block/pr.rst

··· 9 9 setup. 10 10 11 11 This document gives a general overview of the support ioctl commands. 12 - For a more detailed reference please refer the the SCSI Primary 12 + For a more detailed reference please refer to the SCSI Primary 13 13 Commands standard, specifically the section on Reservations and the 14 14 "PERSISTENT RESERVE IN" and "PERSISTENT RESERVE OUT" commands. 15 15

+1

Documentation/bpf/bpf_devel_QA.rst

··· 643 643 .. _selftests: ../../tools/testing/selftests/bpf/ 644 644 .. _Documentation/dev-tools/kselftest.rst: 645 645 https://www.kernel.org/doc/html/latest/dev-tools/kselftest.html 646 + .. _Documentation/bpf/btf.rst: btf.rst 646 647 647 648 Happy BPF hacking!

+8

Documentation/bpf/index.rst

··· 58 58 s390 59 59 60 60 61 + Other 62 + ===== 63 + 64 + .. toctree:: 65 + :maxdepth: 1 66 + 67 + ringbuf 68 + 61 69 .. Links: 62 70 .. _Documentation/networking/filter.rst: ../networking/filter.txt 63 71 .. _man-pages: https://www.kernel.org/doc/man-pages/

+1 -1

Documentation/bus-virt-phys-mapping.txt Documentation/core-api/bus-virt-phys-mapping.rst

··· 8 8 9 9 The virt_to_bus() and bus_to_virt() functions have been 10 10 superseded by the functionality provided by the PCI DMA interface 11 - (see Documentation/DMA-API-HOWTO.txt). They continue 11 + (see :doc:`/core-api/dma-api-howto`). They continue 12 12 to be documented below for historical purposes, but new code 13 13 must not use them. --davidm 00/12/12 14 14

+2 -2

Documentation/core-api/cpu_hotplug.rst

··· 35 35 other CPUs later online. 36 36 37 37 ``nr_cpus=n`` 38 - Restrict the total amount CPUs the kernel will support. If the number 39 - supplied here is lower than the number of physically available CPUs than 38 + Restrict the total amount of CPUs the kernel will support. If the number 39 + supplied here is lower than the number of physically available CPUs, then 40 40 those CPUs can not be brought online later. 41 41 42 42 ``additional_cpus=n``

+3 -3

Documentation/core-api/dma-api.rst

··· 5 5 :Author: James E.J. Bottomley <James.Bottomley@HansenPartnership.com> 6 6 7 7 This document describes the DMA API. For a more gentle introduction 8 - of the API (and actual examples), see Documentation/DMA-API-HOWTO.txt. 8 + of the API (and actual examples), see :doc:`/core-api/dma-api-howto`. 9 9 10 10 This API is split into two pieces. Part I describes the basic API. 11 11 Part II describes extensions for supporting non-consistent memory ··· 479 479 dma_attrs. 480 480 481 481 The interpretation of DMA attributes is architecture-specific, and 482 - each attribute should be documented in Documentation/DMA-attributes.txt. 482 + each attribute should be documented in :doc:`/core-api/dma-attributes`. 483 483 484 484 If dma_attrs are 0, the semantics of each of these functions 485 485 is identical to those of the corresponding function ··· 492 492 493 493 #include <linux/dma-mapping.h> 494 494 /* DMA_ATTR_FOO should be defined in linux/dma-mapping.h and 495 - * documented in Documentation/DMA-attributes.txt */ 495 + * documented in Documentation/core-api/dma-attributes.rst */ 496 496 ... 497 497 498 498 unsigned long attr;

+1 -1

Documentation/core-api/dma-isa-lpc.rst

··· 17 17 #include <asm/dma.h> 18 18 19 19 The first is the generic DMA API used to convert virtual addresses to 20 - bus addresses (see Documentation/DMA-API.txt for details). 20 + bus addresses (see :doc:`/core-api/dma-api` for details). 21 21 22 22 The second contains the routines specific to ISA DMA transfers. Since 23 23 this is not present on all platforms make sure you construct your

+3

Documentation/core-api/index.rst

··· 39 39 rbtree 40 40 generic-radix-tree 41 41 packing 42 + bus-virt-phys-mapping 43 + this_cpu_ops 42 44 timekeeping 43 45 errseq 44 46 ··· 84 82 :maxdepth: 1 85 83 86 84 memory-allocation 85 + unaligned-memory-access 87 86 dma-api 88 87 dma-api-howto 89 88 dma-attributes

+1 -1

Documentation/core-api/kobject.rst

··· 6 6 :Last updated: December 19, 2007 7 7 8 8 Based on an original article by Jon Corbet for lwn.net written October 1, 9 - 2003 and located at http://lwn.net/Articles/51437/ 9 + 2003 and located at https://lwn.net/Articles/51437/ 10 10 11 11 Part of the difficulty in understanding the driver model - and the kobject 12 12 abstraction upon which it is built - is that there is no obvious starting

+44

Documentation/core-api/memory-allocation.rst

··· 84 84 And even with hardware with restrictions it is preferable to use 85 85 `dma_alloc*` APIs. 86 86 87 + GFP flags and reclaim behavior 88 + ------------------------------ 89 + Memory allocations may trigger direct or background reclaim and it is 90 + useful to understand how hard the page allocator will try to satisfy that 91 + or another request. 92 + 93 + * ``GFP_KERNEL & ~__GFP_RECLAIM`` - optimistic allocation without _any_ 94 + attempt to free memory at all. The most light weight mode which even 95 + doesn't kick the background reclaim. Should be used carefully because it 96 + might deplete the memory and the next user might hit the more aggressive 97 + reclaim. 98 + 99 + * ``GFP_KERNEL & ~__GFP_DIRECT_RECLAIM`` (or ``GFP_NOWAIT``)- optimistic 100 + allocation without any attempt to free memory from the current 101 + context but can wake kswapd to reclaim memory if the zone is below 102 + the low watermark. Can be used from either atomic contexts or when 103 + the request is a performance optimization and there is another 104 + fallback for a slow path. 105 + 106 + * ``(GFP_KERNEL|__GFP_HIGH) & ~__GFP_DIRECT_RECLAIM`` (aka ``GFP_ATOMIC``) - 107 + non sleeping allocation with an expensive fallback so it can access 108 + some portion of memory reserves. Usually used from interrupt/bottom-half 109 + context with an expensive slow path fallback. 110 + 111 + * ``GFP_KERNEL`` - both background and direct reclaim are allowed and the 112 + **default** page allocator behavior is used. That means that not costly 113 + allocation requests are basically no-fail but there is no guarantee of 114 + that behavior so failures have to be checked properly by callers 115 + (e.g. OOM killer victim is allowed to fail currently). 116 + 117 + * ``GFP_KERNEL | __GFP_NORETRY`` - overrides the default allocator behavior 118 + and all allocation requests fail early rather than cause disruptive 119 + reclaim (one round of reclaim in this implementation). The OOM killer 120 + is not invoked. 121 + 122 + * ``GFP_KERNEL | __GFP_RETRY_MAYFAIL`` - overrides the default allocator 123 + behavior and all allocation requests try really hard. The request 124 + will fail if the reclaim cannot make any progress. The OOM killer 125 + won't be triggered. 126 + 127 + * ``GFP_KERNEL | __GFP_NOFAIL`` - overrides the default allocator behavior 128 + and all allocation requests will loop endlessly until they succeed. 129 + This might be really dangerous especially for larger orders. 130 + 87 131 Selecting memory allocator 88 132 ========================== 89 133

+1 -1

Documentation/core-api/printk-basics.rst

··· 69 69 The result shows the *current*, *default*, *minimum* and *boot-time-default* log 70 70 levels. 71 71 72 - To change the current console_loglevel simply write the the desired level to 72 + To change the current console_loglevel simply write the desired level to 73 73 ``/proc/sys/kernel/printk``. For example, to print all messages to the console:: 74 74 75 75 # echo 8 > /proc/sys/kernel/printk

+3 -1

Documentation/core-api/printk-formats.rst

··· 494 494 %pt[RT]t HH:MM:SS 495 495 %pt[RT][dt][r] 496 496 497 - For printing date and time as represented by 497 + For printing date and time as represented by:: 498 + 498 499 R struct rtc_time structure 499 500 T time64_t type 501 + 500 502 in human readable format. 501 503 502 504 By default year will be incremented by 1900 and month by 1.

Documentation/crc32.txt Documentation/staging/crc32.rst

+99 -87

Documentation/crypto/api-intro.txt Documentation/crypto/api-intro.rst

··· 1 + .. SPDX-License-Identifier: GPL-2.0 1 2 2 - Scatterlist Cryptographic API 3 - 4 - INTRODUCTION 3 + ============================= 4 + Scatterlist Cryptographic API 5 + ============================= 6 + 7 + Introduction 8 + ============ 5 9 6 10 The Scatterlist Crypto API takes page vectors (scatterlists) as 7 11 arguments, and works directly on pages. In some cases (e.g. ECB ··· 17 13 for linearization. 18 14 19 15 20 - DETAILS 16 + Details 17 + ======= 21 18 22 19 At the lowest level are algorithms, which register dynamically with the 23 20 API. 24 21 25 22 'Transforms' are user-instantiated objects, which maintain state, handle all 26 - of the implementation logic (e.g. manipulating page vectors) and provide an 27 - abstraction to the underlying algorithms. However, at the user 23 + of the implementation logic (e.g. manipulating page vectors) and provide an 24 + abstraction to the underlying algorithms. However, at the user 28 25 level they are very simple. 29 26 30 - Conceptually, the API layering looks like this: 27 + Conceptually, the API layering looks like this:: 31 28 32 29 [transform api] (user interface) 33 30 [transform ops] (per-type logic glue e.g. cipher.c, compress.c) 34 31 [algorithm api] (for registering algorithms) 35 - 32 + 36 33 The idea is to make the user interface and algorithm registration API 37 34 very simple, while hiding the core logic from both. Many good ideas 38 35 from existing APIs such as Cryptoapi and Nettle have been adapted for this. ··· 49 44 subject to block size requirements (i.e., non-stream ciphers can only 50 45 process multiples of blocks). 51 46 52 - Here's an example of how to use the API: 47 + Here's an example of how to use the API:: 53 48 54 49 #include <crypto/hash.h> 55 50 #include <linux/err.h> 56 51 #include <linux/scatterlist.h> 57 - 52 + 58 53 struct scatterlist sg[2]; 59 54 char result[128]; 60 55 struct crypto_ahash *tfm; 61 56 struct ahash_request *req; 62 - 57 + 63 58 tfm = crypto_alloc_ahash("md5", 0, CRYPTO_ALG_ASYNC); 64 59 if (IS_ERR(tfm)) 65 60 fail(); 66 - 61 + 67 62 /* ... set up the scatterlists ... */ 68 63 69 64 req = ahash_request_alloc(tfm, GFP_ATOMIC); ··· 72 67 73 68 ahash_request_set_callback(req, 0, NULL, NULL); 74 69 ahash_request_set_crypt(req, sg, result, 2); 75 - 70 + 76 71 if (crypto_ahash_digest(req)) 77 72 fail(); 78 73 79 74 ahash_request_free(req); 80 75 crypto_free_ahash(tfm); 81 76 82 - 77 + 83 78 Many real examples are available in the regression test module (tcrypt.c). 84 79 85 80 86 - DEVELOPER NOTES 81 + Developer Notes 82 + =============== 87 83 88 84 Transforms may only be allocated in user context, and cryptographic 89 85 methods may only be called from softirq and user contexts. For ··· 97 91 across non-aligned page fragment boundaries. 98 92 99 93 100 - ADDING NEW ALGORITHMS 94 + Adding New Algorithms 95 + ===================== 101 96 102 97 When submitting a new algorithm for inclusion, a mandatory requirement 103 98 is that at least a few test vectors from known sources (preferably ··· 126 119 might already be working on. 127 120 128 121 129 - BUGS 122 + Bugs 123 + ==== 130 124 131 125 Send bug reports to: 132 - linux-crypto@vger.kernel.org 133 - Cc: Herbert Xu <herbert@gondor.apana.org.au>, 126 + linux-crypto@vger.kernel.org 127 + 128 + Cc: 129 + Herbert Xu <herbert@gondor.apana.org.au>, 134 130 David S. Miller <davem@redhat.com> 135 131 136 132 137 - FURTHER INFORMATION 133 + Further Information 134 + =================== 138 135 139 136 For further patches and various updates, including the current TODO 140 137 list, see: 141 138 http://gondor.apana.org.au/~herbert/crypto/ 142 139 143 140 144 - AUTHORS 141 + Authors 142 + ======= 145 143 146 - James Morris 147 - David S. Miller 148 - Herbert Xu 144 + - James Morris 145 + - David S. Miller 146 + - Herbert Xu 149 147 150 148 151 - CREDITS 149 + Credits 150 + ======= 152 151 153 152 The following people provided invaluable feedback during the development 154 153 of the API: 155 154 156 - Alexey Kuznetzov 157 - Rusty Russell 158 - Herbert Valerio Riedel 159 - Jeff Garzik 160 - Michael Richardson 161 - Andrew Morton 162 - Ingo Oeser 163 - Christoph Hellwig 155 + - Alexey Kuznetzov 156 + - Rusty Russell 157 + - Herbert Valerio Riedel 158 + - Jeff Garzik 159 + - Michael Richardson 160 + - Andrew Morton 161 + - Ingo Oeser 162 + - Christoph Hellwig 164 163 165 164 Portions of this API were derived from the following projects: 166 - 165 + 167 166 Kerneli Cryptoapi (http://www.kerneli.org/) 168 - Alexander Kjeldaas 169 - Herbert Valerio Riedel 170 - Kyle McMartin 171 - Jean-Luc Cooke 172 - David Bryson 173 - Clemens Fruhwirth 174 - Tobias Ringstrom 175 - Harald Welte 167 + - Alexander Kjeldaas 168 + - Herbert Valerio Riedel 169 + - Kyle McMartin 170 + - Jean-Luc Cooke 171 + - David Bryson 172 + - Clemens Fruhwirth 173 + - Tobias Ringstrom 174 + - Harald Welte 176 175 177 176 and; 178 - 177 + 179 178 Nettle (https://www.lysator.liu.se/~nisse/nettle/) 180 - Niels Möller 179 + - Niels Möller 181 180 182 181 Original developers of the crypto algorithms: 183 182 184 - Dana L. How (DES) 185 - Andrew Tridgell and Steve French (MD4) 186 - Colin Plumb (MD5) 187 - Steve Reid (SHA1) 188 - Jean-Luc Cooke (SHA256, SHA384, SHA512) 189 - Kazunori Miyazawa / USAGI (HMAC) 190 - Matthew Skala (Twofish) 191 - Dag Arne Osvik (Serpent) 192 - Brian Gladman (AES) 193 - Kartikey Mahendra Bhatt (CAST6) 194 - Jon Oberheide (ARC4) 195 - Jouni Malinen (Michael MIC) 196 - NTT(Nippon Telegraph and Telephone Corporation) (Camellia) 183 + - Dana L. How (DES) 184 + - Andrew Tridgell and Steve French (MD4) 185 + - Colin Plumb (MD5) 186 + - Steve Reid (SHA1) 187 + - Jean-Luc Cooke (SHA256, SHA384, SHA512) 188 + - Kazunori Miyazawa / USAGI (HMAC) 189 + - Matthew Skala (Twofish) 190 + - Dag Arne Osvik (Serpent) 191 + - Brian Gladman (AES) 192 + - Kartikey Mahendra Bhatt (CAST6) 193 + - Jon Oberheide (ARC4) 194 + - Jouni Malinen (Michael MIC) 195 + - NTT(Nippon Telegraph and Telephone Corporation) (Camellia) 197 196 198 197 SHA1 algorithm contributors: 199 - Jean-Francois Dive 200 - 198 + - Jean-Francois Dive 199 + 201 200 DES algorithm contributors: 202 - Raimar Falke 203 - Gisle Sælensminde 204 - Niels Möller 201 + - Raimar Falke 202 + - Gisle Sælensminde 203 + - Niels Möller 205 204 206 205 Blowfish algorithm contributors: 207 - Herbert Valerio Riedel 208 - Kyle McMartin 206 + - Herbert Valerio Riedel 207 + - Kyle McMartin 209 208 210 209 Twofish algorithm contributors: 211 - Werner Koch 212 - Marc Mutz 210 + - Werner Koch 211 + - Marc Mutz 213 212 214 213 SHA256/384/512 algorithm contributors: 215 - Andrew McDonald 216 - Kyle McMartin 217 - Herbert Valerio Riedel 218 - 214 + - Andrew McDonald 215 + - Kyle McMartin 216 + - Herbert Valerio Riedel 217 + 219 218 AES algorithm contributors: 220 - Alexander Kjeldaas 221 - Herbert Valerio Riedel 222 - Kyle McMartin 223 - Adam J. Richter 224 - Fruhwirth Clemens (i586) 225 - Linus Torvalds (i586) 219 + - Alexander Kjeldaas 220 + - Herbert Valerio Riedel 221 + - Kyle McMartin 222 + - Adam J. Richter 223 + - Fruhwirth Clemens (i586) 224 + - Linus Torvalds (i586) 226 225 227 226 CAST5 algorithm contributors: 228 - Kartikey Mahendra Bhatt (original developers unknown, FSF copyright). 227 + - Kartikey Mahendra Bhatt (original developers unknown, FSF copyright). 229 228 230 229 TEA/XTEA algorithm contributors: 231 - Aaron Grothe 232 - Michael Ringe 230 + - Aaron Grothe 231 + - Michael Ringe 233 232 234 233 Khazad algorithm contributors: 235 - Aaron Grothe 234 + - Aaron Grothe 236 235 237 236 Whirlpool algorithm contributors: 238 - Aaron Grothe 239 - Jean-Luc Cooke 237 + - Aaron Grothe 238 + - Jean-Luc Cooke 240 239 241 240 Anubis algorithm contributors: 242 - Aaron Grothe 241 + - Aaron Grothe 243 242 244 243 Tiger algorithm contributors: 245 - Aaron Grothe 244 + - Aaron Grothe 246 245 247 246 VIA PadLock contributors: 248 - Michal Ludvig 247 + - Michal Ludvig 249 248 250 249 Camellia algorithm contributors: 251 - NTT(Nippon Telegraph and Telephone Corporation) (Camellia) 250 + - NTT(Nippon Telegraph and Telephone Corporation) (Camellia) 252 251 253 252 Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com> 254 253 255 254 Please send any credits updates or corrections to: 256 255 Herbert Xu <herbert@gondor.apana.org.au> 257 -

+43 -48

Documentation/crypto/asymmetric-keys.txt Documentation/crypto/asymmetric-keys.rst

··· 1 - ============================================= 2 - ASYMMETRIC / PUBLIC-KEY CRYPTOGRAPHY KEY TYPE 3 - ============================================= 1 + .. SPDX-License-Identifier: GPL-2.0 4 2 5 - Contents: 3 + ============================================= 4 + Asymmetric / Public-key Cryptography Key Type 5 + ============================================= 6 + 7 + .. Contents: 6 8 7 9 - Overview. 8 10 - Key identification. ··· 15 13 - Keyring link restrictions. 16 14 17 15 18 - ======== 19 - OVERVIEW 16 + Overview 20 17 ======== 21 18 22 19 The "asymmetric" key type is designed to be a container for the keys used in ··· 43 42 system (for example, a TPM). 44 43 45 44 46 - ================== 47 - KEY IDENTIFICATION 45 + Key Identification 48 46 ================== 49 47 50 48 If a key is added with an empty name, the instantiation data parsers are given ··· 57 57 comparisons than just the straightforward comparison of the description with 58 58 the criterion string: 59 59 60 - (1) If the criterion string is of the form "id:<hexdigits>" then the match 60 + 1) If the criterion string is of the form "id:<hexdigits>" then the match 61 61 function will examine a key's fingerprint to see if the hex digits given 62 - after the "id:" match the tail. For instance: 62 + after the "id:" match the tail. For instance:: 63 63 64 64 keyctl search @s asymmetric id:5acc2142 65 65 66 - will match a key with fingerprint: 66 + will match a key with fingerprint:: 67 67 68 68 1A00 2040 7601 7889 DE11 882C 3823 04AD 5ACC 2142 69 69 70 - (2) If the criterion string is of the form "<subtype>:<hexdigits>" then the 70 + 2) If the criterion string is of the form "<subtype>:<hexdigits>" then the 71 71 match will match the ID as in (1), but with the added restriction that 72 72 only keys of the specified subtype (e.g. tpm) will be matched. For 73 - instance: 73 + instance:: 74 74 75 75 keyctl search @s asymmetric tpm:5acc2142 76 76 77 77 Looking in /proc/keys, the last 8 hex digits of the key fingerprint are 78 - displayed, along with the subtype: 78 + displayed, along with the subtype:: 79 79 80 80 1a39e171 I----- 1 perm 3f010000 0 0 asymmetric modsign.0: DSA 5acc2142 [] 81 81 82 82 83 - ========================= 84 - ACCESSING ASYMMETRIC KEYS 83 + Accessing Asymmetric Keys 85 84 ========================= 86 85 87 86 For general access to asymmetric keys from within the kernel, the following 88 - inclusion is required: 87 + inclusion is required:: 89 88 90 89 #include <crypto/public_key.h> 91 90 92 91 This gives access to functions for dealing with asymmetric / public keys. 93 92 Three enums are defined there for representing public-key cryptography 94 - algorithms: 93 + algorithms:: 95 94 96 95 enum pkey_algo 97 96 98 - digest algorithms used by those: 97 + digest algorithms used by those:: 99 98 100 99 enum pkey_hash_algo 101 100 102 - and key identifier representations: 101 + and key identifier representations:: 103 102 104 103 enum pkey_id_type 105 104 ··· 109 110 110 111 The operations defined upon a key are: 111 112 112 - (1) Signature verification. 113 + 1) Signature verification. 113 114 114 115 Other operations are possible (such as encryption) with the same key data 115 116 required for verification, but not currently supported, and others 116 117 (eg. decryption and signature generation) require extra key data. 117 118 118 119 119 - SIGNATURE VERIFICATION 120 + Signature Verification 120 121 ---------------------- 121 122 122 123 An operation is provided to perform cryptographic signature verification, using 123 - an asymmetric key to provide or to provide access to the public key. 124 + an asymmetric key to provide or to provide access to the public key:: 124 125 125 126 int verify_signature(const struct key *key, 126 127 const struct public_key_signature *sig); 127 128 128 129 The caller must have already obtained the key from some source and can then use 129 130 it to check the signature. The caller must have parsed the signature and 130 - transferred the relevant bits to the structure pointed to by sig. 131 + transferred the relevant bits to the structure pointed to by sig:: 131 132 132 133 struct public_key_signature { 133 134 u8 *digest; ··· 158 159 if the key argument is the wrong type or is incompletely set up. 159 160 160 161 161 - ======================= 162 - ASYMMETRIC KEY SUBTYPES 162 + Asymmetric Key Subtypes 163 163 ======================= 164 164 165 165 Asymmetric keys have a subtype that defines the set of operations that can be ··· 169 171 the data required for it. The asymmetric key retains a reference on the 170 172 subtype module. 171 173 172 - The subtype definition structure can be found in: 174 + The subtype definition structure can be found in:: 173 175 174 176 #include <keys/asymmetric-subtype.h> 175 177 176 - and looks like the following: 178 + and looks like the following:: 177 179 178 180 struct asymmetric_key_subtype { 179 181 struct module *owner; ··· 196 198 197 199 There are a number of operations defined by the subtype: 198 200 199 - (1) describe(). 201 + 1) describe(). 200 202 201 203 Mandatory. This allows the subtype to display something in /proc/keys 202 204 against the key. For instance the name of the public key algorithm type 203 205 could be displayed. The key type will display the tail of the key 204 206 identity string after this. 205 207 206 - (2) destroy(). 208 + 2) destroy(). 207 209 208 210 Mandatory. This should free the memory associated with the key. The 209 211 asymmetric key will look after freeing the fingerprint and releasing the 210 212 reference on the subtype module. 211 213 212 - (3) query(). 214 + 3) query(). 213 215 214 216 Mandatory. This is a function for querying the capabilities of a key. 215 217 216 - (4) eds_op(). 218 + 4) eds_op(). 217 219 218 220 Optional. This is the entry point for the encryption, decryption and 219 221 signature creation operations (which are distinguished by the operation ID 220 222 in the parameter struct). The subtype may do anything it likes to 221 223 implement an operation, including offloading to hardware. 222 224 223 - (5) verify_signature(). 225 + 5) verify_signature(). 224 226 225 227 Optional. This is the entry point for signature verification. The 226 228 subtype may do anything it likes to implement an operation, including 227 229 offloading to hardware. 228 230 229 - 230 - ========================== 231 - INSTANTIATION DATA PARSERS 231 + Instantiation Data Parsers 232 232 ========================== 233 233 234 234 The asymmetric key type doesn't generally want to store or to deal with a raw ··· 250 254 During key instantiation each parser in the list is tried until one doesn't 251 255 return -EBADMSG. 252 256 253 - The parser definition structure can be found in: 257 + The parser definition structure can be found in:: 254 258 255 259 #include <keys/asymmetric-parser.h> 256 260 257 - and looks like the following: 261 + and looks like the following:: 258 262 259 263 struct asymmetric_key_parser { 260 264 struct module *owner; ··· 269 273 There is currently only a single operation defined by the parser, and it is 270 274 mandatory: 271 275 272 - (1) parse(). 276 + 1) parse(). 273 277 274 278 This is called to preparse the key from the key creation and update paths. 275 279 In particular, it is called during the key creation _before_ a key is ··· 278 282 279 283 The caller passes a pointer to the following struct with all of the fields 280 284 cleared, except for data, datalen and quotalen [see 281 - Documentation/security/keys/core.rst]. 285 + Documentation/security/keys/core.rst]:: 282 286 283 287 struct key_preparsed_payload { 284 288 char *description; ··· 317 321 public-key algorithm such as RSA and DSA this will likely be a printable 318 322 hex version of the key's fingerprint. 319 323 320 - Functions are provided to register and unregister parsers: 324 + Functions are provided to register and unregister parsers:: 321 325 322 326 int register_asymmetric_key_parser(struct asymmetric_key_parser *parser); 323 327 void unregister_asymmetric_key_parser(struct asymmetric_key_parser *subtype); ··· 326 330 displaying in debugging messages. 327 331 328 332 329 - ========================= 330 - KEYRING LINK RESTRICTIONS 333 + Keyring Link Restrictions 331 334 ========================= 332 335 333 336 Keyrings created from userspace using add_key can be configured to check the ··· 335 340 336 341 Several restriction methods are available: 337 342 338 - (1) Restrict using the kernel builtin trusted keyring 343 + 1) Restrict using the kernel builtin trusted keyring 339 344 340 345 - Option string used with KEYCTL_RESTRICT_KEYRING: 341 346 - "builtin_trusted" ··· 345 350 rejected. The ca_keys kernel parameter also affects which keys are used 346 351 for signature verification. 347 352 348 - (2) Restrict using the kernel builtin and secondary trusted keyrings 353 + 2) Restrict using the kernel builtin and secondary trusted keyrings 349 354 350 355 - Option string used with KEYCTL_RESTRICT_KEYRING: 351 356 - "builtin_and_secondary_trusted" ··· 356 361 kernel parameter also affects which keys are used for signature 357 362 verification. 358 363 359 - (3) Restrict using a separate key or keyring 364 + 3) Restrict using a separate key or keyring 360 365 361 366 - Option string used with KEYCTL_RESTRICT_KEYRING: 362 367 - "key_or_keyring:<key or keyring serial number>[:chain]" ··· 373 378 certificate in order (starting closest to the root) to a keyring. For 374 379 instance, one keyring can be populated with links to a set of root 375 380 certificates, with a separate, restricted keyring set up for each 376 - certificate chain to be validated: 381 + certificate chain to be validated:: 377 382 378 383 # Create and populate a keyring for root certificates 379 384 root_id=`keyctl add keyring root-certs "" @s` ··· 395 400 one of the root certificates. 396 401 397 402 A single keyring can be used to verify a chain of signatures by 398 - restricting the keyring after linking the root certificate: 403 + restricting the keyring after linking the root certificate:: 399 404 400 405 # Create a keyring for the certificate chain and add the root 401 406 chain2_id=`keyctl add keyring chain2 "" @s`

+141 -96

Documentation/crypto/async-tx-api.txt Documentation/crypto/async-tx-api.rst

··· 1 - Asynchronous Transfers/Transforms API 1 + .. SPDX-License-Identifier: GPL-2.0 2 2 3 - 1 INTRODUCTION 3 + ===================================== 4 + Asynchronous Transfers/Transforms API 5 + ===================================== 4 6 5 - 2 GENEALOGY 7 + .. Contents 6 8 7 - 3 USAGE 8 - 3.1 General format of the API 9 - 3.2 Supported operations 10 - 3.3 Descriptor management 11 - 3.4 When does the operation execute? 12 - 3.5 When does the operation complete? 13 - 3.6 Constraints 14 - 3.7 Example 9 + 1. INTRODUCTION 15 10 16 - 4 DMAENGINE DRIVER DEVELOPER NOTES 17 - 4.1 Conformance points 18 - 4.2 "My application needs exclusive control of hardware channels" 11 + 2 GENEALOGY 19 12 20 - 5 SOURCE 13 + 3 USAGE 14 + 3.1 General format of the API 15 + 3.2 Supported operations 16 + 3.3 Descriptor management 17 + 3.4 When does the operation execute? 18 + 3.5 When does the operation complete? 19 + 3.6 Constraints 20 + 3.7 Example 21 21 22 - --- 22 + 4 DMAENGINE DRIVER DEVELOPER NOTES 23 + 4.1 Conformance points 24 + 4.2 "My application needs exclusive control of hardware channels" 23 25 24 - 1 INTRODUCTION 26 + 5 SOURCE 27 + 28 + 1. Introduction 29 + =============== 25 30 26 31 The async_tx API provides methods for describing a chain of asynchronous 27 32 bulk memory transfers/transforms with support for inter-transactional ··· 36 31 the API will fit the chain of operations to the available offload 37 32 resources. 38 33 39 - 2 GENEALOGY 34 + 2.Genealogy 35 + =========== 40 36 41 37 The API was initially designed to offload the memory copy and 42 38 xor-parity-calculations of the md-raid5 driver using the offload engines ··· 45 39 on the 'dmaengine' layer developed for offloading memory copies in the 46 40 network stack using Intel(R) I/OAT engines. The following design 47 41 features surfaced as a result: 48 - 1/ implicit synchronous path: users of the API do not need to know if 42 + 43 + 1. implicit synchronous path: users of the API do not need to know if 49 44 the platform they are running on has offload capabilities. The 50 45 operation will be offloaded when an engine is available and carried out 51 46 in software otherwise. 52 - 2/ cross channel dependency chains: the API allows a chain of dependent 47 + 2. cross channel dependency chains: the API allows a chain of dependent 53 48 operations to be submitted, like xor->copy->xor in the raid5 case. The 54 49 API automatically handles cases where the transition from one operation 55 50 to another implies a hardware channel switch. 56 - 3/ dmaengine extensions to support multiple clients and operation types 51 + 3. dmaengine extensions to support multiple clients and operation types 57 52 beyond 'memcpy' 58 53 59 - 3 USAGE 54 + 3. Usage 55 + ======== 60 56 61 - 3.1 General format of the API: 62 - struct dma_async_tx_descriptor * 63 - async_<operation>(<op specific parameters>, struct async_submit ctl *submit) 57 + 3.1 General format of the API 58 + ----------------------------- 64 59 65 - 3.2 Supported operations: 66 - memcpy - memory copy between a source and a destination buffer 67 - memset - fill a destination buffer with a byte value 68 - xor - xor a series of source buffers and write the result to a 60 + :: 61 + 62 + struct dma_async_tx_descriptor * 63 + async_<operation>(<op specific parameters>, struct async_submit ctl *submit) 64 + 65 + 3.2 Supported operations 66 + ------------------------ 67 + 68 + ======== ==================================================================== 69 + memcpy memory copy between a source and a destination buffer 70 + memset fill a destination buffer with a byte value 71 + xor xor a series of source buffers and write the result to a 69 72 destination buffer 70 - xor_val - xor a series of source buffers and set a flag if the 73 + xor_val xor a series of source buffers and set a flag if the 71 74 result is zero. The implementation attempts to prevent 72 75 writes to memory 73 - pq - generate the p+q (raid6 syndrome) from a series of source buffers 74 - pq_val - validate that a p and or q buffer are in sync with a given series of 76 + pq generate the p+q (raid6 syndrome) from a series of source buffers 77 + pq_val validate that a p and or q buffer are in sync with a given series of 75 78 sources 76 - datap - (raid6_datap_recov) recover a raid6 data block and the p block 79 + datap (raid6_datap_recov) recover a raid6 data block and the p block 77 80 from the given sources 78 - 2data - (raid6_2data_recov) recover 2 raid6 data blocks from the given 81 + 2data (raid6_2data_recov) recover 2 raid6 data blocks from the given 79 82 sources 83 + ======== ==================================================================== 80 84 81 - 3.3 Descriptor management: 85 + 3.3 Descriptor management 86 + ------------------------- 87 + 82 88 The return value is non-NULL and points to a 'descriptor' when the operation 83 89 has been queued to execute asynchronously. Descriptors are recycled 84 90 resources, under control of the offload engine driver, to be reused as ··· 100 82 acknowledged by the application before the offload engine driver is allowed to 101 83 recycle (or free) the descriptor. A descriptor can be acked by one of the 102 84 following methods: 103 - 1/ setting the ASYNC_TX_ACK flag if no child operations are to be submitted 104 - 2/ submitting an unacknowledged descriptor as a dependency to another 85 + 86 + 1. setting the ASYNC_TX_ACK flag if no child operations are to be submitted 87 + 2. submitting an unacknowledged descriptor as a dependency to another 105 88 async_tx call will implicitly set the acknowledged state. 106 - 3/ calling async_tx_ack() on the descriptor. 89 + 3. calling async_tx_ack() on the descriptor. 107 90 108 91 3.4 When does the operation execute? 92 + ------------------------------------ 93 + 109 94 Operations do not immediately issue after return from the 110 95 async_<operation> call. Offload engine drivers batch operations to 111 96 improve performance by reducing the number of mmio cycles needed to ··· 119 98 mapping. 120 99 121 100 3.5 When does the operation complete? 101 + ------------------------------------- 102 + 122 103 There are two methods for an application to learn about the completion 123 104 of an operation. 124 - 1/ Call dma_wait_for_async_tx(). This call causes the CPU to spin while 105 + 106 + 1. Call dma_wait_for_async_tx(). This call causes the CPU to spin while 125 107 it polls for the completion of the operation. It handles dependency 126 108 chains and issuing pending operations. 127 - 2/ Specify a completion callback. The callback routine runs in tasklet 109 + 2. Specify a completion callback. The callback routine runs in tasklet 128 110 context if the offload engine driver supports interrupts, or it is 129 111 called in application context if the operation is carried out 130 112 synchronously in software. The callback can be set in the call to ··· 135 111 unknown length it can use the async_trigger_callback() routine to set a 136 112 completion interrupt/callback at the end of the chain. 137 113 138 - 3.6 Constraints: 139 - 1/ Calls to async_<operation> are not permitted in IRQ context. Other 114 + 3.6 Constraints 115 + --------------- 116 + 117 + 1. Calls to async_<operation> are not permitted in IRQ context. Other 140 118 contexts are permitted provided constraint #2 is not violated. 141 - 2/ Completion callback routines cannot submit new operations. This 119 + 2. Completion callback routines cannot submit new operations. This 142 120 results in recursion in the synchronous case and spin_locks being 143 121 acquired twice in the asynchronous case. 144 122 145 - 3.7 Example: 123 + 3.7 Example 124 + ----------- 125 + 146 126 Perform a xor->copy->xor operation where each operation depends on the 147 - result from the previous operation: 127 + result from the previous operation:: 148 128 149 - void callback(void *param) 150 - { 151 - struct completion *cmp = param; 129 + void callback(void *param) 130 + { 131 + struct completion *cmp = param; 152 132 153 - complete(cmp); 154 - } 133 + complete(cmp); 134 + } 155 135 156 - void run_xor_copy_xor(struct page **xor_srcs, 157 - int xor_src_cnt, 158 - struct page *xor_dest, 159 - size_t xor_len, 160 - struct page *copy_src, 161 - struct page *copy_dest, 162 - size_t copy_len) 163 - { 164 - struct dma_async_tx_descriptor *tx; 165 - addr_conv_t addr_conv[xor_src_cnt]; 166 - struct async_submit_ctl submit; 167 - addr_conv_t addr_conv[NDISKS]; 168 - struct completion cmp; 136 + void run_xor_copy_xor(struct page **xor_srcs, 137 + int xor_src_cnt, 138 + struct page *xor_dest, 139 + size_t xor_len, 140 + struct page *copy_src, 141 + struct page *copy_dest, 142 + size_t copy_len) 143 + { 144 + struct dma_async_tx_descriptor *tx; 145 + addr_conv_t addr_conv[xor_src_cnt]; 146 + struct async_submit_ctl submit; 147 + addr_conv_t addr_conv[NDISKS]; 148 + struct completion cmp; 169 149 170 - init_async_submit(&submit, ASYNC_TX_XOR_DROP_DST, NULL, NULL, NULL, 171 - addr_conv); 172 - tx = async_xor(xor_dest, xor_srcs, 0, xor_src_cnt, xor_len, &submit) 150 + init_async_submit(&submit, ASYNC_TX_XOR_DROP_DST, NULL, NULL, NULL, 151 + addr_conv); 152 + tx = async_xor(xor_dest, xor_srcs, 0, xor_src_cnt, xor_len, &submit) 173 153 174 - submit->depend_tx = tx; 175 - tx = async_memcpy(copy_dest, copy_src, 0, 0, copy_len, &submit); 154 + submit->depend_tx = tx; 155 + tx = async_memcpy(copy_dest, copy_src, 0, 0, copy_len, &submit); 176 156 177 - init_completion(&cmp); 178 - init_async_submit(&submit, ASYNC_TX_XOR_DROP_DST | ASYNC_TX_ACK, tx, 179 - callback, &cmp, addr_conv); 180 - tx = async_xor(xor_dest, xor_srcs, 0, xor_src_cnt, xor_len, &submit); 157 + init_completion(&cmp); 158 + init_async_submit(&submit, ASYNC_TX_XOR_DROP_DST | ASYNC_TX_ACK, tx, 159 + callback, &cmp, addr_conv); 160 + tx = async_xor(xor_dest, xor_srcs, 0, xor_src_cnt, xor_len, &submit); 181 161 182 - async_tx_issue_pending_all(); 162 + async_tx_issue_pending_all(); 183 163 184 - wait_for_completion(&cmp); 185 - } 164 + wait_for_completion(&cmp); 165 + } 186 166 187 167 See include/linux/async_tx.h for more information on the flags. See the 188 168 ops_run_* and ops_complete_* routines in drivers/md/raid5.c for more 189 169 implementation examples. 190 170 191 - 4 DRIVER DEVELOPMENT NOTES 171 + 4. Driver Development Notes 172 + =========================== 192 173 193 - 4.1 Conformance points: 174 + 4.1 Conformance points 175 + ---------------------- 176 + 194 177 There are a few conformance points required in dmaengine drivers to 195 178 accommodate assumptions made by applications using the async_tx API: 196 - 1/ Completion callbacks are expected to happen in tasklet context 197 - 2/ dma_async_tx_descriptor fields are never manipulated in IRQ context 198 - 3/ Use async_tx_run_dependencies() in the descriptor clean up path to 179 + 180 + 1. Completion callbacks are expected to happen in tasklet context 181 + 2. dma_async_tx_descriptor fields are never manipulated in IRQ context 182 + 3. Use async_tx_run_dependencies() in the descriptor clean up path to 199 183 handle submission of dependent operations 200 184 201 185 4.2 "My application needs exclusive control of hardware channels" 186 + ----------------------------------------------------------------- 187 + 202 188 Primarily this requirement arises from cases where a DMA engine driver 203 189 is being used to support device-to-memory operations. A channel that is 204 190 performing these operations cannot, for many platform specific reasons, 205 191 be shared. For these cases the dma_request_channel() interface is 206 192 provided. 207 193 208 - The interface is: 209 - struct dma_chan *dma_request_channel(dma_cap_mask_t mask, 210 - dma_filter_fn filter_fn, 211 - void *filter_param); 194 + The interface is:: 212 195 213 - Where dma_filter_fn is defined as: 214 - typedef bool (*dma_filter_fn)(struct dma_chan *chan, void *filter_param); 196 + struct dma_chan *dma_request_channel(dma_cap_mask_t mask, 197 + dma_filter_fn filter_fn, 198 + void *filter_param); 199 + 200 + Where dma_filter_fn is defined as:: 201 + 202 + typedef bool (*dma_filter_fn)(struct dma_chan *chan, void *filter_param); 215 203 216 204 When the optional 'filter_fn' parameter is set to NULL 217 205 dma_request_channel simply returns the first channel that satisfies the ··· 243 207 unused "public" channel. 244 208 245 209 A couple caveats to note when implementing a driver and consumer: 246 - 1/ Once a channel has been privately allocated it will no longer be 210 + 211 + 1. Once a channel has been privately allocated it will no longer be 247 212 considered by the general-purpose allocator even after a call to 248 213 dma_release_channel(). 249 - 2/ Since capabilities are specified at the device level a dma_device 214 + 2. Since capabilities are specified at the device level a dma_device 250 215 with multiple channels will either have all channels public, or all 251 216 channels private. 252 217 253 - 5 SOURCE 218 + 5. Source 219 + --------- 254 220 255 - include/linux/dmaengine.h: core header file for DMA drivers and api users 256 - drivers/dma/dmaengine.c: offload engine channel management routines 257 - drivers/dma/: location for offload engine drivers 258 - include/linux/async_tx.h: core header file for the async_tx api 259 - crypto/async_tx/async_tx.c: async_tx interface to dmaengine and common code 260 - crypto/async_tx/async_memcpy.c: copy offload 261 - crypto/async_tx/async_xor.c: xor and xor zero sum offload 221 + include/linux/dmaengine.h: 222 + core header file for DMA drivers and api users 223 + drivers/dma/dmaengine.c: 224 + offload engine channel management routines 225 + drivers/dma/: 226 + location for offload engine drivers 227 + include/linux/async_tx.h: 228 + core header file for the async_tx api 229 + crypto/async_tx/async_tx.c: 230 + async_tx interface to dmaengine and common code 231 + crypto/async_tx/async_memcpy.c: 232 + copy offload 233 + crypto/async_tx/async_xor.c: 234 + xor and xor zero sum offload

+107 -45

Documentation/crypto/descore-readme.txt Documentation/crypto/descore-readme.rst

··· 1 - Below is the original README file from the descore.shar package. 1 + .. SPDX-License-Identifier: GPL-2.0 2 + .. include:: <isonum.txt> 3 + 4 + =========================================== 5 + Fast & Portable DES encryption & decryption 6 + =========================================== 7 + 8 + .. note:: 9 + 10 + Below is the original README file from the descore.shar package, 11 + converted to ReST format. 12 + 2 13 ------------------------------------------------------------------------------ 3 14 4 15 des - fast & portable DES encryption & decryption. 5 - Copyright (C) 1992 Dana L. How 16 + 17 + Copyright |copy| 1992 Dana L. How 6 18 7 19 This program is free software; you can redistribute it and/or modify 8 20 it under the terms of the GNU Library General Public License as published by ··· 32 20 33 21 Author's address: how@isl.stanford.edu 34 22 35 - $Id: README,v 1.15 1992/05/20 00:25:32 how E $ 23 + .. README,v 1.15 1992/05/20 00:25:32 how E 36 24 37 - 38 - ==>> To compile after untarring/unsharring, just `make' <<== 39 - 25 + ==>> To compile after untarring/unsharring, just ``make`` <<== 40 26 41 27 This package was designed with the following goals: 28 + 42 29 1. Highest possible encryption/decryption PERFORMANCE. 43 30 2. PORTABILITY to any byte-addressable host with a 32bit unsigned C type 44 31 3. Plug-compatible replacement for KERBEROS's low-level routines. ··· 47 36 71755.204@compuserve.com, sparked a number of these enhancements. 48 37 49 38 To more rapidly understand the code in this package, inspect desSmallFips.i 50 - (created by typing `make') BEFORE you tackle desCode.h. The latter is set 39 + (created by typing ``make``) BEFORE you tackle desCode.h. The latter is set 51 40 up in a parameterized fashion so it can easily be modified by speed-daemon 52 41 hackers in pursuit of that last microsecond. You will find it more 53 42 illuminating to inspect one specific implementation, ··· 58 47 compile on a SPARCStation 1 (cc -O4, gcc -O2): 59 48 60 49 this code (byte-order independent): 61 - 30us per encryption (options: 64k tables, no IP/FP) 62 - 33us per encryption (options: 64k tables, FIPS standard bit ordering) 63 - 45us per encryption (options: 2k tables, no IP/FP) 64 - 48us per encryption (options: 2k tables, FIPS standard bit ordering) 65 - 275us to set a new key (uses 1k of key tables) 50 + 51 + - 30us per encryption (options: 64k tables, no IP/FP) 52 + - 33us per encryption (options: 64k tables, FIPS standard bit ordering) 53 + - 45us per encryption (options: 2k tables, no IP/FP) 54 + - 48us per encryption (options: 2k tables, FIPS standard bit ordering) 55 + - 275us to set a new key (uses 1k of key tables) 56 + 66 57 this has the quickest encryption/decryption routines i've seen. 67 58 since i was interested in fast des filters rather than crypt(3) 68 59 and password cracking, i haven't really bothered yet to speed up ··· 76 63 are highly variable because of cache effects). 77 64 78 65 kerberos des replacement from australia (version 1.95): 79 - 53us per encryption (uses 2k of tables) 80 - 96us to set a new key (uses 2.25k of key tables) 66 + 67 + - 53us per encryption (uses 2k of tables) 68 + - 96us to set a new key (uses 2.25k of key tables) 69 + 81 70 so despite the author's inclusion of some of the performance 82 71 improvements i had suggested to him, this package's 83 72 encryption/decryption is still slower on the sparc and 68000. 84 73 more specifically, 19-40% slower on the 68020 and 11-35% slower 85 74 on the sparc, depending on the compiler; 86 75 in full gory detail (ALT_ECB is a libdes variant): 76 + 77 + =============== ============== =============== ================= 87 78 compiler machine desCore libdes ALT_ECB slower by 79 + =============== ============== =============== ================= 88 80 gcc 2.1 -O2 Sun 3/110 304 uS 369.5uS 461.8uS 22% 89 81 cc -O1 Sun 3/110 336 uS 436.6uS 399.3uS 19% 90 82 cc -O2 Sun 3/110 360 uS 532.4uS 505.1uS 40% ··· 97 79 gcc 2.1 -O2 Sun 4/50 48 uS 53.4uS 57.5uS 11% 98 80 cc -O2 Sun 4/50 48 uS 64.6uS 64.7uS 35% 99 81 cc -O4 Sun 4/50 48 uS 64.7uS 64.9uS 35% 82 + =============== ============== =============== ================= 83 + 100 84 (my time measurements are not as accurate as his). 85 + 101 86 the comments in my first release of desCore on version 1.92: 102 - 68us per encryption (uses 2k of tables) 103 - 96us to set a new key (uses 2.25k of key tables) 87 + 88 + - 68us per encryption (uses 2k of tables) 89 + - 96us to set a new key (uses 2.25k of key tables) 90 + 104 91 this is a very nice package which implements the most important 105 92 of the optimizations which i did in my encryption routines. 106 93 it's a bit weak on common low-level optimizations which is why ··· 114 91 speed up the key-setting routines with impressive results. 115 92 (at some point i may do the same in my package). he also implements 116 93 the rest of the mit des library. 94 + 117 95 (code from eay@psych.psy.uq.oz.au via comp.sources.misc) 118 96 119 97 fast crypt(3) package from denmark: 98 + 120 99 the des routine here is buried inside a loop to do the 121 100 crypt function and i didn't feel like ripping it out and measuring 122 101 performance. his code takes 26 sparc instructions to compute one 123 102 des iteration; above, Quick (64k) takes 21 and Small (2k) takes 37. 124 103 he claims to use 280k of tables but the iteration calculation seems 125 104 to use only 128k. his tables and code are machine independent. 105 + 126 106 (code from glad@daimi.aau.dk via alt.sources or comp.sources.misc) 127 107 128 108 swedish reimplementation of Kerberos des library 129 - 108us per encryption (uses 34k worth of tables) 130 - 134us to set a new key (uses 32k of key tables to get this speed!) 109 + 110 + - 108us per encryption (uses 34k worth of tables) 111 + - 134us to set a new key (uses 32k of key tables to get this speed!) 112 + 131 113 the tables used seem to be machine-independent; 132 114 he seems to have included a lot of special case code 133 - so that, e.g., `long' loads can be used instead of 4 `char' loads 115 + so that, e.g., ``long`` loads can be used instead of 4 ``char`` loads 134 116 when the machine's architecture allows it. 117 + 135 118 (code obtained from chalmers.se:pub/des) 136 119 137 120 crack 3.3c package from england: 121 + 138 122 as in crypt above, the des routine is buried in a loop. it's 139 123 also very modified for crypt. his iteration code uses 16k 140 124 of tables and appears to be slow. 125 + 141 126 (code obtained from aem@aber.ac.uk via alt.sources or comp.sources.misc) 142 127 143 - ``highly optimized'' and tweaked Kerberos/Athena code (byte-order dependent): 144 - 165us per encryption (uses 6k worth of tables) 145 - 478us to set a new key (uses <1k of key tables) 128 + ``highly optimized`` and tweaked Kerberos/Athena code (byte-order dependent): 129 + 130 + - 165us per encryption (uses 6k worth of tables) 131 + - 478us to set a new key (uses <1k of key tables) 132 + 146 133 so despite the comments in this code, it was possible to get 147 134 faster code AND smaller tables, as well as making the tables 148 135 machine-independent. 149 136 (code obtained from prep.ai.mit.edu) 150 137 151 138 UC Berkeley code (depends on machine-endedness): 152 - 226us per encryption 153 - 10848us to set a new key 139 + - 226us per encryption 140 + - 10848us to set a new key 141 + 154 142 table sizes are unclear, but they don't look very small 155 143 (code obtained from wuarchive.wustl.edu) 156 144 157 145 158 146 motivation and history 147 + ====================== 159 148 160 149 a while ago i wanted some des routines and the routines documented on sun's 161 150 man pages either didn't exist or dumped core. i had heard of kerberos, ··· 177 142 advantage of the regular structure of operations such as IP, E, and FP 178 143 (i.e. the author didn't sit down and think before coding), 179 144 it was excessively slow, the author had attempted to clarify the code 180 - by adding MORE statements to make the data movement more `consistent' 145 + by adding MORE statements to make the data movement more ``consistent`` 181 146 instead of simplifying his implementation and cutting down on all data 182 147 movement (in particular, his use of L1, R1, L2, R2), and it was full of 183 - idiotic `tweaks' for particular machines which failed to deliver significant 148 + idiotic ``tweaks`` for particular machines which failed to deliver significant 184 149 speedups but which did obfuscate everything. so i took the test data 185 150 from his verification program and rewrote everything else. 186 151 ··· 202 167 203 168 204 169 porting notes 170 + ============= 205 171 206 172 one thing i did not want to do was write an enormous mess 207 173 which depended on endedness and other machine quirks, 208 174 and which necessarily produced different code and different lookup tables 209 175 for different machines. see the kerberos code for an example 210 - of what i didn't want to do; all their endedness-specific `optimizations' 176 + of what i didn't want to do; all their endedness-specific ``optimizations`` 211 177 obfuscate the code and in the end were slower than a simpler machine 212 178 independent approach. however, there are always some portability 213 179 considerations of some kind, and i have included some options ··· 220 184 i assume word pointers can be freely cast to and from char pointers. 221 185 note that 99% of C programs make these assumptions. 222 186 i always use unsigned char's if the high bit could be set. 223 - 2) the typedef `word' means a 32 bit unsigned integral type. 224 - if `unsigned long' is not 32 bits, change the typedef in desCore.h. 187 + 2) the typedef ``word`` means a 32 bit unsigned integral type. 188 + if ``unsigned long`` is not 32 bits, change the typedef in desCore.h. 225 189 i assume sizeof(word) == 4 EVERYWHERE. 226 190 227 191 the (worst-case) cost of my NOT doing endedness-specific optimizations ··· 231 195 232 196 233 197 OPTIONAL performance optimizations 198 + ================================== 234 199 235 - 1) you should define one of `i386,' `vax,' `mc68000,' or `sparc,' 200 + 1) you should define one of ``i386,`` ``vax,`` ``mc68000,`` or ``sparc,`` 236 201 whichever one is closest to the capabilities of your machine. 237 202 see the start of desCode.h to see exactly what this selection implies. 238 203 note that if you select the wrong one, the des code will still work; 239 204 these are just performance tweaks. 240 - 2) for those with functional `asm' keywords: you should change the 205 + 2) for those with functional ``asm`` keywords: you should change the 241 206 ROR and ROL macros to use machine rotate instructions if you have them. 242 207 this will save 2 instructions and a temporary per use, 243 208 or about 32 to 40 instructions per en/decryption. 209 + 244 210 note that gcc is smart enough to translate the ROL/R macros into 245 211 machine rotates! 246 212 247 213 these optimizations are all rather persnickety, yet with them you should 248 214 be able to get performance equal to assembly-coding, except that: 215 + 249 216 1) with the lack of a bit rotate operator in C, rotates have to be synthesized 250 - from shifts. so access to `asm' will speed things up if your machine 217 + from shifts. so access to ``asm`` will speed things up if your machine 251 218 has rotates, as explained above in (3) (not necessary if you use gcc). 252 219 2) if your machine has less than 12 32-bit registers i doubt your compiler will 253 220 generate good code. 254 - `i386' tries to configure the code for a 386 by only declaring 3 registers 221 + 222 + ``i386`` tries to configure the code for a 386 by only declaring 3 registers 255 223 (it appears that gcc can use ebx, esi and edi to hold register variables). 256 224 however, if you like assembly coding, the 386 does have 7 32-bit registers, 257 - and if you use ALL of them, use `scaled by 8' address modes with displacement 225 + and if you use ALL of them, use ``scaled by 8`` address modes with displacement 258 226 and other tricks, you can get reasonable routines for DesQuickCore... with 259 227 about 250 instructions apiece. For DesSmall... it will help to rearrange 260 228 des_keymap, i.e., now the sbox # is the high part of the index and 261 229 the 6 bits of data is the low part; it helps to exchange these. 230 + 262 231 since i have no way to conveniently test it i have not provided my 263 232 shoehorned 386 version. note that with this release of desCore, gcc is able 264 233 to put everything in registers(!), and generate about 370 instructions apiece 265 234 for the DesQuickCore... routines! 266 235 267 236 coding notes 237 + ============ 268 238 269 239 the en/decryption routines each use 6 necessary register variables, 270 240 with 4 being actively used at once during the inner iterations. ··· 278 236 up to 8 more registers are used to hold constants in some configurations. 279 237 280 238 i assume that the use of a constant is more expensive than using a register: 239 + 281 240 a) additionally, i have tried to put the larger constants in registers. 282 241 registering priority was by the following: 283 - anything more than 12 bits (bad for RISC and CISC) 284 - greater than 127 in value (can't use movq or byte immediate on CISC) 285 - 9-127 (may not be able to use CISC shift immediate or add/sub quick), 286 - 1-8 were never registered, being the cheapest constants. 242 + 243 + - anything more than 12 bits (bad for RISC and CISC) 244 + - greater than 127 in value (can't use movq or byte immediate on CISC) 245 + - 9-127 (may not be able to use CISC shift immediate or add/sub quick), 246 + - 1-8 were never registered, being the cheapest constants. 247 + 287 248 b) the compiler may be too stupid to realize table and table+256 should 288 249 be assigned to different constant registers and instead repetitively 289 - do the arithmetic, so i assign these to explicit `m' register variables 250 + do the arithmetic, so i assign these to explicit ``m`` register variables 290 251 when possible and helpful. 291 252 292 253 i assume that indexing is cheaper or equivalent to auto increment/decrement, ··· 298 253 299 254 i assume that addresses can be cheaply formed from two registers, 300 255 or from a register and a small constant. 301 - for the 68000, the `two registers and small offset' form is used sparingly. 256 + for the 68000, the ``two registers and small offset`` form is used sparingly. 302 257 all index scaling is done explicitly - no hidden shifts by log2(sizeof). 303 258 304 259 the code is written so that even a dumb compiler 305 260 should never need more than one hidden temporary, 306 261 increasing the chance that everything will fit in the registers. 307 262 KEEP THIS MORE SUBTLE POINT IN MIND IF YOU REWRITE ANYTHING. 263 + 308 264 (actually, there are some code fragments now which do require two temps, 309 265 but fixing it would either break the structure of the macros or 310 266 require declaring another temporary). 311 267 312 268 313 269 special efficient data format 270 + ============================== 314 271 315 - bits are manipulated in this arrangement most of the time (S7 S5 S3 S1): 272 + bits are manipulated in this arrangement most of the time (S7 S5 S3 S1):: 273 + 316 274 003130292827xxxx242322212019xxxx161514131211xxxx080706050403xxxx 275 + 317 276 (the x bits are still there, i'm just emphasizing where the S boxes are). 318 - bits are rotated left 4 when computing S6 S4 S2 S0: 277 + bits are rotated left 4 when computing S6 S4 S2 S0:: 278 + 319 279 282726252423xxxx201918171615xxxx121110090807xxxx040302010031xxxx 280 + 320 281 the rightmost two bits are usually cleared so the lower byte can be used 321 282 as an index into an sbox mapping table. the next two x'd bits are set 322 283 to various values to access different parts of the tables. ··· 339 288 must be long-aligned. 340 289 341 290 DesQuickInit() 342 - call this before using any other routine with `Quick' in its name. 291 + call this before using any other routine with ``Quick`` in its name. 343 292 it generates the special 64k table these routines need. 344 293 DesQuickDone() 345 294 frees this table ··· 349 298 which must have odd parity (or -1 is returned) and which must 350 299 not be a (semi-)weak key (or -2 is returned). 351 300 normally DesMethod() returns 0. 301 + 352 302 m is filled in from k so that when one of the routines below 353 303 is called with m, the routine will act like standard des 354 304 en/decryption with the key k. if you use DesMethod, ··· 360 308 will be set to magic constants which speed up the encryption/decryption 361 309 on some machines. and yes, each byte controls 362 310 a specific sbox during a specific iteration. 311 + 363 312 you really shouldn't use the 768bit format directly; i should 364 313 provide a routine that converts 128 6-bit bytes (specified in 365 314 S-box mapping order or something) into the right format for you. 366 315 this would entail some byte concatenation and rotation. 367 316 368 317 Des{Small|Quick}{Fips|Core}{Encrypt|Decrypt}(d, m, s) 369 - performs des on the 8 bytes at s into the 8 bytes at d. (d,s: char *). 318 + performs des on the 8 bytes at s into the 8 bytes at 319 + ``d. (d,s: char *)``. 320 + 370 321 uses m as a 768bit key as explained above. 322 + 371 323 the Encrypt|Decrypt choice is obvious. 324 + 372 325 Fips|Core determines whether a completely standard FIPS initial 373 326 and final permutation is done; if not, then the data is loaded 374 327 and stored in a nonstandard bit order (FIPS w/o IP/FP). 328 + 375 329 Fips slows down Quick by 10%, Small by 9%. 330 + 376 331 Small|Quick determines whether you use the normal routine 377 332 or the crazy quick one which gobbles up 64k more of memory. 378 333 Small is 50% slower then Quick, but Quick needs 32 times as much ··· 388 329 389 330 390 331 Getting it to compile on your machine 332 + ===================================== 391 333 392 334 there are no machine-dependencies in the code (see porting), 393 - except perhaps the `now()' macro in desTest.c. 335 + except perhaps the ``now()`` macro in desTest.c. 394 336 ALL generated tables are machine independent. 395 337 you should edit the Makefile with the appropriate optimization flags 396 338 for your compiler (MAX optimization). 397 339 398 340 399 341 Speeding up kerberos (and/or its des library) 342 + ============================================= 400 343 401 344 note that i have included a kerberos-compatible interface in desUtil.c 402 345 through the functions des_key_sched() and des_ecb_encrypt(). ··· 408 347 file provided with the kerberos library. 409 348 410 349 Other uses 350 + ========== 411 351 412 352 the macros in desCode.h would be very useful for putting inline des 413 353 functions in more complicated encryption routines.

+5

Documentation/crypto/index.rst

··· 17 17 :maxdepth: 2 18 18 19 19 intro 20 + api-intro 20 21 architecture 22 + 23 + async-tx-api 24 + asymmetric-keys 21 25 devel-algos 22 26 userspace-if 23 27 crypto_engine 24 28 api 25 29 api-samples 30 + descore-readme

+20 -20

Documentation/dev-tools/coccinelle.rst

··· 85 85 file:line:column-column: message 86 86 87 87 - ``context`` highlights lines of interest and their context in a 88 - diff-like style.Lines of interest are indicated with ``-``. 88 + diff-like style. Lines of interest are indicated with ``-``. 89 89 90 90 - ``org`` generates a report in the Org mode format of Emacs. 91 91 ··· 119 119 description of the problem being checked by the semantic patch, and 120 120 includes a reference to Coccinelle. 121 121 122 - As any static code analyzer, Coccinelle produces false 122 + As with any static code analyzer, Coccinelle produces false 123 123 positives. Thus, reports must be carefully checked, and patches 124 124 reviewed. 125 125 ··· 135 135 136 136 make coccicheck MODE=report J=4 137 137 138 - As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization, 138 + As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization; 139 139 if support for this is detected you will benefit from parmap parallelization. 140 140 141 141 When parmap is enabled coccicheck will enable dynamic load balancing by using 142 - ``--chunksize 1`` argument, this ensures we keep feeding threads with work 142 + ``--chunksize 1`` argument. This ensures we keep feeding threads with work 143 143 one by one, so that we avoid the situation where most work gets done by only 144 144 a few threads. With dynamic load balancing, if a thread finishes early we keep 145 145 feeding it more work. 146 146 147 147 When parmap is enabled, if an error occurs in Coccinelle, this error 148 - value is propagated back, the return value of the ``make coccicheck`` 149 - captures this return value. 148 + value is propagated back, and the return value of the ``make coccicheck`` 149 + command captures this return value. 150 150 151 151 Using Coccinelle with a single semantic patch 152 152 --------------------------------------------- ··· 183 183 184 184 make C=2 CHECK="scripts/coccicheck" 185 185 186 - In these modes, which works on a file basis, there is no information 186 + In these modes, which work on a file basis, there is no information 187 187 about semantic patches displayed, and no commit message proposed. 188 188 189 189 This runs every semantic patch in scripts/coccinelle by default. The ··· 198 198 199 199 Using coccicheck is best as it provides in the spatch command line 200 200 include options matching the options used when we compile the kernel. 201 - You can learn what these options are by using V=1, you could then 201 + You can learn what these options are by using V=1; you could then 202 202 manually run Coccinelle with debug options added. 203 203 204 204 Alternatively you can debug running Coccinelle against SmPL patches 205 - by asking for stderr to be redirected to stderr, by default stderr 206 - is redirected to /dev/null, if you'd like to capture stderr you 205 + by asking for stderr to be redirected to stderr. By default stderr 206 + is redirected to /dev/null; if you'd like to capture stderr you 207 207 can specify the ``DEBUG_FILE="file.txt"`` option to coccicheck. For 208 208 instance:: 209 209 ··· 211 211 make coccicheck COCCI=scripts/coccinelle/free/kfree.cocci MODE=report DEBUG_FILE=cocci.err 212 212 cat cocci.err 213 213 214 - You can use SPFLAGS to add debugging flags, for instance you may want to 215 - add both --profile --show-trying to SPFLAGS when debugging. For instance 214 + You can use SPFLAGS to add debugging flags; for instance you may want to 215 + add both --profile --show-trying to SPFLAGS when debugging. For example 216 216 you may want to use:: 217 217 218 218 rm -f err.log ··· 229 229 -------------------- 230 230 231 231 Coccinelle supports reading .cocciconfig for default Coccinelle options that 232 - should be used every time spatch is spawned, the order of precedence for 232 + should be used every time spatch is spawned. The order of precedence for 233 233 variables for .cocciconfig is as follows: 234 234 235 235 - Your current user's home directory is processed first ··· 237 237 - The directory provided with the --dir option is processed last, if used 238 238 239 239 Since coccicheck runs through make, it naturally runs from the kernel 240 - proper dir, as such the second rule above would be implied for picking up a 240 + proper dir; as such the second rule above would be implied for picking up a 241 241 .cocciconfig when using ``make coccicheck``. 242 242 243 243 ``make coccicheck`` also supports using M= targets. If you do not supply ··· 260 260 order logic of .cocciconfig reading. If using the kernel's coccicheck target, 261 261 override any of the kernel's .coccicheck's settings using SPFLAGS. 262 262 263 - We help Coccinelle when used against Linux with a set of sensible defaults 263 + We help Coccinelle when used against Linux with a set of sensible default 264 264 options for Linux with our own Linux .cocciconfig. This hints to coccinelle 265 - git can be used for ``git grep`` queries over coccigrep. A timeout of 200 265 + that git can be used for ``git grep`` queries over coccigrep. A timeout of 200 266 266 seconds should suffice for now. 267 267 268 268 The options picked up by coccinelle when reading a .cocciconfig do not appear 269 - as arguments to spatch processes running on your system, to confirm what 269 + as arguments to spatch processes running on your system. To confirm what 270 270 options will be used by Coccinelle run:: 271 271 272 272 spatch --print-options-only ··· 290 290 291 291 Coccinelle supports idutils as well but requires coccinelle >= 1.0.6. 292 292 When no ID file is specified coccinelle assumes your ID database file 293 - is in the file .id-utils.index on the top level of the kernel, coccinelle 293 + is in the file .id-utils.index on the top level of the kernel. Coccinelle 294 294 carries a script scripts/idutils_index.sh which creates the database with:: 295 295 296 296 mkid -i C --output .id-utils.index ··· 317 317 --------------------------- 318 318 319 319 SmPL patches can have their own requirements for options passed 320 - to Coccinelle. SmPL patch specific options can be provided by 320 + to Coccinelle. SmPL patch-specific options can be provided by 321 321 providing them at the top of the SmPL patch, for instance:: 322 322 323 323 // Options: --no-includes --include-headers ··· 327 327 328 328 As Coccinelle features get added some more advanced SmPL patches 329 329 may require newer versions of Coccinelle. If an SmPL patch requires 330 - at least a version of Coccinelle, this can be specified as follows, 330 + a minimum version of Coccinelle, this can be specified as follows, 331 331 as an example if requiring at least Coccinelle >= 1.0.5:: 332 332 333 333 // Requires: 1.0.5

+2 -2

Documentation/dev-tools/gcov.rst

··· 22 22 * minimizing kernel configurations (do I need this option if the 23 23 associated code is never run?) 24 24 25 - .. _gcov: http://gcc.gnu.org/onlinedocs/gcc/Gcov.html 25 + .. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html 26 26 .. _lcov: http://ltp.sourceforge.net/coverage/lcov.php 27 27 28 28 ··· 171 171 GCC and LLVM gcov tools are not necessarily compatible. Use gcov_ to work with 172 172 GCC-generated .gcno and .gcda files, and use llvm-cov_ for Clang. 173 173 174 - .. _gcov: http://gcc.gnu.org/onlinedocs/gcc/Gcov.html 174 + .. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html 175 175 .. _llvm-cov: https://llvm.org/docs/CommandGuide/llvm-cov.html 176 176 177 177 Build differences between GCC and Clang gcov are handled by Kconfig. It

+1 -1

Documentation/dev-tools/kgdb.rst

··· 872 872 attached keyboard. The keyboard infrastructure is only compiled into the 873 873 kernel when ``CONFIG_KDB_KEYBOARD=y`` is set in the kernel configuration. 874 874 875 - The core polled keyboard driver driver for PS/2 type keyboards is in 875 + The core polled keyboard driver for PS/2 type keyboards is in 876 876 ``drivers/char/kdb_keyboard.c``. This driver is hooked into the debug core 877 877 when kgdboc populates the callback in the array called 878 878 :c:type:`kdb_poll_funcs[]`. The :c:func:`kdb_get_kbd_char` is the top-level

-2

Documentation/dev-tools/kmemleak.rst

··· 8 8 reported via /sys/kernel/debug/kmemleak. A similar method is used by the 9 9 Valgrind tool (``memcheck --leak-check``) to detect the memory leaks in 10 10 user-space applications. 11 - Kmemleak is supported on x86, arm, arm64, powerpc, sparc, sh, microblaze, mips, 12 - s390, nds32, arc and xtensa. 13 11 14 12 Usage 15 13 -----

+4 -2

Documentation/dev-tools/sparse.rst

··· 9 9 number of potential problems with kernel code. See 10 10 https://lwn.net/Articles/689907/ for an overview of sparse; this document 11 11 contains some kernel-specific sparse information. 12 + More information on sparse, mainly about its internals, can be found in 13 + its official pages at https://sparse.docs.kernel.org. 12 14 13 15 14 16 Using sparse for typechecking ··· 75 73 Getting sparse 76 74 -------------- 77 75 78 - You can get latest released versions from the Sparse homepage at 79 - https://sparse.wiki.kernel.org/index.php/Main_Page 76 + You can get tarballs of the latest released versions from: 77 + https://www.kernel.org/pub/software/devel/sparse/dist/ 80 78 81 79 Alternatively, you can get snapshots of the latest development version 82 80 of sparse using git to clone::

+163 -131

Documentation/devicetree/booting-without-of.txt Documentation/devicetree/booting-without-of.rst

··· 1 - Booting the Linux/ppc kernel without Open Firmware 2 - -------------------------------------------------- 1 + .. SPDX-License-Identifier: GPL-2.0 3 2 4 - (c) 2005 Benjamin Herrenschmidt <benh at kernel.crashing.org>, 5 - IBM Corp. 6 - (c) 2005 Becky Bruce <becky.bruce at freescale.com>, 7 - Freescale Semiconductor, FSL SOC and 32-bit additions 8 - (c) 2006 MontaVista Software, Inc. 9 - Flash chip node definition 3 + ================================================== 4 + Booting the Linux/ppc kernel without Open Firmware 5 + ================================================== 10 6 11 - Table of Contents 12 - ================= 7 + Copyright (c) 2005 Benjamin Herrenschmidt <benh at kernel.crashing.org>, 8 + IBM Corp. 9 + 10 + Copyright (c) 2005 Becky Bruce <becky.bruce at freescale.com>, 11 + Freescale Semiconductor, FSL SOC and 32-bit additions 12 + 13 + Copyright (c) 2006 MontaVista Software, Inc. 14 + Flash chip node definition 15 + 16 + .. Table of Contents 13 17 14 18 I - Introduction 15 19 1) Entry point for arch/arm ··· 65 61 Revision Information 66 62 ==================== 67 63 68 - May 18, 2005: Rev 0.1 - Initial draft, no chapter III yet. 64 + May 18, 2005: Rev 0.1 65 + - Initial draft, no chapter III yet. 69 66 70 - May 19, 2005: Rev 0.2 - Add chapter III and bits & pieces here or 67 + May 19, 2005: Rev 0.2 68 + - Add chapter III and bits & pieces here or 71 69 clarifies the fact that a lot of things are 72 70 optional, the kernel only requires a very 73 71 small device tree, though it is encouraged 74 72 to provide an as complete one as possible. 75 73 76 - May 24, 2005: Rev 0.3 - Precise that DT block has to be in RAM 74 + May 24, 2005: Rev 0.3 75 + - Precise that DT block has to be in RAM 77 76 - Misc fixes 78 77 - Define version 3 and new format version 16 79 78 for the DT block (version 16 needs kernel ··· 89 82 "name" property is now automatically 90 83 deduced from the unit name 91 84 92 - June 1, 2005: Rev 0.4 - Correct confusion between OF_DT_END and 85 + June 1, 2005: Rev 0.4 86 + - Correct confusion between OF_DT_END and 93 87 OF_DT_END_NODE in structure definition. 94 88 - Change version 16 format to always align 95 89 property data to 4 bytes. Since tokens are ··· 123 115 - Compare FSL SOC use of PCI to standard and make sure no new 124 116 node definition required. 125 117 - Add more information about node definitions for SOC devices 126 - that currently have no standard, like the FSL CPM. 118 + that currently have no standard, like the FSL CPM. 127 119 128 120 129 121 I - Introduction ··· 268 260 269 261 b) create your main platform file as 270 262 "arch/powerpc/platforms/myplatform/myboard_setup.c" and add it 271 - to the Makefile under the condition of your CONFIG_ 263 + to the Makefile under the condition of your ``CONFIG_`` 272 264 option. This file will define a structure of type "ppc_md" 273 265 containing the various callbacks that the generic code will 274 266 use to get to your platform specific code ··· 279 271 with classic Powerpc architectures. 280 272 281 273 3) Entry point for arch/x86 282 - ------------------------------- 274 + --------------------------- 283 275 284 276 There is one single 32bit entry point to the kernel at code32_start, 285 277 the decompressor (the real mode entry point goes to the same 32bit ··· 288 280 Documentation/x86/boot.rst 289 281 The physical pointer to the device-tree block (defined in chapter II) 290 282 is passed via setup_data which requires at least boot protocol 2.09. 291 - The type filed is defined as 283 + The type filed is defined as:: 292 284 293 - #define SETUP_DTB 2 285 + #define SETUP_DTB 2 294 286 295 287 This device-tree is used as an extension to the "boot page". As such it 296 288 does not parse / consider data which is already covered by the boot ··· 362 354 363 355 The kernel is passed the physical address pointing to an area of memory 364 356 that is roughly described in include/linux/of_fdt.h by the structure 365 - boot_param_header: 357 + boot_param_header::: 366 358 367 - struct boot_param_header { 359 + struct boot_param_header { 368 360 u32 magic; /* magic word OF_DT_HEADER */ 369 361 u32 totalsize; /* total size of DT block */ 370 362 u32 off_dt_struct; /* offset to structure */ ··· 382 374 383 375 /* version 17 fields below */ 384 376 u32 size_dt_struct; /* size of the DT structure block */ 385 - }; 377 + }; 386 378 387 - Along with the constants: 379 + Along with the constants:: 388 380 389 - /* Definitions used by the flattened device tree */ 390 - #define OF_DT_HEADER 0xd00dfeed /* 4: version, 391 - 4: total size */ 392 - #define OF_DT_BEGIN_NODE 0x1 /* Start node: full name 393 - */ 394 - #define OF_DT_END_NODE 0x2 /* End node */ 395 - #define OF_DT_PROP 0x3 /* Property: name off, 396 - size, content */ 397 - #define OF_DT_END 0x9 381 + /* Definitions used by the flattened device tree */ 382 + #define OF_DT_HEADER 0xd00dfeed /* 4: version, 383 + 4: total size */ 384 + #define OF_DT_BEGIN_NODE 0x1 /* Start node: full name 385 + */ 386 + #define OF_DT_END_NODE 0x2 /* End node */ 387 + #define OF_DT_PROP 0x3 /* Property: name off, 388 + size, content */ 389 + #define OF_DT_END 0x9 398 390 399 391 All values in this header are in big endian format, the various 400 392 fields in this header are defined more precisely below. All ··· 438 430 way to avoid overriding critical things like, on Open Firmware 439 431 capable machines, the RTAS instance, or on some pSeries, the TCE 440 432 tables used for the iommu. Typically, the reserve map should 441 - contain _at least_ this DT block itself (header,total_size). If 433 + contain **at least** this DT block itself (header,total_size). If 442 434 you are passing an initrd to the kernel, you should reserve it as 443 435 well. You do not need to reserve the kernel image itself. The map 444 436 should be 64-bit aligned. ··· 493 485 494 486 So the typical layout of a DT block (though the various parts don't 495 487 need to be in that order) looks like this (addresses go from top to 496 - bottom): 488 + bottom):: 497 489 498 490 499 491 ------------------------------ ··· 519 511 | 520 512 --- (base + totalsize) 521 513 522 - (*) The alignment gaps are not necessarily present; their presence 523 - and size are dependent on the various alignment requirements of 524 - the individual data blocks. 514 + (*) The alignment gaps are not necessarily present; their presence 515 + and size are dependent on the various alignment requirements of 516 + the individual data blocks. 525 517 526 518 527 519 2) Device tree generalities ··· 608 600 you a idea of what a device-tree looks like. I have purposefully kept 609 601 the "name" and "linux,phandle" properties which aren't necessary in 610 602 order to give you a better idea of what the tree looks like in 611 - practice. 603 + practice:: 612 604 613 605 / o device-tree 614 606 |- name = "device-tree" ··· 658 650 659 651 660 652 3) Device tree "structure" block 653 + -------------------------------- 661 654 662 655 The structure of the device tree is a linearized tree structure. The 663 656 "OF_DT_BEGIN_NODE" token starts a new node, and the "OF_DT_END_NODE" ··· 675 666 root node) 676 667 * [align gap to next 4 bytes boundary] 677 668 * for each property: 669 + 678 670 * token OF_DT_PROP (that is 0x00000003) 679 671 * 32-bit value of property value size in bytes (or 0 if no 680 672 value) 681 673 * 32-bit value of offset in string block of property name 682 674 * property value data if any 683 675 * [align gap to next 4 bytes boundary] 676 + 684 677 * [child nodes if any] 685 678 * token OF_DT_END_NODE (that is 0x00000002) 686 679 ··· 699 688 constraint. 700 689 701 690 4) Device tree "strings" block 691 + ------------------------------ 702 692 703 693 In order to save space, property names, which are generally redundant, 704 694 are stored separately in the "strings" block. This block is simply the ··· 712 700 III - Required content of the device tree 713 701 ========================================= 714 702 715 - WARNING: All "linux,*" properties defined in this document apply only 716 - to a flattened device-tree. If your platform uses a real 717 - implementation of Open Firmware or an implementation compatible with 718 - the Open Firmware client interface, those properties will be created 719 - by the trampoline code in the kernel's prom_init() file. For example, 720 - that's where you'll have to add code to detect your board model and 721 - set the platform number. However, when using the flattened device-tree 722 - entry point, there is no prom_init() pass, and thus you have to 723 - provide those properties yourself. 703 + .. Warning:: 704 + 705 + All ``linux,*`` properties defined in this document apply only 706 + to a flattened device-tree. If your platform uses a real 707 + implementation of Open Firmware or an implementation compatible with 708 + the Open Firmware client interface, those properties will be created 709 + by the trampoline code in the kernel's prom_init() file. For example, 710 + that's where you'll have to add code to detect your board model and 711 + set the platform number. However, when using the flattened device-tree 712 + entry point, there is no prom_init() pass, and thus you have to 713 + provide those properties yourself. 724 714 725 715 726 716 1) Note about cells and address representation ··· 783 769 "ranges" property is missing at a given level, it's assumed that 784 770 translation isn't possible, i.e., the registers are not visible on the 785 771 parent bus. The format of the "ranges" property for a bus is a list 786 - of: 772 + of:: 787 773 788 774 bus address, parent bus address, size 789 775 ··· 891 877 892 878 This node is the parent of all individual CPU nodes. It doesn't 893 879 have any specific requirements, though it's generally good practice 894 - to have at least: 880 + to have at least:: 895 881 896 882 #address-cells = <00000001> 897 883 #size-cells = <00000000> ··· 901 887 that format when reading the "reg" properties of a CPU node, see 902 888 below 903 889 904 - c) The /cpus/* nodes 890 + c) The ``/cpus/*`` nodes 905 891 906 892 So under /cpus, you are supposed to create a node for every CPU on 907 893 the machine. There is no specific restriction on the name of the ··· 917 903 - reg : This is the physical CPU number, it's a single 32-bit cell 918 904 and is also used as-is as the unit number for constructing the 919 905 unit name in the full path. For example, with 2 CPUs, you would 920 - have the full path: 906 + have the full path:: 907 + 921 908 /cpus/PowerPC,970FX@0 922 909 /cpus/PowerPC,970FX@1 910 + 923 911 (unit addresses do not require leading zeroes) 924 - - d-cache-block-size : one cell, L1 data cache block size in bytes (*) 912 + - d-cache-block-size : one cell, L1 data cache block size in bytes [#]_ 925 913 - i-cache-block-size : one cell, L1 instruction cache block size in 926 914 bytes 927 915 - d-cache-size : one cell, size of L1 data cache in bytes 928 916 - i-cache-size : one cell, size of L1 instruction cache in bytes 929 917 930 - (*) The cache "block" size is the size on which the cache management 931 - instructions operate. Historically, this document used the cache 932 - "line" size here which is incorrect. The kernel will prefer the cache 933 - block size and will fallback to cache line size for backward 934 - compatibility. 918 + .. [#] The cache "block" size is the size on which the cache management 919 + instructions operate. Historically, this document used the cache 920 + "line" size here which is incorrect. The kernel will prefer the cache 921 + block size and will fallback to cache line size for backward 922 + compatibility. 935 923 936 924 Recommended properties: 937 925 ··· 979 963 #address-cells and #size-cells of the root node. For example, 980 964 with both of these properties being 2 like in the example given 981 965 earlier, a 970 based machine with 6Gb of RAM could typically 982 - have a "reg" property here that looks like: 966 + have a "reg" property here that looks like:: 983 967 984 - 00000000 00000000 00000000 80000000 985 - 00000001 00000000 00000001 00000000 968 + 00000000 00000000 00000000 80000000 969 + 00000001 00000000 00000001 00000000 986 970 987 971 That is a range starting at 0 of 0x80000000 bytes and a range 988 972 starting at 0x100000000 and of 0x100000000 bytes. You can see ··· 1063 1047 See 1) above for more details on defining #address-cells. 1064 1048 - #size-cells : Size representation for "soc" devices 1065 1049 - #interrupt-cells : Defines the width of cells used to represent 1066 - interrupts. Typically this value is <2>, which includes a 1067 - 32-bit number that represents the interrupt number, and a 1068 - 32-bit number that represents the interrupt sense and level. 1069 - This field is only needed if the SOC contains an interrupt 1070 - controller. 1050 + interrupts. Typically this value is <2>, which includes a 1051 + 32-bit number that represents the interrupt number, and a 1052 + 32-bit number that represents the interrupt sense and level. 1053 + This field is only needed if the SOC contains an interrupt 1054 + controller. 1071 1055 1072 1056 The SOC node may contain child nodes for each SOC device that the 1073 1057 platform uses. Nodes should not be created for devices which exist 1074 1058 on the SOC but are not used by a particular platform. See chapter VI 1075 1059 for more information on how to specify devices that are part of a SOC. 1076 1060 1077 - Example SOC node for the MPC8540: 1061 + Example SOC node for the MPC8540:: 1078 1062 1079 1063 soc8540@e0000000 { 1080 1064 #address-cells = <1>; ··· 1095 1079 dtc source code can be found at 1096 1080 <http://git.jdl.com/gitweb/?p=dtc.git> 1097 1081 1098 - WARNING: This version is still in early development stage; the 1099 - resulting device-tree "blobs" have not yet been validated with the 1100 - kernel. The current generated block lacks a useful reserve map (it will 1101 - be fixed to generate an empty one, it's up to the bootloader to fill 1102 - it up) among others. The error handling needs work, bugs are lurking, 1103 - etc... 1082 + .. Warning:: 1083 + 1084 + This version is still in early development stage; the 1085 + resulting device-tree "blobs" have not yet been validated with the 1086 + kernel. The current generated block lacks a useful reserve map (it will 1087 + be fixed to generate an empty one, it's up to the bootloader to fill 1088 + it up) among others. The error handling needs work, bugs are lurking, 1089 + etc... 1104 1090 1105 1091 dtc basically takes a device-tree in a given format and outputs a 1106 1092 device-tree in another format. The currently supported formats are: 1107 1093 1108 - Input formats: 1109 - ------------- 1094 + Input formats 1095 + ------------- 1110 1096 1111 1097 - "dtb": "blob" format, that is a flattened device-tree block 1112 1098 with 1113 - header all in a binary blob. 1099 + header all in a binary blob. 1114 1100 - "dts": "source" format. This is a text file containing a 1115 1101 "source" for a device-tree. The format is defined later in this 1116 - chapter. 1102 + chapter. 1117 1103 - "fs" format. This is a representation equivalent to the 1118 - output of /proc/device-tree, that is nodes are directories and 1119 - properties are files 1104 + output of /proc/device-tree, that is nodes are directories and 1105 + properties are files 1120 1106 1121 - Output formats: 1122 - --------------- 1107 + Output formats 1108 + -------------- 1123 1109 1124 1110 - "dtb": "blob" format 1125 1111 - "dts": "source" format ··· 1131 1113 assembly file exports some symbols that can be used. 1132 1114 1133 1115 1134 - The syntax of the dtc tool is 1116 + The syntax of the dtc tool is:: 1135 1117 1136 1118 dtc [-I <input-format>] [-O <output-format>] 1137 1119 [-o output-filename] [-V output_version] input_filename ··· 1145 1127 uniqueness of linux, phandle properties, validity of strings, etc... 1146 1128 1147 1129 The format of the .dts "source" file is "C" like, supports C and C++ 1148 - style comments. 1130 + style comments:: 1149 1131 1150 - / { 1151 - } 1132 + / { 1133 + } 1152 1134 1153 1135 The above is the "device-tree" definition. It's the only statement 1154 1136 supported currently at the toplevel. 1155 1137 1156 - / { 1157 - property1 = "string_value"; /* define a property containing a 0 1158 - * terminated string 1159 - */ 1138 + :: 1160 1139 1161 - property2 = <0x1234abcd>; /* define a property containing a 1162 - * numerical 32-bit value (hexadecimal) 1163 - */ 1140 + / { 1141 + property1 = "string_value"; /* define a property containing a 0 1142 + * terminated string 1143 + */ 1164 1144 1165 - property3 = <0x12345678 0x12345678 0xdeadbeef>; 1166 - /* define a property containing 3 1167 - * numerical 32-bit values (cells) in 1168 - * hexadecimal 1169 - */ 1170 - property4 = [0x0a 0x0b 0x0c 0x0d 0xde 0xea 0xad 0xbe 0xef]; 1171 - /* define a property whose content is 1172 - * an arbitrary array of bytes 1173 - */ 1145 + property2 = <0x1234abcd>; /* define a property containing a 1146 + * numerical 32-bit value (hexadecimal) 1147 + */ 1174 1148 1175 - childnode@address { /* define a child node named "childnode" 1176 - * whose unit name is "childnode at 1177 - * address" 1178 - */ 1149 + property3 = <0x12345678 0x12345678 0xdeadbeef>; 1150 + /* define a property containing 3 1151 + * numerical 32-bit values (cells) in 1152 + * hexadecimal 1153 + */ 1154 + property4 = [0x0a 0x0b 0x0c 0x0d 0xde 0xea 0xad 0xbe 0xef]; 1155 + /* define a property whose content is 1156 + * an arbitrary array of bytes 1157 + */ 1179 1158 1180 - childprop = "hello\n"; /* define a property "childprop" of 1181 - * childnode (in this case, a string) 1182 - */ 1183 - }; 1184 - }; 1159 + childnode@address { /* define a child node named "childnode" 1160 + * whose unit name is "childnode at 1161 + * address" 1162 + */ 1163 + 1164 + childprop = "hello\n"; /* define a property "childprop" of 1165 + * childnode (in this case, a string) 1166 + */ 1167 + }; 1168 + }; 1185 1169 1186 1170 Nodes can contain other nodes etc... thus defining the hierarchical 1187 1171 structure of the tree. ··· 1342 1322 1343 1323 If the interrupt-parent property is not defined for a node, its 1344 1324 interrupt parent is assumed to be an ancestor in the node's 1345 - _device tree_ hierarchy. 1325 + *device tree* hierarchy. 1346 1326 1347 1327 3) OpenPIC Interrupt Controllers 1348 1328 -------------------------------- ··· 1354 1334 1355 1335 Sense and level information should be encoded as follows: 1356 1336 1357 - 0 = low to high edge sensitive type enabled 1358 - 1 = active low level sensitive type enabled 1359 - 2 = active high level sensitive type enabled 1360 - 3 = high to low edge sensitive type enabled 1337 + == ======================================== 1338 + 0 low to high edge sensitive type enabled 1339 + 1 active low level sensitive type enabled 1340 + 2 active high level sensitive type enabled 1341 + 3 high to low edge sensitive type enabled 1342 + == ======================================== 1361 1343 1362 1344 4) ISA Interrupt Controllers 1363 1345 ---------------------------- ··· 1372 1350 ISA PIC interrupt controllers should adhere to the ISA PIC 1373 1351 encodings listed below: 1374 1352 1375 - 0 = active low level sensitive type enabled 1376 - 1 = active high level sensitive type enabled 1377 - 2 = high to low edge sensitive type enabled 1378 - 3 = low to high edge sensitive type enabled 1353 + == ======================================== 1354 + 0 active low level sensitive type enabled 1355 + 1 active high level sensitive type enabled 1356 + 2 high to low edge sensitive type enabled 1357 + 3 low to high edge sensitive type enabled 1358 + == ======================================== 1379 1359 1380 1360 VIII - Specifying Device Power Management Information (sleep property) 1381 - =================================================================== 1361 + ====================================================================== 1382 1362 1383 1363 Devices on SOCs often have mechanisms for placing devices into low-power 1384 1364 states that are decoupled from the devices' own register blocks. Sometimes, ··· 1411 1387 sleep-map should wait until its necessity is demonstrated). 1412 1388 1413 1389 IX - Specifying dma bus information 1390 + =================================== 1414 1391 1415 1392 Some devices may have DMA memory range shifted relatively to the beginning of 1416 1393 RAM, or even placed outside of kernel RAM. For example, the Keystone 2 SoC ··· 1429 1404 for identifying devices supported coherent DMA operations in DT. 1430 1405 1431 1406 * DMA Bus master 1407 + 1432 1408 Optional property: 1409 + 1433 1410 - dma-ranges: <prop-encoded-array> encoded as arbitrary number of triplets of 1434 - (child-bus-address, parent-bus-address, length). Each triplet specified 1435 - describes a contiguous DMA address range. 1436 - The dma-ranges property is used to describe the direct memory access (DMA) 1437 - structure of a memory-mapped bus whose device tree parent can be accessed 1438 - from DMA operations originating from the bus. It provides a means of 1439 - defining a mapping or translation between the physical address space of 1440 - the bus and the physical address space of the parent of the bus. 1441 - (for more information see the Devicetree Specification) 1411 + (child-bus-address, parent-bus-address, length). Each triplet specified 1412 + describes a contiguous DMA address range. 1413 + The dma-ranges property is used to describe the direct memory access (DMA) 1414 + structure of a memory-mapped bus whose device tree parent can be accessed 1415 + from DMA operations originating from the bus. It provides a means of 1416 + defining a mapping or translation between the physical address space of 1417 + the bus and the physical address space of the parent of the bus. 1418 + (for more information see the Devicetree Specification) 1442 1419 1443 1420 * DMA Bus child 1421 + 1444 1422 Optional property: 1423 + 1445 1424 - dma-ranges: <empty> value. if present - It means that DMA addresses 1446 - translation has to be enabled for this device. 1425 + translation has to be enabled for this device. 1447 1426 - dma-coherent: Present if dma operations are coherent 1448 1427 1449 - Example: 1450 - soc { 1428 + Example:: 1429 + 1430 + soc { 1451 1431 compatible = "ti,keystone","simple-bus"; 1452 1432 ranges = <0x0 0x0 0x0 0xc0000000>; 1453 1433 dma-ranges = <0x80000000 0x8 0x00000000 0x80000000>; ··· 1465 1435 [...] 1466 1436 dma-coherent; 1467 1437 }; 1468 - }; 1438 + }; 1469 1439 1470 1440 Appendix A - Sample SOC node for MPC8540 1471 1441 ======================================== 1442 + 1443 + :: 1472 1444 1473 1445 soc@e0000000 { 1474 1446 #address-cells = <1>;

+1

Documentation/devicetree/index.rst

··· 15 15 overlay-notes 16 16 17 17 bindings/index 18 + booting-without-of

+3 -2

Documentation/driver-api/connector.rst

··· 26 26 easier way:: 27 27 28 28 int cn_add_callback(struct cb_id *id, char *name, void (*callback) (struct cn_msg *, struct netlink_skb_parms *)); 29 - void cn_netlink_send_multi(struct cn_msg *msg, u16 len, u32 portid, u32 __group, int gfp_mask); 29 + void cn_netlink_send_mult(struct cn_msg *msg, u16 len, u32 portid, u32 __group, int gfp_mask); 30 30 void cn_netlink_send(struct cn_msg *msg, u32 portid, u32 __group, int gfp_mask); 31 31 32 32 struct cb_id ··· 48 48 __u32 seq; 49 49 __u32 ack; 50 50 51 - __u32 len; /* Length of the following data */ 51 + __u16 len; /* Length of the following data */ 52 + __u16 flags; 52 53 __u8 data[0]; 53 54 }; 54 55

+11 -11

Documentation/driver-api/device-io.rst

··· 36 36 37 37 This address should not be used directly. Instead, to get an address 38 38 suitable for passing to the accessor functions described below, you 39 - should call :c:func:`ioremap()`. An address suitable for accessing 39 + should call ioremap(). An address suitable for accessing 40 40 the device will be returned to you. 41 41 42 42 After you've finished using the device (say, in your module's exit 43 - routine), call :c:func:`iounmap()` in order to return the address 43 + routine), call iounmap() in order to return the address 44 44 space to the kernel. Most architectures allocate new address space each 45 - time you call :c:func:`ioremap()`, and they can run out unless you 46 - call :c:func:`iounmap()`. 45 + time you call ioremap(), and they can run out unless you 46 + call iounmap(). 47 47 48 48 Accessing the device 49 49 -------------------- ··· 60 60 writeb(), writew(), writel() and writeq(). 61 61 62 62 Some devices (such as framebuffers) would like to use larger transfers than 63 - 8 bytes at a time. For these devices, the :c:func:`memcpy_toio()`, 64 - :c:func:`memcpy_fromio()` and :c:func:`memset_io()` functions are 63 + 8 bytes at a time. For these devices, the memcpy_toio(), 64 + memcpy_fromio() and memset_io() functions are 65 65 provided. Do not use memset or memcpy on IO addresses; they are not 66 66 guaranteed to copy data in order. 67 67 ··· 135 135 136 136 Accesses to this space are provided through a set of functions which 137 137 allow 8-bit, 16-bit and 32-bit accesses; also known as byte, word and 138 - long. These functions are :c:func:`inb()`, :c:func:`inw()`, 139 - :c:func:`inl()`, :c:func:`outb()`, :c:func:`outw()` and 140 - :c:func:`outl()`. 138 + long. These functions are inb(), inw(), 139 + inl(), outb(), outw() and 140 + outl(). 141 141 142 142 Some variants are provided for these functions. Some devices require 143 143 that accesses to their ports are slowed down. This functionality is 144 144 provided by appending a ``_p`` to the end of the function. 145 - There are also equivalents to memcpy. The :c:func:`ins()` and 146 - :c:func:`outs()` functions copy bytes, words or longs to the given 145 + There are also equivalents to memcpy. The ins() and 146 + outs() functions copy bytes, words or longs to the given 147 147 port. 148 148 149 149 Public Functions Provided

+1 -1

Documentation/driver-api/dmaengine/client.rst

··· 5 5 Vinod Koul <vinod dot koul at intel.com> 6 6 7 7 .. note:: For DMA Engine usage in async_tx please see: 8 - ``Documentation/crypto/async-tx-api.txt`` 8 + ``Documentation/crypto/async-tx-api.rst`` 9 9 10 10 11 11 Below is a guide to device driver writers on how to use the Slave-DMA API of the

+1 -1

Documentation/driver-api/dmaengine/provider.rst

··· 95 95 ensure that it stayed compatible. 96 96 97 97 For more information on the Async TX API, please look the relevant 98 - documentation file in Documentation/crypto/async-tx-api.txt. 98 + documentation file in Documentation/crypto/async-tx-api.rst. 99 99 100 100 DMAEngine APIs 101 101 ==============

-2

Documentation/driver-api/driver-model/driver.rst

··· 228 228 not restricted to that. Use it whenever it makes sense to take an action after 229 229 all the consumers of a device have probed:: 230 230 231 - :: 232 - 233 231 int (*remove) (struct device *dev); 234 232 235 233 remove is called to unbind a driver from a device. This may be

+2 -2

Documentation/driver-api/early-userspace/early_userspace_support.rst

··· 92 92 https://www.kernel.org/pub/linux/libs/klibc/ 93 93 94 94 For active users, you are better off using the klibc git 95 - repository, at http://git.kernel.org/?p=libs/klibc/klibc.git 95 + repository, at https://git.kernel.org/?p=libs/klibc/klibc.git 96 96 97 97 The standalone klibc distribution currently provides three components, 98 98 in addition to the klibc library: ··· 122 122 custom initramfs images that meet your needs exactly. 123 123 124 124 For questions and help, you can sign up for the early userspace 125 - mailing list at http://www.zytor.com/mailman/listinfo/klibc 125 + mailing list at https://www.zytor.com/mailman/listinfo/klibc 126 126 127 127 How does it work? 128 128 =================

+1 -1

Documentation/driver-api/i3c/protocol.rst

··· 14 14 This document is just a brief introduction to the I3C protocol and the concepts 15 15 it brings to the table. If you need more information, please refer to the MIPI 16 16 I3C specification (can be downloaded here 17 - http://resources.mipi.org/mipi-i3c-v1-download). 17 + https://resources.mipi.org/mipi-i3c-v1-download). 18 18 19 19 Introduction 20 20 ============

+1

Documentation/driver-api/index.rst

··· 48 48 scsi 49 49 libata 50 50 target 51 + mailbox 51 52 mtdnand 52 53 miscellaneous 53 54 mei/index

+1 -1

Documentation/driver-api/ipmi.rst

··· 18 18 19 19 This document describes how to use the IPMI driver for Linux. If you 20 20 are not familiar with IPMI itself, see the web site at 21 - http://www.intel.com/design/servers/ipmi/index.htm. IPMI is a big 21 + https://www.intel.com/design/servers/ipmi/index.htm. IPMI is a big 22 22 subject and I can't cover it all here! 23 23 24 24 Configuration

+1 -1

Documentation/driver-api/memory-devices/ti-gpmc.rst

··· 14 14 * Pseudo-SRAM devices 15 15 16 16 GPMC is found on Texas Instruments SoC's (OMAP based) 17 - IP details: http://www.ti.com/lit/pdf/spruh73 section 7.1 17 + IP details: https://www.ti.com/lit/pdf/spruh73 section 7.1 18 18 19 19 20 20 GPMC generic timing calculation:

+1 -1

Documentation/driver-api/mmc/mmc-tools.rst

··· 5 5 There is one MMC test tools called mmc-utils, which is maintained by Chris Ball, 6 6 you can find it at the below public git repository: 7 7 8 - http://git.kernel.org/cgit/linux/kernel/git/cjb/mmc-utils.git/ 8 + https://git.kernel.org/cgit/linux/kernel/git/cjb/mmc-utils.git/ 9 9 10 10 Functions 11 11 =========

+1 -1

Documentation/driver-api/ntb.rst

··· 9 9 scratchpad and message registers. Scratchpad registers are read-and-writable 10 10 registers that are accessible from either side of the device, so that peers can 11 11 exchange a small amount of information at a fixed address. Message registers can 12 - be utilized for the same purpose. Additionally they are provided with with 12 + be utilized for the same purpose. Additionally they are provided with 13 13 special status bits to make sure the information isn't rewritten by another 14 14 peer. Doorbell registers provide a way for peers to send interrupt events. 15 15 Memory windows allow translated read and write access to the peer memory.

+7 -7

Documentation/driver-api/nvdimm/nvdimm.rst

··· 73 73 process address space. 74 74 75 75 DSM: 76 - Device Specific Method: ACPI method to to control specific 76 + Device Specific Method: ACPI method to control specific 77 77 device - in this case the firmware. 78 78 79 79 DCR: ··· 113 113 -------------------- 114 114 115 115 ACPI 6: 116 - http://www.uefi.org/sites/default/files/resources/ACPI_6.0.pdf 116 + https://www.uefi.org/sites/default/files/resources/ACPI_6.0.pdf 117 117 NVDIMM Namespace: 118 - http://pmem.io/documents/NVDIMM_Namespace_Spec.pdf 118 + https://pmem.io/documents/NVDIMM_Namespace_Spec.pdf 119 119 DSM Interface Example: 120 - http://pmem.io/documents/NVDIMM_DSM_Interface_Example.pdf 120 + https://pmem.io/documents/NVDIMM_DSM_Interface_Example.pdf 121 121 Driver Writer's Guide: 122 - http://pmem.io/documents/NVDIMM_Driver_Writers_Guide.pdf 122 + https://pmem.io/documents/NVDIMM_Driver_Writers_Guide.pdf 123 123 124 124 Git Trees 125 125 --------- ··· 778 778 779 779 2. The term originated to describe the sub-devices that can be created 780 780 within a NVME controller (see the nvme specification: 781 - http://www.nvmexpress.org/specifications/), and NFIT namespaces are 781 + https://www.nvmexpress.org/specifications/), and NFIT namespaces are 782 782 meant to parallel the capabilities and configurability of 783 783 NVME-namespaces. 784 784 ··· 786 786 LIBNVDIMM/LIBNDCTL: Block Translation Table "btt" 787 787 ------------------------------------------------- 788 788 789 - A BTT (design document: http://pmem.io/2014/09/23/btt.html) is a stacked 789 + A BTT (design document: https://pmem.io/2014/09/23/btt.html) is a stacked 790 790 block device driver that fronts either the whole block device or a 791 791 partition of a block device emitted by either a PMEM or BLK NAMESPACE. 792 792

+1 -1

Documentation/driver-api/nvdimm/security.rst

··· 138 138 This command is only available when the master security is enabled, indicated 139 139 by the extended security status. 140 140 141 - [1]: http://pmem.io/documents/NVDIMM_DSM_Interface-V1.8.pdf 141 + [1]: https://pmem.io/documents/NVDIMM_DSM_Interface-V1.8.pdf 142 142 143 143 [2]: http://www.t13.org/documents/UploadedDocuments/docs2006/e05179r4-ACS-SecurityClarifications.pdf

+2 -2

Documentation/driver-api/rapidio/rapidio.rst

··· 356 356 http://www.rapidio.org/education/technology_comparisons/ 357 357 358 358 [3] RapidIO support for Linux. 359 - http://lwn.net/Articles/139118/ 359 + https://lwn.net/Articles/139118/ 360 360 361 361 [4] Matt Porter. RapidIO for Linux. Ottawa Linux Symposium, 2005 362 - http://www.kernel.org/doc/ols/2005/ols2005v2-pages-43-56.pdf 362 + https://www.kernel.org/doc/ols/2005/ols2005v2-pages-43-56.pdf

+8 -6

Documentation/driver-api/thermal/cpu-idle-cooling.rst

··· 1 + .. SPDX-License-Identifier: GPL-2.0 2 + 1 3 ================ 2 4 CPU Idle Cooling 3 5 ================ ··· 50 48 dynamic leakage for this period (modulo the energy needed to enter 51 49 this state). So the sustainable power with idle cycles has a linear 52 50 relation with the OPP’s sustainable power and can be computed with a 53 - coefficient similar to: 51 + coefficient similar to:: 54 52 55 53 Power(IdleCycle) = Coef x Power(OPP) 56 54 ··· 141 139 -------------------- 142 140 143 141 When we reach the thermal trip point, we have to sustain a specified 144 - power for a specific temperature but at this time we consume: 142 + power for a specific temperature but at this time we consume:: 145 143 146 144 Power = Capacitance x Voltage^2 x Frequency x Utilisation 147 145 ··· 150 148 fixed value, ‘Voltage’ and the ‘Frequency’ are fixed artificially 151 149 because we don’t want to change the OPP. We can group the 152 150 ‘Capacitance’ and the ‘Utilisation’ into a single term which is the 153 - ‘Dynamic Power Coefficient (Cdyn)’ Simplifying the above, we have: 151 + ‘Dynamic Power Coefficient (Cdyn)’ Simplifying the above, we have:: 154 152 155 153 Pdyn = Cdyn x Voltage^2 x Frequency 156 154 ··· 159 157 tree. So with the idle injection mechanism, we want an average power 160 158 (Ptarget) resulting in an amount of time running at full power on a 161 159 specific OPP and idle another amount of time. That could be put in a 162 - equation: 160 + equation:: 163 161 164 162 P(opp)target = ((Trunning x (P(opp)running) + (Tidle x P(opp)idle)) / 165 163 (Trunning + Tidle) ··· 170 168 171 169 At this point if we know the running period for the CPU, that gives us 172 170 the idle injection we need. Alternatively if we have the idle 173 - injection duration, we can compute the running duration with: 171 + injection duration, we can compute the running duration with:: 174 172 175 173 Trunning = Tidle / ((P(opp)running / P(opp)target) - 1) 176 174 ··· 193 191 target residency, otherwise we end up consuming more energy and 194 192 potentially invert the mitigation effect 195 193 196 - So the final equation is: 194 + So the final equation is:: 197 195 198 196 Trunning = (Tidle - Twakeup ) x 199 197 (((P(opp)dyn + P(opp)static ) - P(opp)target) / P(opp)target )

+1 -1

Documentation/driver-api/thermal/nouveau_thermal.rst

··· 93 93 inquiries, please ping mupuf on IRC (#nouveau, freenode). 94 94 95 95 Bug reports should be filled on Freedesktop's bug tracker. Please follow 96 - http://nouveau.freedesktop.org/wiki/Bugs 96 + https://nouveau.freedesktop.org/wiki/Bugs

+3 -3

Documentation/driver-api/usb/dma.rst

··· 10 10 11 11 The big picture is that USB drivers can continue to ignore most DMA issues, 12 12 though they still must provide DMA-ready buffers (see 13 - ``Documentation/DMA-API-HOWTO.txt``). That's how they've worked through 13 + :doc:`/core-api/dma-api-howto`). That's how they've worked through 14 14 the 2.4 (and earlier) kernels, or they can now be DMA-aware. 15 15 16 16 DMA-aware usb drivers: ··· 60 60 force a consistent memory access ordering by using memory barriers. It's 61 61 not using a streaming DMA mapping, so it's good for small transfers on 62 62 systems where the I/O would otherwise thrash an IOMMU mapping. (See 63 - ``Documentation/DMA-API-HOWTO.txt`` for definitions of "coherent" and 63 + :doc:`/core-api/dma-api-howto` for definitions of "coherent" and 64 64 "streaming" DMA mappings.) 65 65 66 66 Asking for 1/Nth of a page (as well as asking for N pages) is reasonably ··· 91 91 Existing buffers aren't usable for DMA without first being mapped into the 92 92 DMA address space of the device. However, most buffers passed to your 93 93 driver can safely be used with such DMA mapping. (See the first section 94 - of Documentation/DMA-API-HOWTO.txt, titled "What memory is DMA-able?") 94 + of :doc:`/core-api/dma-api-howto`, titled "What memory is DMA-able?") 95 95 96 96 - When you're using scatterlists, you can map everything at once. On some 97 97 systems, this kicks in an IOMMU and turns the scatterlists into single

+2 -2

Documentation/driver-api/usb/writing_usb_driver.rst

··· 318 318 https://lore.kernel.org/linux-usb/ 319 319 320 320 Programming Guide for Linux USB Device Drivers: 321 - http://lmu.web.psi.ch/docu/manuals/software_manuals/linux_sl/usb_linux_programming_guide.pdf 321 + https://lmu.web.psi.ch/docu/manuals/software_manuals/linux_sl/usb_linux_programming_guide.pdf 322 322 323 - USB Home Page: http://www.usb.org 323 + USB Home Page: https://www.usb.org

+1 -1

Documentation/fb/modedb.rst

··· 152 152 video=<driver>:<xres>x<yres>[-<bpp>][@refresh] 153 153 154 154 where <driver> is a name from the table below. Valid default modes can be 155 - found in linux/drivers/video/modedb.c. Check your driver's documentation. 155 + found in drivers/video/fbdev/core/modedb.c. Check your driver's documentation. 156 156 There may be more modes:: 157 157 158 158 Drivers that support modedb boot options

+33

Documentation/features/debug/kcov/arch-support.txt

··· 1 + # 2 + # Feature name: kcov 3 + # Kconfig: ARCH_HAS_KCOV 4 + # description: arch supports kcov for coverage-guided fuzzing 5 + # 6 + ----------------------- 7 + | arch |status| 8 + ----------------------- 9 + | alpha: | TODO | 10 + | arc: | TODO | 11 + | arm: | ok | 12 + | arm64: | ok | 13 + | c6x: | TODO | 14 + | csky: | TODO | 15 + | h8300: | TODO | 16 + | hexagon: | TODO | 17 + | ia64: | TODO | 18 + | m68k: | TODO | 19 + | microblaze: | TODO | 20 + | mips: | ok | 21 + | nds32: | TODO | 22 + | nios2: | TODO | 23 + | openrisc: | TODO | 24 + | parisc: | TODO | 25 + | powerpc: | ok | 26 + | riscv: | ok | 27 + | s390: | ok | 28 + | sh: | TODO | 29 + | sparc: | TODO | 30 + | um: | ok | 31 + | x86: | ok | 32 + | xtensa: | TODO | 33 + -----------------------

+1 -1

Documentation/features/debug/kgdb/arch-support.txt

··· 23 23 | openrisc: | TODO | 24 24 | parisc: | ok | 25 25 | powerpc: | ok | 26 - | riscv: | TODO | 26 + | riscv: | ok | 27 27 | s390: | TODO | 28 28 | sh: | ok | 29 29 | sparc: | ok |

+33

Documentation/features/debug/kmemleak/arch-support.txt

··· 1 + # 2 + # Feature name: kmemleak 3 + # Kconfig: HAVE_DEBUG_KMEMLEAK 4 + # description: arch supports the kernel memory leak detector 5 + # 6 + ----------------------- 7 + | arch |status| 8 + ----------------------- 9 + | alpha: | TODO | 10 + | arc: | ok | 11 + | arm: | ok | 12 + | arm64: | ok | 13 + | c6x: | TODO | 14 + | csky: | TODO | 15 + | h8300: | TODO | 16 + | hexagon: | TODO | 17 + | ia64: | TODO | 18 + | m68k: | TODO | 19 + | microblaze: | ok | 20 + | mips: | ok | 21 + | nds32: | ok | 22 + | nios2: | TODO | 23 + | openrisc: | TODO | 24 + | parisc: | TODO | 25 + | powerpc: | ok | 26 + | riscv: | TODO | 27 + | s390: | ok | 28 + | sh: | ok | 29 + | sparc: | ok | 30 + | um: | ok | 31 + | x86: | ok | 32 + | xtensa: | ok | 33 + -----------------------

+1 -1

Documentation/filesystems/9p.rst

··· 18 18 The best detailed explanation of the Linux implementation and applications of 19 19 the 9p client is available in the form of a USENIX paper: 20 20 21 - http://www.usenix.org/events/usenix05/tech/freenix/hensbergen.html 21 + https://www.usenix.org/events/usenix05/tech/freenix/hensbergen.html 22 22 23 23 Other applications are described in the following papers: 24 24

+1 -1

Documentation/filesystems/afs.rst

··· 190 190 Secure operations are initiated by acquiring a key using the klog program. A 191 191 very primitive klog program is available at: 192 192 193 - http://people.redhat.com/~dhowells/rxrpc/klog.c 193 + https://people.redhat.com/~dhowells/rxrpc/klog.c 194 194 195 195 This should be compiled by:: 196 196

+3 -3

Documentation/filesystems/autofs-mount-control.rst

··· 391 391 set to an autofs mount type. The call returns 1 if this is a mount point 392 392 and sets out.devid field to the device number of the mount and out.magic 393 393 field to the relevant super block magic number (described below) or 0 if 394 - it isn't a mountpoint. In both cases the the device number (as returned 394 + it isn't a mountpoint. In both cases the device number (as returned 395 395 by new_encode_dev()) is returned in out.devid field. 396 396 397 397 If supplied with a file descriptor we're looking for a specific mount, ··· 399 399 the descriptor corresponds to is considered a mountpoint if it is itself 400 400 a mountpoint or contains a mount, such as a multi-mount without a root 401 401 mount. In this case we return 1 if the descriptor corresponds to a mount 402 - point and and also returns the super magic of the covering mount if there 402 + point and also returns the super magic of the covering mount if there 403 403 is one or 0 if it isn't a mountpoint. 404 404 405 405 If a path is supplied (and the ioctlfd field is set to -1) then the path 406 406 is looked up and is checked to see if it is the root of a mount. If a 407 407 type is also given we are looking for a particular autofs mount and if 408 - a match isn't found a fail is returned. If the the located path is the 408 + a match isn't found a fail is returned. If the located path is the 409 409 root of a mount 1 is returned along with the super magic of the mount 410 410 or 0 otherwise.

+1 -1

Documentation/filesystems/caching/cachefiles.rst

··· 348 348 349 349 There are policy source files available in: 350 350 351 - http://people.redhat.com/~dhowells/fscache/cachefilesd-0.8.tar.bz2 351 + https://people.redhat.com/~dhowells/fscache/cachefilesd-0.8.tar.bz2 352 352 353 353 and later versions. In that tarball, see the files:: 354 354

+1 -1

Documentation/filesystems/caching/operations.rst

··· 27 27 fscache_operation structs, though these are usually embedded into some other 28 28 structure. 29 29 30 - This facility is available to and expected to be be used by the cache backends, 30 + This facility is available to and expected to be used by the cache backends, 31 31 and FS-Cache will create operations and pass them off to the appropriate cache 32 32 backend for completion. 33 33

+2 -2

Documentation/filesystems/coda.rst

··· 524 524 525 525 Description 526 526 This call is made to determine the ViceFid and filetype of 527 - a directory entry. The directory entry requested carries name name 527 + a directory entry. The directory entry requested carries name 'name' 528 528 and Venus will search the directory identified by cfs_lookup_in.VFid. 529 529 The result may indicate that the name does not exist, or that 530 530 difficulty was encountered in finding it (e.g. due to disconnection). ··· 886 886 none 887 887 888 888 Description 889 - Remove the directory with name name from the directory 889 + Remove the directory with name 'name' from the directory 890 890 identified by VFid. 891 891 892 892 .. Note:: The attributes of the parent directory should be returned since

+1 -1

Documentation/filesystems/configfs.rst

··· 226 226 If an attribute is readable and provides a ->show method, that method will 227 227 be called whenever userspace asks for a read(2) on the attribute. If an 228 228 attribute is writable and provides a ->store method, that method will be 229 - be called whenever userspace asks for a write(2) on the attribute. 229 + called whenever userspace asks for a write(2) on the attribute. 230 230 231 231 struct configfs_bin_attribute 232 232 =============================

+2 -2

Documentation/filesystems/directory-locking.rst

··· 28 28 if the target already exists, lock it. If the source is a non-directory, 29 29 lock it. If we need to lock both, lock them in inode pointer order. 30 30 Then call the method. All locks are exclusive. 31 - NB: we might get away with locking the the source (and target in exchange 31 + NB: we might get away with locking the source (and target in exchange 32 32 case) shared. 33 33 34 34 5) link creation. Locking rules: ··· 56 56 * call the method. 57 57 58 58 All ->i_rwsem are taken exclusive. Again, we might get away with locking 59 - the the source (and target in exchange case) shared. 59 + the source (and target in exchange case) shared. 60 60 61 61 The rules above obviously guarantee that all directories that are going to be 62 62 read, modified or removed by method will be locked by caller.

+161 -162

Documentation/filesystems/f2fs.rst

··· 101 101 ============= 102 102 103 103 104 - ====================== ============================================================ 105 - background_gc=%s Turn on/off cleaning operations, namely garbage 106 - collection, triggered in background when I/O subsystem is 107 - idle. If background_gc=on, it will turn on the garbage 108 - collection and if background_gc=off, garbage collection 109 - will be turned off. If background_gc=sync, it will turn 110 - on synchronous garbage collection running in background. 111 - Default value for this option is on. So garbage 112 - collection is on by default. 113 - disable_roll_forward Disable the roll-forward recovery routine 114 - norecovery Disable the roll-forward recovery routine, mounted read- 115 - only (i.e., -o ro,disable_roll_forward) 116 - discard/nodiscard Enable/disable real-time discard in f2fs, if discard is 117 - enabled, f2fs will issue discard/TRIM commands when a 118 - segment is cleaned. 119 - no_heap Disable heap-style segment allocation which finds free 120 - segments for data from the beginning of main area, while 121 - for node from the end of main area. 122 - nouser_xattr Disable Extended User Attributes. Note: xattr is enabled 123 - by default if CONFIG_F2FS_FS_XATTR is selected. 124 - noacl Disable POSIX Access Control List. Note: acl is enabled 125 - by default if CONFIG_F2FS_FS_POSIX_ACL is selected. 126 - active_logs=%u Support configuring the number of active logs. In the 127 - current design, f2fs supports only 2, 4, and 6 logs. 128 - Default number is 6. 129 - disable_ext_identify Disable the extension list configured by mkfs, so f2fs 130 - does not aware of cold files such as media files. 131 - inline_xattr Enable the inline xattrs feature. 132 - noinline_xattr Disable the inline xattrs feature. 133 - inline_xattr_size=%u Support configuring inline xattr size, it depends on 134 - flexible inline xattr feature. 135 - inline_data Enable the inline data feature: New created small(<~3.4k) 136 - files can be written into inode block. 137 - inline_dentry Enable the inline dir feature: data in new created 138 - directory entries can be written into inode block. The 139 - space of inode block which is used to store inline 140 - dentries is limited to ~3.4k. 141 - noinline_dentry Disable the inline dentry feature. 142 - flush_merge Merge concurrent cache_flush commands as much as possible 143 - to eliminate redundant command issues. If the underlying 144 - device handles the cache_flush command relatively slowly, 145 - recommend to enable this option. 146 - nobarrier This option can be used if underlying storage guarantees 147 - its cached data should be written to the novolatile area. 148 - If this option is set, no cache_flush commands are issued 149 - but f2fs still guarantees the write ordering of all the 150 - data writes. 151 - fastboot This option is used when a system wants to reduce mount 152 - time as much as possible, even though normal performance 153 - can be sacrificed. 154 - extent_cache Enable an extent cache based on rb-tree, it can cache 155 - as many as extent which map between contiguous logical 156 - address and physical address per inode, resulting in 157 - increasing the cache hit ratio. Set by default. 158 - noextent_cache Disable an extent cache based on rb-tree explicitly, see 159 - the above extent_cache mount option. 160 - noinline_data Disable the inline data feature, inline data feature is 161 - enabled by default. 162 - data_flush Enable data flushing before checkpoint in order to 163 - persist data of regular and symlink. 164 - reserve_root=%d Support configuring reserved space which is used for 165 - allocation from a privileged user with specified uid or 166 - gid, unit: 4KB, the default limit is 0.2% of user blocks. 167 - resuid=%d The user ID which may use the reserved blocks. 168 - resgid=%d The group ID which may use the reserved blocks. 169 - fault_injection=%d Enable fault injection in all supported types with 170 - specified injection rate. 171 - fault_type=%d Support configuring fault injection type, should be 172 - enabled with fault_injection option, fault type value 173 - is shown below, it supports single or combined type. 104 + ======================== ============================================================ 105 + background_gc=%s Turn on/off cleaning operations, namely garbage 106 + collection, triggered in background when I/O subsystem is 107 + idle. If background_gc=on, it will turn on the garbage 108 + collection and if background_gc=off, garbage collection 109 + will be turned off. If background_gc=sync, it will turn 110 + on synchronous garbage collection running in background. 111 + Default value for this option is on. So garbage 112 + collection is on by default. 113 + disable_roll_forward Disable the roll-forward recovery routine 114 + norecovery Disable the roll-forward recovery routine, mounted read- 115 + only (i.e., -o ro,disable_roll_forward) 116 + discard/nodiscard Enable/disable real-time discard in f2fs, if discard is 117 + enabled, f2fs will issue discard/TRIM commands when a 118 + segment is cleaned. 119 + no_heap Disable heap-style segment allocation which finds free 120 + segments for data from the beginning of main area, while 121 + for node from the end of main area. 122 + nouser_xattr Disable Extended User Attributes. Note: xattr is enabled 123 + by default if CONFIG_F2FS_FS_XATTR is selected. 124 + noacl Disable POSIX Access Control List. Note: acl is enabled 125 + by default if CONFIG_F2FS_FS_POSIX_ACL is selected. 126 + active_logs=%u Support configuring the number of active logs. In the 127 + current design, f2fs supports only 2, 4, and 6 logs. 128 + Default number is 6. 129 + disable_ext_identify Disable the extension list configured by mkfs, so f2fs 130 + does not aware of cold files such as media files. 131 + inline_xattr Enable the inline xattrs feature. 132 + noinline_xattr Disable the inline xattrs feature. 133 + inline_xattr_size=%u Support configuring inline xattr size, it depends on 134 + flexible inline xattr feature. 135 + inline_data Enable the inline data feature: New created small(<~3.4k) 136 + files can be written into inode block. 137 + inline_dentry Enable the inline dir feature: data in new created 138 + directory entries can be written into inode block. The 139 + space of inode block which is used to store inline 140 + dentries is limited to ~3.4k. 141 + noinline_dentry Disable the inline dentry feature. 142 + flush_merge Merge concurrent cache_flush commands as much as possible 143 + to eliminate redundant command issues. If the underlying 144 + device handles the cache_flush command relatively slowly, 145 + recommend to enable this option. 146 + nobarrier This option can be used if underlying storage guarantees 147 + its cached data should be written to the novolatile area. 148 + If this option is set, no cache_flush commands are issued 149 + but f2fs still guarantees the write ordering of all the 150 + data writes. 151 + fastboot This option is used when a system wants to reduce mount 152 + time as much as possible, even though normal performance 153 + can be sacrificed. 154 + extent_cache Enable an extent cache based on rb-tree, it can cache 155 + as many as extent which map between contiguous logical 156 + address and physical address per inode, resulting in 157 + increasing the cache hit ratio. Set by default. 158 + noextent_cache Disable an extent cache based on rb-tree explicitly, see 159 + the above extent_cache mount option. 160 + noinline_data Disable the inline data feature, inline data feature is 161 + enabled by default. 162 + data_flush Enable data flushing before checkpoint in order to 163 + persist data of regular and symlink. 164 + reserve_root=%d Support configuring reserved space which is used for 165 + allocation from a privileged user with specified uid or 166 + gid, unit: 4KB, the default limit is 0.2% of user blocks. 167 + resuid=%d The user ID which may use the reserved blocks. 168 + resgid=%d The group ID which may use the reserved blocks. 169 + fault_injection=%d Enable fault injection in all supported types with 170 + specified injection rate. 171 + fault_type=%d Support configuring fault injection type, should be 172 + enabled with fault_injection option, fault type value 173 + is shown below, it supports single or combined type. 174 174 175 - =================== =========== 176 - Type_Name Type_Value 177 - =================== =========== 178 - FAULT_KMALLOC 0x000000001 179 - FAULT_KVMALLOC 0x000000002 180 - FAULT_PAGE_ALLOC 0x000000004 181 - FAULT_PAGE_GET 0x000000008 182 - FAULT_ALLOC_BIO 0x000000010 183 - FAULT_ALLOC_NID 0x000000020 184 - FAULT_ORPHAN 0x000000040 185 - FAULT_BLOCK 0x000000080 186 - FAULT_DIR_DEPTH 0x000000100 187 - FAULT_EVICT_INODE 0x000000200 188 - FAULT_TRUNCATE 0x000000400 189 - FAULT_READ_IO 0x000000800 190 - FAULT_CHECKPOINT 0x000001000 191 - FAULT_DISCARD 0x000002000 192 - FAULT_WRITE_IO 0x000004000 193 - =================== =========== 194 - mode=%s Control block allocation mode which supports "adaptive" 195 - and "lfs". In "lfs" mode, there should be no random 196 - writes towards main area. 197 - io_bits=%u Set the bit size of write IO requests. It should be set 198 - with "mode=lfs". 199 - usrquota Enable plain user disk quota accounting. 200 - grpquota Enable plain group disk quota accounting. 201 - prjquota Enable plain project quota accounting. 202 - usrjquota=<file> Appoint specified file and type during mount, so that quota 203 - grpjquota=<file> information can be properly updated during recovery flow, 204 - prjjquota=<file> <quota file>: must be in root directory; 205 - jqfmt=<quota type> <quota type>: [vfsold,vfsv0,vfsv1]. 206 - offusrjquota Turn off user journelled quota. 207 - offgrpjquota Turn off group journelled quota. 208 - offprjjquota Turn off project journelled quota. 209 - quota Enable plain user disk quota accounting. 210 - noquota Disable all plain disk quota option. 211 - whint_mode=%s Control which write hints are passed down to block 212 - layer. This supports "off", "user-based", and 213 - "fs-based". In "off" mode (default), f2fs does not pass 214 - down hints. In "user-based" mode, f2fs tries to pass 215 - down hints given by users. And in "fs-based" mode, f2fs 216 - passes down hints with its policy. 217 - alloc_mode=%s Adjust block allocation policy, which supports "reuse" 218 - and "default". 219 - fsync_mode=%s Control the policy of fsync. Currently supports "posix", 220 - "strict", and "nobarrier". In "posix" mode, which is 221 - default, fsync will follow POSIX semantics and does a 222 - light operation to improve the filesystem performance. 223 - In "strict" mode, fsync will be heavy and behaves in line 224 - with xfs, ext4 and btrfs, where xfstest generic/342 will 225 - pass, but the performance will regress. "nobarrier" is 226 - based on "posix", but doesn't issue flush command for 227 - non-atomic files likewise "nobarrier" mount option. 175 + =================== =========== 176 + Type_Name Type_Value 177 + =================== =========== 178 + FAULT_KMALLOC 0x000000001 179 + FAULT_KVMALLOC 0x000000002 180 + FAULT_PAGE_ALLOC 0x000000004 181 + FAULT_PAGE_GET 0x000000008 182 + FAULT_ALLOC_BIO 0x000000010 183 + FAULT_ALLOC_NID 0x000000020 184 + FAULT_ORPHAN 0x000000040 185 + FAULT_BLOCK 0x000000080 186 + FAULT_DIR_DEPTH 0x000000100 187 + FAULT_EVICT_INODE 0x000000200 188 + FAULT_TRUNCATE 0x000000400 189 + FAULT_READ_IO 0x000000800 190 + FAULT_CHECKPOINT 0x000001000 191 + FAULT_DISCARD 0x000002000 192 + FAULT_WRITE_IO 0x000004000 193 + =================== =========== 194 + mode=%s Control block allocation mode which supports "adaptive" 195 + and "lfs". In "lfs" mode, there should be no random 196 + writes towards main area. 197 + io_bits=%u Set the bit size of write IO requests. It should be set 198 + with "mode=lfs". 199 + usrquota Enable plain user disk quota accounting. 200 + grpquota Enable plain group disk quota accounting. 201 + prjquota Enable plain project quota accounting. 202 + usrjquota=<file> Appoint specified file and type during mount, so that quota 203 + grpjquota=<file> information can be properly updated during recovery flow, 204 + prjjquota=<file> <quota file>: must be in root directory; 205 + jqfmt=<quota type> <quota type>: [vfsold,vfsv0,vfsv1]. 206 + offusrjquota Turn off user journelled quota. 207 + offgrpjquota Turn off group journelled quota. 208 + offprjjquota Turn off project journelled quota. 209 + quota Enable plain user disk quota accounting. 210 + noquota Disable all plain disk quota option. 211 + whint_mode=%s Control which write hints are passed down to block 212 + layer. This supports "off", "user-based", and 213 + "fs-based". In "off" mode (default), f2fs does not pass 214 + down hints. In "user-based" mode, f2fs tries to pass 215 + down hints given by users. And in "fs-based" mode, f2fs 216 + passes down hints with its policy. 217 + alloc_mode=%s Adjust block allocation policy, which supports "reuse" 218 + and "default". 219 + fsync_mode=%s Control the policy of fsync. Currently supports "posix", 220 + "strict", and "nobarrier". In "posix" mode, which is 221 + default, fsync will follow POSIX semantics and does a 222 + light operation to improve the filesystem performance. 223 + In "strict" mode, fsync will be heavy and behaves in line 224 + with xfs, ext4 and btrfs, where xfstest generic/342 will 225 + pass, but the performance will regress. "nobarrier" is 226 + based on "posix", but doesn't issue flush command for 227 + non-atomic files likewise "nobarrier" mount option. 228 228 test_dummy_encryption 229 229 test_dummy_encryption=%s 230 - Enable dummy encryption, which provides a fake fscrypt 231 - context. The fake fscrypt context is used by xfstests. 232 - The argument may be either "v1" or "v2", in order to 233 - select the corresponding fscrypt policy version. 234 - checkpoint=%s[:%u[%]] Set to "disable" to turn off checkpointing. Set to "enable" 235 - to reenable checkpointing. Is enabled by default. While 236 - disabled, any unmounting or unexpected shutdowns will cause 237 - the filesystem contents to appear as they did when the 238 - filesystem was mounted with that option. 239 - While mounting with checkpoint=disabled, the filesystem must 240 - run garbage collection to ensure that all available space can 241 - be used. If this takes too much time, the mount may return 242 - EAGAIN. You may optionally add a value to indicate how much 243 - of the disk you would be willing to temporarily give up to 244 - avoid additional garbage collection. This can be given as a 245 - number of blocks, or as a percent. For instance, mounting 246 - with checkpoint=disable:100% would always succeed, but it may 247 - hide up to all remaining free space. The actual space that 248 - would be unusable can be viewed at /sys/fs/f2fs/<disk>/unusable 249 - This space is reclaimed once checkpoint=enable. 250 - compress_algorithm=%s Control compress algorithm, currently f2fs supports "lzo", 251 - "lz4", "zstd" and "lzo-rle" algorithm. 252 - compress_log_size=%u Support configuring compress cluster size, the size will 253 - be 4KB * (1 << %u), 16KB is minimum size, also it's 254 - default size. 255 - compress_extension=%s Support adding specified extension, so that f2fs can enable 256 - compression on those corresponding files, e.g. if all files 257 - with '.ext' has high compression rate, we can set the '.ext' 258 - on compression extension list and enable compression on 259 - these file by default rather than to enable it via ioctl. 260 - For other files, we can still enable compression via ioctl. 261 - inlinecrypt 262 - When possible, encrypt/decrypt the contents of encrypted 263 - files using the blk-crypto framework rather than 264 - filesystem-layer encryption. This allows the use of 265 - inline encryption hardware. The on-disk format is 266 - unaffected. For more details, see 267 - Documentation/block/inline-encryption.rst. 268 - ====================== ============================================================ 230 + Enable dummy encryption, which provides a fake fscrypt 231 + context. The fake fscrypt context is used by xfstests. 232 + The argument may be either "v1" or "v2", in order to 233 + select the corresponding fscrypt policy version. 234 + checkpoint=%s[:%u[%]] Set to "disable" to turn off checkpointing. Set to "enable" 235 + to reenable checkpointing. Is enabled by default. While 236 + disabled, any unmounting or unexpected shutdowns will cause 237 + the filesystem contents to appear as they did when the 238 + filesystem was mounted with that option. 239 + While mounting with checkpoint=disabled, the filesystem must 240 + run garbage collection to ensure that all available space can 241 + be used. If this takes too much time, the mount may return 242 + EAGAIN. You may optionally add a value to indicate how much 243 + of the disk you would be willing to temporarily give up to 244 + avoid additional garbage collection. This can be given as a 245 + number of blocks, or as a percent. For instance, mounting 246 + with checkpoint=disable:100% would always succeed, but it may 247 + hide up to all remaining free space. The actual space that 248 + would be unusable can be viewed at /sys/fs/f2fs/<disk>/unusable 249 + This space is reclaimed once checkpoint=enable. 250 + compress_algorithm=%s Control compress algorithm, currently f2fs supports "lzo", 251 + "lz4", "zstd" and "lzo-rle" algorithm. 252 + compress_log_size=%u Support configuring compress cluster size, the size will 253 + be 4KB * (1 << %u), 16KB is minimum size, also it's 254 + default size. 255 + compress_extension=%s Support adding specified extension, so that f2fs can enable 256 + compression on those corresponding files, e.g. if all files 257 + with '.ext' has high compression rate, we can set the '.ext' 258 + on compression extension list and enable compression on 259 + these file by default rather than to enable it via ioctl. 260 + For other files, we can still enable compression via ioctl. 261 + inlinecrypt When possible, encrypt/decrypt the contents of encrypted 262 + files using the blk-crypto framework rather than 263 + filesystem-layer encryption. This allows the use of 264 + inline encryption hardware. The on-disk format is 265 + unaffected. For more details, see 266 + Documentation/block/inline-encryption.rst. 267 + ======================== ============================================================ 269 268 270 269 Debugfs Entries 271 270 ===============

+1 -1

Documentation/filesystems/fsverity.rst

··· 659 659 retrofit existing filesystems with new consistency mechanisms. 660 660 Data journalling is available on ext4, but is very slow. 661 661 662 - - Rebuilding the the Merkle tree after every write, which would be 662 + - Rebuilding the Merkle tree after every write, which would be 663 663 extremely inefficient. Alternatively, a different authenticated 664 664 dictionary structure such as an "authenticated skiplist" could 665 665 be used. However, this would be far more complex.

+1 -1

Documentation/filesystems/hfs.rst

··· 76 76 77 77 The hfsutils package from Robert Leslie contains a program called 78 78 hformat that can be used to create HFS filesystem. See 79 - <http://www.mars.org/home/rob/proj/hfs/> for details. 79 + <https://www.mars.org/home/rob/proj/hfs/> for details. 80 80 81 81 82 82 Credits

+1 -1

Documentation/filesystems/hpfs.rst

··· 7 7 1998-2004, Mikulas Patocka 8 8 9 9 :email: mikulas@artax.karlin.mff.cuni.cz 10 - :homepage: http://artax.karlin.mff.cuni.cz/~mikulas/vyplody/hpfs/index-e.cgi 10 + :homepage: https://artax.karlin.mff.cuni.cz/~mikulas/vyplody/hpfs/index-e.cgi 11 11 12 12 Credits 13 13 =======

+6 -6

Documentation/filesystems/locking.rst

··· 433 433 434 434 locking rules: 435 435 436 - ========== ============= ================= ========= 436 + ====================== ============= ================= ========= 437 437 ops inode->i_lock blocked_lock_lock may block 438 - ========== ============= ================= ========= 438 + ====================== ============= ================= ========= 439 439 lm_notify: yes yes no 440 440 lm_grant: no no no 441 441 lm_break: yes no no 442 442 lm_change yes no no 443 443 lm_breaker_owns_lease: no no no 444 - ========== ============= ================= ========= 444 + ====================== ============= ================= ========= 445 445 446 446 buffer_head 447 447 =========== ··· 614 614 615 615 locking rules: 616 616 617 - ============= ======== =========================== 617 + ============= ========= =========================== 618 618 ops mmap_lock PageLocked(page) 619 - ============= ======== =========================== 619 + ============= ========= =========================== 620 620 open: yes 621 621 close: yes 622 622 fault: yes can return with page locked ··· 624 624 page_mkwrite: yes can return with page locked 625 625 pfn_mkwrite: yes 626 626 access: yes 627 - ============= ======== =========================== 627 + ============= ========= =========================== 628 628 629 629 ->fault() is called when a previously not present pte is about 630 630 to be faulted in. The filesystem must find and return the page associated

+2 -2

Documentation/filesystems/mount_api.rst

··· 213 213 void (*free)(struct fs_context *fc); 214 214 int (*dup)(struct fs_context *fc, struct fs_context *src_fc); 215 215 int (*parse_param)(struct fs_context *fc, 216 - struct struct fs_parameter *param); 216 + struct fs_parameter *param); 217 217 int (*parse_monolithic)(struct fs_context *fc, void *data); 218 218 int (*get_tree)(struct fs_context *fc); 219 219 int (*reconfigure)(struct fs_context *fc); ··· 247 247 * :: 248 248 249 249 int (*parse_param)(struct fs_context *fc, 250 - struct struct fs_parameter *param); 250 + struct fs_parameter *param); 251 251 252 252 Called when a parameter is being added to the filesystem context. param 253 253 points to the key name and maybe a value object. VFS-specific options

+3 -3

Documentation/filesystems/nfs/rpc-server-gss.rst

··· 10 10 11 11 RPCGSS is specified in a few IETF documents: 12 12 13 - - RFC2203 v1: http://tools.ietf.org/rfc/rfc2203.txt 14 - - RFC5403 v2: http://tools.ietf.org/rfc/rfc5403.txt 13 + - RFC2203 v1: https://tools.ietf.org/rfc/rfc2203.txt 14 + - RFC5403 v2: https://tools.ietf.org/rfc/rfc5403.txt 15 15 16 16 and there is a 3rd version being proposed: 17 17 18 - - http://tools.ietf.org/id/draft-williams-rpcsecgssv3.txt 18 + - https://tools.ietf.org/id/draft-williams-rpcsecgssv3.txt 19 19 (At draft n. 02 at the time of writing) 20 20 21 21 Background

+1 -1

Documentation/filesystems/omfs.rst

··· 24 24 Various utilities, including mkomfs and omfsck, are included with 25 25 omfsprogs, available at: 26 26 27 - http://bobcopeland.com/karma/ 27 + https://bobcopeland.com/karma/ 28 28 29 29 Instructions are included in its README. 30 30

+1 -1

Documentation/filesystems/overlayfs.rst

··· 328 328 Multiple lower layers 329 329 --------------------- 330 330 331 - Multiple lower layers can now be given using the the colon (":") as a 331 + Multiple lower layers can now be given using the colon (":") as a 332 332 separator character between the directory names. For example: 333 333 334 334 mount -t overlay overlay -olowerdir=/lower1:/lower2:/lower3 /merged

+16 -16

Documentation/filesystems/path-lookup.rst

··· 43 43 non-"``/``" characters. These form two kinds of paths. Those that 44 44 start with slashes are "absolute" and start from the filesystem root. 45 45 The others are "relative" and start from the current directory, or 46 - from some other location specified by a file descriptor given to a 47 - "``XXXat``" system call such as `openat() <openat_>`_. 46 + from some other location specified by a file descriptor given to 47 + "``*at()``" system calls such as `openat() <openat_>`_. 48 48 49 49 .. _execveat: http://man7.org/linux/man-pages/man2/execveat.2.html 50 50 51 51 It is tempting to describe the second kind as starting with a 52 52 component, but that isn't always accurate: a pathname can lack both 53 53 slashes and components, it can be empty, in other words. This is 54 - generally forbidden in POSIX, but some of those "xxx``at``" system calls 54 + generally forbidden in POSIX, but some of those "``*at()``" system calls 55 55 in Linux permit it when the ``AT_EMPTY_PATH`` flag is given. For 56 56 example, if you have an open file descriptor on an executable file you 57 57 can execute it by calling `execveat() <execveat_>`_ passing ··· 69 69 exist, it could be "``.``" or "``..``" which are handled quite differently 70 70 from other components. 71 71 72 - .. _POSIX: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_12 72 + .. _POSIX: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_12 73 73 74 74 If a pathname ends with a slash, such as "``/tmp/foo/``" it might be 75 75 tempting to consider that to have an empty final component. In many 76 76 ways that would lead to correct results, but not always. In 77 77 particular, ``mkdir()`` and ``rmdir()`` each create or remove a directory named 78 78 by the final component, and they are required to work with pathnames 79 - ending in "``/``". According to POSIX_ 79 + ending in "``/``". According to POSIX_: 80 80 81 - A pathname that contains at least one non- <slash> character and 82 - that ends with one or more trailing <slash> characters shall not 81 + A pathname that contains at least one non-<slash> character and 82 + that ends with one or more trailing <slash> characters shall not 83 83 be resolved successfully unless the last pathname component before 84 84 the trailing <slash> characters names an existing directory or a 85 85 directory entry that is to be created for a directory immediately ··· 229 229 it might end up continuing the search down the wrong chain, 230 230 and so miss out on part of the correct chain. 231 231 232 - The name-lookup process (``d_lookup()``) does _not_ try to prevent this 232 + The name-lookup process (``d_lookup()``) does *not* try to prevent this 233 233 from happening, but only to detect when it happens. 234 234 ``rename_lock`` is a seqlock that is updated whenever any dentry is 235 235 renamed. If ``d_lookup`` finds that a rename happened while it ··· 376 376 Bringing it together with ``struct nameidata`` 377 377 ---------------------------------------------- 378 378 379 - .. _First edition Unix: http://minnie.tuhs.org/cgi-bin/utree.pl?file=V1/u2.s 379 + .. _First edition Unix: https://minnie.tuhs.org/cgi-bin/utree.pl?file=V1/u2.s 380 380 381 381 Throughout the process of walking a path, the current status is stored 382 382 in a ``struct nameidata``, "namei" being the traditional name - dating ··· 398 398 ``struct qstr last`` 399 399 ~~~~~~~~~~~~~~~~~~~~ 400 400 401 - This is a string together with a length (i.e. _not_ ``nul`` terminated) 401 + This is a string together with a length (i.e. *not* ``nul`` terminated) 402 402 that is the "next" component in the pathname. 403 403 404 404 ``int last_type`` ··· 655 655 clearly seen in functions like ``filename_lookup()``, 656 656 ``filename_parentat()``, ``filename_mountpoint()``, 657 657 ``do_filp_open()``, and ``do_file_open_root()``. These five 658 - correspond roughly to the four ``path_``* functions we met earlier, 659 - each of which calls ``link_path_walk()``. The ``path_*`` functions are 658 + correspond roughly to the four ``path_*()`` functions we met earlier, 659 + each of which calls ``link_path_walk()``. The ``path_*()`` functions are 660 660 called using different mode flags until a mode is found which works. 661 661 They are first called with ``LOOKUP_RCU`` set to request "RCU-walk". If 662 662 that fails with the error ``ECHILD`` they are called again with no ··· 720 720 variables, then ``read_seqcount_retry()`` is called to confirm the two 721 721 are consistent, and only then is ``->d_compare()`` called. When 722 722 standard filename comparison is used, ``dentry_cmp()`` is called 723 - instead. Notably it does _not_ use ``read_seqcount_retry()``, but 723 + instead. Notably it does *not* use ``read_seqcount_retry()``, but 724 724 instead has a large comment explaining why the consistency guarantee 725 725 isn't necessary. A subsequent ``read_seqcount_retry()`` will be 726 726 sufficient to catch any problem that could occur at this point. ··· 928 928 sedate approach. 929 929 930 930 The emphasis here is "try quickly and check". It should probably be 931 - "try quickly _and carefully,_ then check". The fact that checking is 931 + "try quickly *and carefully*, then check". The fact that checking is 932 932 needed is a reminder that the system is dynamic and only a limited 933 933 number of things are safe at all. The most likely cause of errors in 934 934 this whole process is assuming something is safe when in reality it ··· 1265 1265 and looking up a symlink on the way to some other destination can 1266 1266 update the atime on that symlink. 1267 1267 1268 - .. _clearest statement: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_08 1268 + .. _clearest statement: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_08 1269 1269 1270 1270 It is not clear why this is the case; POSIX has little to say on the 1271 1271 subject. The `clearest statement`_ is that, if a particular implementation ··· 1365 1365 resolution of "..". Magic-links are also blocked. 1366 1366 1367 1367 ``LOOKUP_IN_ROOT`` resolves all path components as though the starting point 1368 - were the filesystem root. ``nd_jump_root()`` brings the resolution back to to 1368 + were the filesystem root. ``nd_jump_root()`` brings the resolution back to 1369 1369 the starting point, and ".." at the starting point will act as a no-op. As with 1370 1370 ``LOOKUP_BENEATH``, ``rename_lock`` and ``mount_lock`` are used to detect 1371 1371 attacks against ".." resolution. Magic-links are also blocked.

+76 -79

Documentation/filesystems/proc.rst

··· 123 123 The directory /proc contains (among other things) one subdirectory for each 124 124 process running on the system, which is named after the process ID (PID). 125 125 126 - The link self points to the process reading the file system. Each process 126 + The link 'self' points to the process reading the file system. Each process 127 127 subdirectory has the entries listed in Table 1-1. 128 128 129 - Note that an open a file descriptor to /proc/<pid> or to any of its 129 + Note that an open file descriptor to /proc/<pid> or to any of its 130 130 contained files or subdirectories does not prevent <pid> being reused 131 131 for some other process in the event that <pid> exits. Operations on 132 132 open /proc/<pid> file descriptors corresponding to dead processes ··· 220 220 221 221 The statm file contains more detailed information about the process 222 222 memory usage. Its seven fields are explained in Table 1-3. The stat file 223 - contains details information about the process itself. Its fields are 223 + contains detailed information about the process itself. Its fields are 224 224 explained in Table 1-4. 225 225 226 226 (for SMP CONFIG users) ··· 545 545 hg huge page advise flag 546 546 nh no huge page advise flag 547 547 mg mergable advise flag 548 - bt - arm64 BTI guarded page 548 + bt arm64 BTI guarded page 549 549 == ======================================= 550 550 551 551 Note that there is no guarantee that every flag and associated mnemonic will ··· 782 782 For this case the APIC will generate the interrupt with a IRQ vector 783 783 of 0xff. This might also be generated by chipset bugs. 784 784 785 - RES, CAL, TLB] 785 + RES, CAL, TLB 786 786 rescheduling, call and TLB flush interrupts are 787 787 sent from one CPU to another per the needs of the OS. Typically, 788 788 their statistics are used by kernel developers and interested users to ··· 794 794 i386 and x86_64 platforms support the new IRQ vector displays. 795 795 796 796 Of some interest is the introduction of the /proc/irq directory to 2.4. 797 - It could be used to set IRQ to CPU affinity, this means that you can "hook" an 797 + It could be used to set IRQ to CPU affinity. This means that you can "hook" an 798 798 IRQ to only one CPU, or to exclude a CPU of handling IRQs. The contents of the 799 799 irq subdir is one subdir for each IRQ, and two files; default_smp_affinity and 800 800 prof_cpu_mask. ··· 808 808 smp_affinity 809 809 810 810 smp_affinity is a bitmask, in which you can specify which CPUs can handle the 811 - IRQ, you can set it by doing:: 811 + IRQ. You can set it by doing:: 812 812 813 813 > echo 1 > /proc/irq/10/smp_affinity 814 814 ··· 821 821 ffffffff 822 822 823 823 There is an alternate interface, smp_affinity_list which allows specifying 824 - a cpu range instead of a bitmask:: 824 + a CPU range instead of a bitmask:: 825 825 826 826 > cat /proc/irq/0/smp_affinity_list 827 827 1024-1031 ··· 835 835 include information about any possible driver locality preference. 836 836 837 837 prof_cpu_mask specifies which CPUs are to be profiled by the system wide 838 - profiler. Default value is ffffffff (all cpus if there are only 32 of them). 838 + profiler. Default value is ffffffff (all CPUs if there are only 32 of them). 839 839 840 840 The way IRQs are routed is handled by the IO-APIC, and it's Round Robin 841 841 between all the CPUs which are allowed to handle it. As usual the kernel has ··· 897 897 898 898 Fragmentation avoidance in the kernel works by grouping pages of different 899 899 migrate types into the same contiguous regions of memory called page blocks. 900 - A page block is typically the size of the default hugepage size e.g. 2MB on 900 + A page block is typically the size of the default hugepage size, e.g. 2MB on 901 901 X86-64. By keeping pages grouped based on their ability to move, the kernel 902 902 can reclaim pages within a page block to satisfy a high-order allocation. 903 903 ··· 965 965 ShmemPmdMapped: 0 kB 966 966 967 967 MemTotal 968 - Total usable ram (i.e. physical ram minus a few reserved 968 + Total usable RAM (i.e. physical RAM minus a few reserved 969 969 bits and the kernel binary code) 970 970 MemFree 971 971 The sum of LowFree+HighFree ··· 996 996 Memory which has been less recently used. It is more 997 997 eligible to be reclaimed for other purposes 998 998 HighTotal, HighFree 999 - Highmem is all memory above ~860MB of physical memory 999 + Highmem is all memory above ~860MB of physical memory. 1000 1000 Highmem areas are for use by userspace programs, or 1001 1001 for the pagecache. The kernel must use tricks to access 1002 1002 this memory, making it slower to access than lowmem. ··· 1078 1078 using 1G. This 1G is memory which has been "committed" to 1079 1079 by the VM and can be used at any time by the allocating 1080 1080 application. With strict overcommit enabled on the system 1081 - (mode 2 in 'vm.overcommit_memory'),allocations which would 1081 + (mode 2 in 'vm.overcommit_memory'), allocations which would 1082 1082 exceed the CommitLimit (detailed above) will not be permitted. 1083 1083 This is useful if one needs to guarantee that processes will 1084 1084 not fail due to lack of memory once that memory has been ··· 1099 1099 Provides information about vmalloced/vmaped areas. One line per area, 1100 1100 containing the virtual address range of the area, size in bytes, 1101 1101 caller information of the creator, and optional information depending 1102 - on the kind of area : 1102 + on the kind of area: 1103 1103 1104 1104 ========== =================================================== 1105 1105 pages=nr number of pages ··· 1144 1144 softirqs 1145 1145 ~~~~~~~~ 1146 1146 1147 - Provides counts of softirq handlers serviced since boot time, for each cpu. 1147 + Provides counts of softirq handlers serviced since boot time, for each CPU. 1148 1148 1149 1149 :: 1150 1150 1151 1151 > cat /proc/softirqs 1152 - CPU0 CPU1 CPU2 CPU3 1152 + CPU0 CPU1 CPU2 CPU3 1153 1153 HI: 0 0 0 0 1154 - TIMER: 27166 27120 27097 27034 1154 + TIMER: 27166 27120 27097 27034 1155 1155 NET_TX: 0 0 0 17 1156 1156 NET_RX: 42 0 0 39 1157 - BLOCK: 0 0 107 1121 1158 - TASKLET: 0 0 0 290 1159 - SCHED: 27035 26983 26971 26746 1160 - HRTIMER: 0 0 0 0 1161 - RCU: 1678 1769 2178 2250 1157 + BLOCK: 0 0 107 1121 1158 + TASKLET: 0 0 0 290 1159 + SCHED: 27035 26983 26971 26746 1160 + HRTIMER: 0 0 0 0 1161 + RCU: 1678 1769 2178 2250 1162 1162 1163 1163 1164 1164 1.3 IDE devices in /proc/ide ··· 1169 1169 file drivers and a link for each IDE device, pointing to the device directory 1170 1170 in the controller specific subtree. 1171 1171 1172 - The file drivers contains general information about the drivers used for the 1172 + The file 'drivers' contains general information about the drivers used for the 1173 1173 IDE devices:: 1174 1174 1175 1175 > cat /proc/ide/drivers ··· 1409 1409 ------------------------- 1410 1410 1411 1411 Information about the available and actually used tty's can be found in the 1412 - directory /proc/tty.You'll find entries for drivers and line disciplines in 1412 + directory /proc/tty. You'll find entries for drivers and line disciplines in 1413 1413 this directory, as shown in Table 1-11. 1414 1414 1415 1415 ··· 1471 1471 - iowait: In a word, iowait stands for waiting for I/O to complete. But there 1472 1472 are several problems: 1473 1473 1474 - 1. Cpu will not wait for I/O to complete, iowait is the time that a task is 1475 - waiting for I/O to complete. When cpu goes into idle state for 1476 - outstanding task io, another task will be scheduled on this CPU. 1474 + 1. CPU will not wait for I/O to complete, iowait is the time that a task is 1475 + waiting for I/O to complete. When CPU goes into idle state for 1476 + outstanding task I/O, another task will be scheduled on this CPU. 1477 1477 2. In a multi-core CPU, the task waiting for I/O to complete is not running 1478 1478 on any CPU, so the iowait of each CPU is difficult to calculate. 1479 1479 3. The value of iowait field in /proc/stat will decrease in certain ··· 1529 1529 mb_groups details of multiblock allocator buddy cache of free blocks 1530 1530 ============== ========================================================== 1531 1531 1532 - 2.0 /proc/consoles 1533 - ------------------ 1532 + 1.10 /proc/consoles 1533 + ------------------- 1534 1534 Shows registered system console lines. 1535 1535 1536 1536 To see which character device lines are currently used for the system console ··· 1590 1590 everything works the way you want it to. You may have no alternative but to 1591 1591 reboot the machine once an error has been made. 1592 1592 1593 - To change a value, simply echo the new value into the file. An example is 1594 - given below in the section on the file system data. You need to be root to do 1595 - this. You can create your own boot script to perform this every time your 1596 - system boots. 1593 + To change a value, simply echo the new value into the file. 1594 + You need to be root to do this. You can create your own boot script 1595 + to perform this every time your system boots. 1597 1596 1598 1597 The files in /proc/sys can be used to fine tune and monitor miscellaneous and 1599 1598 general things in the operation of the Linux kernel. Since some of the files ··· 1623 1624 3.1 /proc/<pid>/oom_adj & /proc/<pid>/oom_score_adj- Adjust the oom-killer score 1624 1625 -------------------------------------------------------------------------------- 1625 1626 1626 - These file can be used to adjust the badness heuristic used to select which 1627 - process gets killed in out of memory conditions. 1627 + These files can be used to adjust the badness heuristic used to select which 1628 + process gets killed in out of memory (oom) conditions. 1628 1629 1629 1630 The badness heuristic assigns a value to each candidate task ranging from 0 1630 1631 (never kill) to 1000 (always kill) to determine which process is targeted. The ··· 1680 1681 3.2 /proc/<pid>/oom_score - Display current oom-killer score 1681 1682 ------------------------------------------------------------- 1682 1683 1683 - This file can be used to check the current score used by the oom-killer is for 1684 + This file can be used to check the current score used by the oom-killer for 1684 1685 any given <pid>. Use it together with /proc/<pid>/oom_score_adj to tune which 1685 1686 process should be killed in an out-of-memory situation. 1686 1687 ··· 1688 1689 3.3 /proc/<pid>/io - Display the IO accounting fields 1689 1690 ------------------------------------------------------- 1690 1691 1691 - This file contains IO statistics for each running process 1692 + This file contains IO statistics for each running process. 1692 1693 1693 1694 Example 1694 1695 ~~~~~~~ ··· 1719 1720 is simply the sum of bytes which this process passed to read() and pread(). 1720 1721 It includes things like tty IO and it is unaffected by whether or not actual 1721 1722 physical disk IO was required (the read might have been satisfied from 1722 - pagecache) 1723 + pagecache). 1723 1724 1724 1725 1725 1726 wchar ··· 1877 1878 1878 1879 3.6 /proc/<pid>/comm & /proc/<pid>/task/<tid>/comm 1879 1880 -------------------------------------------------------- 1880 - These files provide a method to access a tasks comm value. It also allows for 1881 + These files provide a method to access a task's comm value. It also allows for 1881 1882 a task to set its own or one of its thread siblings comm value. The comm value 1882 1883 is limited in size compared to the cmdline value, so writing anything longer 1883 1884 then the kernel's TASK_COMM_LEN (currently 16 chars) will result in a truncated ··· 1890 1891 of a task pointed by <pid>/<tid> pair. The format is a space separated 1891 1892 stream of pids. 1892 1893 1893 - Note the "first level" here -- if a child has own children they will 1894 - not be listed here, one needs to read /proc/<children-pid>/task/<tid>/children 1894 + Note the "first level" here -- if a child has its own children they will 1895 + not be listed here; one needs to read /proc/<children-pid>/task/<tid>/children 1895 1896 to obtain the descendants. 1896 1897 1897 1898 Since this interface is intended to be fast and cheap it doesn't 1898 1899 guarantee to provide precise results and some children might be 1899 1900 skipped, especially if they've exited right after we printed their 1900 - pids, so one need to either stop or freeze processes being inspected 1901 + pids, so one needs to either stop or freeze processes being inspected 1901 1902 if precise results are needed. 1902 1903 1903 1904 1904 1905 3.8 /proc/<pid>/fdinfo/<fd> - Information about opened file 1905 1906 --------------------------------------------------------------- 1906 1907 This file provides information associated with an opened file. The regular 1907 - files have at least three fields -- 'pos', 'flags' and mnt_id. The 'pos' 1908 + files have at least three fields -- 'pos', 'flags' and 'mnt_id'. The 'pos' 1908 1909 represents the current offset of the opened file in decimal form [see lseek(2) 1909 1910 for details], 'flags' denotes the octal O_xxx mask the file has been 1910 1911 created with [see open(2) for details] and 'mnt_id' represents mount ID of ··· 1975 1976 flags: 02000000 1976 1977 inotify wd:3 ino:9e7e sdev:800013 mask:800afce ignored_mask:0 fhandle-bytes:8 fhandle-type:1 f_handle:7e9e0000640d1b6d 1977 1978 1978 - where 'wd' is a watch descriptor in decimal form, ie a target file 1979 + where 'wd' is a watch descriptor in decimal form, i.e. a target file 1979 1980 descriptor number, 'ino' and 'sdev' are inode and device where the 1980 1981 target file resides and the 'mask' is the mask of events, all in hex 1981 1982 form [see inotify(7) for more details]. ··· 2002 2003 where fanotify 'flags' and 'event-flags' are values used in fanotify_init 2003 2004 call, 'mnt_id' is the mount point identifier, 'mflags' is the value of 2004 2005 flags associated with mark which are tracked separately from events 2005 - mask. 'ino', 'sdev' are target inode and device, 'mask' is the events 2006 + mask. 'ino' and 'sdev' are target inode and device, 'mask' is the events 2006 2007 mask and 'ignored_mask' is the mask of events which are to be ignored. 2007 - All in hex format. Incorporation of 'mflags', 'mask' and 'ignored_mask' 2008 - does provide information about flags and mask used in fanotify_mark 2008 + All are in hex format. Incorporation of 'mflags', 'mask' and 'ignored_mask' 2009 + provide information about flags and mask used in fanotify_mark 2009 2010 call [see fsnotify manpage for details]. 2010 2011 2011 2012 While the first three lines are mandatory and always printed, the rest is ··· 2028 2029 where 'clockid' is the clock type and 'ticks' is the number of the timer expirations 2029 2030 that have occurred [see timerfd_create(2) for details]. 'settime flags' are 2030 2031 flags in octal form been used to setup the timer [see timerfd_settime(2) for 2031 - details]. 'it_value' is remaining time until the timer exiration. 2032 + details]. 'it_value' is remaining time until the timer expiration. 2032 2033 'it_interval' is the interval for the timer. Note the timer might be set up 2033 2034 with TIMER_ABSTIME option which will be shown in 'settime flags', but 'it_value' 2034 2035 still exhibits timer's remaining time. ··· 2058 2059 3.10 /proc/<pid>/timerslack_ns - Task timerslack value 2059 2060 --------------------------------------------------------- 2060 2061 This file provides the value of the task's timerslack value in nanoseconds. 2061 - This value specifies a amount of time that normal timers may be deferred 2062 + This value specifies an amount of time that normal timers may be deferred 2062 2063 in order to coalesce timers and avoid unnecessary wakeups. 2063 2064 2064 - This allows a task's interactivity vs power consumption trade off to be 2065 + This allows a task's interactivity vs power consumption tradeoff to be 2065 2066 adjusted. 2066 2067 2067 - Writing 0 to the file will set the tasks timerslack to the default value. 2068 + Writing 0 to the file will set the task's timerslack to the default value. 2068 2069 2069 2070 Valid values are from 0 - ULLONG_MAX 2070 2071 ··· 2104 2105 Description 2105 2106 ~~~~~~~~~~~ 2106 2107 2107 - x86 specific entries: 2108 + x86 specific entries 2108 2109 ~~~~~~~~~~~~~~~~~~~~~ 2109 2110 2110 - AVX512_elapsed_ms: 2111 + AVX512_elapsed_ms 2111 2112 ^^^^^^^^^^^^^^^^^^ 2112 2113 2113 2114 If AVX512 is supported on the machine, this entry shows the milliseconds ··· 2133 2134 the task is unlikely an AVX512 user, but depends on the workload and the 2134 2135 scheduling scenario, it also could be a false negative mentioned above. 2135 2136 2136 - Configuring procfs 2137 - ------------------ 2137 + Chapter 4: Configuring procfs 2138 + ============================= 2138 2139 2139 2140 4.1 Mount options 2140 2141 --------------------- ··· 2177 2178 subset=pid hides all top level files and directories in the procfs that 2178 2179 are not related to tasks. 2179 2180 2180 - 5 Filesystem behavior 2181 - ---------------------------- 2181 + Chapter 5: Filesystem behavior 2182 + ============================== 2182 2183 2183 2184 Originally, before the advent of pid namepsace, procfs was a global file 2184 2185 system. It means that there was only one procfs instance in the system. 2185 2186 2186 2187 When pid namespace was added, a separate procfs instance was mounted in 2187 2188 each pid namespace. So, procfs mount options are global among all 2188 - mountpoints within the same namespace. 2189 + mountpoints within the same namespace:: 2189 2190 2190 - :: 2191 + # grep ^proc /proc/mounts 2192 + proc /proc proc rw,relatime,hidepid=2 0 0 2191 2193 2192 - # grep ^proc /proc/mounts 2193 - proc /proc proc rw,relatime,hidepid=2 0 0 2194 + # strace -e mount mount -o hidepid=1 -t proc proc /tmp/proc 2195 + mount("proc", "/tmp/proc", "proc", 0, "hidepid=1") = 0 2196 + +++ exited with 0 +++ 2194 2197 2195 - # strace -e mount mount -o hidepid=1 -t proc proc /tmp/proc 2196 - mount("proc", "/tmp/proc", "proc", 0, "hidepid=1") = 0 2197 - +++ exited with 0 +++ 2198 - 2199 - # grep ^proc /proc/mounts 2200 - proc /proc proc rw,relatime,hidepid=2 0 0 2201 - proc /tmp/proc proc rw,relatime,hidepid=2 0 0 2198 + # grep ^proc /proc/mounts 2199 + proc /proc proc rw,relatime,hidepid=2 0 0 2200 + proc /tmp/proc proc rw,relatime,hidepid=2 0 0 2202 2201 2203 2202 and only after remounting procfs mount options will change at all 2204 - mountpoints. 2203 + mountpoints:: 2205 2204 2206 - # mount -o remount,hidepid=1 -t proc proc /tmp/proc 2205 + # mount -o remount,hidepid=1 -t proc proc /tmp/proc 2207 2206 2208 - # grep ^proc /proc/mounts 2209 - proc /proc proc rw,relatime,hidepid=1 0 0 2210 - proc /tmp/proc proc rw,relatime,hidepid=1 0 0 2207 + # grep ^proc /proc/mounts 2208 + proc /proc proc rw,relatime,hidepid=1 0 0 2209 + proc /tmp/proc proc rw,relatime,hidepid=1 0 0 2211 2210 2212 2211 This behavior is different from the behavior of other filesystems. 2213 2212 2214 2213 The new procfs behavior is more like other filesystems. Each procfs mount 2215 2214 creates a new procfs instance. Mount options affect own procfs instance. 2216 2215 It means that it became possible to have several procfs instances 2217 - displaying tasks with different filtering options in one pid namespace. 2216 + displaying tasks with different filtering options in one pid namespace:: 2218 2217 2219 - # mount -o hidepid=invisible -t proc proc /proc 2220 - # mount -o hidepid=noaccess -t proc proc /tmp/proc 2221 - # grep ^proc /proc/mounts 2222 - proc /proc proc rw,relatime,hidepid=invisible 0 0 2223 - proc /tmp/proc proc rw,relatime,hidepid=noaccess 0 0 2218 + # mount -o hidepid=invisible -t proc proc /proc 2219 + # mount -o hidepid=noaccess -t proc proc /tmp/proc 2220 + # grep ^proc /proc/mounts 2221 + proc /proc proc rw,relatime,hidepid=invisible 0 0 2222 + proc /tmp/proc proc rw,relatime,hidepid=noaccess 0 0

+4 -4

Documentation/filesystems/ramfs-rootfs-initramfs.rst

··· 246 246 you need to get a minimal root filesystem up and running, here are some 247 247 references: 248 248 249 - - http://www.tldp.org/HOWTO/Bootdisk-HOWTO/ 250 - - http://www.tldp.org/HOWTO/From-PowerUp-To-Bash-Prompt-HOWTO.html 249 + - https://www.tldp.org/HOWTO/Bootdisk-HOWTO/ 250 + - https://www.tldp.org/HOWTO/From-PowerUp-To-Bash-Prompt-HOWTO.html 251 251 - http://www.linuxfromscratch.org/lfs/view/stable/ 252 252 253 - The "klibc" package (http://www.kernel.org/pub/linux/libs/klibc) is 253 + The "klibc" package (https://www.kernel.org/pub/linux/libs/klibc) is 254 254 designed to be a tiny C library to statically link early userspace 255 255 code against, along with some related utilities. It is BSD licensed. 256 256 257 - I use uClibc (http://www.uclibc.org) and busybox (http://www.busybox.net) 257 + I use uClibc (https://www.uclibc.org) and busybox (https://www.busybox.net) 258 258 myself. These are LGPL and GPL, respectively. (A self-contained initramfs 259 259 package is planned for the busybox 1.3 release.) 260 260

+1 -1

Documentation/filesystems/sysfs-pci.rst

··· 63 63 binary - file contains binary data 64 64 cpumask - file contains a cpumask type 65 65 66 - .. [1] rw for RESOURCE_IO (I/O port) regions only 66 + .. [1] rw for IORESOURCE_IO (I/O port) regions only 67 67 68 68 The read only files are informational, writes to them will be ignored, with 69 69 the exception of the 'rom' file. Writable files can be used to perform

+1 -1

Documentation/filesystems/sysfs-tagging.rst

··· 15 15 namespaces to see the same interface that is currently presented in 16 16 sysfs, sysfs now has tagging directory support. 17 17 18 - By using the network namespace pointers as tags to separate out the 18 + By using the network namespace pointers as tags to separate out 19 19 the sysfs directory entries we ensure that we don't have conflicts 20 20 in the directories and applications only see a limited set of 21 21 the network devices.

+2 -2

Documentation/filesystems/ubifs-authentication.rst

··· 433 433 References 434 434 ========== 435 435 436 - [CRYPTSETUP2] http://www.saout.de/pipermail/dm-crypt/2017-November/005745.html 436 + [CRYPTSETUP2] https://www.saout.de/pipermail/dm-crypt/2017-November/005745.html 437 437 438 - [DMC-CBC-ATTACK] http://www.jakoblell.com/blog/2013/12/22/practical-malleability-attack-against-cbc-encrypted-luks-partitions/ 438 + [DMC-CBC-ATTACK] https://www.jakoblell.com/blog/2013/12/22/practical-malleability-attack-against-cbc-encrypted-luks-partitions/ 439 439 440 440 [DM-INTEGRITY] https://www.kernel.org/doc/Documentation/device-mapper/dm-integrity.rst 441 441

+8 -8

Documentation/filesystems/vfs.rst

··· 392 392 ``set`` 393 393 Called by the VFS to set the value of a particular extended 394 394 attribute. When the new value is NULL, called to remove a 395 - particular extended attribute. This method is called by the the 395 + particular extended attribute. This method is called by the 396 396 setxattr(2) and removexattr(2) system calls. 397 397 398 398 When none of the xattr handlers of a filesystem match the specified ··· 652 652 PG_Writeback is cleared. 653 653 654 654 Writeback makes use of a writeback_control structure to direct the 655 - operations. This gives the the writepage and writepages operations some 655 + operations. This gives the writepage and writepages operations some 656 656 information about the nature of and reason for the writeback request, 657 657 and the constraints under which it is being done. It is also used to 658 658 return information back to the caller about the result of a writepage or ··· 766 766 767 767 ``writepages`` 768 768 called by the VM to write out pages associated with the 769 - address_space object. If wbc->sync_mode is WBC_SYNC_ALL, then 769 + address_space object. If wbc->sync_mode is WB_SYNC_ALL, then 770 770 the writeback_control will specify a range of pages that must be 771 - written out. If it is WBC_SYNC_NONE, then a nr_to_write is 771 + written out. If it is WB_SYNC_NONE, then a nr_to_write is 772 772 given and that many pages should be written if possible. If no 773 773 ->writepages is given, then mpage_writepages is used instead. 774 774 This will choose pages from the address space that are tagged as ··· 1116 1116 before any bytes were remapped. The remap_flags parameter 1117 1117 accepts REMAP_FILE_* flags. If REMAP_FILE_DEDUP is set then the 1118 1118 implementation must only remap if the requested file ranges have 1119 - identical contents. If REMAP_CAN_SHORTEN is set, the caller is 1119 + identical contents. If REMAP_FILE_CAN_SHORTEN is set, the caller is 1120 1120 ok with the implementation shortening the request length to 1121 1121 satisfy alignment or EOF requirements (or any other reason). 1122 1122 ··· 1431 1431 version.) 1432 1432 1433 1433 Creating Linux virtual filesystems. 2002 1434 - <http://lwn.net/Articles/13325/> 1434 + <https://lwn.net/Articles/13325/> 1435 1435 1436 1436 The Linux Virtual File-system Layer by Neil Brown. 1999 1437 1437 <http://www.cse.unsw.edu.au/~neilb/oss/linux-commentary/vfs.html> 1438 1438 1439 1439 A tour of the Linux VFS by Michael K. Johnson. 1996 1440 - <http://www.tldp.org/LDP/khg/HyperNews/get/fs/vfstour.html> 1440 + <https://www.tldp.org/LDP/khg/HyperNews/get/fs/vfstour.html> 1441 1441 1442 1442 A small trail through the Linux kernel by Andries Brouwer. 2001 1443 - <http://www.win.tue.nl/~aeb/linux/vfs/trail.html> 1443 + <https://www.win.tue.nl/~aeb/linux/vfs/trail.html>

+1 -1

Documentation/fpga/dfl.rst

··· 8 8 - Xiao Guangrong <guangrong.xiao@linux.intel.com> 9 9 - Wu Hao <hao.wu@intel.com> 10 10 11 - The Device Feature List (DFL) FPGA framework (and drivers according to this 11 + The Device Feature List (DFL) FPGA framework (and drivers according to 12 12 this framework) hides the very details of low layer hardwares and provides 13 13 unified interfaces to userspace. Applications could use these interfaces to 14 14 configure, enumerate, open and access FPGA accelerators on platforms which

+1 -1

Documentation/gpu/drm-mm.rst

··· 314 314 a pointer on drm_gem_cma_get_unmapped_area(). 315 315 316 316 More detailed information about get_unmapped_area can be found in 317 - Documentation/nommu-mmap.txt 317 + Documentation/admin-guide/mm/nommu-mmap.rst 318 318 319 319 Memory Coherency 320 320 ----------------

+1 -1

Documentation/gpu/drm-uapi.rst

··· 195 195 EPERM/EACCES: 196 196 Returned for an operation that is valid, but needs more privileges. 197 197 E.g. root-only or much more common, DRM master-only operations return 198 - this when when called by unpriviledged clients. There's no clear 198 + this when called by unpriviledged clients. There's no clear 199 199 difference between EACCES and EPERM. 200 200 201 201 ENODEV:

+1 -1

Documentation/gpu/komeda-kms.rst

··· 41 41 frame. its output frame can be fed into post image processor for showing it on 42 42 the monitor or fed into wb_layer and written to memory at the same time. 43 43 user can also insert a scaler between compositor and wb_layer to down scale 44 - the display frame first and and then write to memory. 44 + the display frame first and then write to memory. 45 45 46 46 Writeback Layer (wb_layer) 47 47 --------------------------

+1 -1

Documentation/hid/hiddev.rst

··· 65 65 ============== 66 66 67 67 This description should be read in conjunction with the HID 68 - specification, freely available from http://www.usb.org, and 68 + specification, freely available from https://www.usb.org, and 69 69 conveniently linked of http://www.linux-usb.org. 70 70 71 71 The hiddev API uses a read() interface, and a set of ioctl() calls.

+1 -1

Documentation/hid/intel-ish-hid.rst

··· 235 235 236 236 To ease in implantation and allow independent driver handle each client 237 237 this transport layer takes advantage of Linux Bus driver model. Each 238 - client is registered as device on the the transport bus (ishtp bus). 238 + client is registered as device on the transport bus (ishtp bus). 239 239 240 240 Enumeration sequence of messages: 241 241

+1 -1

Documentation/i2c/upgrading-clients.rst

··· 8 8 ------------ 9 9 10 10 This guide outlines how to alter existing Linux 2.6 client drivers from 11 - the old to the new new binding methods. 11 + the old to the new binding methods. 12 12 13 13 14 14 Example old-style driver

+1 -1

Documentation/ia64/efirtc.rst

··· 113 113 114 114 Read the current state of the alarm:: 115 115 116 - ioctl(d, RTC_WKLAM_RD, &wkt) 116 + ioctl(d, RTC_WKALM_RD, &wkt) 117 117 118 118 Set the alarm or change its status:: 119 119

+14

Documentation/index.rst

··· 182 182 183 183 filesystems/ext4/index 184 184 185 + Other documentation 186 + ------------------- 187 + 188 + There are several unsorted documents that don't seem to fit on other parts 189 + of the documentation body, or may require some adjustments and/or conversion 190 + to ReStructured Text format, or are simply too old. 191 + 192 + .. toctree:: 193 + :maxdepth: 2 194 + 195 + staging/index 196 + watch_queue 197 + 198 + 185 199 Translations 186 200 ------------ 187 201

+1 -1

Documentation/kbuild/kconfig-language.rst

··· 681 681 find dead code / features (always inactive), 114 dead features were found in 682 682 Linux using this methodology [1]_ (Section 8: Threats to validity). 683 683 684 - Confirming this could prove useful as Kconfig stands as one of the the leading 684 + Confirming this could prove useful as Kconfig stands as one of the leading 685 685 industrial variability modeling languages [1]_ [2]_. Its study would help 686 686 evaluate practical uses of such languages, their use was only theoretical 687 687 and real world requirements were not well understood. As it stands though

+9 -7

Documentation/kprobes.txt Documentation/trace/kprobes.rst

··· 20 20 10. Deprecated Features 21 21 Appendix A: The kprobes debugfs interface 22 22 Appendix B: The kprobes sysctl interface 23 + Appendix C: References 23 24 24 25 Concepts: Kprobes and Return Probes 25 26 ========================================= ··· 711 710 712 711 See samples/kprobes/kretprobe_example.c 713 712 714 - For additional information on Kprobes, refer to the following URLs: 715 - 716 - - http://www-106.ibm.com/developerworks/library/l-kprobes.html?ca=dgr-lnxw42Kprobe 717 - - http://www.redhat.com/magazine/005mar05/features/kprobes/ 718 - - http://www-users.cs.umn.edu/~boutcher/kprobes/ 719 - - http://www.linuxsymposium.org/2006/linuxsymposium_procv2.pdf (pages 101-115) 720 - 721 713 Deprecated Features 722 714 =================== 723 715 ··· 792 798 Note that this knob *changes* the optimized state. This means that optimized 793 799 probes (marked [OPTIMIZED]) will be unoptimized ([OPTIMIZED] tag will be 794 800 removed). If the knob is turned on, they will be optimized again. 801 + 802 + References 803 + ========== 804 + 805 + For additional information on Kprobes, refer to the following URLs: 806 + 807 + - https://www.ibm.com/developerworks/library/l-kprobes/index.html 808 + - https://www.kernel.org/doc/ols/2006/ols2006v2-pages-109-124.pdf 795 809

+1 -1

Documentation/leds/ledtrig-transient.rst

··· 157 157 echo 1 > activate - start timer = duration to run once 158 158 echo none > trigger 159 159 160 - This trigger is intended to be used for for the following example use cases: 160 + This trigger is intended to be used for the following example use cases: 161 161 162 162 - Control of vibrate (phones, tablets etc.) hardware by user space app. 163 163 - Use of LED by user space app as activity indicator.

+1 -1

Documentation/locking/mutex-design.rst

··· 28 28 (->owner) to keep track of the lock state during its lifetime. Field owner 29 29 actually contains `struct task_struct *` to the current lock owner and it is 30 30 therefore NULL if not currently owned. Since task_struct pointers are aligned 31 - at at least L1_CACHE_BYTES, low bits (3) are used to store extra state (e.g., 31 + to at least L1_CACHE_BYTES, low bits (3) are used to store extra state (e.g., 32 32 if waiter list is non-empty). In its most basic form it also includes a 33 33 wait-queue and a spinlock that serializes access to it. Furthermore, 34 34 CONFIG_MUTEX_SPIN_ON_OWNER=y systems use a spinner MCS lock (->osq), described

+1 -1

Documentation/locking/ww-mutex-design.rst

··· 49 49 compared to Wait-Die, but is, on the other hand, associated with more work than 50 50 Wait-Die when recovering from a backoff. Wound-Wait is also a preemptive 51 51 algorithm in that transactions are wounded by other transactions, and that 52 - requires a reliable way to pick up up the wounded condition and preempt the 52 + requires a reliable way to pick up the wounded condition and preempt the 53 53 running transaction. Note that this is not the same as process preemption. A 54 54 Wound-Wait transaction is considered preempted when it dies (returning 55 55 -EDEADLK) following a wound.

Documentation/lzo.txt Documentation/staging/lzo.rst

Documentation/mailbox.txt Documentation/driver-api/mailbox.rst

+1 -1

Documentation/maintainer/maintainer-entry-profile.rst

··· 31 31 - What branch should contributors submit against? 32 32 - Links to any other Maintainer Entry Profiles? For example a 33 33 device-driver may point to an entry for its parent subsystem. This makes 34 - the contributor aware of obligations a maintainer may have have for 34 + the contributor aware of obligations a maintainer may have for 35 35 other maintainers in the submission chain. 36 36 37 37

+1 -1

Documentation/mips/ingenic-tcu.rst

··· 5 5 =============================================== 6 6 7 7 The Timer/Counter Unit (TCU) in Ingenic JZ47xx SoCs is a multi-function 8 - hardware block. It features up to to eight channels, that can be used as 8 + hardware block. It features up to eight channels, that can be used as 9 9 counters, timers, or PWM. 10 10 11 11 - JZ4725B, JZ4750, JZ4755 only have six TCU channels. The other SoCs all

+12 -12

Documentation/misc-devices/ad525x_dpot.txt Documentation/misc-devices/ad525x_dpot.rst

··· 1 - --------------------------------- 2 - AD525x Digital Potentiometers 3 - --------------------------------- 1 + .. SPDX-License-Identifier: GPL-2.0 2 + 3 + ============================= 4 + AD525x Digital Potentiometers 5 + ============================= 4 6 5 7 The ad525x_dpot driver exports a simple sysfs interface. This allows you to 6 8 work with the immediate resistance settings as well as update the saved startup ··· 10 8 interpretation of this settings is required by the end application according to 11 9 the specific part in use. 12 10 13 - --------- 14 - Files 15 - --------- 11 + Files 12 + ===== 16 13 17 14 Each dpot device will have a set of eeprom, rdac, and tolerance files. How 18 15 many depends on the actual part you have, as will the range of allowed values. ··· 25 24 this field, please consult the datasheet for your part. This is presented 26 25 as a hex file for easier parsing. 27 26 28 - ----------- 29 - Example 30 - ----------- 27 + Example 28 + ======= 31 29 32 30 Locate the device in your sysfs tree. This is probably easiest by going into 33 - the common i2c directory and locating the device by the i2c slave address. 31 + the common i2c directory and locating the device by the i2c slave address:: 34 32 35 33 # ls /sys/bus/i2c/devices/ 36 34 0-0022 0-0027 0-002f 37 35 38 36 So assuming the device in question is on the first i2c bus and has the slave 39 - address of 0x2f, we descend (unrelated sysfs entries have been trimmed). 37 + address of 0x2f, we descend (unrelated sysfs entries have been trimmed):: 40 38 41 39 # ls /sys/bus/i2c/devices/0-002f/ 42 40 eeprom0 rdac0 tolerance0 43 41 44 - You can use simple reads/writes to access these files: 42 + You can use simple reads/writes to access these files:: 45 43 46 44 # cd /sys/bus/i2c/devices/0-002f/ 47 45

+24 -7

Documentation/misc-devices/apds990x.txt Documentation/misc-devices/apds990x.rst

··· 1 + .. SPDX-License-Identifier: GPL-2.0 2 + 3 + ====================== 1 4 Kernel driver apds990x 2 5 ====================== 3 6 ··· 53 50 54 51 power_state 55 52 RW - enable / disable chip. Uses counting logic 53 + 56 54 1 enables the chip 57 55 0 disables the chip 58 56 lux0_input 59 57 RO - measured lux value 58 + 60 59 sysfs_notify called when threshold interrupt occurs 61 60 62 61 lux0_sensor_range 63 - RO - lux0_input max value. Actually never reaches since sensor tends 62 + RO - lux0_input max value. 63 + 64 + Actually never reaches since sensor tends 64 65 to saturate much before that. Real max value varies depending 65 66 on the light spectrum etc. 66 67 ··· 75 68 RO - supported measurement rates 76 69 77 70 lux0_calibscale 78 - RW - calibration value. Set to neutral value by default. 71 + RW - calibration value. 72 + 73 + Set to neutral value by default. 79 74 Output results are multiplied with calibscale / calibscale_default 80 75 value. 81 76 ··· 85 76 RO - neutral calibration value 86 77 87 78 lux0_thresh_above_value 88 - RW - HI level threshold value. All results above the value 79 + RW - HI level threshold value. 80 + 81 + All results above the value 89 82 trigs an interrupt. 65535 (i.e. sensor_range) disables the above 90 83 interrupt. 91 84 92 85 lux0_thresh_below_value 93 - RW - LO level threshold value. All results below the value 86 + RW - LO level threshold value. 87 + 88 + All results below the value 94 89 trigs an interrupt. 0 disables the below interrupt. 95 90 96 91 prox0_raw 97 92 RO - measured proximity value 93 + 98 94 sysfs_notify called when threshold interrupt occurs 99 95 100 96 prox0_sensor_range ··· 107 93 108 94 prox0_raw_en 109 95 RW - enable / disable proximity - uses counting logic 110 - 1 enables the proximity 111 - 0 disables the proximity 96 + 97 + - 1 enables the proximity 98 + - 0 disables the proximity 112 99 113 100 prox0_reporting_mode 114 - RW - trigger / periodic. In "trigger" mode the driver tells two possible 101 + RW - trigger / periodic. 102 + 103 + In "trigger" mode the driver tells two possible 115 104 values: 0 or prox0_sensor_range value. 0 means no proximity, 116 105 1023 means proximity. This causes minimal number of interrupts. 117 106 In "periodic" mode the driver reports all values above

+32 -13

Documentation/misc-devices/bh1770glc.txt Documentation/misc-devices/bh1770glc.rst

··· 1 + .. SPDX-License-Identifier: GPL-2.0 2 + 3 + ======================= 1 4 Kernel driver bh1770glc 2 5 ======================= 3 6 4 7 Supported chips: 5 - ROHM BH1770GLC 6 - OSRAM SFH7770 8 + 9 + - ROHM BH1770GLC 10 + - OSRAM SFH7770 7 11 8 12 Data sheet: 9 13 Not freely available ··· 52 48 RO - shows detected chip type and version 53 49 54 50 power_state 55 - RW - enable / disable chip. Uses counting logic 56 - 1 enables the chip 57 - 0 disables the chip 51 + RW - enable / disable chip 52 + 53 + Uses counting logic 54 + 55 + - 1 enables the chip 56 + - 0 disables the chip 58 57 59 58 lux0_input 60 59 RO - measured lux value 60 + 61 61 sysfs_notify called when threshold interrupt occurs 62 62 63 63 lux0_sensor_range ··· 74 66 RO - supported measurement rates 75 67 76 68 lux0_thresh_above_value 77 - RW - HI level threshold value. All results above the value 69 + RW - HI level threshold value 70 + 71 + All results above the value 78 72 trigs an interrupt. 65535 (i.e. sensor_range) disables the above 79 73 interrupt. 80 74 81 75 lux0_thresh_below_value 82 - RW - LO level threshold value. All results below the value 76 + RW - LO level threshold value 77 + 78 + All results below the value 83 79 trigs an interrupt. 0 disables the below interrupt. 84 80 85 81 lux0_calibscale 86 - RW - calibration value. Set to neutral value by default. 82 + RW - calibration value 83 + 84 + Set to neutral value by default. 87 85 Output results are multiplied with calibscale / calibscale_default 88 86 value. 89 87 ··· 98 84 99 85 prox0_raw 100 86 RO - measured proximity value 87 + 101 88 sysfs_notify called when threshold interrupt occurs 102 89 103 90 prox0_sensor_range 104 91 RO - prox0_raw max value 105 92 106 93 prox0_raw_en 107 - RW - enable / disable proximity - uses counting logic 108 - 1 enables the proximity 109 - 0 disables the proximity 94 + RW - enable / disable proximity 95 + 96 + Uses counting logic 97 + 98 + - 1 enables the proximity 99 + - 0 disables the proximity 110 100 111 101 prox0_thresh_above_count 112 102 RW - number of proximity interrupts needed before triggering the event 113 103 114 104 prox0_rate_above 115 105 RW - Measurement rate (in Hz) when the level is above threshold 116 - i.e. when proximity on has been reported. 106 + i.e. when proximity on has been reported. 117 107 118 108 prox0_rate_below 119 109 RW - Measurement rate (in Hz) when the level is below threshold 120 - i.e. when proximity off has been reported. 110 + i.e. when proximity off has been reported. 121 111 122 112 prox0_rate_avail 123 113 RO - Supported proximity measurement rates in Hz 124 114 125 115 prox0_thresh_above0_value 126 116 RW - threshold level which trigs proximity events. 117 + 127 118 Filtered by persistence filter (prox0_thresh_above_count) 128 119 129 120 prox0_thresh_above1_value

+30 -26

Documentation/misc-devices/c2port.txt Documentation/misc-devices/c2port.rst

··· 1 - C2 port support 2 - --------------- 1 + .. SPDX-License-Identifier: GPL-2.0 2 + .. include:: <isonum.txt> 3 + 4 + =============== 5 + C2 port support 6 + =============== 3 7 4 8 (C) Copyright 2007 Rodolfo Giometti <giometti@enneenne.com> 5 9 ··· 36 32 Silicon Laboratories site], see: 37 33 38 34 - AN127: FLASH Programming via the C2 Interface at 39 - https://www.silabs.com/Support Documents/TechnicalDocs/an127.pdf 35 + https://www.silabs.com/Support Documents/TechnicalDocs/an127.pdf 40 36 41 37 - C2 Specification at 42 - https://www.silabs.com/pages/DownloadDoc.aspx?FILEURL=Support%20Documents/TechnicalDocs/an127.pdf&src=SearchResults 38 + https://www.silabs.com/pages/DownloadDoc.aspx?FILEURL=Support%20Documents/TechnicalDocs/an127.pdf&src=SearchResults 43 39 44 40 however it implements a two wire serial communication protocol (bit 45 41 banging) designed to enable in-system programming, debugging, and ··· 51 47 ---------------- 52 48 53 49 Once the driver is loaded you can use sysfs support to get C2port's 54 - info or read/write in-system flash. 50 + info or read/write in-system flash:: 55 51 56 - # ls /sys/class/c2port/c2port0/ 57 - access flash_block_size flash_erase rev_id 58 - dev_id flash_blocks_num flash_size subsystem/ 59 - flash_access flash_data reset uevent 52 + # ls /sys/class/c2port/c2port0/ 53 + access flash_block_size flash_erase rev_id 54 + dev_id flash_blocks_num flash_size subsystem/ 55 + flash_access flash_data reset uevent 60 56 61 57 Initially the C2port access is disabled since you hardware may have 62 58 such lines multiplexed with other devices so, to get access to the 63 - C2port, you need the command: 59 + C2port, you need the command:: 64 60 65 - # echo 1 > /sys/class/c2port/c2port0/access 61 + # echo 1 > /sys/class/c2port/c2port0/access 66 62 67 63 after that you should read the device ID and revision ID of the 68 - connected micro controller: 64 + connected micro controller:: 69 65 70 - # cat /sys/class/c2port/c2port0/dev_id 71 - 8 72 - # cat /sys/class/c2port/c2port0/rev_id 73 - 1 66 + # cat /sys/class/c2port/c2port0/dev_id 67 + 8 68 + # cat /sys/class/c2port/c2port0/rev_id 69 + 1 74 70 75 71 However, for security reasons, the in-system flash access in not 76 - enabled yet, to do so you need the command: 72 + enabled yet, to do so you need the command:: 77 73 78 - # echo 1 > /sys/class/c2port/c2port0/flash_access 74 + # echo 1 > /sys/class/c2port/c2port0/flash_access 79 75 80 - After that you can read the whole flash: 76 + After that you can read the whole flash:: 81 77 82 - # cat /sys/class/c2port/c2port0/flash_data > image 78 + # cat /sys/class/c2port/c2port0/flash_data > image 83 79 84 - erase it: 80 + erase it:: 85 81 86 - # echo 1 > /sys/class/c2port/c2port0/flash_erase 82 + # echo 1 > /sys/class/c2port/c2port0/flash_erase 87 83 88 - and write it: 84 + and write it:: 89 85 90 - # cat image > /sys/class/c2port/c2port0/flash_data 86 + # cat image > /sys/class/c2port/c2port0/flash_data 91 87 92 - after writing you have to reset the device to execute the new code: 88 + after writing you have to reset the device to execute the new code:: 93 89 94 - # echo 1 > /sys/class/c2port/c2port0/reset 90 + # echo 1 > /sys/class/c2port/c2port0/reset

+6

Documentation/misc-devices/index.rst

··· 14 14 .. toctree:: 15 15 :maxdepth: 2 16 16 17 + ad525x_dpot 18 + apds990x 19 + bh1770glc 17 20 eeprom 21 + c2port 18 22 ibmvmc 19 23 ics932s401 20 24 isl29003 21 25 lis3lv02d 22 26 max6875 23 27 mic/index 28 + pci-endpoint-test 29 + spear-pcie-gadget 24 30 uacce 25 31 xilinx_sdfec

+56

Documentation/misc-devices/pci-endpoint-test.rst

··· 1 + .. SPDX-License-Identifier: GPL-2.0 2 + 3 + ===================================== 4 + Driver for PCI Endpoint Test Function 5 + ===================================== 6 + 7 + This driver should be used as a host side driver if the root complex is 8 + connected to a configurable PCI endpoint running ``pci_epf_test`` function 9 + driver configured according to [1]_. 10 + 11 + The "pci_endpoint_test" driver can be used to perform the following tests. 12 + 13 + The PCI driver for the test device performs the following tests: 14 + 15 + #) verifying addresses programmed in BAR 16 + #) raise legacy IRQ 17 + #) raise MSI IRQ 18 + #) raise MSI-X IRQ 19 + #) read data 20 + #) write data 21 + #) copy data 22 + 23 + This misc driver creates /dev/pci-endpoint-test.<num> for every 24 + ``pci_epf_test`` function connected to the root complex and "ioctls" 25 + should be used to perform the above tests. 26 + 27 + ioctl 28 + ----- 29 + 30 + PCITEST_BAR: 31 + Tests the BAR. The number of the BAR to be tested 32 + should be passed as argument. 33 + PCITEST_LEGACY_IRQ: 34 + Tests legacy IRQ 35 + PCITEST_MSI: 36 + Tests message signalled interrupts. The MSI number 37 + to be tested should be passed as argument. 38 + PCITEST_MSIX: 39 + Tests message signalled interrupts. The MSI-X number 40 + to be tested should be passed as argument. 41 + PCITEST_SET_IRQTYPE: 42 + Changes driver IRQ type configuration. The IRQ type 43 + should be passed as argument (0: Legacy, 1:MSI, 2:MSI-X). 44 + PCITEST_GET_IRQTYPE: 45 + Gets driver IRQ type configuration. 46 + PCITEST_WRITE: 47 + Perform write tests. The size of the buffer should be passed 48 + as argument. 49 + PCITEST_READ: 50 + Perform read tests. The size of the buffer should be passed 51 + as argument. 52 + PCITEST_COPY: 53 + Perform read tests. The size of the buffer should be passed 54 + as argument. 55 + 56 + .. [1] Documentation/PCI/endpoint/function/binding/pci-test.rst

-41

Documentation/misc-devices/pci-endpoint-test.txt

··· 1 - Driver for PCI Endpoint Test Function 2 - 3 - This driver should be used as a host side driver if the root complex is 4 - connected to a configurable PCI endpoint running *pci_epf_test* function 5 - driver configured according to [1]. 6 - 7 - The "pci_endpoint_test" driver can be used to perform the following tests. 8 - 9 - The PCI driver for the test device performs the following tests 10 - *) verifying addresses programmed in BAR 11 - *) raise legacy IRQ 12 - *) raise MSI IRQ 13 - *) raise MSI-X IRQ 14 - *) read data 15 - *) write data 16 - *) copy data 17 - 18 - This misc driver creates /dev/pci-endpoint-test.<num> for every 19 - *pci_epf_test* function connected to the root complex and "ioctls" 20 - should be used to perform the above tests. 21 - 22 - ioctl 23 - ----- 24 - PCITEST_BAR: Tests the BAR. The number of the BAR to be tested 25 - should be passed as argument. 26 - PCITEST_LEGACY_IRQ: Tests legacy IRQ 27 - PCITEST_MSI: Tests message signalled interrupts. The MSI number 28 - to be tested should be passed as argument. 29 - PCITEST_MSIX: Tests message signalled interrupts. The MSI-X number 30 - to be tested should be passed as argument. 31 - PCITEST_SET_IRQTYPE: Changes driver IRQ type configuration. The IRQ type 32 - should be passed as argument (0: Legacy, 1:MSI, 2:MSI-X). 33 - PCITEST_GET_IRQTYPE: Gets driver IRQ type configuration. 34 - PCITEST_WRITE: Perform write tests. The size of the buffer should be passed 35 - as argument. 36 - PCITEST_READ: Perform read tests. The size of the buffer should be passed 37 - as argument. 38 - PCITEST_COPY: Perform read tests. The size of the buffer should be passed 39 - as argument. 40 - 41 - [1] -> Documentation/PCI/endpoint/function/binding/pci-test.txt

+170

Documentation/misc-devices/spear-pcie-gadget.rst

··· 1 + .. SPDX-License-Identifier: GPL-2.0 2 + 3 + ======================== 4 + Spear PCIe Gadget Driver 5 + ======================== 6 + 7 + Author 8 + ====== 9 + Pratyush Anand (pratyush.anand@gmail.com) 10 + 11 + Location 12 + ======== 13 + driver/misc/spear13xx_pcie_gadget.c 14 + 15 + Supported Chip: 16 + =============== 17 + SPEAr1300 18 + SPEAr1310 19 + 20 + Menuconfig option: 21 + ================== 22 + Device Drivers 23 + Misc devices 24 + PCIe gadget support for SPEAr13XX platform 25 + 26 + purpose 27 + ======= 28 + This driver has several nodes which can be read/written by configfs interface. 29 + Its main purpose is to configure selected dual mode PCIe controller as device 30 + and then program its various registers to configure it as a particular device 31 + type. This driver can be used to show spear's PCIe device capability. 32 + 33 + Description of different nodes: 34 + =============================== 35 + 36 + read behavior of nodes: 37 + ----------------------- 38 + 39 + =============== ============================================================== 40 + link gives ltssm status. 41 + int_type type of supported interrupt 42 + no_of_msi zero if MSI is not enabled by host. A positive value is the 43 + number of MSI vector granted. 44 + vendor_id returns programmed vendor id (hex) 45 + device_id returns programmed device id(hex) 46 + bar0_size: returns size of bar0 in hex. 47 + bar0_address returns address of bar0 mapped area in hex. 48 + bar0_rw_offset returns offset of bar0 for which bar0_data will return value. 49 + bar0_data returns data at bar0_rw_offset. 50 + =============== ============================================================== 51 + 52 + write behavior of nodes: 53 + ------------------------ 54 + 55 + =============== ================================================================ 56 + link write UP to enable ltsmm DOWN to disable 57 + int_type write interrupt type to be configured and (int_type could be 58 + INTA, MSI or NO_INT). Select MSI only when you have programmed 59 + no_of_msi node. 60 + no_of_msi number of MSI vector needed. 61 + inta write 1 to assert INTA and 0 to de-assert. 62 + send_msi write MSI vector to be sent. 63 + vendor_id write vendor id(hex) to be programmed. 64 + device_id write device id(hex) to be programmed. 65 + bar0_size write size of bar0 in hex. default bar0 size is 1000 (hex) 66 + bytes. 67 + bar0_address write address of bar0 mapped area in hex. (default mapping of 68 + bar0 is SYSRAM1(E0800000). Always program bar size before bar 69 + address. Kernel might modify bar size and address for alignment, 70 + so read back bar size and address after writing to cross check. 71 + bar0_rw_offset write offset of bar0 for which bar0_data will write value. 72 + bar0_data write data to be written at bar0_rw_offset. 73 + =============== ================================================================ 74 + 75 + Node programming example 76 + ======================== 77 + 78 + Program all PCIe registers in such a way that when this device is connected 79 + to the PCIe host, then host sees this device as 1MB RAM. 80 + 81 + :: 82 + 83 + #mount -t configfs none /Config 84 + 85 + For nth PCIe Device Controller:: 86 + 87 + # cd /config/pcie_gadget.n/ 88 + 89 + Now you have all the nodes in this directory. 90 + program vendor id as 0x104a:: 91 + 92 + # echo 104A >> vendor_id 93 + 94 + program device id as 0xCD80:: 95 + 96 + # echo CD80 >> device_id 97 + 98 + program BAR0 size as 1MB:: 99 + 100 + # echo 100000 >> bar0_size 101 + 102 + check for programmed bar0 size:: 103 + 104 + # cat bar0_size 105 + 106 + Program BAR0 Address as DDR (0x2100000). This is the physical address of 107 + memory, which is to be made visible to PCIe host. Similarly any other peripheral 108 + can also be made visible to PCIe host. E.g., if you program base address of UART 109 + as BAR0 address then when this device will be connected to a host, it will be 110 + visible as UART. 111 + 112 + :: 113 + 114 + # echo 2100000 >> bar0_address 115 + 116 + program interrupt type : INTA:: 117 + 118 + # echo INTA >> int_type 119 + 120 + go for link up now:: 121 + 122 + # echo UP >> link 123 + 124 + It will have to be insured that, once link up is done on gadget, then only host 125 + is initialized and start to search PCIe devices on its port. 126 + 127 + :: 128 + 129 + /*wait till link is up*/ 130 + # cat link 131 + 132 + Wait till it returns UP. 133 + 134 + To assert INTA:: 135 + 136 + # echo 1 >> inta 137 + 138 + To de-assert INTA:: 139 + 140 + # echo 0 >> inta 141 + 142 + if MSI is to be used as interrupt, program no of msi vector needed (say4):: 143 + 144 + # echo 4 >> no_of_msi 145 + 146 + select MSI as interrupt type:: 147 + 148 + # echo MSI >> int_type 149 + 150 + go for link up now:: 151 + 152 + # echo UP >> link 153 + 154 + wait till link is up:: 155 + 156 + # cat link 157 + 158 + An application can repetitively read this node till link is found UP. It can 159 + sleep between two read. 160 + 161 + wait till msi is enabled:: 162 + 163 + # cat no_of_msi 164 + 165 + Should return 4 (number of requested MSI vector) 166 + 167 + to send msi vector 2:: 168 + 169 + # echo 2 >> send_msi 170 + # cd -

-130

Documentation/misc-devices/spear-pcie-gadget.txt

··· 1 - Spear PCIe Gadget Driver: 2 - 3 - Author 4 - ============= 5 - Pratyush Anand (pratyush.anand@gmail.com) 6 - 7 - Location 8 - ============ 9 - driver/misc/spear13xx_pcie_gadget.c 10 - 11 - Supported Chip: 12 - =================== 13 - SPEAr1300 14 - SPEAr1310 15 - 16 - Menuconfig option: 17 - ========================== 18 - Device Drivers 19 - Misc devices 20 - PCIe gadget support for SPEAr13XX platform 21 - purpose 22 - =========== 23 - This driver has several nodes which can be read/written by configfs interface. 24 - Its main purpose is to configure selected dual mode PCIe controller as device 25 - and then program its various registers to configure it as a particular device 26 - type. This driver can be used to show spear's PCIe device capability. 27 - 28 - Description of different nodes: 29 - ================================= 30 - 31 - read behavior of nodes: 32 - ------------------------------ 33 - link :gives ltssm status. 34 - int_type :type of supported interrupt 35 - no_of_msi :zero if MSI is not enabled by host. A positive value is the 36 - number of MSI vector granted. 37 - vendor_id :returns programmed vendor id (hex) 38 - device_id :returns programmed device id(hex) 39 - bar0_size: :returns size of bar0 in hex. 40 - bar0_address :returns address of bar0 mapped area in hex. 41 - bar0_rw_offset :returns offset of bar0 for which bar0_data will return value. 42 - bar0_data :returns data at bar0_rw_offset. 43 - 44 - write behavior of nodes: 45 - ------------------------------ 46 - link :write UP to enable ltsmm DOWN to disable 47 - int_type :write interrupt type to be configured and (int_type could be 48 - INTA, MSI or NO_INT). Select MSI only when you have programmed 49 - no_of_msi node. 50 - no_of_msi :number of MSI vector needed. 51 - inta :write 1 to assert INTA and 0 to de-assert. 52 - send_msi :write MSI vector to be sent. 53 - vendor_id :write vendor id(hex) to be programmed. 54 - device_id :write device id(hex) to be programmed. 55 - bar0_size :write size of bar0 in hex. default bar0 size is 1000 (hex) 56 - bytes. 57 - bar0_address :write address of bar0 mapped area in hex. (default mapping of 58 - bar0 is SYSRAM1(E0800000). Always program bar size before bar 59 - address. Kernel might modify bar size and address for alignment, so 60 - read back bar size and address after writing to cross check. 61 - bar0_rw_offset :write offset of bar0 for which bar0_data will write value. 62 - bar0_data :write data to be written at bar0_rw_offset. 63 - 64 - Node programming example 65 - =========================== 66 - Program all PCIe registers in such a way that when this device is connected 67 - to the PCIe host, then host sees this device as 1MB RAM. 68 - #mount -t configfs none /Config 69 - For nth PCIe Device Controller 70 - # cd /config/pcie_gadget.n/ 71 - Now you have all the nodes in this directory. 72 - program vendor id as 0x104a 73 - # echo 104A >> vendor_id 74 - 75 - program device id as 0xCD80 76 - # echo CD80 >> device_id 77 - 78 - program BAR0 size as 1MB 79 - # echo 100000 >> bar0_size 80 - 81 - check for programmed bar0 size 82 - # cat bar0_size 83 - 84 - Program BAR0 Address as DDR (0x2100000). This is the physical address of 85 - memory, which is to be made visible to PCIe host. Similarly any other peripheral 86 - can also be made visible to PCIe host. E.g., if you program base address of UART 87 - as BAR0 address then when this device will be connected to a host, it will be 88 - visible as UART. 89 - # echo 2100000 >> bar0_address 90 - 91 - program interrupt type : INTA 92 - # echo INTA >> int_type 93 - 94 - go for link up now. 95 - # echo UP >> link 96 - 97 - It will have to be insured that, once link up is done on gadget, then only host 98 - is initialized and start to search PCIe devices on its port. 99 - 100 - /*wait till link is up*/ 101 - # cat link 102 - wait till it returns UP. 103 - 104 - To assert INTA 105 - # echo 1 >> inta 106 - 107 - To de-assert INTA 108 - # echo 0 >> inta 109 - 110 - if MSI is to be used as interrupt, program no of msi vector needed (say4) 111 - # echo 4 >> no_of_msi 112 - 113 - select MSI as interrupt type 114 - # echo MSI >> int_type 115 - 116 - go for link up now 117 - # echo UP >> link 118 - 119 - wait till link is up 120 - # cat link 121 - An application can repetitively read this node till link is found UP. It can 122 - sleep between two read. 123 - 124 - wait till msi is enabled 125 - # cat no_of_msi 126 - Should return 4 (number of requested MSI vector) 127 - 128 - to send msi vector 2 129 - # echo 2 >> send_msi 130 - #cd -

+1 -1

Documentation/misc-devices/xilinx_sdfec.rst

··· 78 78 - open: Implements restriction that only a single file descriptor can be open per SD-FEC instance at any time 79 79 - release: Allows another file descriptor to be open, that is after current file descriptor is closed 80 80 - poll: Provides a method to monitor for SD-FEC Error events 81 - - unlocked_ioctl: Provides the the following ioctl commands that allows the application configure the SD-FEC core: 81 + - unlocked_ioctl: Provides the following ioctl commands that allows the application configure the SD-FEC core: 82 82 83 83 - :c:macro:`XSDFEC_START_DEV` 84 84 - :c:macro:`XSDFEC_STOP_DEV`

Documentation/nommu-mmap.txt Documentation/admin-guide/mm/nommu-mmap.rst

+1 -1

Documentation/openrisc/openrisc_port.rst

··· 8 8 For information about OpenRISC processors and ongoing development: 9 9 10 10 ======= ============================= 11 - website http://openrisc.io 11 + website https://openrisc.io 12 12 email openrisc@lists.librecores.org 13 13 ======= ============================= 14 14

+1

Documentation/powerpc/index.rst

··· 31 31 transactional_memory 32 32 ultravisor 33 33 vas-api 34 + vcpudispatch_stats 34 35 35 36 .. only:: subproject and html 36 37

+19 -6

Documentation/powerpc/vas-api.rst

··· 43 43 should use the mmap() system call to map the hardware address of engine's 44 44 request queue into the application's virtual address space. 45 45 46 - The application can then submit one or more requests to the the engine by 46 + The application can then submit one or more requests to the engine by 47 47 using copy/paste instructions and pasting the CRBs to the virtual address 48 48 (aka paste_address) returned by mmap(). User space can close the 49 49 established connection or send window by closing the file descriptior ··· 87 87 the vas_id field in the VAS_TX_WIN_OPEN ioctl as detailed below. 88 88 89 89 A userspace library libnxz is available here but still in development: 90 + 90 91 https://github.com/abalib/power-gzip 91 92 92 93 Applications that use inflate / deflate calls can link with libnxz ··· 111 110 a connection with NX co-processor engine: 112 111 113 112 :: 113 + 114 114 struct vas_tx_win_open_attr { 115 115 __u32 version; 116 116 __s16 vas_id; /* specific instance of vas or -1 ··· 121 119 __u64 reserved2[6]; 122 120 }; 123 121 124 - version: The version field must be currently set to 1. 125 - vas_id: If '-1' is passed, kernel will make a best-effort attempt 122 + version: 123 + The version field must be currently set to 1. 124 + vas_id: 125 + If '-1' is passed, kernel will make a best-effort attempt 126 126 to assign an optimal instance of NX for the process. To 127 127 select the specific VAS instance, refer 128 128 "Discovery of available VAS engines" section below. ··· 133 129 and must be set to 0. 134 130 135 131 The attributes attr for the VAS_TX_WIN_OPEN ioctl are defined as 136 - follows: 132 + follows:: 133 + 137 134 #define VAS_MAGIC 'v' 138 135 #define VAS_TX_WIN_OPEN _IOW(VAS_MAGIC, 1, 139 136 struct vas_tx_win_open_attr) ··· 146 141 returns -1 and sets the errno variable to indicate the error. 147 142 148 143 Error conditions: 144 + 145 + ====== ================================================ 149 146 EINVAL fd does not refer to a valid VAS device. 150 147 EINVAL Invalid vas ID 151 148 EINVAL version is not set with proper value ··· 156 149 ENOSPC System has too many active windows (connections) 157 150 opened 158 151 EINVAL reserved fields are not set to 0. 152 + ====== ================================================ 159 153 160 154 See the ioctl(2) man page for more details, error codes and 161 155 restrictions. ··· 166 158 167 159 The mmap() system call for a NX-GZIP device fd returns a paste_address 168 160 that the application can use to copy/paste its CRB to the hardware engines. 161 + 169 162 :: 170 163 171 164 paste_addr = mmap(addr, size, prot, flags, fd, offset); 172 165 173 166 Only restrictions on mmap for a NX-GZIP device fd are: 167 + 174 168 * size should be PAGE_SIZE 175 169 * offset parameter should be 0ULL 176 170 ··· 180 170 In addition to the error conditions listed on the mmap(2) man 181 171 page, can also fail with one of the following error codes: 182 172 173 + ====== ============================================= 183 174 EINVAL fd is not associated with an open window 184 175 (i.e mmap() does not follow a successful call 185 176 to the VAS_TX_WIN_OPEN ioctl). 186 177 EINVAL offset field is not 0ULL. 178 + ====== ============================================= 187 179 188 180 Discovery of available VAS engines 189 181 ================================== ··· 222 210 address or any request buffer, raises an interrupt on the CPU to handle the 223 211 fault. Page fault can happen if an application passes invalid addresses or 224 212 request buffers are not in memory. The operating system handles the fault by 225 - updating CSB with the following data: 213 + updating CSB with the following data:: 226 214 227 215 csb.flags = CSB_V; 228 216 csb.cc = CSB_CC_FAULT_ADDRESS; ··· 235 223 236 224 If the OS can not update CSB due to invalid CSB address, sends SEGV signal 237 225 to the process who opened the send window on which the original request was 238 - issued. This signal returns with the following siginfo struct: 226 + issued. This signal returns with the following siginfo struct:: 239 227 240 228 siginfo.si_signo = SIGSEGV; 241 229 siginfo.si_errno = EFAULT; ··· 260 248 ============== 261 249 262 250 :: 251 + 263 252 int use_nx_gzip() 264 253 { 265 254 int rc, fd;

+12 -5

Documentation/powerpc/vcpudispatch_stats.txt Documentation/powerpc/vcpudispatch_stats.rst

··· 1 - VCPU Dispatch Statistics: 2 - ========================= 1 + .. SPDX-License-Identifier: GPL-2.0 2 + 3 + ======================== 4 + VCPU Dispatch Statistics 5 + ======================== 3 6 4 7 For Shared Processor LPARs, the POWER Hypervisor maintains a relatively 5 8 static mapping of the LPAR processors (vcpus) to physical processor ··· 23 20 a vcpu as represented by the first field, followed by 8 numbers. 24 21 25 22 The first number corresponds to: 23 + 26 24 1. total vcpu dispatches since the beginning of statistics collection 27 25 28 26 The next 4 numbers represent vcpu dispatch dispersions: 27 + 29 28 2. number of times this vcpu was dispatched on the same processor as last 30 29 time 31 30 3. number of times this vcpu was dispatched on a different processor core 32 31 as last time, but within the same chip 33 32 4. number of times this vcpu was dispatched on a different chip 34 33 5. number of times this vcpu was dispatches on a different socket/drawer 35 - (next numa boundary) 34 + (next numa boundary) 36 35 37 36 The final 3 numbers represent statistics in relation to the home node of 38 37 the vcpu: 38 + 39 39 6. number of times this vcpu was dispatched in its home node (chip) 40 40 7. number of times this vcpu was dispatched in a different node 41 41 8. number of times this vcpu was dispatched in a node further away (numa 42 - distance) 42 + distance) 43 43 44 - An example output: 44 + An example output:: 45 + 45 46 $ sudo cat /proc/powerpc/vcpudispatch_stats 46 47 cpu0 6839 4126 2683 30 0 6821 18 0 47 48 cpu1 2515 1274 1229 12 0 2509 6 0

+6 -6

Documentation/process/2.Process.rst

··· 295 295 The current -mm patch is available in the "mmotm" (-mm of the moment) 296 296 directory at: 297 297 298 - http://www.ozlabs.org/~akpm/mmotm/ 298 + https://www.ozlabs.org/~akpm/mmotm/ 299 299 300 300 Use of the MMOTM tree is likely to be a frustrating experience, though; 301 301 there is a definite chance that it will not even compile. ··· 306 306 Linux-next trees are announced on the linux-kernel and linux-next mailing 307 307 lists when they are assembled; they can be downloaded from: 308 308 309 - http://www.kernel.org/pub/linux/kernel/next/ 309 + https://www.kernel.org/pub/linux/kernel/next/ 310 310 311 311 Linux-next has become an integral part of the kernel development process; 312 312 all patches merged during a given merge window should really have found ··· 365 365 Git is now packaged by almost all Linux distributions. There is a home 366 366 page at: 367 367 368 - http://git-scm.com/ 368 + https://git-scm.com/ 369 369 370 370 That page has pointers to documentation and tutorials. 371 371 372 372 Among the kernel developers who do not use git, the most popular choice is 373 373 almost certainly Mercurial: 374 374 375 - http://www.selenic.com/mercurial/ 375 + https://www.selenic.com/mercurial/ 376 376 377 377 Mercurial shares many features with git, but it provides an interface which 378 378 many find easier to use. 379 379 380 380 The other tool worth knowing about is Quilt: 381 381 382 - http://savannah.nongnu.org/projects/quilt/ 382 + https://savannah.nongnu.org/projects/quilt/ 383 383 384 384 Quilt is a patch management system, rather than a source code management 385 385 system. It does not track history over time; it is, instead, oriented ··· 494 494 with others on getting things fixed up (this can require 495 495 persistence!) but that's fine - it's a part of kernel development. 496 496 497 - (http://lwn.net/Articles/283982/). 497 + (https://lwn.net/Articles/283982/). 498 498 499 499 In the absence of obvious problems to fix, developers are advised to look 500 500 at the current lists of regressions and open bugs in general. There is

+2 -2

Documentation/process/4.Coding.rst

··· 210 210 progress at all. Is it two steps forwards, one step back, or one 211 211 step forward and two steps back? 212 212 213 - (http://lwn.net/Articles/243460/). 213 + (https://lwn.net/Articles/243460/). 214 214 215 215 An especially unwelcome type of regression is any sort of change to the 216 216 user-space ABI. Once an interface has been exported to user space, it must ··· 323 323 Blackfin development board handy, you can still perform the compilation 324 324 step. A large set of cross compilers for x86 systems can be found at 325 325 326 - http://www.kernel.org/pub/tools/crosstool/ 326 + https://www.kernel.org/pub/tools/crosstool/ 327 327 328 328 Some time spent installing and using these compilers will help avoid 329 329 embarrassment later.

+1 -1

Documentation/process/botching-up-ioctls.rst

··· 2 2 (How to avoid) Botching up ioctls 3 3 ================================= 4 4 5 - From: http://blog.ffwll.ch/2013/11/botching-up-ioctls.html 5 + From: https://blog.ffwll.ch/2013/11/botching-up-ioctls.html 6 6 7 7 By: Daniel Vetter, Copyright © 2013 Intel Corporation 8 8

+3 -3

Documentation/process/changes.rst

··· 129 129 --------------------- 130 130 131 131 DevFS has been obsoleted in favour of udev 132 - (http://www.kernel.org/pub/linux/utils/kernel/hotplug/) 132 + (https://www.kernel.org/pub/linux/utils/kernel/hotplug/) 133 133 134 134 32-bit UID support is now in place. Have fun! 135 135 ··· 421 421 udev 422 422 ---- 423 423 424 - - <http://www.freedesktop.org/software/systemd/man/udev.html> 424 + - <https://www.freedesktop.org/software/systemd/man/udev.html> 425 425 426 426 FUSE 427 427 ---- ··· 474 474 Sphinx 475 475 ------ 476 476 477 - - <http://www.sphinx-doc.org/> 477 + - <https://www.sphinx-doc.org/>

+1 -1

Documentation/process/clang-format.rst

··· 32 32 your repositories. Otherwise, you can either download pre-built 33 33 LLVM/clang binaries or build the source code from: 34 34 35 - http://releases.llvm.org/download.html 35 + https://releases.llvm.org/download.html 36 36 37 37 See more information about the tool at: 38 38

+1 -1

Documentation/process/coding-style.rst

··· 1149 1149 ISBN 0-201-61586-X. 1150 1150 1151 1151 GNU manuals - where in compliance with K&R and this text - for cpp, gcc, 1152 - gcc internals and indent, all available from http://www.gnu.org/manual/ 1152 + gcc internals and indent, all available from https://www.gnu.org/manual/ 1153 1153 1154 1154 WG14 is the international standardization working group for the programming 1155 1155 language C, URL: http://www.open-std.org/JTC1/SC22/WG14/

+118

Documentation/process/deprecated.rst

··· 103 103 104 104 header = kzalloc(struct_size(header, item, count), GFP_KERNEL); 105 105 106 + .. note:: If you are using struct_size() on a structure containing a zero-length 107 + or a one-element array as a trailing array member, please refactor such 108 + array usage and switch to a `flexible array member 109 + <#zero-length-and-one-element-arrays>`_ instead. 110 + 106 111 See array_size(), array3_size(), and struct_size(), 107 112 for more details as well as the related check_add_overflow() and 108 113 check_mul_overflow() family of functions. ··· 223 218 * continue; 224 219 * goto <label>; 225 220 * return [expression]; 221 + 222 + Zero-length and one-element arrays 223 + ---------------------------------- 224 + There is a regular need in the kernel to provide a way to declare having 225 + a dynamically sized set of trailing elements in a structure. Kernel code 226 + should always use `"flexible array members" <https://en.wikipedia.org/wiki/Flexible_array_member>`_ 227 + for these cases. The older style of one-element or zero-length arrays should 228 + no longer be used. 229 + 230 + In older C code, dynamically sized trailing elements were done by specifying 231 + a one-element array at the end of a structure:: 232 + 233 + struct something { 234 + size_t count; 235 + struct foo items[1]; 236 + }; 237 + 238 + This led to fragile size calculations via sizeof() (which would need to 239 + remove the size of the single trailing element to get a correct size of 240 + the "header"). A `GNU C extension <https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_ 241 + was introduced to allow for zero-length arrays, to avoid these kinds of 242 + size problems:: 243 + 244 + struct something { 245 + size_t count; 246 + struct foo items[0]; 247 + }; 248 + 249 + But this led to other problems, and didn't solve some problems shared by 250 + both styles, like not being able to detect when such an array is accidentally 251 + being used _not_ at the end of a structure (which could happen directly, or 252 + when such a struct was in unions, structs of structs, etc). 253 + 254 + C99 introduced "flexible array members", which lacks a numeric size for 255 + the array declaration entirely:: 256 + 257 + struct something { 258 + size_t count; 259 + struct foo items[]; 260 + }; 261 + 262 + This is the way the kernel expects dynamically sized trailing elements 263 + to be declared. It allows the compiler to generate errors when the 264 + flexible array does not occur last in the structure, which helps to prevent 265 + some kind of `undefined behavior 266 + <https://git.kernel.org/linus/76497732932f15e7323dc805e8ea8dc11bb587cf>`_ 267 + bugs from being inadvertently introduced to the codebase. It also allows 268 + the compiler to correctly analyze array sizes (via sizeof(), 269 + `CONFIG_FORTIFY_SOURCE`, and `CONFIG_UBSAN_BOUNDS`). For instance, 270 + there is no mechanism that warns us that the following application of the 271 + sizeof() operator to a zero-length array always results in zero:: 272 + 273 + struct something { 274 + size_t count; 275 + struct foo items[0]; 276 + }; 277 + 278 + struct something *instance; 279 + 280 + instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL); 281 + instance->count = count; 282 + 283 + size = sizeof(instance->items) * instance->count; 284 + memcpy(instance->items, source, size); 285 + 286 + At the last line of code above, ``size`` turns out to be ``zero``, when one might 287 + have thought it represents the total size in bytes of the dynamic memory recently 288 + allocated for the trailing array ``items``. Here are a couple examples of this 289 + issue: `link 1 290 + <https://git.kernel.org/linus/f2cd32a443da694ac4e28fbf4ac6f9d5cc63a539>`_, 291 + `link 2 292 + <https://git.kernel.org/linus/ab91c2a89f86be2898cee208d492816ec238b2cf>`_. 293 + Instead, `flexible array members have incomplete type, and so the sizeof() 294 + operator may not be applied <https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_, 295 + so any misuse of such operators will be immediately noticed at build time. 296 + 297 + With respect to one-element arrays, one has to be acutely aware that `such arrays 298 + occupy at least as much space as a single object of the type 299 + <https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_, 300 + hence they contribute to the size of the enclosing structure. This is prone 301 + to error every time people want to calculate the total size of dynamic memory 302 + to allocate for a structure containing an array of this kind as a member:: 303 + 304 + struct something { 305 + size_t count; 306 + struct foo items[1]; 307 + }; 308 + 309 + struct something *instance; 310 + 311 + instance = kmalloc(struct_size(instance, items, count - 1), GFP_KERNEL); 312 + instance->count = count; 313 + 314 + size = sizeof(instance->items) * instance->count; 315 + memcpy(instance->items, source, size); 316 + 317 + In the example above, we had to remember to calculate ``count - 1`` when using 318 + the struct_size() helper, otherwise we would have --unintentionally-- allocated 319 + memory for one too many ``items`` objects. The cleanest and least error-prone way 320 + to implement this is through the use of a `flexible array member`:: 321 + 322 + struct something { 323 + size_t count; 324 + struct foo items[]; 325 + }; 326 + 327 + struct something *instance; 328 + 329 + instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL); 330 + instance->count = count; 331 + 332 + size = sizeof(instance->items[0]) * instance->count; 333 + memcpy(instance->items, source, size);

+1 -1

Documentation/process/howto.rst

··· 597 597 ChangeLog section of the document: 598 598 599 599 "The Perfect Patch" 600 - http://www.ozlabs.org/~akpm/stuff/tpp.txt 600 + https://www.ozlabs.org/~akpm/stuff/tpp.txt 601 601 602 602 603 603 All of these things are sometimes very hard to do. It can take years to

+2 -2

Documentation/process/index.rst

··· 32 32 kernel-enforcement-statement 33 33 kernel-driver-statement 34 34 35 - Other guides to the community that are of interest to most developers are: 35 + Other guides to the community that are of interest to most developers are: 36 36 37 37 .. toctree:: 38 38 :maxdepth: 1 ··· 61 61 botching-up-ioctls 62 62 clang-format 63 63 ../riscv/patch-acceptance 64 - unaligned-memory-access 64 + ../core-api/unaligned-memory-access 65 65 66 66 .. only:: subproject and html 67 67

+14 -14

Documentation/process/kernel-docs.rst

··· 98 98 * Title: **Linux Device Drivers, Third Edition** 99 99 100 100 :Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman 101 - :URL: http://lwn.net/Kernel/LDD3/ 101 + :URL: https://lwn.net/Kernel/LDD3/ 102 102 :Date: 2005 103 103 :Description: A 600-page book covering the (2.6.10) driver 104 104 programming API and kernel hacking in general. Available under the ··· 129 129 * Title: **Linux Kernel Module Programming Guide** 130 130 131 131 :Author: Ori Pomerantz. 132 - :URL: http://tldp.org/LDP/lkmpg/2.6/html/index.html 132 + :URL: https://tldp.org/LDP/lkmpg/2.6/html/index.html 133 133 :Date: 2001 134 134 :Keywords: modules, GPL book, /proc, ioctls, system calls, 135 135 interrupt handlers . ··· 244 244 * Title: **I/O Event Handling Under Linux** 245 245 246 246 :Author: Richard Gooch. 247 - :URL: http://web.mit.edu/~yandros/doc/io-events.html 247 + :URL: https://web.mit.edu/~yandros/doc/io-events.html 248 248 :Date: 1999 249 249 :Keywords: IO, I/O, select(2), poll(2), FDs, aio_read(2), readiness 250 250 event queues. ··· 295 295 * Title: **Design and Implementation of the Second Extended Filesystem** 296 296 297 297 :Author: Rémy Card, Theodore Ts'o, Stephen Tweedie. 298 - :URL: http://web.mit.edu/tytso/www/linux/ext2intro.html 298 + :URL: https://web.mit.edu/tytso/www/linux/ext2intro.html 299 299 :Date: 1998 300 300 :Keywords: ext2, linux fs history, inode, directory, link, devices, 301 301 VFS, physical structure, performance, benchmarks, ext2fs library, ··· 322 322 * Title: **Linux Kernel Hackers' Guide** 323 323 324 324 :Author: Michael K. Johnson. 325 - :URL: http://www.tldp.org/LDP/khg/HyperNews/get/khg.html 325 + :URL: https://www.tldp.org/LDP/khg/HyperNews/get/khg.html 326 326 :Date: 1997 327 327 :Keywords: device drivers, files, VFS, kernel interface, character vs 328 328 block devices, hardware interrupts, scsi, DMA, access to user memory, ··· 375 375 * Title: **Dissecting Interrupts and Browsing DMA** 376 376 377 377 :Author: Alessandro Rubini and Georg v. Zezschwitz. 378 - :URL: http://www.linuxjournal.com/article.php?sid=1222 378 + :URL: https://www.linuxjournal.com/article.php?sid=1222 379 379 :Date: 1996 380 380 :Keywords: interrupts, irqs, DMA, bottom halves, task queues. 381 381 :Description: Linux Journal Kernel Korner article. ··· 391 391 * Title: **Device Drivers Concluded** 392 392 393 393 :Author: Georg v. Zezschwitz. 394 - :URL: http://www.linuxjournal.com/article.php?sid=1287 394 + :URL: https://www.linuxjournal.com/article.php?sid=1287 395 395 :Date: 1996 396 396 :Keywords: address spaces, pages, pagination, page management, 397 397 demand loading, swapping, memory protection, memory mapping, mmap, ··· 405 405 * Title: **Network Buffers And Memory Management** 406 406 407 407 :Author: Alan Cox. 408 - :URL: http://www.linuxjournal.com/article.php?sid=1312 408 + :URL: https://www.linuxjournal.com/article.php?sid=1312 409 409 :Date: 1996 410 410 :Keywords: sk_buffs, network devices, protocol/link layer 411 411 variables, network devices flags, transmit, receive, ··· 418 418 * Title: **Analysis of the Ext2fs structure** 419 419 420 420 :Author: Louis-Dominique Dubeau. 421 - :URL: http://teaching.csse.uwa.edu.au/units/CITS2002/fs-ext2/ 421 + :URL: https://teaching.csse.uwa.edu.au/units/CITS2002/fs-ext2/ 422 422 :Date: 1994 423 423 :Keywords: ext2, filesystem, ext2fs. 424 424 :Description: Description of ext2's blocks, directories, inodes, ··· 480 480 :ISBN: 0-596-00590-3 481 481 :Notes: Further information in 482 482 http://www.oreilly.com/catalog/linuxdrive3/ 483 - PDF format, URL: http://lwn.net/Kernel/LDD3/ 483 + PDF format, URL: https://lwn.net/Kernel/LDD3/ 484 484 485 485 * Title: **Linux Kernel Internals** 486 486 ··· 561 561 562 562 * Name: **Linux Weekly News** 563 563 564 - :URL: http://lwn.net 564 + :URL: https://lwn.net 565 565 :Keywords: latest kernel news. 566 566 :Description: The title says it all. There's a fixed kernel section 567 567 summarizing developers' work, bug fixes, new features and versions ··· 570 570 * Name: **The home page of Linux-MM** 571 571 572 572 :Author: The Linux-MM team. 573 - :URL: http://linux-mm.org/ 573 + :URL: https://linux-mm.org/ 574 574 :Keywords: memory management, Linux-MM, mm patches, TODO, docs, 575 575 mailing list. 576 576 :Description: Site devoted to Linux Memory Management development. ··· 579 579 580 580 * Name: **Kernel Newbies IRC Channel and Website** 581 581 582 - :URL: http://www.kernelnewbies.org 582 + :URL: https://www.kernelnewbies.org 583 583 :Keywords: IRC, newbies, channel, asking doubts. 584 584 :Description: #kernelnewbies on irc.oftc.net. 585 585 #kernelnewbies is an IRC network dedicated to the 'newbie' ··· 605 605 Document last updated on Tue 2016-Sep-20 606 606 607 607 This document is based on: 608 - http://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html 608 + https://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html

+1 -1

Documentation/process/maintainer-pgp-guide.rst

··· 462 462 .. _`Nitrokey Start`: https://shop.nitrokey.com/shop/product/nitrokey-start-6 463 463 .. _`Nitrokey Pro 2`: https://shop.nitrokey.com/shop/product/nitrokey-pro-2-3 464 464 .. _`Yubikey 5`: https://www.yubico.com/products/yubikey-5-overview/ 465 - .. _Gnuk: http://www.fsij.org/doc-gnuk/ 465 + .. _Gnuk: https://www.fsij.org/doc-gnuk/ 466 466 .. _`LWN has a good review`: https://lwn.net/Articles/736231/ 467 467 .. _`qualify for a free Nitrokey Start`: https://www.kernel.org/nitrokey-digital-tokens-for-kernel-developers.html 468 468

+11 -11

Documentation/process/submitting-drivers.rst

··· 5 5 6 6 This document is intended to explain how to submit device drivers to the 7 7 various kernel trees. Note that if you are interested in video card drivers 8 - you should probably talk to XFree86 (http://www.xfree86.org/) and/or X.Org 9 - (http://x.org/) instead. 8 + you should probably talk to XFree86 (https://www.xfree86.org/) and/or X.Org 9 + (https://x.org/) instead. 10 10 11 11 .. note:: 12 12 ··· 25 25 26 26 Major and minor numbers for block and character devices are allocated 27 27 by the Linux assigned name and number authority (currently this is 28 - Torben Mathiasen). The site is http://www.lanana.org/. This 28 + Torben Mathiasen). The site is https://www.lanana.org/. This 29 29 also deals with allocating numbers for devices that are not going to 30 30 be submitted to the mainstream kernel. 31 31 See :ref:`Documentation/admin-guide/devices.rst <admin_devices>` ··· 155 155 where *country_code* == your country code, such as 156 156 **us**, **uk**, **fr**, etc. 157 157 158 - http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git 158 + https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git 159 159 160 160 Linux kernel mailing list: 161 161 linux-kernel@vger.kernel.org 162 162 [mail majordomo@vger.kernel.org to subscribe] 163 163 164 164 Linux Device Drivers, Third Edition (covers 2.6.10): 165 - http://lwn.net/Kernel/LDD3/ (free version) 165 + https://lwn.net/Kernel/LDD3/ (free version) 166 166 167 167 LWN.net: 168 - Weekly summary of kernel development activity - http://lwn.net/ 168 + Weekly summary of kernel development activity - https://lwn.net/ 169 169 170 170 2.6 API changes: 171 171 172 - http://lwn.net/Articles/2.6-kernel-api/ 172 + https://lwn.net/Articles/2.6-kernel-api/ 173 173 174 174 Porting drivers from prior kernels to 2.6: 175 175 176 - http://lwn.net/Articles/driver-porting/ 176 + https://lwn.net/Articles/driver-porting/ 177 177 178 178 KernelNewbies: 179 179 Documentation and assistance for new kernel programmers 180 180 181 - http://kernelnewbies.org/ 181 + https://kernelnewbies.org/ 182 182 183 183 Linux USB project: 184 184 http://www.linux-usb.org/ ··· 187 187 http://www.fenrus.org/how-to-not-write-a-device-driver-paper.pdf 188 188 189 189 Kernel Janitor: 190 - http://kernelnewbies.org/KernelJanitors 190 + https://kernelnewbies.org/KernelJanitors 191 191 192 192 GIT, Fast Version Control System: 193 - http://git-scm.com/ 193 + https://git-scm.com/

+7 -2

Documentation/process/submitting-patches.rst

··· 94 94 very important if you want your patch accepted. 95 95 96 96 If you're using ``git``, ``git rebase -i`` can help you with this process. If 97 - you're not using ``git``, ``quilt`` <http://savannah.nongnu.org/projects/quilt> 97 + you're not using ``git``, ``quilt`` <https://savannah.nongnu.org/projects/quilt> 98 98 is another popular alternative. 99 99 100 100 .. _describe_changes: ··· 195 195 abbrev = 12 196 196 [pretty] 197 197 fixes = Fixes: %h (\"%s\") 198 + 199 + An example call:: 200 + 201 + $ git log -1 --pretty=fixes 54a4f0239f2e 202 + Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") 198 203 199 204 .. _split_changes: 200 205 ··· 897 892 ---------- 898 893 899 894 Andrew Morton, "The perfect patch" (tpp). 900 - <http://www.ozlabs.org/~akpm/stuff/tpp.txt> 895 + <https://www.ozlabs.org/~akpm/stuff/tpp.txt> 901 896 902 897 Jeff Garzik, "Linux kernel patch submission format". 903 898 <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>

Documentation/process/unaligned-memory-access.rst Documentation/core-api/unaligned-memory-access.rst

+1 -1

Documentation/remoteproc.txt Documentation/staging/remoteproc.rst

··· 22 22 platform-specific remoteproc drivers only need to provide a few low-level 23 23 handlers, and then all rpmsg drivers will then just work 24 24 (for more information about the virtio-based rpmsg bus and its drivers, 25 - please read Documentation/rpmsg.txt). 25 + please read Documentation/staging/rpmsg.rst). 26 26 Registration of other types of virtio devices is now also possible. Firmwares 27 27 just need to publish what kind of virtio devices do they support, and then 28 28 remoteproc will add those devices. This makes it possible to reuse the

Documentation/rpmsg.txt Documentation/staging/rpmsg.rst

+1 -1

Documentation/s390/monreader.rst

··· 146 146 147 147 See "Appendix A: `*MONITOR`" in the "z/VM Performance" document for a description 148 148 of the monitor control element layout. The layout of the monitor records can 149 - be found here (z/VM 5.1): http://www.vm.ibm.com/pubs/mon510/index.html 149 + be found here (z/VM 5.1): https://www.vm.ibm.com/pubs/mon510/index.html 150 150 151 151 The layout of the data stream provided by the monreader device is as follows:: 152 152

+1 -1

Documentation/s390/vfio-ap.rst

··· 361 361 assign_domain / unassign_domain: 362 362 Write-only attributes for assigning/unassigning an AP usage domain to/from 363 363 the mediated matrix device. To assign/unassign a domain, the domain 364 - number of the the usage domain is echoed to the respective attribute 364 + number of the usage domain is echoed to the respective attribute 365 365 file. 366 366 matrix: 367 367 A read-only file for displaying the APQNs derived from the cross product

+7 -3

Documentation/security/credentials.rst

··· 453 453 454 454 When replacing the group list, the new list must be sorted before it 455 455 is added to the credential, as a binary search is used to test for 456 - membership. In practice, this means :c:func:`groups_sort` should be 457 - called before :c:func:`set_groups` or :c:func:`set_current_groups`. 458 - :c:func:`groups_sort)` must not be called on a ``struct group_list`` which 456 + membership. In practice, this means groups_sort() should be 457 + called before set_groups() or set_current_groups(). 458 + groups_sort() must not be called on a ``struct group_list`` which 459 459 is shared as it may permute elements as part of the sorting process 460 460 even if the array is already sorted. 461 461 ··· 548 548 contents of the cred struct pointed to, barring the exceptions listed above 549 549 (see the Task Credentials section). 550 550 551 + To avoid "confused deputy" privilege escalation attacks, access control checks 552 + during subsequent operations on an opened file should use these credentials 553 + instead of "current"'s credentials, as the file may have been passed to a more 554 + privileged process. 551 555 552 556 Overriding the VFS's Use of Credentials 553 557 =======================================

+1 -1

Documentation/security/keys/core.rst

··· 912 912 913 913 One application of restricted keyrings is to verify X.509 certificate 914 914 chains or individual certificate signatures using the asymmetric key type. 915 - See Documentation/crypto/asymmetric-keys.txt for specific restrictions 915 + See Documentation/crypto/asymmetric-keys.rst for specific restrictions 916 916 applicable to the asymmetric key type. 917 917 918 918

+1 -1

Documentation/security/keys/trusted-encrypted.rst

··· 200 200 24717c64 5972dcb82ab2dde83376d82b2e3c09ffc 201 201 202 202 Other uses for trusted and encrypted keys, such as for disk and file encryption 203 - are anticipated. In particular the new format 'ecryptfs' has been defined in 203 + are anticipated. In particular the new format 'ecryptfs' has been defined 204 204 in order to use encrypted keys to mount an eCryptfs filesystem. More details 205 205 about the usage can be found in the file 206 206 ``Documentation/security/keys/ecryptfs.rst``.

+6

Documentation/sh/index.rst

··· 4 4 5 5 :Author: Paul Mundt 6 6 7 + .. toctree:: 8 + :maxdepth: 1 9 + 10 + new-machine 11 + register-banks 12 + 7 13 Memory Management 8 14 ================= 9 15

+101 -94

Documentation/sh/new-machine.txt Documentation/sh/new-machine.rst

··· 1 + .. SPDX-License-Identifier: GPL-2.0 1 2 2 - Adding a new board to LinuxSH 3 - ================================ 3 + ============================= 4 + Adding a new board to LinuxSH 5 + ============================= 4 6 5 7 Paul Mundt <lethal@linux-sh.org> 6 8 ··· 21 19 companion chip type, and CPU type. Looking at a tree view of this directory 22 20 hierarchy looks like the following: 23 21 24 - Board-specific code: 22 + Board-specific code:: 25 23 26 - . 27 - |-- arch 28 - | `-- sh 29 - | `-- boards 30 - | |-- adx 31 - | | `-- board-specific files 32 - | |-- bigsur 33 - | | `-- board-specific files 34 - | | 35 - | ... more boards here ... 36 - | 37 - `-- include 38 - `-- asm-sh 39 - |-- adx 40 - | `-- board-specific headers 41 - |-- bigsur 42 - | `-- board-specific headers 43 - | 44 - .. more boards here ... 24 + . 25 + |-- arch 26 + | `-- sh 27 + | `-- boards 28 + | |-- adx 29 + | | `-- board-specific files 30 + | |-- bigsur 31 + | | `-- board-specific files 32 + | | 33 + | ... more boards here ... 34 + | 35 + `-- include 36 + `-- asm-sh 37 + |-- adx 38 + | `-- board-specific headers 39 + |-- bigsur 40 + | `-- board-specific headers 41 + | 42 + .. more boards here ... 45 43 46 - Next, for companion chips: 47 - . 48 - `-- arch 49 - `-- sh 50 - `-- cchips 51 - `-- hd6446x 52 - `-- hd64461 53 - `-- cchip-specific files 44 + Next, for companion chips:: 45 + 46 + . 47 + `-- arch 48 + `-- sh 49 + `-- cchips 50 + `-- hd6446x 51 + `-- hd64461 52 + `-- cchip-specific files 54 53 55 54 ... and so on. Headers for the companion chips are treated the same way as 56 55 board-specific headers. Thus, include/asm-sh/hd64461 is home to all of the 57 56 hd64461-specific headers. 58 57 59 - Finally, CPU family support is also abstracted: 60 - . 61 - |-- arch 62 - | `-- sh 63 - | |-- kernel 64 - | | `-- cpu 65 - | | |-- sh2 66 - | | | `-- SH-2 generic files 67 - | | |-- sh3 68 - | | | `-- SH-3 generic files 69 - | | `-- sh4 70 - | | `-- SH-4 generic files 71 - | `-- mm 72 - | `-- This is also broken out per CPU family, so each family can 73 - | have their own set of cache/tlb functions. 74 - | 75 - `-- include 76 - `-- asm-sh 77 - |-- cpu-sh2 78 - | `-- SH-2 specific headers 79 - |-- cpu-sh3 80 - | `-- SH-3 specific headers 81 - `-- cpu-sh4 82 - `-- SH-4 specific headers 58 + Finally, CPU family support is also abstracted:: 59 + 60 + . 61 + |-- arch 62 + | `-- sh 63 + | |-- kernel 64 + | | `-- cpu 65 + | | |-- sh2 66 + | | | `-- SH-2 generic files 67 + | | |-- sh3 68 + | | | `-- SH-3 generic files 69 + | | `-- sh4 70 + | | `-- SH-4 generic files 71 + | `-- mm 72 + | `-- This is also broken out per CPU family, so each family can 73 + | have their own set of cache/tlb functions. 74 + | 75 + `-- include 76 + `-- asm-sh 77 + |-- cpu-sh2 78 + | `-- SH-2 specific headers 79 + |-- cpu-sh3 80 + | `-- SH-3 specific headers 81 + `-- cpu-sh4 82 + `-- SH-4 specific headers 83 83 84 84 It should be noted that CPU subtypes are _not_ abstracted. Thus, these still 85 85 need to be dealt with by the CPU family specific code. ··· 114 110 explain this, we use some examples for adding an imaginary board. For 115 111 setup code, we're required at the very least to provide definitions for 116 112 get_system_type() and platform_setup(). For our imaginary board, this 117 - might look something like: 113 + might look something like:: 118 114 119 - /* 120 - * arch/sh/boards/vapor/setup.c - Setup code for imaginary board 121 - */ 122 - #include <linux/init.h> 115 + /* 116 + * arch/sh/boards/vapor/setup.c - Setup code for imaginary board 117 + */ 118 + #include <linux/init.h> 123 119 124 - const char *get_system_type(void) 125 - { 126 - return "FooTech Vaporboard"; 127 - } 120 + const char *get_system_type(void) 121 + { 122 + return "FooTech Vaporboard"; 123 + } 128 124 129 - int __init platform_setup(void) 130 - { 131 - /* 132 - * If our hardware actually existed, we would do real 133 - * setup here. Though it's also sane to leave this empty 134 - * if there's no real init work that has to be done for 135 - * this board. 136 - */ 125 + int __init platform_setup(void) 126 + { 127 + /* 128 + * If our hardware actually existed, we would do real 129 + * setup here. Though it's also sane to leave this empty 130 + * if there's no real init work that has to be done for 131 + * this board. 132 + */ 137 133 138 - /* Start-up imaginary PCI ... */ 134 + /* Start-up imaginary PCI ... */ 139 135 140 - /* And whatever else ... */ 136 + /* And whatever else ... */ 141 137 142 - return 0; 143 - } 138 + return 0; 139 + } 144 140 145 141 Our new imaginary board will also have to tie into the machvec in order for it 146 142 to be of any use. ··· 176 172 vector. 177 173 178 174 Note that these prototypes are generated automatically by setting 179 - __IO_PREFIX to something sensible. A typical example would be: 175 + __IO_PREFIX to something sensible. A typical example would be:: 180 176 181 177 #define __IO_PREFIX vapor 182 - #include <asm/io_generic.h> 178 + #include <asm/io_generic.h> 183 179 184 180 somewhere in the board-specific header. Any boards being ported that still 185 181 have a legacy io.h should remove it entirely and switch to the new model. 186 182 187 183 - Add machine vector definitions to the board's setup.c. At a bare minimum, 188 - this must be defined as something like: 184 + this must be defined as something like:: 189 185 190 186 struct sh_machine_vector mv_vapor __initmv = { 191 187 .mv_name = "vapor", ··· 206 202 require the proper entry here and there in order to get things done. 207 203 208 204 The first thing to do is to add an entry to arch/sh/Kconfig, under the 209 - "System type" menu: 205 + "System type" menu:: 210 206 211 - config SH_VAPOR 212 - bool "Vapor" 213 - help 214 - select Vapor if configuring for a FooTech Vaporboard. 207 + config SH_VAPOR 208 + bool "Vapor" 209 + help 210 + select Vapor if configuring for a FooTech Vaporboard. 215 211 216 212 next, this has to be added into arch/sh/Makefile. All boards require a 217 213 machdir-y entry in order to be built. This entry needs to be the name of 218 214 the board directory as it appears in arch/sh/boards, even if it is in a 219 215 sub-directory (in which case, all parent directories below arch/sh/boards/ 220 - need to be listed). For our new board, this entry can look like: 216 + need to be listed). For our new board, this entry can look like:: 221 217 222 - machdir-$(CONFIG_SH_VAPOR) += vapor 218 + machdir-$(CONFIG_SH_VAPOR) += vapor 223 219 224 220 provided that we've placed everything in the arch/sh/boards/vapor/ directory. 225 221 ··· 234 230 list. The method for doing this is self explanatory, and so we won't waste 235 231 space restating it here. After this is done, you will be able to use 236 232 implicit checks for your board if you need this somewhere throughout the 237 - common code, such as: 233 + common code, such as:: 238 234 239 235 /* Make sure we're on the FooTech Vaporboard */ 240 236 if (!mach_is_vapor()) ··· 257 253 Looking at the 'make help' output, you should now see something like: 258 254 259 255 Architecture specific targets (sh): 260 - zImage - Compressed kernel image (arch/sh/boot/zImage) 261 - adx_defconfig - Build for adx 262 - cqreek_defconfig - Build for cqreek 263 - dreamcast_defconfig - Build for dreamcast 264 - ... 265 - vapor_defconfig - Build for vapor 266 256 267 - which then allows you to do: 257 + ======================= ============================================= 258 + zImage Compressed kernel image (arch/sh/boot/zImage) 259 + adx_defconfig Build for adx 260 + cqreek_defconfig Build for cqreek 261 + dreamcast_defconfig Build for dreamcast 262 + ... 263 + vapor_defconfig Build for vapor 264 + ======================= ============================================= 268 265 269 - $ make ARCH=sh CROSS_COMPILE=sh4-linux- vapor_defconfig vmlinux 266 + which then allows you to do:: 267 + 268 + $ make ARCH=sh CROSS_COMPILE=sh4-linux- vapor_defconfig vmlinux 270 269 271 270 which will in turn copy the defconfig for this board, run it through 272 271 oldconfig (prompting you for any new options since the time of creation),

+10 -3

Documentation/sh/register-banks.txt Documentation/sh/register-banks.rst

··· 1 - Notes on register bank usage in the kernel 2 - ========================================== 1 + .. SPDX-License-Identifier: GPL-2.0 2 + 3 + ========================================== 4 + Notes on register bank usage in the kernel 5 + ========================================== 3 6 4 7 Introduction 5 8 ------------ ··· 26 23 27 24 - r0_bank, r1_bank (referenced as k0 and k1, used for scratch 28 25 registers when doing exception handling). 26 + 29 27 - r2_bank (used to track the EXPEVT/INTEVT code) 28 + 30 29 - Used by do_IRQ() and friends for doing irq mapping based off 31 30 of the interrupt exception vector jump table offset 31 + 32 32 - r6_bank (global interrupt mask) 33 + 33 34 - The SR.IMASK interrupt handler makes use of this to set the 34 35 interrupt priority level (used by local_irq_enable()) 35 - - r7_bank (current) 36 36 37 + - r7_bank (current)

+5 -3

Documentation/speculation.txt Documentation/staging/speculation.rst

··· 1 - This document explains potential effects of speculation, and how undesirable 2 - effects can be mitigated portably using common APIs. 3 - 4 1 =========== 5 2 Speculation 6 3 =========== 4 + 5 + This document explains potential effects of speculation, and how undesirable 6 + effects can be mitigated portably using common APIs. 7 + 8 + ------------------------------------------------------------------------------ 7 9 8 10 To improve performance and minimize average latencies, many contemporary CPUs 9 11 employ speculative execution techniques such as branch prediction, performing

+1 -1

Documentation/sphinx/parse-headers.pl

··· 393 393 394 394 Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab+samsung@kernel.org>. 395 395 396 - License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>. 396 + License GPLv2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>. 397 397 398 398 This is free software: you are free to change and redistribute it. 399 399 There is NO WARRANTY, to the extent permitted by law.

+58

Documentation/staging/index.rst

··· 1 + .. SPDX-License-Identifier: GPL-2.0 2 + 3 + Unsorted Documentation 4 + ====================== 5 + 6 + .. toctree:: 7 + :maxdepth: 2 8 + 9 + crc32 10 + lzo 11 + remoteproc 12 + rpmsg 13 + speculation 14 + static-keys 15 + tee 16 + xz 17 + 18 + Atomic Types 19 + ============ 20 + 21 + .. raw:: latex 22 + 23 + \footnotesize 24 + 25 + .. include:: ../atomic_t.txt 26 + :literal: 27 + 28 + .. raw:: latex 29 + 30 + \normalsize 31 + 32 + Atomic bitops 33 + ============= 34 + 35 + .. raw:: latex 36 + 37 + \footnotesize 38 + 39 + .. include:: ../atomic_bitops.txt 40 + :literal: 41 + 42 + .. raw:: latex 43 + 44 + \normalsize 45 + 46 + Memory Barriers 47 + =============== 48 + 49 + .. raw:: latex 50 + 51 + \footnotesize 52 + 53 + .. include:: ../memory-barriers.txt 54 + :literal: 55 + 56 + .. raw:: latex 57 + 58 + \normalsize

Documentation/static-keys.txt Documentation/staging/static-keys.rst

+73

Documentation/tee.txt Documentation/staging/tee.rst

··· 53 53 supplicants the communication goes in the other direction, the TEE sends 54 54 requests to the supplicant which then sends back the result. 55 55 56 + The TEE kernel interface 57 + ======================== 58 + 59 + Kernel provides a TEE bus infrastructure where a Trusted Application is 60 + represented as a device identified via Universally Unique Identifier (UUID) and 61 + client drivers register a table of supported device UUIDs. 62 + 63 + TEE bus infrastructure registers following APIs: 64 + 65 + match(): 66 + iterates over the client driver UUID table to find a corresponding 67 + match for device UUID. If a match is found, then this particular device is 68 + probed via corresponding probe API registered by the client driver. This 69 + process happens whenever a device or a client driver is registered with TEE 70 + bus. 71 + 72 + uevent(): 73 + notifies user-space (udev) whenever a new device is registered on 74 + TEE bus for auto-loading of modularized client drivers. 75 + 76 + TEE bus device enumeration is specific to underlying TEE implementation, so it 77 + is left open for TEE drivers to provide corresponding implementation. 78 + 79 + Then TEE client driver can talk to a matched Trusted Application using APIs 80 + listed in include/linux/tee_drv.h. 81 + 82 + TEE client driver example 83 + ------------------------- 84 + 85 + Suppose a TEE client driver needs to communicate with a Trusted Application 86 + having UUID: ``ac6a4085-0e82-4c33-bf98-8eb8e118b6c2``, so driver registration 87 + snippet would look like:: 88 + 89 + static const struct tee_client_device_id client_id_table[] = { 90 + {UUID_INIT(0xac6a4085, 0x0e82, 0x4c33, 91 + 0xbf, 0x98, 0x8e, 0xb8, 0xe1, 0x18, 0xb6, 0xc2)}, 92 + {} 93 + }; 94 + 95 + MODULE_DEVICE_TABLE(tee, client_id_table); 96 + 97 + static struct tee_client_driver client_driver = { 98 + .id_table = client_id_table, 99 + .driver = { 100 + .name = DRIVER_NAME, 101 + .bus = &tee_bus_type, 102 + .probe = client_probe, 103 + .remove = client_remove, 104 + }, 105 + }; 106 + 107 + static int __init client_init(void) 108 + { 109 + return driver_register(&client_driver.driver); 110 + } 111 + 112 + static void __exit client_exit(void) 113 + { 114 + driver_unregister(&client_driver.driver); 115 + } 116 + 117 + module_init(client_init); 118 + module_exit(client_exit); 119 + 56 120 OP-TEE driver 57 121 ============= 58 122 ··· 176 112 tee-supplicant without further involvement of the driver, except switching 177 113 shared memory buffer representation. 178 114 115 + OP-TEE device enumeration 116 + ------------------------- 117 + 118 + OP-TEE provides a pseudo Trusted Application: drivers/tee/optee/device.c in 119 + order to support device enumeration. In other words, OP-TEE driver invokes this 120 + application to retrieve a list of Trusted Applications which can be registered 121 + as devices on the TEE bus. 122 + 179 123 AMD-TEE driver 180 124 ============== 181 125 ··· 234 162 The command buffer format for the different TEE commands can be found in [7]. 235 163 236 164 The TEE commands supported by AMD-TEE Trusted OS are: 165 + 237 166 * TEE_CMD_ID_LOAD_TA - loads a Trusted Application (TA) binary into 238 167 TEE environment. 239 168 * TEE_CMD_ID_UNLOAD_TA - unloads TA binary from TEE environment.

Documentation/this_cpu_ops.txt Documentation/core-api/this_cpu_ops.rst

-2

Documentation/timers/no_hz.rst

··· 171 171 slightly differently than those for non-adaptive-tick CPUs. 172 172 This might in turn perturb load-balancing of real-time tasks. 173 173 174 - 6. The LB_BIAS scheduler feature is disabled by adaptive ticks. 175 - 176 174 Although improvements are expected over time, adaptive ticks is quite 177 175 useful for many types of real-time and compute-intensive applications. 178 176 However, the drawbacks listed above mean that adaptive ticks should not

+9 -9

Documentation/trace/ftrace.rst

··· 34 34 can be enabled via the tracefs file system to see what is 35 35 going on in certain parts of the kernel. 36 36 37 - See events.txt for more information. 37 + See events.rst for more information. 38 38 39 39 40 40 Implementation Details ··· 376 376 377 377 kprobe_events: 378 378 379 - Enable dynamic trace points. See kprobetrace.txt. 379 + Enable dynamic trace points. See kprobetrace.rst. 380 380 381 381 kprobe_profile: 382 382 383 - Dynamic trace points stats. See kprobetrace.txt. 383 + Dynamic trace points stats. See kprobetrace.rst. 384 384 385 385 max_graph_depth: 386 386 ··· 561 561 562 562 trace_marker_raw: 563 563 564 - This is similar to trace_marker above, but is meant for for binary data 564 + This is similar to trace_marker above, but is meant for binary data 565 565 to be written to it, where a tool can be used to parse the data 566 566 from trace_pipe_raw. 567 567 568 568 uprobe_events: 569 569 570 570 Add dynamic tracepoints in programs. 571 - See uprobetracer.txt 571 + See uprobetracer.rst 572 572 573 573 uprobe_profile: 574 574 ··· 589 589 files at various levels that can enable the tracepoints 590 590 when a "1" is written to them. 591 591 592 - See events.txt for more information. 592 + See events.rst for more information. 593 593 594 594 set_event: 595 595 596 596 By echoing in the event into this file, will enable that event. 597 597 598 - See events.txt for more information. 598 + See events.rst for more information. 599 599 600 600 available_events: 601 601 602 602 A list of events that can be enabled in tracing. 603 603 604 - See events.txt for more information. 604 + See events.rst for more information. 605 605 606 606 timestamp_mode: 607 607 ··· 1394 1394 => x86_64_start_reservations 1395 1395 => x86_64_start_kernel 1396 1396 1397 - Here we see that that we had a latency of 16 microseconds (which is 1397 + Here we see that we had a latency of 16 microseconds (which is 1398 1398 very good). The _raw_spin_lock_irq in run_timer_softirq disabled 1399 1399 interrupts. The difference between the 16 and the displayed 1400 1400 timestamp 25us occurred because the clock was incremented

+2 -2

Documentation/trace/histogram-design.rst

··· 780 780 Moving on to the sched_switch trigger hist_debug output, in addition 781 781 to the unused wakeup_lat variable, we see a new section displaying 782 782 variable references. Variable references are displayed in a separate 783 - section because in addition to to being logically separate from 783 + section because in addition to being logically separate from 784 784 variables and values, they actually live in a separate hist_data 785 785 array, var_refs[]. 786 786 ··· 863 863 The onmatch() action below basically says that whenever we have a 864 864 sched_switch event, if we have a matching sched_waking event, in this 865 865 case if we have a pid in the sched_waking histogram that matches the 866 - the next_pid field on this sched_switch event, we retrieve the 866 + next_pid field on this sched_switch event, we retrieve the 867 867 variables specified in the wakeup_latency() trace action, and use 868 868 them to generate a new wakeup_latency event into the trace stream. 869 869

+3

Documentation/trace/index.rst

··· 9 9 tracepoint-analysis 10 10 ftrace 11 11 ftrace-uses 12 + kprobes 12 13 kprobetrace 13 14 uprobetracer 14 15 tracepoints ··· 20 19 events-msr 21 20 mmiotrace 22 21 histogram 22 + histogram-design 23 23 boottime-trace 24 24 hwlat_detector 25 25 intel_th 26 + ring-buffer-design 26 27 stm 27 28 sys-t 28 29 coresight/index

+1 -1

Documentation/trace/kprobetrace.rst

··· 40 40 MEMADDR : Address where the probe is inserted. 41 41 MAXACTIVE : Maximum number of instances of the specified function that 42 42 can be probed simultaneously, or 0 for the default value 43 - as defined in Documentation/kprobes.txt section 1.3.1. 43 + as defined in Documentation/staging/kprobes.rst section 1.3.1. 44 44 45 45 FETCHARGS : Arguments. Each probe can have up to 128 args. 46 46 %REG : Fetch register REG

+431 -379

Documentation/trace/ring-buffer-design.txt Documentation/trace/ring-buffer-design.rst

··· 1 - Lockless Ring Buffer Design 2 - =========================== 1 + .. This file is dual-licensed: you can use it either under the terms 2 + .. of the GPL 2.0 or the GFDL 1.2 license, at your option. Note that this 3 + .. dual licensing only applies to this file, and not this project as a 4 + .. whole. 5 + .. 6 + .. a) This file is free software; you can redistribute it and/or 7 + .. modify it under the terms of the GNU General Public License as 8 + .. published by the Free Software Foundation version 2 of 9 + .. the License. 10 + .. 11 + .. This file is distributed in the hope that it will be useful, 12 + .. but WITHOUT ANY WARRANTY; without even the implied warranty of 13 + .. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 + .. GNU General Public License for more details. 15 + .. 16 + .. Or, alternatively, 17 + .. 18 + .. b) Permission is granted to copy, distribute and/or modify this 19 + .. document under the terms of the GNU Free Documentation License, 20 + .. Version 1.2 version published by the Free Software 21 + .. Foundation, with no Invariant Sections, no Front-Cover Texts 22 + .. and no Back-Cover Texts. A copy of the license is included at 23 + .. Documentation/userspace-api/media/fdl-appendix.rst. 24 + .. 25 + .. TODO: replace it to GPL-2.0 OR GFDL-1.2 WITH no-invariant-sections 26 + 27 + =========================== 28 + Lockless Ring Buffer Design 29 + =========================== 3 30 4 31 Copyright 2009 Red Hat Inc. 5 - Author: Steven Rostedt <srostedt@redhat.com> 6 - License: The GNU Free Documentation License, Version 1.2 7 - (dual licensed under the GPL v2) 8 - Reviewers: Mathieu Desnoyers, Huang Ying, Hidetoshi Seto, 32 + 33 + :Author: Steven Rostedt <srostedt@redhat.com> 34 + :License: The GNU Free Documentation License, Version 1.2 35 + (dual licensed under the GPL v2) 36 + :Reviewers: Mathieu Desnoyers, Huang Ying, Hidetoshi Seto, 9 37 and Frederic Weisbecker. 10 38 11 39 ··· 42 14 Terminology used in this Document 43 15 --------------------------------- 44 16 45 - tail - where new writes happen in the ring buffer. 17 + tail 18 + - where new writes happen in the ring buffer. 46 19 47 - head - where new reads happen in the ring buffer. 20 + head 21 + - where new reads happen in the ring buffer. 48 22 49 - producer - the task that writes into the ring buffer (same as writer) 23 + producer 24 + - the task that writes into the ring buffer (same as writer) 50 25 51 - writer - same as producer 26 + writer 27 + - same as producer 52 28 53 - consumer - the task that reads from the buffer (same as reader) 29 + consumer 30 + - the task that reads from the buffer (same as reader) 54 31 55 - reader - same as consumer. 32 + reader 33 + - same as consumer. 56 34 57 - reader_page - A page outside the ring buffer used solely (for the most part) 58 - by the reader. 35 + reader_page 36 + - A page outside the ring buffer used solely (for the most part) 37 + by the reader. 59 38 60 - head_page - a pointer to the page that the reader will use next 39 + head_page 40 + - a pointer to the page that the reader will use next 61 41 62 - tail_page - a pointer to the page that will be written to next 42 + tail_page 43 + - a pointer to the page that will be written to next 63 44 64 - commit_page - a pointer to the page with the last finished non-nested write. 45 + commit_page 46 + - a pointer to the page with the last finished non-nested write. 65 47 66 - cmpxchg - hardware-assisted atomic transaction that performs the following: 48 + cmpxchg 49 + - hardware-assisted atomic transaction that performs the following:: 67 50 68 - A = B if previous A == C 51 + A = B if previous A == C 69 52 70 - R = cmpxchg(A, C, B) is saying that we replace A with B if and only if 71 - current A is equal to C, and we put the old (current) A into R 53 + R = cmpxchg(A, C, B) is saying that we replace A with B if and only 54 + if current A is equal to C, and we put the old (current) 55 + A into R 72 56 73 - R gets the previous A regardless if A is updated with B or not. 57 + R gets the previous A regardless if A is updated with B or not. 74 58 75 - To see if the update was successful a compare of R == C may be used. 59 + To see if the update was successful a compare of ``R == C`` 60 + may be used. 76 61 77 62 The Generic Ring Buffer 78 63 ----------------------- ··· 105 64 but a writer may interrupt another writer, but it must finish writing 106 65 before the previous writer may continue. This is very important to the 107 66 algorithm. The writers act like a "stack". The way interrupts works 108 - enforces this behavior. 67 + enforces this behavior:: 109 68 110 69 111 70 writer1 start ··· 155 114 A sample of how the reader page is swapped: Note this does not 156 115 show the head page in the buffer, it is for demonstrating a swap 157 116 only. 117 + 118 + :: 158 119 159 120 +------+ 160 121 |reader| RING BUFFER ··· 215 172 It is possible that the page swapped is the commit page and the tail page, 216 173 if what is in the ring buffer is less than what is held in a buffer page. 217 174 175 + :: 218 176 219 - reader page commit page tail page 220 - | | | 221 - v | | 222 - +---+ | | 223 - | |<----------+ | 224 - | |<------------------------+ 225 - | |------+ 226 - +---+ | 227 - | 228 - v 229 - +---+ +---+ +---+ +---+ 230 - <---| |--->| |--->| |--->| |---> 231 - --->| |<---| |<---| |<---| |<--- 232 - +---+ +---+ +---+ +---+ 177 + reader page commit page tail page 178 + | | | 179 + v | | 180 + +---+ | | 181 + | |<----------+ | 182 + | |<------------------------+ 183 + | |------+ 184 + +---+ | 185 + | 186 + v 187 + +---+ +---+ +---+ +---+ 188 + <---| |--->| |--->| |--->| |---> 189 + --->| |<---| |<---| |<---| |<--- 190 + +---+ +---+ +---+ +---+ 233 191 234 192 This case is still valid for this algorithm. 235 193 When the writer leaves the page, it simply goes into the ring buffer ··· 240 196 241 197 The main pointers: 242 198 243 - reader page - The page used solely by the reader and is not part 244 - of the ring buffer (may be swapped in) 199 + reader page 200 + - The page used solely by the reader and is not part 201 + of the ring buffer (may be swapped in) 245 202 246 - head page - the next page in the ring buffer that will be swapped 203 + head page 204 + - the next page in the ring buffer that will be swapped 247 205 with the reader page. 248 206 249 - tail page - the page where the next write will take place. 207 + tail page 208 + - the page where the next write will take place. 250 209 251 - commit page - the page that last finished a write. 210 + commit page 211 + - the page that last finished a write. 252 212 253 213 The commit page only is updated by the outermost writer in the 254 214 writer stack. A writer that preempts another writer will not move the ··· 267 219 with the previous write. 268 220 269 221 270 - Write reserve: 222 + Write reserve:: 271 223 272 224 Buffer page 273 225 +---------+ ··· 278 230 | empty | 279 231 +---------+ 280 232 281 - Write commit: 233 + Write commit:: 282 234 283 235 Buffer page 284 236 +---------+ ··· 290 242 +---------+ 291 243 292 244 293 - If a write happens after the first reserve: 245 + If a write happens after the first reserve:: 294 246 295 247 Buffer page 296 248 +---------+ ··· 301 253 |reserved | 302 254 +---------+ <--- tail pointer 303 255 304 - After second writer commits: 256 + After second writer commits:: 305 257 306 258 307 259 Buffer page ··· 314 266 |commit | 315 267 +---------+ <--- tail pointer 316 268 317 - When the first writer commits: 269 + When the first writer commits:: 318 270 319 271 Buffer page 320 272 +---------+ ··· 340 292 page then no more writes may take place (regardless of the mode 341 293 of the ring buffer: overwrite and produce/consumer). 342 294 343 - The order of pages is: 295 + The order of pages is:: 344 296 345 297 head page 346 298 commit page 347 299 tail page 348 300 349 - Possible scenario: 350 - tail page 351 - head page commit page | 352 - | | | 353 - v v v 354 - +---+ +---+ +---+ +---+ 355 - <---| |--->| |--->| |--->| |---> 356 - --->| |<---| |<---| |<---| |<--- 357 - +---+ +---+ +---+ +---+ 301 + Possible scenario:: 302 + 303 + tail page 304 + head page commit page | 305 + | | | 306 + v v v 307 + +---+ +---+ +---+ +---+ 308 + <---| |--->| |--->| |--->| |---> 309 + --->| |<---| |<---| |<---| |<--- 310 + +---+ +---+ +---+ +---+ 358 311 359 312 There is a special case that the head page is after either the commit page 360 313 and possibly the tail page. That is when the commit (and tail) page has been ··· 364 315 has been less than a full page that has been committed inside the ring buffer, 365 316 and a reader swaps out a page, it will be swapping out the commit page. 366 317 318 + :: 367 319 368 - reader page commit page tail page 369 - | | | 370 - v | | 371 - +---+ | | 372 - | |<----------+ | 373 - | |<------------------------+ 374 - | |------+ 375 - +---+ | 376 - | 377 - v 378 - +---+ +---+ +---+ +---+ 379 - <---| |--->| |--->| |--->| |---> 380 - --->| |<---| |<---| |<---| |<--- 381 - +---+ +---+ +---+ +---+ 382 - ^ 383 - | 384 - head page 320 + reader page commit page tail page 321 + | | | 322 + v | | 323 + +---+ | | 324 + | |<----------+ | 325 + | |<------------------------+ 326 + | |------+ 327 + +---+ | 328 + | 329 + v 330 + +---+ +---+ +---+ +---+ 331 + <---| |--->| |--->| |--->| |---> 332 + --->| |<---| |<---| |<---| |<--- 333 + +---+ +---+ +---+ +---+ 334 + ^ 335 + | 336 + head page 385 337 386 338 387 339 In this case, the head page will not move when the tail and commit ··· 397 347 the head page will be pushed ahead one. If the buffer is in producer/consumer 398 348 mode, the write will fail. 399 349 400 - Overwrite mode: 350 + Overwrite mode:: 401 351 402 - tail page 403 - | 404 - v 405 - +---+ +---+ +---+ +---+ 406 - <---| |--->| |--->| |--->| |---> 407 - --->| |<---| |<---| |<---| |<--- 408 - +---+ +---+ +---+ +---+ 409 - ^ 410 - | 411 - head page 412 - 413 - 414 - tail page 415 - | 416 - v 417 - +---+ +---+ +---+ +---+ 418 - <---| |--->| |--->| |--->| |---> 419 - --->| |<---| |<---| |<---| |<--- 420 - +---+ +---+ +---+ +---+ 421 - ^ 422 - | 423 - head page 352 + tail page 353 + | 354 + v 355 + +---+ +---+ +---+ +---+ 356 + <---| |--->| |--->| |--->| |---> 357 + --->| |<---| |<---| |<---| |<--- 358 + +---+ +---+ +---+ +---+ 359 + ^ 360 + | 361 + head page 424 362 425 363 426 - tail page 427 - | 428 - v 429 - +---+ +---+ +---+ +---+ 430 - <---| |--->| |--->| |--->| |---> 431 - --->| |<---| |<---| |<---| |<--- 432 - +---+ +---+ +---+ +---+ 433 - ^ 434 - | 435 - head page 364 + tail page 365 + | 366 + v 367 + +---+ +---+ +---+ +---+ 368 + <---| |--->| |--->| |--->| |---> 369 + --->| |<---| |<---| |<---| |<--- 370 + +---+ +---+ +---+ +---+ 371 + ^ 372 + | 373 + head page 374 + 375 + 376 + tail page 377 + | 378 + v 379 + +---+ +---+ +---+ +---+ 380 + <---| |--->| |--->| |--->| |---> 381 + --->| |<---| |<---| |<---| |<--- 382 + +---+ +---+ +---+ +---+ 383 + ^ 384 + | 385 + head page 436 386 437 387 Note, the reader page will still point to the previous head page. 438 388 But when a swap takes place, it will use the most recent head page. ··· 447 397 each page must be aligned in memory by 4 bytes. This will allow the 2 448 398 least significant bits of the address to be used as flags, since 449 399 they will always be zero for the address. To get the address, 450 - simply mask out the flags. 400 + simply mask out the flags:: 451 401 452 402 MASK = ~3 453 403 ··· 455 405 456 406 Two flags will be kept by these two bits: 457 407 458 - HEADER - the page being pointed to is a head page 408 + HEADER 409 + - the page being pointed to is a head page 459 410 460 - UPDATE - the page being pointed to is being updated by a writer 411 + UPDATE 412 + - the page being pointed to is being updated by a writer 461 413 and was or is about to be a head page. 462 414 415 + :: 463 416 464 - reader page 465 - | 466 - v 467 - +---+ 468 - | |------+ 469 - +---+ | 470 - | 471 - v 472 - +---+ +---+ +---+ +---+ 473 - <---| |--->| |-H->| |--->| |---> 474 - --->| |<---| |<---| |<---| |<--- 475 - +---+ +---+ +---+ +---+ 417 + reader page 418 + | 419 + v 420 + +---+ 421 + | |------+ 422 + +---+ | 423 + | 424 + v 425 + +---+ +---+ +---+ +---+ 426 + <---| |--->| |-H->| |--->| |---> 427 + --->| |<---| |<---| |<---| |<--- 428 + +---+ +---+ +---+ +---+ 476 429 477 430 478 431 The above pointer "-H->" would have the HEADER flag set. That is ··· 483 430 This pointer means the next page is the head page. 484 431 485 432 When the tail page meets the head pointer, it will use cmpxchg to 486 - change the pointer to the UPDATE state: 433 + change the pointer to the UPDATE state:: 487 434 488 435 489 - tail page 490 - | 491 - v 492 - +---+ +---+ +---+ +---+ 493 - <---| |--->| |-H->| |--->| |---> 494 - --->| |<---| |<---| |<---| |<--- 495 - +---+ +---+ +---+ +---+ 436 + tail page 437 + | 438 + v 439 + +---+ +---+ +---+ +---+ 440 + <---| |--->| |-H->| |--->| |---> 441 + --->| |<---| |<---| |<---| |<--- 442 + +---+ +---+ +---+ +---+ 496 443 497 - tail page 498 - | 499 - v 500 - +---+ +---+ +---+ +---+ 501 - <---| |--->| |-U->| |--->| |---> 502 - --->| |<---| |<---| |<---| |<--- 503 - +---+ +---+ +---+ +---+ 444 + tail page 445 + | 446 + v 447 + +---+ +---+ +---+ +---+ 448 + <---| |--->| |-U->| |--->| |---> 449 + --->| |<---| |<---| |<---| |<--- 450 + +---+ +---+ +---+ +---+ 504 451 505 452 "-U->" represents a pointer in the UPDATE state. 506 453 ··· 515 462 and the reader will need to look for the new head page and try again. 516 463 Note, the flags UPDATE and HEADER are never set at the same time. 517 464 518 - The reader swaps the reader page as follows: 465 + The reader swaps the reader page as follows:: 519 466 520 467 +------+ 521 468 |reader| RING BUFFER ··· 530 477 +-----H-------------+ 531 478 532 479 The reader sets the reader page next pointer as HEADER to the page after 533 - the head page. 480 + the head page:: 534 481 535 482 536 483 +------+ ··· 548 495 549 496 It does a cmpxchg with the pointer to the previous head page to make it 550 497 point to the reader page. Note that the new pointer does not have the HEADER 551 - flag set. This action atomically moves the head page forward. 498 + flag set. This action atomically moves the head page forward:: 552 499 553 500 +------+ 554 501 |reader| RING BUFFER ··· 564 511 +------------------------------------+ 565 512 566 513 After the new head page is set, the previous pointer of the head page is 567 - updated to the reader page. 514 + updated to the reader page:: 568 515 569 516 +------+ 570 517 |reader| RING BUFFER ··· 601 548 602 549 Note, the way to determine a reader page is simply by examining the previous 603 550 pointer of the page. If the next pointer of the previous page does not 604 - point back to the original page, then the original page is a reader page: 551 + point back to the original page, then the original page is a reader page:: 605 552 606 553 607 554 +--------+ ··· 625 572 move the head page, until the writer is finished with the move. 626 573 627 574 This eliminates any races that the reader can have on the writer. The reader 628 - must spin, and this is why the reader cannot preempt the writer. 575 + must spin, and this is why the reader cannot preempt the writer:: 629 576 630 - tail page 631 - | 632 - v 633 - +---+ +---+ +---+ +---+ 634 - <---| |--->| |-H->| |--->| |---> 635 - --->| |<---| |<---| |<---| |<--- 636 - +---+ +---+ +---+ +---+ 577 + tail page 578 + | 579 + v 580 + +---+ +---+ +---+ +---+ 581 + <---| |--->| |-H->| |--->| |---> 582 + --->| |<---| |<---| |<---| |<--- 583 + +---+ +---+ +---+ +---+ 637 584 638 - tail page 639 - | 640 - v 641 - +---+ +---+ +---+ +---+ 642 - <---| |--->| |-U->| |--->| |---> 643 - --->| |<---| |<---| |<---| |<--- 644 - +---+ +---+ +---+ +---+ 585 + tail page 586 + | 587 + v 588 + +---+ +---+ +---+ +---+ 589 + <---| |--->| |-U->| |--->| |---> 590 + --->| |<---| |<---| |<---| |<--- 591 + +---+ +---+ +---+ +---+ 645 592 646 - The following page will be made into the new head page. 593 + The following page will be made into the new head page:: 647 594 648 - tail page 649 - | 650 - v 651 - +---+ +---+ +---+ +---+ 652 - <---| |--->| |-U->| |-H->| |---> 653 - --->| |<---| |<---| |<---| |<--- 654 - +---+ +---+ +---+ +---+ 595 + tail page 596 + | 597 + v 598 + +---+ +---+ +---+ +---+ 599 + <---| |--->| |-U->| |-H->| |---> 600 + --->| |<---| |<---| |<---| |<--- 601 + +---+ +---+ +---+ +---+ 655 602 656 603 After the new head page has been set, we can set the old head page 657 - pointer back to NORMAL. 604 + pointer back to NORMAL:: 658 605 659 - tail page 660 - | 661 - v 662 - +---+ +---+ +---+ +---+ 663 - <---| |--->| |--->| |-H->| |---> 664 - --->| |<---| |<---| |<---| |<--- 665 - +---+ +---+ +---+ +---+ 606 + tail page 607 + | 608 + v 609 + +---+ +---+ +---+ +---+ 610 + <---| |--->| |--->| |-H->| |---> 611 + --->| |<---| |<---| |<---| |<--- 612 + +---+ +---+ +---+ +---+ 666 613 667 - After the head page has been moved, the tail page may now move forward. 614 + After the head page has been moved, the tail page may now move forward:: 668 615 669 - tail page 670 - | 671 - v 672 - +---+ +---+ +---+ +---+ 673 - <---| |--->| |--->| |-H->| |---> 674 - --->| |<---| |<---| |<---| |<--- 675 - +---+ +---+ +---+ +---+ 616 + tail page 617 + | 618 + v 619 + +---+ +---+ +---+ +---+ 620 + <---| |--->| |--->| |-H->| |---> 621 + --->| |<---| |<---| |<---| |<--- 622 + +---+ +---+ +---+ +---+ 676 623 677 624 678 625 The above are the trivial updates. Now for the more complex scenarios. ··· 683 630 page. At this time, we must start dropping writes (usually with some kind 684 631 of warning to the user). But what happens if the commit was still on the 685 632 reader page? The commit page is not part of the ring buffer. The tail page 686 - must account for this. 633 + must account for this:: 687 634 688 635 689 - reader page commit page 690 - | | 691 - v | 692 - +---+ | 693 - | |<----------+ 694 - | | 695 - | |------+ 696 - +---+ | 697 - | 698 - v 699 - +---+ +---+ +---+ +---+ 700 - <---| |--->| |-H->| |--->| |---> 701 - --->| |<---| |<---| |<---| |<--- 702 - +---+ +---+ +---+ +---+ 703 - ^ 704 - | 705 - tail page 636 + reader page commit page 637 + | | 638 + v | 639 + +---+ | 640 + | |<----------+ 641 + | | 642 + | |------+ 643 + +---+ | 644 + | 645 + v 646 + +---+ +---+ +---+ +---+ 647 + <---| |--->| |-H->| |--->| |---> 648 + --->| |<---| |<---| |<---| |<--- 649 + +---+ +---+ +---+ +---+ 650 + ^ 651 + | 652 + tail page 706 653 707 654 If the tail page were to simply push the head page forward, the commit when 708 655 leaving the reader page would not be pointing to the correct page. ··· 729 676 is not the next page, the tail page is simply updated with a cmpxchg. 730 677 731 678 Only writers move the tail page. This must be done atomically to protect 732 - against nested writers. 679 + against nested writers:: 733 680 734 681 temp_page = tail_page 735 682 next_page = temp_page->next ··· 737 684 738 685 The above will update the tail page if it is still pointing to the expected 739 686 page. If this fails, a nested write pushed it forward, the current write 740 - does not need to push it. 687 + does not need to push it:: 741 688 742 689 743 - temp page 744 - | 745 - v 746 - tail page 747 - | 748 - v 749 - +---+ +---+ +---+ +---+ 750 - <---| |--->| |--->| |--->| |---> 751 - --->| |<---| |<---| |<---| |<--- 752 - +---+ +---+ +---+ +---+ 690 + temp page 691 + | 692 + v 693 + tail page 694 + | 695 + v 696 + +---+ +---+ +---+ +---+ 697 + <---| |--->| |--->| |--->| |---> 698 + --->| |<---| |<---| |<---| |<--- 699 + +---+ +---+ +---+ +---+ 753 700 754 - Nested write comes in and moves the tail page forward: 701 + Nested write comes in and moves the tail page forward:: 755 702 756 - tail page (moved by nested writer) 757 - temp page | 758 - | | 759 - v v 760 - +---+ +---+ +---+ +---+ 761 - <---| |--->| |--->| |--->| |---> 762 - --->| |<---| |<---| |<---| |<--- 763 - +---+ +---+ +---+ +---+ 703 + tail page (moved by nested writer) 704 + temp page | 705 + | | 706 + v v 707 + +---+ +---+ +---+ +---+ 708 + <---| |--->| |--->| |--->| |---> 709 + --->| |<---| |<---| |<---| |<--- 710 + +---+ +---+ +---+ +---+ 764 711 765 712 The above would fail the cmpxchg, but since the tail page has already 766 713 been moved forward, the writer will just try again to reserve storage 767 714 on the new tail page. 768 715 769 - But the moving of the head page is a bit more complex. 716 + But the moving of the head page is a bit more complex:: 770 717 771 - tail page 772 - | 773 - v 774 - +---+ +---+ +---+ +---+ 775 - <---| |--->| |-H->| |--->| |---> 776 - --->| |<---| |<---| |<---| |<--- 777 - +---+ +---+ +---+ +---+ 718 + tail page 719 + | 720 + v 721 + +---+ +---+ +---+ +---+ 722 + <---| |--->| |-H->| |--->| |---> 723 + --->| |<---| |<---| |<---| |<--- 724 + +---+ +---+ +---+ +---+ 778 725 779 - The write converts the head page pointer to UPDATE. 726 + The write converts the head page pointer to UPDATE:: 780 727 781 - tail page 782 - | 783 - v 784 - +---+ +---+ +---+ +---+ 785 - <---| |--->| |-U->| |--->| |---> 786 - --->| |<---| |<---| |<---| |<--- 787 - +---+ +---+ +---+ +---+ 728 + tail page 729 + | 730 + v 731 + +---+ +---+ +---+ +---+ 732 + <---| |--->| |-U->| |--->| |---> 733 + --->| |<---| |<---| |<---| |<--- 734 + +---+ +---+ +---+ +---+ 788 735 789 736 But if a nested writer preempts here, it will see that the next 790 737 page is a head page, but it is also nested. It will detect that ··· 792 739 fact that it sees the UPDATE flag instead of a HEADER or NORMAL 793 740 pointer. 794 741 795 - The nested writer will set the new head page pointer. 742 + The nested writer will set the new head page pointer:: 796 743 797 - tail page 798 - | 799 - v 800 - +---+ +---+ +---+ +---+ 801 - <---| |--->| |-U->| |-H->| |---> 802 - --->| |<---| |<---| |<---| |<--- 803 - +---+ +---+ +---+ +---+ 744 + tail page 745 + | 746 + v 747 + +---+ +---+ +---+ +---+ 748 + <---| |--->| |-U->| |-H->| |---> 749 + --->| |<---| |<---| |<---| |<--- 750 + +---+ +---+ +---+ +---+ 804 751 805 752 But it will not reset the update back to normal. Only the writer 806 753 that converted a pointer from HEAD to UPDATE will convert it back 807 - to NORMAL. 754 + to NORMAL:: 808 755 809 - tail page 810 - | 811 - v 812 - +---+ +---+ +---+ +---+ 813 - <---| |--->| |-U->| |-H->| |---> 814 - --->| |<---| |<---| |<---| |<--- 815 - +---+ +---+ +---+ +---+ 756 + tail page 757 + | 758 + v 759 + +---+ +---+ +---+ +---+ 760 + <---| |--->| |-U->| |-H->| |---> 761 + --->| |<---| |<---| |<---| |<--- 762 + +---+ +---+ +---+ +---+ 816 763 817 764 After the nested writer finishes, the outermost writer will convert 818 - the UPDATE pointer to NORMAL. 765 + the UPDATE pointer to NORMAL:: 819 766 820 767 821 - tail page 822 - | 823 - v 824 - +---+ +---+ +---+ +---+ 825 - <---| |--->| |--->| |-H->| |---> 826 - --->| |<---| |<---| |<---| |<--- 827 - +---+ +---+ +---+ +---+ 768 + tail page 769 + | 770 + v 771 + +---+ +---+ +---+ +---+ 772 + <---| |--->| |--->| |-H->| |---> 773 + --->| |<---| |<---| |<---| |<--- 774 + +---+ +---+ +---+ +---+ 828 775 829 776 830 777 It can be even more complex if several nested writes came in and moved 831 - the tail page ahead several pages: 778 + the tail page ahead several pages:: 832 779 833 780 834 - (first writer) 781 + (first writer) 835 782 836 - tail page 837 - | 838 - v 839 - +---+ +---+ +---+ +---+ 840 - <---| |--->| |-H->| |--->| |---> 841 - --->| |<---| |<---| |<---| |<--- 842 - +---+ +---+ +---+ +---+ 783 + tail page 784 + | 785 + v 786 + +---+ +---+ +---+ +---+ 787 + <---| |--->| |-H->| |--->| |---> 788 + --->| |<---| |<---| |<---| |<--- 789 + +---+ +---+ +---+ +---+ 843 790 844 - The write converts the head page pointer to UPDATE. 791 + The write converts the head page pointer to UPDATE:: 845 792 846 - tail page 847 - | 848 - v 849 - +---+ +---+ +---+ +---+ 850 - <---| |--->| |-U->| |--->| |---> 851 - --->| |<---| |<---| |<---| |<--- 852 - +---+ +---+ +---+ +---+ 793 + tail page 794 + | 795 + v 796 + +---+ +---+ +---+ +---+ 797 + <---| |--->| |-U->| |--->| |---> 798 + --->| |<---| |<---| |<---| |<--- 799 + +---+ +---+ +---+ +---+ 853 800 854 801 Next writer comes in, and sees the update and sets up the new 855 - head page. 802 + head page:: 856 803 857 - (second writer) 804 + (second writer) 858 805 859 - tail page 860 - | 861 - v 862 - +---+ +---+ +---+ +---+ 863 - <---| |--->| |-U->| |-H->| |---> 864 - --->| |<---| |<---| |<---| |<--- 865 - +---+ +---+ +---+ +---+ 806 + tail page 807 + | 808 + v 809 + +---+ +---+ +---+ +---+ 810 + <---| |--->| |-U->| |-H->| |---> 811 + --->| |<---| |<---| |<---| |<--- 812 + +---+ +---+ +---+ +---+ 866 813 867 814 The nested writer moves the tail page forward. But does not set the old 868 - update page to NORMAL because it is not the outermost writer. 815 + update page to NORMAL because it is not the outermost writer:: 869 816 870 - tail page 871 - | 872 - v 873 - +---+ +---+ +---+ +---+ 874 - <---| |--->| |-U->| |-H->| |---> 875 - --->| |<---| |<---| |<---| |<--- 876 - +---+ +---+ +---+ +---+ 817 + tail page 818 + | 819 + v 820 + +---+ +---+ +---+ +---+ 821 + <---| |--->| |-U->| |-H->| |---> 822 + --->| |<---| |<---| |<---| |<--- 823 + +---+ +---+ +---+ +---+ 877 824 878 825 Another writer preempts and sees the page after the tail page is a head page. 879 - It changes it from HEAD to UPDATE. 826 + It changes it from HEAD to UPDATE:: 880 827 881 - (third writer) 828 + (third writer) 882 829 883 - tail page 884 - | 885 - v 886 - +---+ +---+ +---+ +---+ 887 - <---| |--->| |-U->| |-U->| |---> 888 - --->| |<---| |<---| |<---| |<--- 889 - +---+ +---+ +---+ +---+ 830 + tail page 831 + | 832 + v 833 + +---+ +---+ +---+ +---+ 834 + <---| |--->| |-U->| |-U->| |---> 835 + --->| |<---| |<---| |<---| |<--- 836 + +---+ +---+ +---+ +---+ 890 837 891 - The writer will move the head page forward: 838 + The writer will move the head page forward:: 892 839 893 840 894 - (third writer) 841 + (third writer) 895 842 896 - tail page 897 - | 898 - v 899 - +---+ +---+ +---+ +---+ 900 - <---| |--->| |-U->| |-U->| |-H-> 901 - --->| |<---| |<---| |<---| |<--- 902 - +---+ +---+ +---+ +---+ 843 + tail page 844 + | 845 + v 846 + +---+ +---+ +---+ +---+ 847 + <---| |--->| |-U->| |-U->| |-H-> 848 + --->| |<---| |<---| |<---| |<--- 849 + +---+ +---+ +---+ +---+ 903 850 904 851 But now that the third writer did change the HEAD flag to UPDATE it 905 - will convert it to normal: 852 + will convert it to normal:: 906 853 907 854 908 - (third writer) 855 + (third writer) 909 856 910 - tail page 911 - | 912 - v 913 - +---+ +---+ +---+ +---+ 914 - <---| |--->| |-U->| |--->| |-H-> 915 - --->| |<---| |<---| |<---| |<--- 916 - +---+ +---+ +---+ +---+ 917 - 918 - 919 - Then it will move the tail page, and return back to the second writer. 857 + tail page 858 + | 859 + v 860 + +---+ +---+ +---+ +---+ 861 + <---| |--->| |-U->| |--->| |-H-> 862 + --->| |<---| |<---| |<---| |<--- 863 + +---+ +---+ +---+ +---+ 920 864 921 865 922 - (second writer) 866 + Then it will move the tail page, and return back to the second writer:: 923 867 924 - tail page 925 - | 926 - v 927 - +---+ +---+ +---+ +---+ 928 - <---| |--->| |-U->| |--->| |-H-> 929 - --->| |<---| |<---| |<---| |<--- 930 - +---+ +---+ +---+ +---+ 868 + 869 + (second writer) 870 + 871 + tail page 872 + | 873 + v 874 + +---+ +---+ +---+ +---+ 875 + <---| |--->| |-U->| |--->| |-H-> 876 + --->| |<---| |<---| |<---| |<--- 877 + +---+ +---+ +---+ +---+ 931 878 932 879 933 880 The second writer will fail to move the tail page because it was already 934 881 moved, so it will try again and add its data to the new tail page. 935 - It will return to the first writer. 882 + It will return to the first writer:: 936 883 937 884 938 - (first writer) 885 + (first writer) 939 886 940 - tail page 941 - | 942 - v 943 - +---+ +---+ +---+ +---+ 944 - <---| |--->| |-U->| |--->| |-H-> 945 - --->| |<---| |<---| |<---| |<--- 946 - +---+ +---+ +---+ +---+ 887 + tail page 888 + | 889 + v 890 + +---+ +---+ +---+ +---+ 891 + <---| |--->| |-U->| |--->| |-H-> 892 + --->| |<---| |<---| |<---| |<--- 893 + +---+ +---+ +---+ +---+ 947 894 948 895 The first writer cannot know atomically if the tail page moved 949 896 while it updates the HEAD page. It will then update the head page to 950 - what it thinks is the new head page. 897 + what it thinks is the new head page:: 951 898 952 899 953 - (first writer) 900 + (first writer) 954 901 955 - tail page 956 - | 957 - v 958 - +---+ +---+ +---+ +---+ 959 - <---| |--->| |-U->| |-H->| |-H-> 960 - --->| |<---| |<---| |<---| |<--- 961 - +---+ +---+ +---+ +---+ 902 + tail page 903 + | 904 + v 905 + +---+ +---+ +---+ +---+ 906 + <---| |--->| |-U->| |-H->| |-H-> 907 + --->| |<---| |<---| |<---| |<--- 908 + +---+ +---+ +---+ +---+ 962 909 963 910 Since the cmpxchg returns the old value of the pointer the first writer 964 911 will see it succeeded in updating the pointer from NORMAL to HEAD. 965 912 But as we can see, this is not good enough. It must also check to see 966 - if the tail page is either where it use to be or on the next page: 913 + if the tail page is either where it use to be or on the next page:: 967 914 968 915 969 - (first writer) 916 + (first writer) 970 917 971 - A B tail page 972 - | | | 973 - v v v 974 - +---+ +---+ +---+ +---+ 975 - <---| |--->| |-U->| |-H->| |-H-> 976 - --->| |<---| |<---| |<---| |<--- 977 - +---+ +---+ +---+ +---+ 918 + A B tail page 919 + | | | 920 + v v v 921 + +---+ +---+ +---+ +---+ 922 + <---| |--->| |-U->| |-H->| |-H-> 923 + --->| |<---| |<---| |<---| |<--- 924 + +---+ +---+ +---+ +---+ 978 925 979 926 If tail page != A and tail page != B, then it must reset the pointer 980 927 back to NORMAL. The fact that it only needs to worry about nested 981 - writers means that it only needs to check this after setting the HEAD page. 928 + writers means that it only needs to check this after setting the HEAD page:: 982 929 983 930 984 - (first writer) 931 + (first writer) 985 932 986 - A B tail page 987 - | | | 988 - v v v 989 - +---+ +---+ +---+ +---+ 990 - <---| |--->| |-U->| |--->| |-H-> 991 - --->| |<---| |<---| |<---| |<--- 992 - +---+ +---+ +---+ +---+ 933 + A B tail page 934 + | | | 935 + v v v 936 + +---+ +---+ +---+ +---+ 937 + <---| |--->| |-U->| |--->| |-H-> 938 + --->| |<---| |<---| |<---| |<--- 939 + +---+ +---+ +---+ +---+ 993 940 994 941 Now the writer can update the head page. This is also why the head page must 995 942 remain in UPDATE and only reset by the outermost writer. This prevents 996 - the reader from seeing the incorrect head page. 943 + the reader from seeing the incorrect head page:: 997 944 998 945 999 - (first writer) 946 + (first writer) 1000 947 1001 - A B tail page 1002 - | | | 1003 - v v v 1004 - +---+ +---+ +---+ +---+ 1005 - <---| |--->| |--->| |--->| |-H-> 1006 - --->| |<---| |<---| |<---| |<--- 1007 - +---+ +---+ +---+ +---+ 1008 - 948 + A B tail page 949 + | | | 950 + v v v 951 + +---+ +---+ +---+ +---+ 952 + <---| |--->| |--->| |--->| |-H-> 953 + --->| |<---| |<---| |<---| |<--- 954 + +---+ +---+ +---+ +---+

+2 -2

Documentation/trace/stm.rst

··· 33 33 have a name (string identifier) and a range of masters and channels 34 34 associated with it, located in "stp-policy" subsystem directory in 35 35 configfs. The topmost directory's name (the policy) is formatted as 36 - the STM device name to which this policy applies and and arbitrary 37 - string identifier separated by a stop. From the examle above, a rule 36 + the STM device name to which this policy applies and an arbitrary 37 + string identifier separated by a stop. From the example above, a rule 38 38 may look like this:: 39 39 40 40 $ ls /config/stp-policy/dummy_stm.my-policy/user

+18

Documentation/translations/it_IT/core-api/index.rst

··· 1 + =============================== 2 + Documentazione dell'API di base 3 + =============================== 4 + 5 + Utilità di base 6 + =============== 7 + 8 + .. toctree:: 9 + :maxdepth: 1 10 + 11 + symbol-namespaces 12 + 13 + .. only:: subproject and html 14 + 15 + Indices 16 + ======= 17 + 18 + * :ref:`genindex`

+166

Documentation/translations/it_IT/core-api/symbol-namespaces.rst

··· 1 + .. include:: ../disclaimer-ita.rst 2 + 3 + :Original: :doc:`../../../core-api/symbol-namespaces` 4 + :Translator: Federico Vaga <federico.vaga@vaga.pv.it> 5 + 6 + =========================== 7 + Spazio dei nomi dei simboli 8 + =========================== 9 + 10 + Questo documento descrive come usare lo spazio dei nomi dei simboli 11 + per strutturare quello che viene esportato internamente al kernel 12 + grazie alle macro della famiglia EXPORT_SYMBOL(). 13 + 14 + 1. Introduzione 15 + =============== 16 + 17 + Lo spazio dei nomi dei simboli è stato introdotto come mezzo per strutturare 18 + l'API esposta internamente al kernel. Permette ai manutentori di un 19 + sottosistema di organizzare i simboli esportati in diversi spazi di 20 + nomi. Questo meccanismo è utile per la documentazione (pensate ad 21 + esempio allo spazio dei nomi SUBSYSTEM_DEBUG) così come per limitare 22 + la disponibilità di un gruppo di simboli in altre parti del kernel. Ad 23 + oggi, i moduli che usano simboli esportati da uno spazio di nomi 24 + devono prima importare detto spazio. Altrimenti il kernel, a seconda 25 + della configurazione, potrebbe rifiutare di caricare il modulo o 26 + avvisare l'utente di un'importazione mancante. 27 + 28 + 2. Come definire uno spazio dei nomi dei simboli 29 + ================================================ 30 + 31 + I simboli possono essere esportati in spazi dei nomi usando diversi 32 + meccanismi. Tutti questi meccanismi cambiano il modo in cui 33 + EXPORT_SYMBOL e simili vengono guidati verso la creazione di voci in ksymtab. 34 + 35 + 2.1 Usare le macro EXPORT_SYMBOL 36 + ================================ 37 + 38 + In aggiunta alle macro EXPORT_SYMBOL() e EXPORT_SYMBOL_GPL(), che permettono 39 + di esportare simboli del kernel nella rispettiva tabella, ci sono 40 + varianti che permettono di esportare simboli all'interno di uno spazio dei 41 + nomi: EXPORT_SYMBOL_NS() ed EXPORT_SYMBOL_NS_GPL(). Queste macro richiedono un 42 + argomento aggiuntivo: lo spazio dei nomi. 43 + Tenete presente che per via dell'espansione delle macro questo argomento deve 44 + essere un simbolo di preprocessore. Per esempio per esportare il 45 + simbolo `usb_stor_suspend` nello spazio dei nomi `USB_STORAGE` usate:: 46 + 47 + EXPORT_SYMBOL_NS(usb_stor_suspend, USB_STORAGE); 48 + 49 + Di conseguenza, nella tabella dei simboli del kernel ci sarà una voce 50 + rappresentata dalla struttura `kernel_symbol` che avrà il campo 51 + `namespace` (spazio dei nomi) impostato. Un simbolo esportato senza uno spazio 52 + dei nomi avrà questo campo impostato a `NULL`. Non esiste uno spazio dei nomi 53 + di base. Il programma `modpost` e il codice in kernel/module.c usano lo spazio 54 + dei nomi, rispettivamente, durante la compilazione e durante il caricamento 55 + di un modulo. 56 + 57 + 2.2 Usare il simbolo di preprocessore DEFAULT_SYMBOL_NAMESPACE 58 + ============================================================== 59 + 60 + Definire lo spazio dei nomi per tutti i simboli di un sottosistema può essere 61 + logorante e di difficile manutenzione. Perciò è stato fornito un simbolo 62 + di preprocessore di base (DEFAULT_SYMBOL_NAMESPACE), che, se impostato, 63 + diventa lo spazio dei simboli di base per tutti gli usi di EXPORT_SYMBOL() 64 + ed EXPORT_SYMBOL_GPL() che non specificano esplicitamente uno spazio dei nomi. 65 + 66 + Ci sono molti modi per specificare questo simbolo di preprocessore e il loro 67 + uso dipende dalle preferenze del manutentore di un sottosistema. La prima 68 + possibilità è quella di definire il simbolo nel `Makefile` del sottosistema. 69 + Per esempio per esportare tutti i simboli definiti in usb-common nello spazio 70 + dei nomi USB_COMMON, si può aggiungere la seguente linea in 71 + drivers/usb/common/Makefile:: 72 + 73 + ccflags-y += -DDEFAULT_SYMBOL_NAMESPACE=USB_COMMON 74 + 75 + Questo cambierà tutte le macro EXPORT_SYMBOL() ed EXPORT_SYMBOL_GPL(). Invece, 76 + un simbolo esportato con EXPORT_SYMBOL_NS() non verrà cambiato e il simbolo 77 + verrà esportato nello spazio dei nomi indicato. 78 + 79 + Una seconda possibilità è quella di definire il simbolo di preprocessore 80 + direttamente nei file da compilare. L'esempio precedente diventerebbe:: 81 + 82 + #undef DEFAULT_SYMBOL_NAMESPACE 83 + #define DEFAULT_SYMBOL_NAMESPACE USB_COMMON 84 + 85 + Questo va messo prima di un qualsiasi uso di EXPORT_SYMBOL. 86 + 87 + 3. Come usare i simboli esportati attraverso uno spazio dei nomi 88 + ================================================================ 89 + 90 + Per usare i simboli esportati da uno spazio dei nomi, i moduli del 91 + kernel devono esplicitamente importare il relativo spazio dei nomi; altrimenti 92 + il kernel potrebbe rifiutarsi di caricare il modulo. Il codice del 93 + modulo deve usare la macro MODULE_IMPORT_NS per importare lo spazio 94 + dei nomi che contiene i simboli desiderati. Per esempio un modulo che 95 + usa il simbolo usb_stor_suspend deve importare lo spazio dei nomi 96 + USB_STORAGE usando la seguente dichiarazione:: 97 + 98 + MODULE_IMPORT_NS(USB_STORAGE); 99 + 100 + Questo creerà un'etichetta `modinfo` per ogni spazio dei nomi 101 + importato. Un risvolto di questo fatto è che gli spazi dei 102 + nomi importati da un modulo possono essere ispezionati tramite 103 + modinfo:: 104 + 105 + $ modinfo drivers/usb/storage/ums-karma.ko 106 + [...] 107 + import_ns: USB_STORAGE 108 + [...] 109 + 110 + 111 + Si consiglia di posizionare la dichiarazione MODULE_IMPORT_NS() vicino 112 + ai metadati del modulo come MODULE_AUTHOR() o MODULE_LICENSE(). Fate 113 + riferimento alla sezione 5. per creare automaticamente le importazioni 114 + mancanti. 115 + 116 + 4. Caricare moduli che usano simboli provenienti da spazi dei nomi 117 + ================================================================== 118 + 119 + Quando un modulo viene caricato (per esempio usando `insmod`), il kernel 120 + verificherà la disponibilità di ogni simbolo usato e se lo spazio dei nomi 121 + che potrebbe contenerli è stato importato. Il comportamento di base del kernel 122 + è di rifiutarsi di caricare quei moduli che non importano tutti gli spazi dei 123 + nomi necessari. L'errore verrà annotato e il caricamento fallirà con l'errore 124 + EINVAL. Per caricare i moduli che non soddisfano questo requisito esiste 125 + un'opzione di configurazione: impostare 126 + MODULE_ALLOW_MISSING_NAMESPACE_IMPORTS=y caricherà i moduli comunque ma 127 + emetterà un avviso. 128 + 129 + 5. Creare automaticamente la dichiarazione MODULE_IMPORT_NS 130 + =========================================================== 131 + 132 + La mancanza di un'importazione può essere individuata facilmente al momento 133 + della compilazione. Infatti, modpost emetterà un avviso se il modulo usa 134 + un simbolo da uno spazio dei nomi che non è stato importato. 135 + La dichiarazione MODULE_IMPORT_NS() viene solitamente aggiunta in un posto 136 + ben definito (assieme agli altri metadati del modulo). Per facilitare 137 + la vita di chi scrive moduli (e i manutentori di sottosistemi), esistono uno 138 + script e un target make per correggere le importazioni mancanti. Questo può 139 + essere fatto con:: 140 + 141 + $ make nsdeps 142 + 143 + Lo scenario tipico di chi scrive un modulo potrebbe essere:: 144 + 145 + - scrivere codice che dipende da un simbolo appartenente ad uno spazio 146 + dei nomi non importato 147 + - eseguire `make` 148 + - aver notato un avviso da modpost che parla di un'importazione 149 + mancante 150 + - eseguire `make nsdeps` per aggiungere import nel posto giusto 151 + 152 + Per i manutentori di sottosistemi che vogliono aggiungere uno spazio dei nomi, 153 + l'approccio è simile. Di nuovo, eseguendo `make nsdeps` aggiungerà le 154 + importazioni mancanti nei moduli inclusi nel kernel:: 155 + 156 + - spostare o aggiungere simboli ad uno spazio dei nomi (per esempio 157 + usando EXPORT_SYMBOL_NS()) 158 + - eseguire `make` (preferibilmente con allmodconfig per coprire tutti 159 + i moduli del kernel) 160 + - aver notato un avviso da modpost che parla di un'importazione 161 + mancante 162 + - eseguire `make nsdeps` per aggiungere import nel posto giusto 163 + 164 + Potete anche eseguire nsdeps per moduli esterni. Solitamente si usa così:: 165 + 166 + $ make -C <path_to_kernel_src> M=$PWD nsdeps

+3 -2

Documentation/translations/it_IT/index.rst

··· 121 121 (o almeno ci proviamo — probabilmente *non* tutto quello che è davvero 122 122 necessario). 123 123 124 - .. warning:: 124 + .. toctree:: 125 + :maxdepth: 2 125 126 126 - TODO ancora da tradurre 127 + core-api/index 127 128 128 129 Documentazione specifica per architettura 129 130 -----------------------------------------

+2 -2

Documentation/translations/it_IT/kernel-hacking/hacking.rst

··· 634 634 635 635 Questa è una variate di `EXPORT_SYMBOL()` che permette di specificare uno 636 636 spazio dei nomi. Lo spazio dei nomi è documentato in 637 - :doc:`../../../core-api/symbol-namespaces` 637 + :doc:`../core-api/symbol-namespaces` 638 638 639 639 :c:func:`EXPORT_SYMBOL_NS_GPL()` 640 640 -------------------------------- ··· 643 643 644 644 Questa è una variate di `EXPORT_SYMBOL_GPL()` che permette di specificare uno 645 645 spazio dei nomi. Lo spazio dei nomi è documentato in 646 - :doc:`../../../core-api/symbol-namespaces` 646 + :doc:`../core-api/symbol-namespaces` 647 647 648 648 Procedure e convenzioni 649 649 =======================

+1 -1

Documentation/translations/it_IT/process/coding-style.rst

··· 1097 1097 1098 1098 Se avete una variabile o funzione che potrebbe non essere usata in alcune 1099 1099 configurazioni, e quindi il compilatore potrebbe avvisarvi circa la definizione 1100 - inutilizzata, marcate questa definizione come __maybe_used piuttosto che 1100 + inutilizzata, marcate questa definizione come __maybe_unused piuttosto che 1101 1101 racchiuderla in una direttiva condizionale del preprocessore. (Comunque, 1102 1102 se una variabile o funzione è *sempre* inutilizzata, rimuovetela). 1103 1103

+3 -3

Documentation/translations/ko_KR/memory-barriers.txt

··· 570 570 [*] 버스 마스터링 DMA 와 일관성에 대해서는 다음을 참고하시기 바랍니다: 571 571 572 572 Documentation/driver-api/pci/pci.rst 573 - Documentation/DMA-API-HOWTO.txt 574 - Documentation/DMA-API.txt 573 + Documentation/core-api/dma-api-howto.rst 574 + Documentation/core-api/dma-api.rst 575 575 576 576 577 577 데이터 의존성 배리어 (역사적) ··· 1907 1907 1908 1908 writel_relaxed() 와 같은 완화된 I/O 접근자들에 대한 자세한 내용을 위해서는 1909 1909 "커널 I/O 배리어의 효과" 섹션을, consistent memory 에 대한 자세한 내용을 1910 - 위해선 Documentation/DMA-API.txt 문서를 참고하세요. 1910 + 위해선 Documentation/core-api/dma-api.rst 문서를 참고하세요. 1911 1911 1912 1912 1913 1913 =========================

+9

Documentation/translations/zh_CN/admin-guide/clearing-warn-once.rst

··· 1 + 清除 WARN_ONCE 2 + -------------- 3 + 4 + WARN_ONCE / WARN_ON_ONCE / printk_once 仅仅打印一次消息. 5 + 6 + echo 1 > /sys/kernel/debug/clear_warn_once 7 + 8 + 可以清除这种状态并且再次允许打印一次告警信息，这对于运行测试集后重现问题 9 + 很有用。

+105

Documentation/translations/zh_CN/admin-guide/cpu-load.rst

··· 1 + ======= 2 + CPU 负载 3 + ======= 4 + 5 + Linux通过``/proc/stat``和``/proc/uptime``导出各种信息，用户空间工具 6 + 如top(1)使用这些信息计算系统花费在某个特定状态的平均时间。 7 + 例如： 8 + 9 + $ iostat 10 + Linux 2.6.18.3-exp (linmac) 02/20/2007 11 + 12 + avg-cpu: %user %nice %system %iowait %steal %idle 13 + 10.01 0.00 2.92 5.44 0.00 81.63 14 + 15 + ... 16 + 17 + 这里系统认为在默认采样周期內有10.01%的时间工作在用户空间，2.92%的时 18 + 间用在系统空间，总体上有81.63%的时间是空闲的。 19 + 20 + 大多数情况下``/proc/stat``的信息几乎真实反映了系统信息，然而，由于内 21 + 核采集这些数据的方式/时间的特点，有时这些信息根本不可靠。 22 + 23 + 那么这些信息是如何被搜集的呢？每当时间中断触发时，内核查看此刻运行的 24 + 进程类型，并增加与此类型/状态进程对应的计数器的值。这种方法的问题是 25 + 在两次时间中断之间系统（进程）能够在多种状态之间切换多次，而计数器只 26 + 增加最后一种状态下的计数。 27 + 28 + 举例 29 + --- 30 + 31 + 假设系统有一个进程以如下方式周期性地占用cpu:: 32 + 33 + 两个时钟中断之间的时间线 34 + |-----------------------| 35 + ^ ^ 36 + |_ 开始运行 | 37 + |_ 开始睡眠 38 + （很快会被唤醒） 39 + 40 + 在上面的情况下，根据``/proc/stat``的信息（由于当系统处于空闲状态时， 41 + 时间中断经常会发生）系统的负载将会是0 42 + 43 + 大家能够想象内核的这种行为会发生在许多情况下，这将导致``/proc/stat`` 44 + 中存在相当古怪的信息:: 45 + 46 + /* gcc -o hog smallhog.c */ 47 + #include <time.h> 48 + #include <limits.h> 49 + #include <signal.h> 50 + #include <sys/time.h> 51 + #define HIST 10 52 + 53 + static volatile sig_atomic_t stop; 54 + 55 + static void sighandler (int signr) 56 + { 57 + (void) signr; 58 + stop = 1; 59 + } 60 + static unsigned long hog (unsigned long niters) 61 + { 62 + stop = 0; 63 + while (!stop && --niters); 64 + return niters; 65 + } 66 + int main (void) 67 + { 68 + int i; 69 + struct itimerval it = { .it_interval = { .tv_sec = 0, .tv_usec = 1 }, 70 + .it_value = { .tv_sec = 0, .tv_usec = 1 } }; 71 + sigset_t set; 72 + unsigned long v[HIST]; 73 + double tmp = 0.0; 74 + unsigned long n; 75 + signal (SIGALRM, &sighandler); 76 + setitimer (ITIMER_REAL, &it, NULL); 77 + 78 + hog (ULONG_MAX); 79 + for (i = 0; i < HIST; ++i) v[i] = ULONG_MAX - hog (ULONG_MAX); 80 + for (i = 0; i < HIST; ++i) tmp += v[i]; 81 + tmp /= HIST; 82 + n = tmp - (tmp / 3.0); 83 + 84 + sigemptyset (&set); 85 + sigaddset (&set, SIGALRM); 86 + 87 + for (;;) { 88 + hog (n); 89 + sigwait (&set, &i); 90 + } 91 + return 0; 92 + } 93 + 94 + 95 + 参考 96 + --- 97 + 98 + - http://lkml.org/lkml/2007/2/12/6 99 + - Documentation/filesystems/proc.rst (1.8) 100 + 101 + 102 + 谢谢 103 + --- 104 + 105 + Con Kolivas, Pavel Machek

+125

Documentation/translations/zh_CN/admin-guide/index.rst

··· 1 + .. include:: ../disclaimer-zh_CN.rst 2 + 3 + :Original: :ref:`Documentation/admin-guide/index.rst` 4 + :Translator: Alex Shi <alex.shi@linux.alibaba.com> 5 + 6 + 7 + Linux 内核用户和管理员指南 8 + ========================== 9 + 10 + 下面是一组随时间添加到内核中的面向用户的文档的集合。到目前为止，还没有一个 11 + 整体的顺序或组织 - 这些材料不是一个单一的，连贯的文件！幸运的话，情况会随着 12 + 时间的推移而迅速改善。 13 + 14 + 这个初始部分包含总体信息，包括描述内核的README，关于内核参数的文档等。 15 + 16 + Todolist: 17 + 18 + README 19 + kernel-parameters 20 + devices 21 + sysctl/index 22 + 23 + 本节介绍CPU漏洞及其缓解措施。 24 + 25 + Todolist: 26 + 27 + hw-vuln/index 28 + 29 + 下面的一组文档，针对的是试图跟踪问题和bug的用户。 30 + 31 + Todolist: 32 + 33 + reporting-bugs 34 + security-bugs 35 + bug-hunting 36 + bug-bisect 37 + tainted-kernels 38 + ramoops 39 + dynamic-debug-howto 40 + init 41 + kdump/index 42 + perf/index 43 + 44 + 这是应用程序开发人员感兴趣的章节的开始。可以在这里找到涵盖内核ABI各个 45 + 方面的文档。 46 + 47 + Todolist: 48 + 49 + sysfs-rules 50 + 51 + 本手册的其余部分包括各种指南，介绍如何根据您的喜好配置内核的特定行为。 52 + 53 + 54 + .. toctree:: 55 + :maxdepth: 1 56 + 57 + clearing-warn-once 58 + cpu-load 59 + 60 + Todolist: 61 + 62 + acpi/index 63 + aoe/index 64 + auxdisplay/index 65 + bcache 66 + binderfs 67 + binfmt-misc 68 + blockdev/index 69 + bootconfig 70 + braille-console 71 + btmrvl 72 + cgroup-v1/index 73 + cgroup-v2 74 + cifs/index 75 + cputopology 76 + dell_rbu 77 + device-mapper/index 78 + edid 79 + efi-stub 80 + ext4 81 + nfs/index 82 + gpio/index 83 + highuid 84 + hw_random 85 + initrd 86 + iostats 87 + java 88 + jfs 89 + kernel-per-CPU-kthreads 90 + laptops/index 91 + lcd-panel-cgram 92 + ldm 93 + lockup-watchdogs 94 + LSM/index 95 + md 96 + media/index 97 + mm/index 98 + module-signing 99 + mono 100 + namespaces/index 101 + numastat 102 + parport 103 + perf-security 104 + pm/index 105 + pnp 106 + rapidio 107 + ras 108 + rtc 109 + serial-console 110 + svga 111 + sysrq 112 + thunderbolt 113 + ufs 114 + unicode 115 + vga-softcursor 116 + video-output 117 + wimax/index 118 + xfs 119 + 120 + .. only:: subproject and html 121 + 122 + Indices 123 + ======= 124 + 125 + * :ref:`genindex`

+1 -1

Documentation/translations/zh_CN/arm/Booting

··· 124 124 125 125 bootloader 必须以 64bit 地址对齐的形式加载一个设备树映像(dtb)到系统 126 126 RAM 中，并用启动数据初始化它。dtb 格式在文档 127 - Documentation/devicetree/booting-without-of.txt 中。内核将会在 127 + Documentation/devicetree/booting-without-of.rst 中。内核将会在 128 128 dtb 物理地址处查找 dtb 魔数值（0xd00dfeed），以确定 dtb 是否已经代替 129 129 标签列表被传递进来。 130 130

+4 -2

Documentation/translations/zh_CN/filesystems/sysfs.txt

··· 213 213 214 214 - 缓冲区应总是 PAGE_SIZE 大小。对于i386，这个值为4096。 215 215 216 - - show() 方法应该返回写入缓冲区的字节数，也就是 snprintf()的 216 + - show() 方法应该返回写入缓冲区的字节数，也就是 scnprintf()的 217 217 返回值。 218 218 219 - - show() 应始终使用 snprintf()。 219 + - show() 方法在将格式化返回值返回用户空间的时候，禁止使用snprintf()。 220 + 如果可以保证不会发生缓冲区溢出，可以使用sprintf()，否则必须使用 221 + scnprintf()。 220 222 221 223 - store() 应返回缓冲区的已用字节数。如果整个缓存都已填满，只需返回 222 224 count 参数。

+4

Documentation/translations/zh_CN/index.rst

··· 10 10 人员做出贡献。与任何大型社区一样，知道如何完成任务将使得更改合并的过程变得更 11 11 加容易。 12 12 13 + 翻译计划: 14 + 内核中文文档欢迎任何翻译投稿，特别是关于内核用户和管理员指南部分。 15 + 13 16 .. toctree:: 14 17 :maxdepth: 2 15 18 19 + admin-guide/index 16 20 process/index 17 21 filesystems/index 18 22

+4 -4

Documentation/translations/zh_CN/process/2.Process.rst

··· 212 212 213 213 当前-mm 补丁可在“mmotm”（-mm of the moment）目录中找到，地址： 214 214 215 - http://www.ozlabs.org/~akpm/mmotm/ 215 + https://www.ozlabs.org/~akpm/mmotm/ 216 216 217 217 然而，使用mmotm树可能是一种令人沮丧的体验；它甚至可能无法编译。 218 218 ··· 220 220 linux-next 是下一个合并窗口关闭后主线的快照。linux-next树在Linux-kernel 和 221 221 Linux-next 邮件列表中发布，可从以下位置下载： 222 222 223 - http://www.kernel.org/pub/linux/kernel/next/ 223 + https://www.kernel.org/pub/linux/kernel/next/ 224 224 225 225 Linux-next 已经成为内核开发过程中不可或缺的一部分；在一个给定的合并窗口中合并 226 226 的所有补丁都应该在合并窗口打开之前的一段时间内找到进入Linux-next 的方法。 ··· 260 260 261 261 现在几乎所有的Linux发行版都打包了Git。主页位于： 262 262 263 - http://git-scm.com/ 263 + https://git-scm.com/ 264 264 265 265 那个页面有指向文档和教程的指针。 266 266 ··· 272 272 273 273 另一个值得了解的工具是quilt: 274 274 275 - http://savannah.nongnu.org/projects/quilt 275 + https://savannah.nongnu.org/projects/quilt 276 276 277 277 Quilt 是一个补丁管理系统，而不是源代码管理系统。它不会随着时间的推移跟踪历史； 278 278 相反，它面向根据不断发展的代码库跟踪一组特定的更改。一些主要的子系统维护人员

+1 -1

Documentation/translations/zh_CN/process/4.Coding.rst

··· 224 224 或Blackfin开发板，您仍然可以执行编译步骤。可以在以下位置找到一组用于x86系统的 225 225 大型交叉编译器： 226 226 227 - http://www.kernel.org/pub/tools/crosstool/ 227 + https://www.kernel.org/pub/tools/crosstool/ 228 228 229 229 花一些时间安装和使用这些编译器将有助于避免以后的尴尬。 230 230

+3 -3

Documentation/translations/zh_CN/process/7.AdvancedTopics.rst

··· 25 25 将是Git如何特别适合内核开发过程。想要加快Git的开发人员可以在以下网站上找到 26 26 更多信息： 27 27 28 - http://git-scm.com/ 28 + https://git-scm.com/ 29 29 30 - http://www.kernel.org/pub/software/scm/git/docs/user-manual.html 30 + https://www.kernel.org/pub/software/scm/git/docs/user-manual.html 31 31 32 32 在尝试使用它使补丁可供其他人使用之前，第一要务是阅读上述站点，对Git的工作 33 33 方式有一个扎实的了解。使用Git的开发人员应该能够获得主线存储库的副本，探索 ··· 42 42 如果您有一个可以访问Internet的系统，那么使用git守护进程设置这样的服务器相 43 43 对简单。否则，免费的公共托管网站（例如github）开始出现在网络上。成熟的开发 44 44 人员可以在kernel.org上获得一个帐户，但这些帐户并不容易找到；有关更多信息， 45 - 请参阅 http://kernel.org/faq/ 45 + 请参阅 https://kernel.org/faq/ 46 46 47 47 正常的Git工作流程涉及到许多分支的使用。每一条开发线都可以分为单独的“主题 48 48 分支”，并独立维护。Git的分支机构很便宜，没有理由不免费使用它们。而且，在

+5 -5

Documentation/translations/zh_CN/process/8.Conclusion.rst

··· 17 17 记录的；“make htmldocs”或“make pdfdocs”可用于以HTML或PDF格式生成这些文档（ 18 18 尽管某些发行版提供的tex版本会遇到内部限制，无法正确处理文档）。 19 19 20 - 不同的网站在各个细节层次上讨论内核开发。您的作者想谦虚地建议用 http://lwn.net/ 20 + 不同的网站在各个细节层次上讨论内核开发。您的作者想谦虚地建议用 https://lwn.net/ 21 21 作为来源；有关许多特定内核主题的信息可以通过以下网址的lwn内核索引找到： 22 22 23 23 http://lwn.net/kernel/index/ 24 24 25 25 除此之外，内核开发人员的一个宝贵资源是： 26 26 27 - http://kernelnewbies.org/ 27 + https://kernelnewbies.org/ 28 28 29 - 当然，我们不应该忘记 http://kernel.org/ 这是内核发布信息的最终位置。 29 + 当然，我们不应该忘记 https://kernel.org/ 这是内核发布信息的最终位置。 30 30 31 31 关于内核开发有很多书： 32 32 ··· 42 42 43 43 有关git的文档，请访问： 44 44 45 - http://www.kernel.org/pub/software/scm/git/docs/ 45 + https://www.kernel.org/pub/software/scm/git/docs/ 46 46 47 - http://www.kernel.org/pub/software/scm/git/docs/user-manual.html 47 + https://www.kernel.org/pub/software/scm/git/docs/user-manual.html 48 48 49 49 结论 50 50 ====

+1 -1

Documentation/translations/zh_CN/process/coding-style.rst

··· 946 946 ISBN 0-201-61586-X. 947 947 948 948 GNU 手册 - 遵循 K&R 标准和此文本 - cpp, gcc, gcc internals and indent, 949 - 都可以从 http://www.gnu.org/manual/ 找到 949 + 都可以从 https://www.gnu.org/manual/ 找到 950 950 951 951 WG14 是 C 语言的国际标准化工作组，URL: http://www.open-std.org/JTC1/SC22/WG14/ 952 952

+6 -6

Documentation/translations/zh_CN/process/howto.rst

··· 69 69 邮件组里的人并不是律师，不要期望他们的话有法律效力。 70 70 71 71 对于GPL的常见问题和解答，请访问以下链接： 72 - http://www.gnu.org/licenses/gpl-faq.html 72 + https://www.gnu.org/licenses/gpl-faq.html 73 73 74 74 75 75 文档 ··· 109 109 其他关于如何正确地生成补丁的优秀文档包括： 110 110 "The Perfect Patch" 111 111 112 - http://www.ozlabs.org/~akpm/stuff/tpp.txt 112 + https://www.ozlabs.org/~akpm/stuff/tpp.txt 113 113 114 114 "Linux kernel patch submission format" 115 115 ··· 163 163 ------------------ 164 164 如果你对Linux内核开发一无所知，你应该访问“Linux内核新手”计划： 165 165 166 - http://kernelnewbies.org 166 + https://kernelnewbies.org 167 167 168 168 它拥有一个可以问各种最基本的内核开发问题的邮件列表（在提问之前一定要记得 169 169 查找已往的邮件，确认是否有人已经回答过相同的问题）。它还拥有一个可以获得 ··· 176 176 如果你想加入内核开发社区并协助完成一些任务，却找不到从哪里开始，可以访问 177 177 “Linux内核房管员”计划： 178 178 179 - http://kernelnewbies.org/KernelJanitors 179 + https://kernelnewbies.org/KernelJanitors 180 180 181 181 这是极佳的起点。它提供一个相对简单的任务列表，列出内核代码中需要被重新 182 182 整理或者改正的地方。通过和负责这个计划的开发者们一同工作，你会学到将补丁 ··· 212 212 - 每当一个新版本的内核被发布，为期两周的集成窗口将被打开。在这段时间里 213 213 维护者可以向Linus提交大段的修改，通常这些修改已经被放到-mm内核中几个 214 214 星期了。提交大量修改的首选方式是使用git工具（内核的代码版本管理工具 215 - ，更多的信息可以在 http://git-scm.com/ 获取），不过使用普通补丁也是 215 + ，更多的信息可以在 https://git-scm.com/ 获取），不过使用普通补丁也是 216 216 可以的。 217 217 - 两个星期以后-rc1版本内核发布。之后只有不包含可能影响整个内核稳定性的 218 218 新功能的补丁才可能被接受。请注意一个全新的驱动程序（或者文件系统）有 ··· 472 472 473 473 想了解它具体应该看起来像什么，请查阅以下文档中的“ChangeLog”章节： 474 474 “The Perfect Patch” 475 - http://www.ozlabs.org/~akpm/stuff/tpp.txt 475 + https://www.ozlabs.org/~akpm/stuff/tpp.txt 476 476 477 477 478 478 这些事情有时候做起来很难。要在任何方面都做到完美可能需要好几年时间。这是

+9 -9

Documentation/translations/zh_CN/process/submitting-drivers.rst

··· 19 19 ============================= 20 20 21 21 这篇文档将会解释如何向不同的内核源码树提交设备驱动程序。请注意，如果你感 22 - 兴趣的是显卡驱动程序，你也许应该访问 XFree86 项目(http://www.xfree86.org/) 23 - 和／或 X.org 项目 (http://x.org)。 22 + 兴趣的是显卡驱动程序，你也许应该访问 XFree86 项目(https://www.xfree86.org/) 23 + 和／或 X.org 项目 (https://x.org)。 24 24 25 25 另请参阅 Documentation/translations/zh_CN/process/submitting-patches.rst 文档。 26 26 ··· 29 29 ---------- 30 30 31 31 块设备和字符设备的主设备号与从设备号是由 Linux 命名编号分配权威 LANANA（ 32 - 现在是 Torben Mathiasen）负责分配。申请的网址是 http://www.lanana.org/。 32 + 现在是 Torben Mathiasen）负责分配。申请的网址是 https://www.lanana.org/。 33 33 即使不准备提交到主流内核的设备驱动也需要在这里分配设备号。有关详细信息， 34 34 请参阅 Documentation/admin-guide/devices.rst。 35 35 ··· 133 133 [可通过向majordomo@vger.kernel.org发邮件来订阅] 134 134 135 135 Linux 设备驱动程序，第三版（探讨 2.6.10 版内核）： 136 - http://lwn.net/Kernel/LDD3/ （免费版） 136 + https://lwn.net/Kernel/LDD3/ （免费版） 137 137 138 138 LWN.net: 139 - 每周内核开发活动摘要 - http://lwn.net/ 139 + 每周内核开发活动摘要 - https://lwn.net/ 140 140 141 141 2.6 版中 API 的变更： 142 142 143 - http://lwn.net/Articles/2.6-kernel-api/ 143 + https://lwn.net/Articles/2.6-kernel-api/ 144 144 145 145 将旧版内核的驱动程序移植到 2.6 版： 146 146 147 - http://lwn.net/Articles/driver-porting/ 147 + https://lwn.net/Articles/driver-porting/ 148 148 149 149 内核新手(KernelNewbies): 150 150 为新的内核开发者提供文档和帮助 151 - http://kernelnewbies.org/ 151 + https://kernelnewbies.org/ 152 152 153 153 Linux USB项目： 154 154 http://www.linux-usb.org/ ··· 157 157 http://www.fenrus.org/how-to-not-write-a-device-driver-paper.pdf 158 158 159 159 内核清洁工 (Kernel Janitor): 160 - http://kernelnewbies.org/KernelJanitors 160 + https://kernelnewbies.org/KernelJanitors

+2 -2

Documentation/translations/zh_CN/process/submitting-patches.rst

··· 91 91 :ref:`cn_split_changes` 92 92 93 93 如果你用 ``git`` , ``git rebase -i`` 可以帮助你这一点。如果你不用 ``git``, 94 - ``quilt`` <http://savannah.nongnu.org/projects/quilt> 另外一个流行的选择。 94 + ``quilt`` <https://savannah.nongnu.org/projects/quilt> 另外一个流行的选择。 95 95 96 96 .. _cn_describe_changes: 97 97 ··· 649 649 -------- 650 650 651 651 Andrew Morton, "The perfect patch" (tpp). 652 - <http://www.ozlabs.org/~akpm/stuff/tpp.txt> 652 + <https://www.ozlabs.org/~akpm/stuff/tpp.txt> 653 653 654 654 Jeff Garzik, "Linux kernel patch submission format". 655 655 <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>

+2 -2

Documentation/translations/zh_CN/process/volatile-considered-harmful.rst

··· 94 94 注释 95 95 ---- 96 96 97 - [1] http://lwn.net/Articles/233481/ 98 - [2] http://lwn.net/Articles/233482/ 97 + [1] https://lwn.net/Articles/233481/ 98 + [2] https://lwn.net/Articles/233482/ 99 99 100 100 致谢 101 101 ----

+3 -3

Documentation/virt/kvm/amd-memory-encryption.rst

··· 270 270 See [white-paper]_, [api-spec]_, [amd-apm]_ and [kvm-forum]_ for more info. 271 271 272 272 .. [white-paper] http://amd-dev.wpengine.netdna-cdn.com/wordpress/media/2013/12/AMD_Memory_Encryption_Whitepaper_v7-Public.pdf 273 - .. [api-spec] http://support.amd.com/TechDocs/55766_SEV-KM_API_Specification.pdf 274 - .. [amd-apm] http://support.amd.com/TechDocs/24593.pdf (section 15.34) 275 - .. [kvm-forum] http://www.linux-kvm.org/images/7/74/02x08A-Thomas_Lendacky-AMDs_Virtualizatoin_Memory_Encryption_Technology.pdf 273 + .. [api-spec] https://support.amd.com/TechDocs/55766_SEV-KM_API_Specification.pdf 274 + .. [amd-apm] https://support.amd.com/TechDocs/24593.pdf (section 15.34) 275 + .. [kvm-forum] https://www.linux-kvm.org/images/7/74/02x08A-Thomas_Lendacky-AMDs_Virtualizatoin_Memory_Encryption_Technology.pdf

+9 -9

Documentation/virt/kvm/api.rst

··· 65 65 put their references to the VM's file descriptor. 66 66 67 67 Because a VM's resources are not freed until the last reference to its 68 - file descriptor is released, creating additional references to a VM via 68 + file descriptor is released, creating additional references to a VM 69 69 via fork(), dup(), etc... without careful consideration is strongly 70 70 discouraged and may have unwanted side effects, e.g. memory allocated 71 71 by and on behalf of the VM's process may not be freed/unaccounted when ··· 536 536 ========= =================================== 537 537 0 on success, 538 538 -EEXIST if an interrupt is already enqueued 539 - -EINVAL the the irq number is invalid 539 + -EINVAL the irq number is invalid 540 540 -ENXIO if the PIC is in the kernel 541 541 -EFAULT if the pointer is invalid 542 542 ========= =================================== ··· 3147 3147 :Capability: basic 3148 3148 :Architectures: arm, arm64 3149 3149 :Type: vm ioctl 3150 - :Parameters: struct struct kvm_vcpu_init (out) 3150 + :Parameters: struct kvm_vcpu_init (out) 3151 3151 :Returns: 0 on success; -1 on error 3152 3152 3153 3153 Errors: ··· 3167 3167 3168 3168 The information returned by this ioctl can be used to prepare an instance 3169 3169 of struct kvm_vcpu_init for KVM_ARM_VCPU_INIT ioctl which will result in 3170 - in VCPU matching underlying host. 3170 + VCPU matching underlying host. 3171 3171 3172 3172 3173 3173 4.84 KVM_GET_REG_LIST ··· 5856 5856 :Architectures: ppc 5857 5857 5858 5858 This capability, if KVM_CHECK_EXTENSION indicates that it is 5859 - available, means that that the kernel has an implementation of the 5859 + available, means that the kernel has an implementation of the 5860 5860 H_RANDOM hypercall backed by a hardware random-number generator. 5861 5861 If present, the kernel H_RANDOM handler can be enabled for guest use 5862 5862 with the KVM_CAP_PPC_ENABLE_HCALL capability. ··· 5867 5867 :Architectures: x86 5868 5868 5869 5869 This capability, if KVM_CHECK_EXTENSION indicates that it is 5870 - available, means that that the kernel has an implementation of the 5870 + available, means that the kernel has an implementation of the 5871 5871 Hyper-V Synthetic interrupt controller(SynIC). Hyper-V SynIC is 5872 5872 used to support Windows Hyper-V based guest paravirt drivers(VMBus). 5873 5873 ··· 5882 5882 :Architectures: ppc 5883 5883 5884 5884 This capability, if KVM_CHECK_EXTENSION indicates that it is 5885 - available, means that that the kernel can support guests using the 5885 + available, means that the kernel can support guests using the 5886 5886 radix MMU defined in Power ISA V3.00 (as implemented in the POWER9 5887 5887 processor). 5888 5888 ··· 5892 5892 :Architectures: ppc 5893 5893 5894 5894 This capability, if KVM_CHECK_EXTENSION indicates that it is 5895 - available, means that that the kernel can support guests using the 5895 + available, means that the kernel can support guests using the 5896 5896 hashed page table MMU defined in Power ISA V3.00 (as implemented in 5897 5897 the POWER9 processor), including in-memory segment tables. 5898 5898 ··· 5997 5997 5998 5998 If KVM_CAP_ARM_USER_IRQ is supported, the KVM_CHECK_EXTENSION ioctl returns a 5999 5999 number larger than 0 indicating the version of this capability is implemented 6000 - and thereby which bits in in run->s.regs.device_irq_level can signal values. 6000 + and thereby which bits in run->s.regs.device_irq_level can signal values. 6001 6001 6002 6002 Currently the following bits are defined for the device_irq_level bitmap:: 6003 6003

+1 -1

Documentation/virt/kvm/mmu.rst

··· 480 480 =============== 481 481 482 482 - NPT presentation from KVM Forum 2008 483 - http://www.linux-kvm.org/images/c/c8/KvmForum2008%24kdf2008_21.pdf 483 + https://www.linux-kvm.org/images/c/c8/KvmForum2008%24kdf2008_21.pdf

+1 -1

Documentation/virt/kvm/nested-vmx.rst

··· 22 22 "The Turtles Project: Design and Implementation of Nested Virtualization", 23 23 available at: 24 24 25 - http://www.usenix.org/events/osdi10/tech/full_papers/Ben-Yehuda.pdf 25 + https://www.usenix.org/events/osdi10/tech/full_papers/Ben-Yehuda.pdf 26 26 27 27 28 28 Terminology

+1 -1

Documentation/virt/kvm/s390-pv.rst

··· 78 78 Only GR values needed to emulate an instruction will be copied into this 79 79 save area and the real register numbers will be hidden. 80 80 81 - The Interception Parameters state description field still contains the 81 + The Interception Parameters state description field still contains 82 82 the bytes of the instruction text, but with pre-set register values 83 83 instead of the actual ones. I.e. each instruction always uses the same 84 84 instruction text, in order not to leak guest instruction text.

+1 -1

Documentation/vm/memory-model.rst

··· 159 159 The sparse vmemmap uses a virtually mapped memory map to optimize 160 160 pfn_to_page and page_to_pfn operations. There is a global `struct 161 161 page *vmemmap` pointer that points to a virtually contiguous array of 162 - `struct page` objects. A PFN is an index to that array and the the 162 + `struct page` objects. A PFN is an index to that array and the 163 163 offset of the `struct page` from `vmemmap` is the PFN of that 164 164 page. 165 165

+1 -1

Documentation/x86/earlyprintk.rst

··· 8 8 USB2 Debug port key and a debug cable, on x86 systems. 9 9 10 10 You need two computers, the 'USB debug key' special gadget and 11 - and two USB cables, connected like this:: 11 + two USB cables, connected like this:: 12 12 13 13 [host/target] <-------> [USB debug key] <-------> [client/console] 14 14

+1 -1

Documentation/x86/x86_64/machinecheck.rst

··· 81 81 For more details about the x86 machine check architecture 82 82 see the Intel and AMD architecture manuals from their developer websites. 83 83 84 - For more details about the architecture see 84 + For more details about the architecture 85 85 see http://one.firstfloor.org/~andi/mce.pdf

Documentation/xz.txt Documentation/staging/xz.rst

+11 -11

MAINTAINERS

··· 2867 2867 M: David Howells <dhowells@redhat.com> 2868 2868 L: keyrings@vger.kernel.org 2869 2869 S: Maintained 2870 - F: Documentation/crypto/asymmetric-keys.txt 2870 + F: Documentation/crypto/asymmetric-keys.rst 2871 2871 F: crypto/asymmetric_keys/ 2872 2872 F: include/crypto/pkcs7.h 2873 2873 F: include/crypto/public_key.h ··· 2877 2877 R: Dan Williams <dan.j.williams@intel.com> 2878 2878 S: Odd fixes 2879 2879 W: http://sourceforge.net/projects/xscaleiop 2880 - F: Documentation/crypto/async-tx-api.txt 2880 + F: Documentation/crypto/async-tx-api.rst 2881 2881 F: crypto/async_tx/ 2882 2882 F: drivers/dma/ 2883 2883 F: include/linux/async_tx.h ··· 2921 2921 F: drivers/net/wireless/ath/* 2922 2922 2923 2923 ATHEROS ATH5K WIRELESS DRIVER 2924 - M: Jiri Slaby <jirislaby@gmail.com> 2924 + M: Jiri Slaby <jirislaby@kernel.org> 2925 2925 M: Nick Kossifidis <mickflemm@gmail.com> 2926 2926 M: Luis Chamberlain <mcgrof@kernel.org> 2927 2927 L: linux-wireless@vger.kernel.org ··· 7147 7147 F: include/uapi/linux/futex.h 7148 7148 F: kernel/futex.c 7149 7149 F: tools/perf/bench/futex* 7150 - F: Documentation/locking/*futex* 7150 + F: tools/testing/selftests/futex/ 7151 7151 7152 7152 GATEWORKS SYSTEM CONTROLLER (GSC) DRIVER 7153 7153 M: Tim Harvey <tharvey@gateworks.com> ··· 9655 9655 M: "David S. Miller" <davem@davemloft.net> 9656 9656 M: Masami Hiramatsu <mhiramat@kernel.org> 9657 9657 S: Maintained 9658 - F: Documentation/kprobes.txt 9658 + F: Documentation/trace/kprobes.rst 9659 9659 F: include/asm-generic/kprobes.h 9660 9660 F: include/linux/kprobes.h 9661 9661 F: kernel/kprobes.c ··· 11629 11629 F: include/uapi/linux/meye.h 11630 11630 11631 11631 MOXA SMARTIO/INDUSTIO/INTELLIO SERIAL CARD 11632 - M: Jiri Slaby <jirislaby@gmail.com> 11632 + M: Jiri Slaby <jirislaby@kernel.org> 11633 11633 S: Maintained 11634 11634 F: Documentation/driver-api/serial/moxa-smartio.rst 11635 11635 F: drivers/tty/mxser.* ··· 14582 14582 T: git git://git.kernel.org/pub/scm/linux/kernel/git/andersson/remoteproc.git rproc-next 14583 14583 F: Documentation/ABI/testing/sysfs-class-remoteproc 14584 14584 F: Documentation/devicetree/bindings/remoteproc/ 14585 - F: Documentation/remoteproc.txt 14585 + F: Documentation/staging/remoteproc.rst 14586 14586 F: drivers/remoteproc/ 14587 14587 F: include/linux/remoteproc.h 14588 14588 F: include/linux/remoteproc/ ··· 14594 14594 S: Maintained 14595 14595 T: git git://git.kernel.org/pub/scm/linux/kernel/git/andersson/remoteproc.git rpmsg-next 14596 14596 F: Documentation/ABI/testing/sysfs-bus-rpmsg 14597 - F: Documentation/rpmsg.txt 14597 + F: Documentation/staging/rpmsg.rst 14598 14598 F: drivers/rpmsg/ 14599 14599 F: include/linux/rpmsg.h 14600 14600 F: include/linux/rpmsg/ ··· 15431 15431 F: security/selinux/ 15432 15432 15433 15433 SENSABLE PHANTOM 15434 - M: Jiri Slaby <jirislaby@gmail.com> 15434 + M: Jiri Slaby <jirislaby@kernel.org> 15435 15435 S: Maintained 15436 15436 F: drivers/misc/phantom.c 15437 15437 F: include/uapi/linux/phantom.h ··· 16846 16846 M: Jens Wiklander <jens.wiklander@linaro.org> 16847 16847 L: op-tee@lists.trustedfirmware.org 16848 16848 S: Maintained 16849 - F: Documentation/tee.txt 16849 + F: Documentation/staging/tee.rst 16850 16850 F: drivers/tee/ 16851 16851 F: include/linux/tee_drv.h 16852 16852 F: include/uapi/linux/tee.h ··· 17450 17450 17451 17451 TTY LAYER 17452 17452 M: Greg Kroah-Hartman <gregkh@linuxfoundation.org> 17453 - M: Jiri Slaby <jslaby@suse.com> 17453 + M: Jiri Slaby <jirislaby@kernel.org> 17454 17454 S: Supported 17455 17455 T: git git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/tty.git 17456 17456 F: Documentation/driver-api/serial/

+1 -1

arch/Kconfig

··· 150 150 problems with received packets if doing so would not help 151 151 much. 152 152 153 - See Documentation/unaligned-memory-access.txt for more 153 + See Documentation/core-api/unaligned-memory-access.rst for more 154 154 information on the topic of unaligned memory accesses. 155 155 156 156 config ARCH_USE_BUILTIN_BSWAP

+6 -6

arch/ia64/hp/common/sba_iommu.c

··· 907 907 * @dir: dma direction 908 908 * @attrs: optional dma attributes 909 909 * 910 - * See Documentation/DMA-API-HOWTO.txt 910 + * See Documentation/core-api/dma-api-howto.rst 911 911 */ 912 912 static dma_addr_t sba_map_page(struct device *dev, struct page *page, 913 913 unsigned long poff, size_t size, ··· 1028 1028 * @dir: R/W or both. 1029 1029 * @attrs: optional dma attributes 1030 1030 * 1031 - * See Documentation/DMA-API-HOWTO.txt 1031 + * See Documentation/core-api/dma-api-howto.rst 1032 1032 */ 1033 1033 static void sba_unmap_page(struct device *dev, dma_addr_t iova, size_t size, 1034 1034 enum dma_data_direction dir, unsigned long attrs) ··· 1105 1105 * @size: number of bytes mapped in driver buffer. 1106 1106 * @dma_handle: IOVA of new buffer. 1107 1107 * 1108 - * See Documentation/DMA-API-HOWTO.txt 1108 + * See Documentation/core-api/dma-api-howto.rst 1109 1109 */ 1110 1110 static void * 1111 1111 sba_alloc_coherent(struct device *dev, size_t size, dma_addr_t *dma_handle, ··· 1162 1162 * @vaddr: virtual address IOVA of "consistent" buffer. 1163 1163 * @dma_handler: IO virtual address of "consistent" buffer. 1164 1164 * 1165 - * See Documentation/DMA-API-HOWTO.txt 1165 + * See Documentation/core-api/dma-api-howto.rst 1166 1166 */ 1167 1167 static void sba_free_coherent(struct device *dev, size_t size, void *vaddr, 1168 1168 dma_addr_t dma_handle, unsigned long attrs) ··· 1425 1425 * @dir: R/W or both. 1426 1426 * @attrs: optional dma attributes 1427 1427 * 1428 - * See Documentation/DMA-API-HOWTO.txt 1428 + * See Documentation/core-api/dma-api-howto.rst 1429 1429 */ 1430 1430 static int sba_map_sg_attrs(struct device *dev, struct scatterlist *sglist, 1431 1431 int nents, enum dma_data_direction dir, ··· 1524 1524 * @dir: R/W or both. 1525 1525 * @attrs: optional dma attributes 1526 1526 * 1527 - * See Documentation/DMA-API-HOWTO.txt 1527 + * See Documentation/core-api/dma-api-howto.rst 1528 1528 */ 1529 1529 static void sba_unmap_sg_attrs(struct device *dev, struct scatterlist *sglist, 1530 1530 int nents, enum dma_data_direction dir,

+1 -1

arch/parisc/kernel/pci-dma.c

··· 3 3 ** PARISC 1.1 Dynamic DMA mapping support. 4 4 ** This implementation is for PA-RISC platforms that do not support 5 5 ** I/O TLBs (aka DMA address translation hardware). 6 - ** See Documentation/DMA-API-HOWTO.txt for interface definitions. 6 + ** See Documentation/core-api/dma-api-howto.rst for interface definitions. 7 7 ** 8 8 ** (c) Copyright 1999,2000 Hewlett-Packard Company 9 9 ** (c) Copyright 2000 Grant Grundler

+1 -1

arch/sh/Kconfig.cpu

··· 85 85 that are lacking this bit must have another method in place for 86 86 accomplishing what is taken care of by the banked registers. 87 87 88 - See <file:Documentation/sh/register-banks.txt> for further 88 + See <file:Documentation/sh/register-banks.rst> for further 89 89 information on SR.RB and register banking in the kernel in general. 90 90 91 91 config CPU_HAS_PTEAEX

+2 -2

arch/x86/include/asm/dma-mapping.h

··· 3 3 #define _ASM_X86_DMA_MAPPING_H 4 4 5 5 /* 6 - * IOMMU interface. See Documentation/DMA-API-HOWTO.txt and 7 - * Documentation/DMA-API.txt for documentation. 6 + * IOMMU interface. See Documentation/core-api/dma-api-howto.rst and 7 + * Documentation/core-api/dma-api.rst for documentation. 8 8 */ 9 9 10 10 #include <linux/scatterlist.h>

+1 -1

arch/x86/kernel/amd_gart_64.c

··· 6 6 * This allows to use PCI devices that only support 32bit addresses on systems 7 7 * with more than 4GB. 8 8 * 9 - * See Documentation/DMA-API-HOWTO.txt for the interface specification. 9 + * See Documentation/core-api/dma-api-howto.rst for the interface specification. 10 10 * 11 11 * Copyright 2002 Andi Kleen, SuSE Labs. 12 12 */

+1 -1

crypto/asymmetric_keys/asymmetric_type.c

··· 1 1 // SPDX-License-Identifier: GPL-2.0-or-later 2 2 /* Asymmetric public-key cryptography key type 3 3 * 4 - * See Documentation/crypto/asymmetric-keys.txt 4 + * See Documentation/crypto/asymmetric-keys.rst 5 5 * 6 6 * Copyright (C) 2012 Red Hat, Inc. All Rights Reserved. 7 7 * Written by David Howells (dhowells@redhat.com)

+1 -1

crypto/asymmetric_keys/public_key.c

··· 1 1 // SPDX-License-Identifier: GPL-2.0-or-later 2 2 /* In-software asymmetric public-key crypto subtype 3 3 * 4 - * See Documentation/crypto/asymmetric-keys.txt 4 + * See Documentation/crypto/asymmetric-keys.rst 5 5 * 6 6 * Copyright (C) 2012 Red Hat, Inc. All Rights Reserved. 7 7 * Written by David Howells (dhowells@redhat.com)

+1 -1

crypto/asymmetric_keys/signature.c

··· 1 1 // SPDX-License-Identifier: GPL-2.0-or-later 2 2 /* Signature verification with an asymmetric key 3 3 * 4 - * See Documentation/crypto/asymmetric-keys.txt 4 + * See Documentation/crypto/asymmetric-keys.rst 5 5 * 6 6 * Copyright (C) 2012 Red Hat, Inc. All Rights Reserved. 7 7 * Written by David Howells (dhowells@redhat.com)

+1 -1

drivers/block/drbd/Kconfig

··· 35 35 cache coherency. 36 36 37 37 For automatic failover you need a cluster manager (e.g. heartbeat). 38 - See also: http://www.drbd.org/, http://www.linux-ha.org 38 + See also: https://www.drbd.org/, http://www.linux-ha.org 39 39 40 40 If unsure, say N. 41 41

+4 -4

drivers/md/Kconfig

··· 27 27 28 28 More information about Software RAID on Linux is contained in the 29 29 Software RAID mini-HOWTO, available from 30 - <http://www.tldp.org/docs.html#howto>. There you will also learn 30 + <https://www.tldp.org/docs.html#howto>. There you will also learn 31 31 where to get the supporting user space utilities raidtools. 32 32 33 33 If unsure, say N. ··· 71 71 72 72 Information about Software RAID on Linux is contained in the 73 73 Software-RAID mini-HOWTO, available from 74 - <http://www.tldp.org/docs.html#howto>. There you will also 74 + <https://www.tldp.org/docs.html#howto>. There you will also 75 75 learn where to get the supporting user space utilities raidtools. 76 76 77 77 To compile this as a module, choose M here: the module ··· 93 93 94 94 Information about Software RAID on Linux is contained in the 95 95 Software-RAID mini-HOWTO, available from 96 - <http://www.tldp.org/docs.html#howto>. There you will also 96 + <https://www.tldp.org/docs.html#howto>. There you will also 97 97 learn where to get the supporting user space utilities raidtools. 98 98 99 99 If you want to use such a RAID-1 set, say Y. To compile this code ··· 148 148 149 149 Information about Software RAID on Linux is contained in the 150 150 Software-RAID mini-HOWTO, available from 151 - <http://www.tldp.org/docs.html#howto>. There you will also 151 + <https://www.tldp.org/docs.html#howto>. There you will also 152 152 learn where to get the supporting user space utilities raidtools. 153 153 154 154 If you want to use such a RAID-4/RAID-5/RAID-6 set, say Y. To

+1 -1

drivers/md/dm-crypt.c

··· 300 300 * elephant: The extended version of eboiv with additional Elephant diffuser 301 301 * used with Bitlocker CBC mode. 302 302 * This mode was used in older Windows systems 303 - * http://download.microsoft.com/download/0/2/3/0238acaf-d3bf-4a6d-b3d6-0a0be4bbb36e/bitlockercipher200608.pdf 303 + * https://download.microsoft.com/download/0/2/3/0238acaf-d3bf-4a6d-b3d6-0a0be4bbb36e/bitlockercipher200608.pdf 304 304 */ 305 305 306 306 static int crypt_iv_plain_gen(struct crypt_config *cc, u8 *iv,

+1 -1

drivers/misc/Kconfig

··· 24 24 AD5271, AD5272, AD5274 25 25 digital potentiometer chips. 26 26 27 - See Documentation/misc-devices/ad525x_dpot.txt for the 27 + See Documentation/misc-devices/ad525x_dpot.rst for the 28 28 userspace interface. 29 29 30 30 This driver can also be built as a module. If so, the module

+1 -1

drivers/misc/ad525x_dpot.c

··· 58 58 * AD5272 1 1024 20, 50, 100 (50-TP) 59 59 * AD5274 1 256 20, 50, 100 (50-TP) 60 60 * 61 - * See Documentation/misc-devices/ad525x_dpot.txt for more info. 61 + * See Documentation/misc-devices/ad525x_dpot.rst for more info. 62 62 * 63 63 * derived from ad5258.c 64 64 * Copyright (c) 2009 Cyber Switching, Inc.

+7 -7

drivers/parisc/sba_iommu.c

··· 666 666 * @dev: instance of PCI owned by the driver that's asking 667 667 * @mask: number of address bits this PCI device can handle 668 668 * 669 - * See Documentation/DMA-API-HOWTO.txt 669 + * See Documentation/core-api/dma-api-howto.rst 670 670 */ 671 671 static int sba_dma_supported( struct device *dev, u64 mask) 672 672 { ··· 698 698 * @size: number of bytes to map in driver buffer. 699 699 * @direction: R/W or both. 700 700 * 701 - * See Documentation/DMA-API-HOWTO.txt 701 + * See Documentation/core-api/dma-api-howto.rst 702 702 */ 703 703 static dma_addr_t 704 704 sba_map_single(struct device *dev, void *addr, size_t size, ··· 788 788 * @size: number of bytes mapped in driver buffer. 789 789 * @direction: R/W or both. 790 790 * 791 - * See Documentation/DMA-API-HOWTO.txt 791 + * See Documentation/core-api/dma-api-howto.rst 792 792 */ 793 793 static void 794 794 sba_unmap_page(struct device *dev, dma_addr_t iova, size_t size, ··· 867 867 * @size: number of bytes mapped in driver buffer. 868 868 * @dma_handle: IOVA of new buffer. 869 869 * 870 - * See Documentation/DMA-API-HOWTO.txt 870 + * See Documentation/core-api/dma-api-howto.rst 871 871 */ 872 872 static void *sba_alloc(struct device *hwdev, size_t size, dma_addr_t *dma_handle, 873 873 gfp_t gfp, unsigned long attrs) ··· 898 898 * @vaddr: virtual address IOVA of "consistent" buffer. 899 899 * @dma_handler: IO virtual address of "consistent" buffer. 900 900 * 901 - * See Documentation/DMA-API-HOWTO.txt 901 + * See Documentation/core-api/dma-api-howto.rst 902 902 */ 903 903 static void 904 904 sba_free(struct device *hwdev, size_t size, void *vaddr, ··· 933 933 * @nents: number of entries in list 934 934 * @direction: R/W or both. 935 935 * 936 - * See Documentation/DMA-API-HOWTO.txt 936 + * See Documentation/core-api/dma-api-howto.rst 937 937 */ 938 938 static int 939 939 sba_map_sg(struct device *dev, struct scatterlist *sglist, int nents, ··· 1017 1017 * @nents: number of entries in list 1018 1018 * @direction: R/W or both. 1019 1019 * 1020 - * See Documentation/DMA-API-HOWTO.txt 1020 + * See Documentation/core-api/dma-api-howto.rst 1021 1021 */ 1022 1022 static void 1023 1023 sba_unmap_sg(struct device *dev, struct scatterlist *sglist, int nents,

+2 -2

fs/cifs/cifsacl.c

··· 49 49 {cpu_to_le32(2), 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0} }; 50 50 51 51 /* 52 - * See http://technet.microsoft.com/en-us/library/hh509017(v=ws.10).aspx 52 + * See https://technet.microsoft.com/en-us/library/hh509017(v=ws.10).aspx 53 53 */ 54 54 55 55 /* S-1-5-88 MS NFS and Apple style UID/GID/mode */ ··· 825 825 826 826 /* 827 827 * Fill in the special SID based on the mode. See 828 - * http://technet.microsoft.com/en-us/library/hh509017(v=ws.10).aspx 828 + * https://technet.microsoft.com/en-us/library/hh509017(v=ws.10).aspx 829 829 */ 830 830 unsigned int setup_special_mode_ACE(struct cifs_ace *pntace, __u64 nmode) 831 831 {

+1 -1

fs/cifs/cifsglob.h

··· 928 928 * 929 929 * Citation: 930 930 * 931 - * http://blogs.msdn.com/b/openspecification/archive/2009/04/10/smb-maximum-transmit-buffer-size-and-performance-tuning.aspx 931 + * https://blogs.msdn.com/b/openspecification/archive/2009/04/10/smb-maximum-transmit-buffer-size-and-performance-tuning.aspx 932 932 */ 933 933 #define CIFS_DEFAULT_NON_POSIX_RSIZE (60 * 1024) 934 934 #define CIFS_DEFAULT_NON_POSIX_WSIZE (65536)

+1 -1

fs/cifs/winucase.c

··· 9 9 * 10 10 * 3.1.5.3 Mapping UTF-16 Strings to Upper Case: 11 11 * 12 - * http://msdn.microsoft.com/en-us/library/hh877830.aspx 12 + * https://msdn.microsoft.com/en-us/library/hh877830.aspx 13 13 * http://www.microsoft.com/en-us/download/details.aspx?displaylang=en&id=10921 14 14 * 15 15 * In particular, the table in "Windows 8 Upper Case Mapping Table.txt" was

+1 -1

include/crypto/public_key.h

··· 1 1 /* SPDX-License-Identifier: GPL-2.0-or-later */ 2 2 /* Asymmetric public-key algorithm definitions 3 3 * 4 - * See Documentation/crypto/asymmetric-keys.txt 4 + * See Documentation/crypto/asymmetric-keys.rst 5 5 * 6 6 * Copyright (C) 2012 Red Hat, Inc. All Rights Reserved. 7 7 * Written by David Howells (dhowells@redhat.com)

+1 -1

include/keys/asymmetric-parser.h

··· 1 1 /* SPDX-License-Identifier: GPL-2.0-or-later */ 2 2 /* Asymmetric public-key cryptography data parser 3 3 * 4 - * See Documentation/crypto/asymmetric-keys.txt 4 + * See Documentation/crypto/asymmetric-keys.rst 5 5 * 6 6 * Copyright (C) 2012 Red Hat, Inc. All Rights Reserved. 7 7 * Written by David Howells (dhowells@redhat.com)

+1 -1

include/keys/asymmetric-subtype.h

··· 1 1 /* SPDX-License-Identifier: GPL-2.0-or-later */ 2 2 /* Asymmetric public-key cryptography key subtype 3 3 * 4 - * See Documentation/crypto/asymmetric-keys.txt 4 + * See Documentation/crypto/asymmetric-keys.rst 5 5 * 6 6 * Copyright (C) 2012 Red Hat, Inc. All Rights Reserved. 7 7 * Written by David Howells (dhowells@redhat.com)

+1 -1

include/keys/asymmetric-type.h

··· 1 1 /* SPDX-License-Identifier: GPL-2.0-or-later */ 2 2 /* Asymmetric Public-key cryptography key type interface 3 3 * 4 - * See Documentation/crypto/asymmetric-keys.txt 4 + * See Documentation/crypto/asymmetric-keys.rst 5 5 * 6 6 * Copyright (C) 2012 Red Hat, Inc. All Rights Reserved. 7 7 * Written by David Howells (dhowells@redhat.com)

+1 -1

include/linux/dma-mapping.h

··· 14 14 15 15 /** 16 16 * List of possible attributes associated with a DMA mapping. The semantics 17 - * of each attribute should be defined in Documentation/DMA-attributes.txt. 17 + * of each attribute should be defined in Documentation/core-api/dma-attributes.rst. 18 18 */ 19 19 20 20 /*

+1 -1

include/linux/fs.h

··· 2675 2675 2676 2676 /** 2677 2677 * file_sample_sb_err - sample the current errseq_t to test for later errors 2678 - * @mapping: mapping to be sampled 2678 + * @file: file pointer to be sampled 2679 2679 * 2680 2680 * Grab the most current superblock-level errseq_t value for the given 2681 2681 * struct file.

+1 -1

include/linux/jump_label.h

··· 68 68 * Lacking toolchain and or architecture support, static keys fall back to a 69 69 * simple conditional branch. 70 70 * 71 - * Additional babbling in: Documentation/static-keys.txt 71 + * Additional babbling in: Documentation/staging/static-keys.rst 72 72 */ 73 73 74 74 #ifndef __ASSEMBLY__

+6 -4

include/linux/kcsan-checks.h

··· 337 337 * release_for_reuse(obj); 338 338 * } 339 339 * 340 - * Note: ASSERT_EXCLUSIVE_ACCESS_SCOPED(), if applicable, performs more thorough 341 - * checking if a clear scope where no concurrent accesses are expected exists. 340 + * Note: 342 341 * 343 - * Note: For cases where the object is freed, `KASAN <kasan.html>`_ is a better 344 - * fit to detect use-after-free bugs. 342 + * 1. ASSERT_EXCLUSIVE_ACCESS_SCOPED(), if applicable, performs more thorough 343 + * checking if a clear scope where no concurrent accesses are expected exists. 344 + * 345 + * 2. For cases where the object is freed, `KASAN <kasan.html>`_ is a better 346 + * fit to detect use-after-free bugs. 345 347 * 346 348 * @var: variable to assert on 347 349 */

+2

include/linux/netdevice.h

··· 1742 1742 * @real_num_rx_queues: Number of RX queues currently active in device 1743 1743 * @xdp_prog: XDP sockets filter program pointer 1744 1744 * @gro_flush_timeout: timeout for GRO layer in NAPI 1745 + * @napi_defer_hard_irqs: If not zero, provides a counter that would 1746 + * allow to avoid NIC hard IRQ, on busy queues. 1745 1747 * 1746 1748 * @rx_handler: handler for received packets 1747 1749 * @rx_handler_data: XXX: need comments on this one

+4

include/linux/phylink.h

··· 62 62 * @dev: a pointer to a struct device associated with the MAC 63 63 * @type: operation type of PHYLINK instance 64 64 * @pcs_poll: MAC PCS cannot provide link change interrupt 65 + * @poll_fixed_state: if true, starts link_poll, 66 + * if MAC link is at %MLO_AN_FIXED mode. 67 + * @get_fixed_state: callback to execute to determine the fixed link state, 68 + * if MAC link is at %MLO_AN_FIXED mode. 65 69 */ 66 70 struct phylink_config { 67 71 struct device *dev;

+1 -1

include/media/videobuf-dma-sg.h

··· 31 31 * does memory allocation too using vmalloc_32(). 32 32 * 33 33 * videobuf_dma_*() 34 - * see Documentation/DMA-API-HOWTO.txt, these functions to 34 + * see Documentation/core-api/dma-api-howto.rst, these functions to 35 35 * basically the same. The map function does also build a 36 36 * scatterlist for the buffer (and unmap frees it ...) 37 37 *

+1 -1

init/Kconfig

··· 1985 1985 userspace. Since that isn't generally a problem on no-MMU systems, 1986 1986 it is normally safe to say Y here. 1987 1987 1988 - See Documentation/nommu-mmap.txt for more information. 1988 + See Documentation/mm/nommu-mmap.rst for more information. 1989 1989 1990 1990 config SYSTEM_DATA_VERIFICATION 1991 1991 def_bool n

+1 -1

kernel/dma/debug.c

··· 1075 1075 /* 1076 1076 * Drivers should use dma_mapping_error() to check the returned 1077 1077 * addresses of dma_map_single() and dma_map_page(). 1078 - * If not, print this warning message. See Documentation/DMA-API.txt. 1078 + * If not, print this warning message. See Documentation/core-api/dma-api.rst. 1079 1079 */ 1080 1080 if (entry->map_err_type == MAP_ERR_NOT_CHECKED) { 1081 1081 err_printk(ref->dev, entry,

+1 -1

lib/crc32.c

··· 24 24 * Version 2. See the file COPYING for more details. 25 25 */ 26 26 27 - /* see: Documentation/crc32.txt for a description of algorithms */ 27 + /* see: Documentation/staging/crc32.rst for a description of algorithms */ 28 28 29 29 #include <linux/crc32.h> 30 30 #include <linux/crc32poly.h>

+1 -1

lib/lzo/lzo1x_decompress_safe.c

··· 32 32 * depending on the base count. Since the base count is taken from a u8 33 33 * and a few bits, it is safe to assume that it will always be lower than 34 34 * or equal to 2*255, thus we can always prevent any overflow by accepting 35 - * two less 255 steps. See Documentation/lzo.txt for more information. 35 + * two less 255 steps. See Documentation/staging/lzo.rst for more information. 36 36 */ 37 37 #define MAX_255_COUNT ((((size_t)~0) / 255) - 2) 38 38

+1 -1

lib/xz/Kconfig

··· 5 5 help 6 6 LZMA2 compression algorithm and BCJ filters are supported using 7 7 the .xz file format as the container. For integrity checking, 8 - CRC32 is supported. See Documentation/xz.txt for more information. 8 + CRC32 is supported. See Documentation/staging/xz.rst for more information. 9 9 10 10 if XZ_DEC 11 11

+1 -1

mm/Kconfig

··· 387 387 This option specifies the initial value of this option. The default 388 388 of 1 says that all excess pages should be trimmed. 389 389 390 - See Documentation/nommu-mmap.txt for more information. 390 + See Documentation/mm/nommu-mmap.rst for more information. 391 391 392 392 config TRANSPARENT_HUGEPAGE 393 393 bool "Transparent Hugepage Support"

+1 -1

mm/nommu.c

··· 5 5 * Replacement code for mm functions to support CPU's that don't 6 6 * have any form of memory management unit (thus no virtual memory). 7 7 * 8 - * See Documentation/nommu-mmap.txt 8 + * See Documentation/mm/nommu-mmap.rst 9 9 * 10 10 * Copyright (c) 2004-2008 David Howells <dhowells@redhat.com> 11 11 * Copyright (c) 2000-2003 David McCullough <davidm@snapgear.com>

+1

net/core/dev.c

··· 7900 7900 7901 7901 /** 7902 7902 * netdev_get_xmit_slave - Get the xmit slave of master device 7903 + * @dev: device 7903 7904 * @skb: The packet 7904 7905 * @all_slaves: assume all the slaves are active 7905 7906 *

+1 -1

samples/kprobes/kprobe_example.c

··· 5 5 * stack trace and selected registers when _do_fork() is called. 6 6 * 7 7 * For more information on theory of operation of kprobes, see 8 - * Documentation/kprobes.txt 8 + * Documentation/staging/kprobes.rst 9 9 * 10 10 * You will see the trace data in /var/log/messages and on the console 11 11 * whenever _do_fork() is invoked to create a new process.

+1 -1

samples/kprobes/kretprobe_example.c

··· 11 11 * If no func_name is specified, _do_fork is instrumented 12 12 * 13 13 * For more information on theory of operation of kretprobes, see 14 - * Documentation/kprobes.txt 14 + * Documentation/staging/kprobes.rst 15 15 * 16 16 * Build and insert the kernel module as done in the kprobe example. 17 17 * You will see the trace data in /var/log/messages and on the console

+29 -1

scripts/kernel-doc

··· 81 81 Other parameters: 82 82 -v Verbose output, more warnings and other information. 83 83 -h Print this help. 84 + -Werror Treat warnings as errors. 84 85 85 86 EOF 86 87 print $message; ··· 274 273 my $dohighlight = ""; 275 274 276 275 my $verbose = 0; 276 + my $Werror = 0; 277 277 my $output_mode = "rst"; 278 278 my $output_preformatted = 0; 279 279 my $no_doc_sections = 0; ··· 319 317 320 318 if (defined($ENV{'KBUILD_VERBOSE'})) { 321 319 $verbose = "$ENV{'KBUILD_VERBOSE'}"; 320 + } 321 + 322 + if (defined($ENV{'KDOC_WERROR'})) { 323 + $Werror = "$ENV{'KDOC_WERROR'}"; 324 + } 325 + 326 + if (defined($ENV{'KCFLAGS'})) { 327 + my $kcflags = "$ENV{'KCFLAGS'}"; 328 + 329 + if ($kcflags =~ /Werror/) { 330 + $Werror = 1; 331 + } 322 332 } 323 333 324 334 # Generated docbook code is inserted in a template at a point where ··· 447 433 push(@export_file_list, $file); 448 434 } elsif ($cmd eq "v") { 449 435 $verbose = 1; 436 + } elsif ($cmd eq "Werror") { 437 + $Werror = 1; 450 438 } elsif (($cmd eq "h") || ($cmd eq "help")) { 451 439 usage(); 452 440 } elsif ($cmd eq 'no-doc-sections') { ··· 1099 1083 $members =~ s/\s*__packed\s*/ /gos; 1100 1084 $members =~ s/\s*CRYPTO_MINALIGN_ATTR/ /gos; 1101 1085 $members =~ s/\s*____cacheline_aligned_in_smp/ /gos; 1086 + 1102 1087 # replace DECLARE_BITMAP 1088 + $members =~ s/__ETHTOOL_DECLARE_LINK_MODE_MASK\s*$([^$]+)\)/DECLARE_BITMAP($1, __ETHTOOL_LINK_MODE_MASK_NBITS)/gos; 1103 1089 $members =~ s/DECLARE_BITMAP\s*$([^,)]+),\s*([^,)]+)$/unsigned long $1\[BITS_TO_LONGS($2)\]/gos; 1104 1090 # replace DECLARE_HASHTABLE 1105 1091 $members =~ s/DECLARE_HASHTABLE\s*$([^,)]+),\s*([^,)]+)$/unsigned long $1\[1 << (($2) - 1)\]/gos; ··· 1787 1769 $prototype =~ s@/\*.*?\*/@@gos; # strip comments. 1788 1770 $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's. 1789 1771 $prototype =~ s@^\s+@@gos; # strip leading spaces 1772 + 1773 + # Handle prototypes for function pointers like: 1774 + # int (*pcs_config)(struct foo) 1775 + $prototype =~ s@^(\S+\s+)$\s*\*(\S+)$@$1$2@gos; 1776 + 1790 1777 if ($prototype =~ /SYSCALL_DEFINE/) { 1791 1778 syscall_munge(); 1792 1779 } ··· 2278 2255 print STDERR "$warnings warnings\n"; 2279 2256 } 2280 2257 2281 - exit($output_mode eq "none" ? 0 : $errors); 2258 + if ($Werror && $warnings) { 2259 + print STDERR "$warnings warnings as Errors\n"; 2260 + exit($warnings); 2261 + } else { 2262 + exit($output_mode eq "none" ? 0 : $errors) 2263 + }

-4

scripts/sphinx-pre-install

··· 323 323 $rec_sphinx_upgrade = 1; 324 324 return; 325 325 } 326 - if ($cur_version lt $min_pdf_version) { 327 - $rec_sphinx_upgrade = 1; 328 - return; 329 - } 330 326 331 327 # On version check mode, just assume Sphinx has all mandatory deps 332 328 exit (0) if ($version_check);

+1 -1

tools/testing/selftests/vm/protection_keys.c

··· 1 1 // SPDX-License-Identifier: GPL-2.0 2 2 /* 3 - * Tests Memory Protection Keys (see Documentation/vm/protection-keys.txt) 3 + * Tests Memory Protection Keys (see Documentation/core-api/protection-keys.rst) 4 4 * 5 5 * There are examples in here of: 6 6 * * how to set protection keys on memory

Configure Feed

Configure Feed