It's been a busy cycle for documentation - hopefully the busiest for a

while to come.  Changes include:
 
  - Some new Chinese translations
 
  - Progress on the battle against double words words and non-HTTPS URLs
 
  - Some block-mq documentation
 
  - More RST conversions from Mauro.  At this point, that task is
    essentially complete, so we shouldn't see this kind of churn again for a
    while.  Unless we decide to switch to asciidoc or something...:)
 
  - Lots of typo fixes, warning fixes, and more.
 -----BEGIN PGP SIGNATURE-----
 
 iQFDBAABCAAtFiEEIw+MvkEiF49krdp9F0NaE2wMflgFAl8oVkwPHGNvcmJldEBs
 d24ubmV0AAoJEBdDWhNsDH5YoW8H/jJ/xnXFn7tkgVPQAlL3k5HCnK7A5nDP9RVR
 cg1pTx1cEFdjzxPlJyExU6/v+AImOvtweHXC+JDK7YcJ6XFUNYXJI3LxL5KwUXbY
 BL/xRFszDSXH2C7SJF5GECcFYp01e/FWSLN3yWAh+g+XwsKiTJ8q9+CoIDkHfPGO
 7oQsHKFu6s36Af0LfSgxk4sVB7EJbo8e4psuPsP5SUrl+oXRO43Put0rXkR4yJoH
 9oOaB51Do5fZp8I4JVAqGXvpXoExyLMO4yw0mASm6YSZ3KyjR8Fae+HD9Cq4ZuwY
 0uzb9K+9NEhqbfwtyBsi99S64/6Zo/MonwKwevZuhtsDTK4l4iU=
 =JQLZ
 -----END PGP SIGNATURE-----

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

Pull documentation updates from Jonathan Corbet:
 "It's been a busy cycle for documentation - hopefully the busiest for a
  while to come. Changes include:

   - Some new Chinese translations

   - Progress on the battle against double words words and non-HTTPS
     URLs

   - Some block-mq documentation

   - More RST conversions from Mauro. At this point, that task is
     essentially complete, so we shouldn't see this kind of churn again
     for a while. Unless we decide to switch to asciidoc or
     something...:)

   - Lots of typo fixes, warning fixes, and more"

* tag 'docs-5.9' of git://git.lwn.net/linux: (195 commits)
  scripts/kernel-doc: optionally treat warnings as errors
  docs: ia64: correct typo
  mailmap: add entry for <alobakin@marvell.com>
  doc/zh_CN: add cpu-load Chinese version
  Documentation/admin-guide: tainted-kernels: fix spelling mistake
  MAINTAINERS: adjust kprobes.rst entry to new location
  devices.txt: document rfkill allocation
  PCI: correct flag name
  docs: filesystems: vfs: correct flag name
  docs: filesystems: vfs: correct sync_mode flag names
  docs: path-lookup: markup fixes for emphasis
  docs: path-lookup: more markup fixes
  docs: path-lookup: fix HTML entity mojibake
  CREDITS: Replace HTTP links with HTTPS ones
  docs: process: Add an example for creating a fixes tag
  doc/zh_CN: add Chinese translation prefer section
  doc/zh_CN: add clearing-warn-once Chinese version
  doc/zh_CN: add admin-guide index
  doc:it_IT: process: coding-style.rst: Correct __maybe_unused compiler label
  futex: MAINTAINERS: Re-add selftests directory
  ...
This commit is contained in:
Linus Torvalds 2020-08-04 22:47:54 -07:00
commit 2324d50d05
274 changed files with 3327 additions and 1888 deletions

View File

@ -18,6 +18,9 @@ Aleksey Gorelov <aleksey_gorelov@phoenix.com>
Aleksandar Markovic <aleksandar.markovic@mips.com> <aleksandar.markovic@imgtec.com>
Alex Shi <alex.shi@linux.alibaba.com> <alex.shi@intel.com>
Alex Shi <alex.shi@linux.alibaba.com> <alex.shi@linaro.org>
Alexander Lobakin <alobakin@pm.me> <alobakin@dlink.ru>
Alexander Lobakin <alobakin@pm.me> <alobakin@marvell.com>
Alexander Lobakin <alobakin@pm.me> <bloodyreaper@yandex.ru>
Alexandre Belloni <alexandre.belloni@bootlin.com> <alexandre.belloni@free-electrons.com>
Alexei Starovoitov <ast@kernel.org> <ast@plumgrid.com>
Alexei Starovoitov <ast@kernel.org> <alexei.starovoitov@gmail.com>
@ -134,6 +137,11 @@ Jeff Layton <jlayton@kernel.org> <jlayton@poochiereds.net>
Jeff Layton <jlayton@kernel.org> <jlayton@primarydata.com>
Jens Axboe <axboe@suse.de>
Jens Osterkamp <Jens.Osterkamp@de.ibm.com>
Jiri Slaby <jirislaby@kernel.org> <jirislaby@gmail.com>
Jiri Slaby <jirislaby@kernel.org> <jslaby@novell.com>
Jiri Slaby <jirislaby@kernel.org> <jslaby@suse.com>
Jiri Slaby <jirislaby@kernel.org> <jslaby@suse.cz>
Jiri Slaby <jirislaby@kernel.org> <xslaby@fi.muni.cz>
Johan Hovold <johan@kernel.org> <jhovold@gmail.com>
Johan Hovold <johan@kernel.org> <johan@hovoldconsulting.com>
John Paul Adrian Glaubitz <glaubitz@physik.fu-berlin.de>
@ -151,6 +159,7 @@ Kamil Konieczny <k.konieczny@samsung.com> <k.konieczny@partner.samsung.com>
Kay Sievers <kay.sievers@vrfy.org>
Kenneth W Chen <kenneth.w.chen@intel.com>
Konstantin Khlebnikov <koct9i@gmail.com> <k.khlebnikov@samsung.com>
Konstantin Khlebnikov <koct9i@gmail.com> <khlebnikov@yandex-team.ru>
Koushik <raghavendra.koushik@neterion.com>
Krzysztof Kozlowski <krzk@kernel.org> <k.kozlowski@samsung.com>
Krzysztof Kozlowski <krzk@kernel.org> <k.kozlowski.k@gmail.com>

72
CREDITS
View File

@ -34,7 +34,7 @@ S: Romania
N: Mark Adler
E: madler@alumni.caltech.edu
W: http://alumnus.caltech.edu/~madler/
W: https://alumnus.caltech.edu/~madler/
D: zlib decompression
N: Monalisa Agrawal
@ -62,7 +62,7 @@ S: United Kingdom
N: Werner Almesberger
E: werner@almesberger.net
W: http://www.almesberger.net/
W: https://www.almesberger.net/
D: dosfs, LILO, some fd features, ATM, various other hacks here and there
S: Buenos Aires
S: Argentina
@ -96,7 +96,7 @@ S: USA
N: Erik Andersen
E: andersen@codepoet.org
W: http://www.codepoet.org/
W: https://www.codepoet.org/
P: 1024D/30D39057 1BC4 2742 E885 E4DE 9301 0C82 5F9B 643E 30D3 9057
D: Maintainer of ide-cd and Uniform CD-ROM driver,
D: ATAPI CD-Changer support, Major 2.1.x CD-ROM update.
@ -114,7 +114,7 @@ S: Canada K2P 0X3
N: H. Peter Anvin
E: hpa@zytor.com
W: http://www.zytor.com/~hpa/
W: https://www.zytor.com/~hpa/
P: 2047/2A960705 BA 03 D3 2C 14 A8 A8 BD 1E DF FE 69 EE 35 BD 74
D: Author of the SYSLINUX boot loader, maintainer of the linux.* news
D: hierarchy and the Linux Device List; various kernel hacks
@ -124,7 +124,7 @@ S: USA
N: Andrea Arcangeli
E: andrea@suse.de
W: http://www.kernel.org/pub/linux/kernel/people/andrea/
W: https://www.kernel.org/pub/linux/kernel/people/andrea/
P: 1024D/68B9CB43 13D9 8355 295F 4823 7C49 C012 DFA1 686E 68B9 CB43
P: 1024R/CB4660B9 CC A0 71 81 F4 A0 63 AC C0 4B 81 1D 8C 15 C8 E5
D: Parport hacker
@ -339,7 +339,7 @@ S: Haifa, Israel
N: Johannes Berg
E: johannes@sipsolutions.net
W: http://johannes.sipsolutions.net/
W: https://johannes.sipsolutions.net/
P: 4096R/7BF9099A C0EB C440 F6DA 091C 884D 8532 E0F3 73F3 7BF9 099A
D: powerpc & 802.11 hacker
@ -376,7 +376,7 @@ D: Original author of the Linux networking code
N: Anton Blanchard
E: anton@samba.org
W: http://samba.org/~anton/
W: https://samba.org/~anton/
P: 1024/8462A731 4C 55 86 34 44 59 A7 99 2B 97 88 4A 88 9A 0D 97
D: sun4 port, Sparc hacker
@ -509,7 +509,7 @@ S: Sweden
N: Paul Bristow
E: paul@paulbristow.net
W: http://paulbristow.net/linux/idefloppy.html
W: https://paulbristow.net/linux/idefloppy.html
D: Maintainer of IDE/ATAPI floppy driver
N: Stefano Brivio
@ -518,7 +518,7 @@ D: Broadcom B43 driver
N: Dominik Brodowski
E: linux@brodo.de
W: http://www.brodo.de/
W: https://www.brodo.de/
P: 1024D/725B37C6 190F 3E77 9C89 3B6D BECD 46EE 67C3 0308 725B 37C6
D: parts of CPUFreq code, ACPI bugfixes, PCMCIA rewrite, cpufrequtils
S: Tuebingen, Germany
@ -865,7 +865,7 @@ D: Promise DC4030VL caching HD controller drivers
N: Todd J. Derr
E: tjd@fore.com
W: http://www.wordsmith.org/~tjd
W: https://www.wordsmith.org/~tjd
D: Random console hacks and other miscellaneous stuff
S: 3000 FORE Drive
S: Warrendale, Pennsylvania 15086
@ -894,8 +894,8 @@ S: USA
N: Matt Domsch
E: Matt_Domsch@dell.com
W: http://www.dell.com/linux
W: http://domsch.com/linux
W: https://www.dell.com/linux
W: https://domsch.com/linux
D: Linux/IA-64
D: Dell PowerEdge server, SCSI layer, misc drivers, and other patches
S: Dell Inc.
@ -992,7 +992,7 @@ S: USA
N: Randy Dunlap
E: rdunlap@infradead.org
W: http://www.infradead.org/~rdunlap/
W: https://www.infradead.org/~rdunlap/
D: Linux-USB subsystem, USB core/UHCI/printer/storage drivers
D: x86 SMP, ACPI, bootflag hacking
D: documentation, builds
@ -1157,7 +1157,7 @@ S: Germany
N: Jeremy Fitzhardinge
E: jeremy@goop.org
W: http://www.goop.org/~jeremy
W: https://www.goop.org/~jeremy
D: author of userfs filesystem
D: Improved mmap and munmap handling
D: General mm minor tidyups
@ -1460,7 +1460,7 @@ S: The Netherlands
N: Oliver Hartkopp
E: oliver.hartkopp@volkswagen.de
W: http://www.volkswagen.de
W: https://www.volkswagen.de
D: Controller Area Network (network layer core)
S: Brieffach 1776
S: 38436 Wolfsburg
@ -1599,13 +1599,13 @@ S: Germany
N: Kenji Hollis
E: kenji@bitgate.com
W: http://www.bitgate.com/
W: https://www.bitgate.com/
D: Berkshire PC Watchdog Driver
D: Small/Industrial Driver Project
N: Nick Holloway
E: Nick.Holloway@pyrites.org.uk
W: http://www.pyrites.org.uk/
W: https://www.pyrites.org.uk/
P: 1024/36115A04 F4E1 3384 FCFD C055 15D6 BA4C AB03 FBF8 3611 5A04
D: Occasional Linux hacker...
S: (ask for current address)
@ -1655,7 +1655,7 @@ S: USA
N: Harald Hoyer
E: harald@redhat.com
W: http://www.harald-hoyer.de
W: https://www.harald-hoyer.de
D: ip_masq_quake
D: md boot support
S: Am Strand 5
@ -1856,7 +1856,7 @@ E: kas@fi.muni.cz
D: Author of the COSA/SRP sync serial board driver.
D: Port of the syncppp.c from the 2.0 to the 2.1 kernel.
P: 1024/D3498839 0D 99 A7 FB 20 66 05 D7 8B 35 FC DE 05 B1 8A 5E
W: http://www.fi.muni.cz/~kas/
W: https://www.fi.muni.cz/~kas/
S: c/o Faculty of Informatics, Masaryk University
S: Botanicka' 68a
S: 602 00 Brno
@ -2017,7 +2017,7 @@ S: Prague, Czech Republic
N: Gene Kozin
E: 74604.152@compuserve.com
W: http://www.sangoma.com
W: https://www.sangoma.com
D: WAN Router & Sangoma WAN drivers
S: Sangoma Technologies Inc.
S: 7170 Warden Avenue, Unit 2
@ -2112,7 +2112,7 @@ D: Original author of software suspend
N: Jaroslav Kysela
E: perex@perex.cz
W: http://www.perex.cz
W: https://www.perex.cz
D: Original Author and Maintainer for HP 10/100 Mbit Network Adapters
D: ISA PnP
S: Sindlovy Dvory 117
@ -2316,7 +2316,7 @@ S: Finland
N: Daniel J. Maas
E: dmaas@dcine.com
W: http://www.maasdigital.com
W: https://www.maasdigital.com
D: dv1394
N: Hamish Macdonald
@ -2647,7 +2647,7 @@ D: bug fixes, documentation, minor hackery
N: Paul Moore
E: paul@paul-moore.com
W: http://www.paul-moore.com
W: https://www.paul-moore.com
D: NetLabel, SELinux, audit
N: James Morris
@ -2786,7 +2786,7 @@ N: David C. Niemi
E: niemi@tux.org
W: http://www.tux.org/~niemi/
D: Assistant maintainer of Mtools, fdutils, and floppy driver
D: Administrator of Tux.Org Linux Server, http://www.tux.org
D: Administrator of Tux.Org Linux Server, https://www.tux.org
S: 2364 Old Trail Drive
S: Reston, Virginia 20191
S: USA
@ -2850,7 +2850,7 @@ S: USA
N: Mikulas Patocka
E: mikulas@artax.karlin.mff.cuni.cz
W: http://artax.karlin.mff.cuni.cz/~mikulas/
W: https://artax.karlin.mff.cuni.cz/~mikulas/
P: 1024/BB11D2D5 A0 F1 28 4A C4 14 1E CF 92 58 7A 8F 69 BC A4 D3
D: Read/write HPFS filesystem
S: Weissova 8
@ -2872,7 +2872,7 @@ D: RFC2385 Support for TCP
N: Barak A. Pearlmutter
E: bap@cs.unm.edu
W: http://www.cs.unm.edu/~bap/
W: https://www.cs.unm.edu/~bap/
P: 512/602D785D 9B A1 83 CD EE CB AD 93 20 C6 4C B7 F5 E9 60 D4
D: Author of mark-and-sweep GC integrated by Alan Cox
S: Computer Science Department
@ -3035,7 +3035,7 @@ S: United Kingdom
N: Daniel Quinlan
E: quinlan@pathname.com
W: http://www.pathname.com/~quinlan/
W: https://www.pathname.com/~quinlan/
D: FSSTND coordinator; FHS editor
D: random Linux documentation, patches, and hacks
S: 4390 Albany Drive #41A
@ -3130,7 +3130,7 @@ S: France
N: Rik van Riel
E: riel@redhat.com
W: http://www.surriel.com/
W: https://www.surriel.com/
D: Linux-MM site, Documentation/admin-guide/sysctl/*, swap/mm readaround
D: kswapd fixes, random kernel hacker, rmap VM,
D: nl.linux.org administrator, minor scheduler additions
@ -3246,7 +3246,7 @@ S: Germany
N: Paul `Rusty' Russell
E: rusty@rustcorp.com.au
W: http://ozlabs.org/~rusty
W: https://ozlabs.org/~rusty
D: Ruggedly handsome.
D: netfilter, ipchains with Michael Neuling.
S: 52 Moore St
@ -3369,7 +3369,7 @@ S: Germany
N: Robert Schwebel
E: robert@schwebel.de
W: http://www.schwebel.de
W: https://www.schwebel.de
D: Embedded hacker and book author,
D: AMD Elan support for Linux
S: Pengutronix
@ -3545,7 +3545,7 @@ S: Australia
N: Henrik Storner
E: storner@image.dk
W: http://www.image.dk/~storner/
W: http://www.sslug.dk/
W: https://www.sslug.dk/
D: Configure script: Invented tristate for module-configuration
D: vfat/msdos integration, kerneld docs, Linux promotion
D: Miscellaneous bug-fixes
@ -3579,7 +3579,7 @@ S: USA
N: Eugene Surovegin
E: ebs@ebshome.net
W: http://kernel.ebshome.net/
W: https://kernel.ebshome.net/
P: 1024D/AE5467F1 FF22 39F1 6728 89F6 6E6C 2365 7602 F33D AE54 67F1
D: Embedded PowerPC 4xx: EMAC, I2C, PIC and random hacks/fixes
S: Sunnyvale, California 94085
@ -3609,7 +3609,7 @@ S: France
N: Urs Thuermann
E: urs.thuermann@volkswagen.de
W: http://www.volkswagen.de
W: https://www.volkswagen.de
D: Controller Area Network (network layer core)
S: Brieffach 1776
S: 38436 Wolfsburg
@ -3656,7 +3656,7 @@ S: Canada K2L 1S2
N: Andrew Tridgell
E: tridge@samba.org
W: http://samba.org/tridge/
W: https://samba.org/tridge/
D: dosemu, networking, samba
S: 3 Ballow Crescent
S: MacGregor A.C.T 2615
@ -3894,7 +3894,7 @@ D: The Linux Support Team Erlangen
N: David Weinehall
E: tao@acc.umu.se
P: 1024D/DC47CA16 7ACE 0FB0 7A74 F994 9B36 E1D1 D14E 8526 DC47 CA16
W: http://www.acc.umu.se/~tao/
W: https://www.acc.umu.se/~tao/
D: v2.0 kernel maintainer
D: Fixes for the NE/2-driver
D: Miscellaneous MCA-support
@ -3919,7 +3919,7 @@ S: USA
N: Harald Welte
E: laforge@netfilter.org
P: 1024D/30F48BFF DBDE 6912 8831 9A53 879B 9190 5DA5 C655 30F4 8BFF
W: http://gnumonks.org/users/laforge
W: https://gnumonks.org/users/laforge
D: netfilter: new nat helper infrastructure
D: netfilter: ULOG, ECN, DSCP target
D: netfilter: TTL match

View File

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

View File

@ -0,0 +1,26 @@
.. SPDX-License-Identifier: GPL-2.0
==========================
PCI Test Endpoint Function
==========================
name: Should be "pci_epf_test" to bind to the pci_epf_test driver.
Configurable Fields:
================ ===========================================================
vendorid should be 0x104c
deviceid should be 0xb500 for DRA74x and 0xb501 for DRA72x
revid don't care
progif_code don't care
subclass_code don't care
baseclass_code should be 0xff
cache_line_size don't care
subsys_vendor_id don't care
subsys_id don't care
interrupt_pin Should be 1 - INTA, 2 - INTB, 3 - INTC, 4 -INTD
msi_interrupts Should be 1 to 32 depending on the number of MSI interrupts
to test
msix_interrupts Should be 1 to 2048 depending on the number of MSI-X
interrupts to test
================ ===========================================================

View File

@ -1,19 +0,0 @@
PCI TEST ENDPOINT FUNCTION
name: Should be "pci_epf_test" to bind to the pci_epf_test driver.
Configurable Fields:
vendorid : should be 0x104c
deviceid : should be 0xb500 for DRA74x and 0xb501 for DRA72x
revid : don't care
progif_code : don't care
subclass_code : don't care
baseclass_code : should be 0xff
cache_line_size : don't care
subsys_vendor_id : don't care
subsys_id : don't care
interrupt_pin : Should be 1 - INTA, 2 - INTB, 3 - INTC, 4 -INTD
msi_interrupts : Should be 1 to 32 depending on the number of MSI interrupts
to test
msix_interrupts : Should be 1 to 2048 depending on the number of MSI-X
interrupts to test

View File

@ -11,3 +11,5 @@ PCI Endpoint Framework
pci-endpoint-cfs
pci-test-function
pci-test-howto
function/binding/pci-test

View File

@ -24,7 +24,7 @@ Directory Structure
The pci_ep configfs has two directories at its root: controllers and
functions. Every EPC device present in the system will have an entry in
the *controllers* directory and and every EPF driver present in the system
the *controllers* directory and every EPF driver present in the system
will have an entry in the *functions* directory.
::

View File

@ -214,7 +214,7 @@ pci-ep-cfs.c can be used as reference for using these APIs.
* pci_epf_create()
Create a new PCI EPF device by passing the name of the PCI EPF device.
This name will be used to bind the the EPF device to a EPF driver.
This name will be used to bind the EPF device to a EPF driver.
* pci_epf_destroy()

View File

@ -248,7 +248,7 @@ STEP 4: Slot Reset
------------------
In response to a return value of PCI_ERS_RESULT_NEED_RESET, the
the platform will perform a slot reset on the requesting PCI device(s).
platform will perform a slot reset on the requesting PCI device(s).
The actual steps taken by a platform to perform a slot reset
will be platform-dependent. Upon completion of slot reset, the
platform will call the device slot_reset() callback.

View File

@ -209,7 +209,7 @@ the PCI device by calling pci_enable_device(). This will:
OS BUG: we don't check resource allocations before enabling those
resources. The sequence would make more sense if we called
pci_request_resources() before calling pci_enable_device().
Currently, the device drivers can't detect the bug when when two
Currently, the device drivers can't detect the bug when two
devices have been allocated the same range. This is not a common
problem and unlikely to get fixed soon.
@ -265,7 +265,7 @@ Set the DMA mask size
---------------------
.. note::
If anything below doesn't make sense, please refer to
Documentation/DMA-API.txt. This section is just a reminder that
:doc:`/core-api/dma-api`. This section is just a reminder that
drivers need to indicate DMA capabilities of the device and is not
an authoritative source for DMA interfaces.
@ -291,7 +291,7 @@ Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are
Setup shared control data
-------------------------
Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared)
memory. See Documentation/DMA-API.txt for a full description of
memory. See :doc:`/core-api/dma-api` for a full description of
the DMA APIs. This section is just a reminder that it needs to be done
before enabling DMA on the device.
@ -421,7 +421,7 @@ owners if there is one.
Then clean up "consistent" buffers which contain the control data.
See Documentation/DMA-API.txt for details on unmapping interfaces.
See :doc:`/core-api/dma-api` for details on unmapping interfaces.
Unregister from other subsystems

View File

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

View File

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

View File

@ -6,7 +6,7 @@ FAQ list:
=========
A FAQ list may be found in the fdutils package (see below), and also
at <http://fdutils.linux.lu/faq.html>.
at <https://fdutils.linux.lu/faq.html>.
LILO configuration options (Thinkpad users, read this)
@ -220,11 +220,11 @@ It also contains additional documentation about the floppy driver.
The latest version can be found at fdutils homepage:
http://fdutils.linux.lu
https://fdutils.linux.lu
The fdutils releases can be found at:
http://fdutils.linux.lu/download.html
https://fdutils.linux.lu/download.html
http://www.tux.org/pub/knaff/fdutils/

View File

@ -114,4 +114,4 @@ Following resources can be accounted by rdma controller.
(d) Delete resource limit::
echo echo mlx4_0 hca_handle=max hca_object=max > /sys/fs/cgroup/rdma/1/rdma.max
echo mlx4_0 hca_handle=max hca_object=max > /sys/fs/cgroup/rdma/1/rdma.max

View File

@ -1683,9 +1683,9 @@ per-cgroup dirty memory states are examined and the more restrictive
of the two is enforced.
cgroup writeback requires explicit support from the underlying
filesystem. Currently, cgroup writeback is implemented on ext2, ext4
and btrfs. On other filesystems, all writeback IOs are attributed to
the root cgroup.
filesystem. Currently, cgroup writeback is implemented on ext2, ext4,
btrfs, f2fs, and xfs. On other filesystems, all writeback IOs are
attributed to the root cgroup.
There are inherent differences in memory and writeback management
which affects how cgroup ownership is tracked. Memory is tracked per
@ -2042,7 +2042,7 @@ RDMA
----
The "rdma" controller regulates the distribution and accounting of
of RDMA resources.
RDMA resources.
RDMA Interface Files
~~~~~~~~~~~~~~~~~~~~

View File

@ -98,7 +98,7 @@ x) Finish support for SMB3.1.1 compression
Known Bugs
==========
See http://bugzilla.samba.org - search on product "CifsVFS" for
See https://bugzilla.samba.org - search on product "CifsVFS" for
current bug list. Also check http://bugzilla.kernel.org (Product = File System, Component = CIFS)
1) existing symbolic links (Windows reparse points) are recognized but

View File

@ -16,8 +16,7 @@ standard for interoperating between Macs and Windows and major NAS appliances.
Please see
MS-SMB2 (for detailed SMB2/SMB3/SMB3.1.1 protocol specification)
http://protocolfreedom.org/ and
http://samba.org/samba/PFIF/
or https://samba.org/samba/PFIF/
for more details.
@ -32,7 +31,7 @@ Build instructions
For Linux:
1) Download the kernel (e.g. from http://www.kernel.org)
1) Download the kernel (e.g. from https://www.kernel.org)
and change directory into the top of the kernel directory tree
(e.g. /usr/src/linux-2.5.73)
2) make menuconfig (or make xconfig)
@ -831,7 +830,7 @@ the active sessions and the shares that are mounted.
Enabling Kerberos (extended security) works but requires version 1.2 or later
of the helper program cifs.upcall to be present and to be configured in the
/etc/request-key.conf file. The cifs.upcall helper program is from the Samba
project(http://www.samba.org). NTLM and NTLMv2 and LANMAN support do not
project(https://www.samba.org). NTLM and NTLMv2 and LANMAN support do not
require this helper. Note that NTLMv2 security (which does not require the
cifs.upcall helper program), instead of using Kerberos, is sufficient for
some use cases.

View File

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

View File

@ -26,7 +26,7 @@ Please go to http://support.dell.com register and you can find info on
OpenManage and Dell Update packages (DUP).
Libsmbios can also be used to update BIOS on Dell systems go to
http://linux.dell.com/libsmbios/ for details.
https://linux.dell.com/libsmbios/ for details.
Dell_RBU driver supports BIOS update using the monolithic image and packetized
image methods. In case of monolithic the driver allocates a contiguous chunk

View File

@ -45,7 +45,7 @@ To use the target for the first time:
will format the device
3. unload the dm-integrity target
4. read the "provided_data_sectors" value from the superblock
5. load the dm-integrity target with the the target size
5. load the dm-integrity target with the target size
"provided_data_sectors"
6. if you want to use dm-integrity with dm-crypt, load the dm-crypt target
with the size "provided_data_sectors"
@ -99,7 +99,7 @@ interleave_sectors:number
the superblock is used.
meta_device:device
Don't interleave the data and metadata on on device. Use a
Don't interleave the data and metadata on the device. Use a
separate device for metadata.
buffer_sectors:number

View File

@ -71,7 +71,7 @@ The target is named "raid" and it accepts the following parameters::
============= ===============================================================
Reference: Chapter 4 of
http://www.snia.org/sites/default/files/SNIA_DDF_Technical_Position_v2.0.pdf
https://www.snia.org/sites/default/files/SNIA_DDF_Technical_Position_v2.0.pdf
<#raid_params>: The number of parameters that follow.

View File

@ -14,7 +14,7 @@ host-aware zoned block devices.
For a more detailed description of the zoned block device models and
their constraints see (for SCSI devices):
http://www.t10.org/drafts.htm#ZBC_Family
https://www.t10.org/drafts.htm#ZBC_Family
and (for ATA devices):

View File

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

View File

@ -618,7 +618,7 @@ kernel source: <file:fs/ext4/>
programs: http://e2fsprogs.sourceforge.net/
useful links: http://fedoraproject.org/wiki/ext3-devel
useful links: https://fedoraproject.org/wiki/ext3-devel
http://www.bullopensource.org/ext4/
http://ext4.wiki.kernel.org/index.php/Main_Page
http://fedoraproject.org/wiki/Features/Ext4
https://fedoraproject.org/wiki/Features/Ext4

View File

@ -14,7 +14,7 @@ to the core through the special register mechanism that is susceptible
to MDS attacks.
Affected processors
--------------------
-------------------
Core models (desktop, mobile, Xeon-E3) that implement RDRAND and/or RDSEED may
be affected.
@ -59,7 +59,7 @@ executed on another core or sibling thread using MDS techniques.
Mitigation mechanism
-------------------
--------------------
Intel will release microcode updates that modify the RDRAND, RDSEED, and
EGETKEY instructions to overwrite secret special register data in the shared
staging buffer before the secret data can be accessed by another logical
@ -118,7 +118,7 @@ with the option "srbds=". The option for this is:
============= =============================================================
SRBDS System Information
-----------------------
------------------------
The Linux kernel provides vulnerability status information through sysfs. For
SRBDS this can be accessed by the following sysfs file:
/sys/devices/system/cpu/vulnerabilities/srbds

View File

@ -41,6 +41,7 @@ problems and bugs in particular.
init
kdump/index
perf/index
pstore-blk
This is the beginning of a section with information of interest to
application developers. Documents covering various aspects of the kernel

View File

@ -1212,26 +1212,28 @@
Format: {"off" | "on" | "skip[mbr]"}
efi= [EFI]
Format: { "old_map", "nochunk", "noruntime", "debug",
"nosoftreserve", "disable_early_pci_dma",
"no_disable_early_pci_dma" }
old_map [X86-64]: switch to the old ioremap-based EFI
runtime services mapping. [Needs CONFIG_X86_UV=y]
Format: { "debug", "disable_early_pci_dma",
"nochunk", "noruntime", "nosoftreserve",
"novamap", "no_disable_early_pci_dma",
"old_map" }
debug: enable misc debug output.
disable_early_pci_dma: disable the busmaster bit on all
PCI bridges while in the EFI boot stub.
nochunk: disable reading files in "chunks" in the EFI
boot stub, as chunking can cause problems with some
firmware implementations.
noruntime : disable EFI runtime services support
debug: enable misc debug output
nosoftreserve: The EFI_MEMORY_SP (Specific Purpose)
attribute may cause the kernel to reserve the
memory range for a memory mapping driver to
claim. Specify efi=nosoftreserve to disable this
reservation and treat the memory by its base type
(i.e. EFI_CONVENTIONAL_MEMORY / "System RAM").
disable_early_pci_dma: Disable the busmaster bit on all
PCI bridges while in the EFI boot stub
novamap: do not call SetVirtualAddressMap().
no_disable_early_pci_dma: Leave the busmaster bit set
on all PCI bridges while in the EFI boot stub
old_map [X86-64]: switch to the old ioremap-based EFI
runtime services mapping. [Needs CONFIG_X86_UV=y]
efi_no_storage_paranoia [EFI; X86]
Using this parameter you can use more than 50% of
@ -2791,7 +2793,7 @@
touchscreen support is not enabled in the mainstream
kernel as of 2.6.30, a preliminary port can be found
in the "bleeding edge" mini2440 support kernel at
http://repo.or.cz/w/linux-2.6/mini2440.git
https://repo.or.cz/w/linux-2.6/mini2440.git
mitigations=
[X86,PPC,S390,ARM64] Control optional mitigations for

View File

@ -135,7 +135,7 @@ single project which, although still considered experimental, is fit
for use. Please feel free to add projects that have been the victims
of my ignorance.
- http://www.thinkwiki.org/wiki/HDAPS
- https://www.thinkwiki.org/wiki/HDAPS
See this page for information about Linux support of the hard disk
active protection system as implemented in IBM/Lenovo Thinkpads.

View File

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

View File

@ -905,7 +905,7 @@ temperatures:
The mapping of thermal sensors to physical locations varies depending on
system-board model (and thus, on ThinkPad model).
http://thinkwiki.org/wiki/Thermal_Sensors is a public wiki page that
https://thinkwiki.org/wiki/Thermal_Sensors is a public wiki page that
tries to track down these locations for various models.
Most (newer?) models seem to follow this pattern:
@ -926,7 +926,7 @@ For the R51 (source: Thomas Gruber):
- 3: Internal HDD
For the T43, T43/p (source: Shmidoax/Thinkwiki.org)
http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_T43.2C_T43p
https://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_T43.2C_T43p
- 2: System board, left side (near PCMCIA slot), reported as HDAPS temp
- 3: PCMCIA slot
@ -936,7 +936,7 @@ http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_T43.2C_T43p
- 11: Power regulator, underside of system board, below F2 key
The A31 has a very atypical layout for the thermal sensors
(source: Milos Popovic, http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_A31)
(source: Milos Popovic, https://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_A31)
- 1: CPU
- 2: Main Battery: main sensor

View File

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

View File

@ -35,7 +35,7 @@ physical memory (demand paging) and provides a mechanism for the
protection and controlled sharing of data between processes.
With virtual memory, each and every memory access uses a virtual
address. When the CPU decodes the an instruction that reads (or
address. When the CPU decodes an instruction that reads (or
writes) from (or to) the system memory, it translates the `virtual`
address encoded in that instruction to a `physical` address that the
memory controller can understand.

View File

@ -101,37 +101,48 @@ be specified in bytes with optional scale suffix [kKmMgG]. The default huge
page size may be selected with the "default_hugepagesz=<size>" boot parameter.
Hugetlb boot command line parameter semantics
hugepagesz - Specify a huge page size. Used in conjunction with hugepages
hugepagesz
Specify a huge page size. Used in conjunction with hugepages
parameter to preallocate a number of huge pages of the specified
size. Hence, hugepagesz and hugepages are typically specified in
pairs such as:
pairs such as::
hugepagesz=2M hugepages=512
hugepagesz can only be specified once on the command line for a
specific huge page size. Valid huge page sizes are architecture
dependent.
hugepages - Specify the number of huge pages to preallocate. This typically
hugepages
Specify the number of huge pages to preallocate. This typically
follows a valid hugepagesz or default_hugepagesz parameter. However,
if hugepages is the first or only hugetlb command line parameter it
implicitly specifies the number of huge pages of default size to
allocate. If the number of huge pages of default size is implicitly
specified, it can not be overwritten by a hugepagesz,hugepages
parameter pair for the default size.
For example, on an architecture with 2M default huge page size:
For example, on an architecture with 2M default huge page size::
hugepages=256 hugepagesz=2M hugepages=512
will result in 256 2M huge pages being allocated and a warning message
indicating that the hugepages=512 parameter is ignored. If a hugepages
parameter is preceded by an invalid hugepagesz parameter, it will
be ignored.
default_hugepagesz - Specify the default huge page size. This parameter can
default_hugepagesz
pecify the default huge page size. This parameter can
only be specified once on the command line. default_hugepagesz can
optionally be followed by the hugepages parameter to preallocate a
specific number of huge pages of default size. The number of default
sized huge pages to preallocate can also be implicitly specified as
mentioned in the hugepages section above. Therefore, on an
architecture with 2M default huge page size:
architecture with 2M default huge page size::
hugepages=256
default_hugepagesz=2M hugepages=256
hugepages=256 default_hugepagesz=2M
will all result in 256 2M huge pages being allocated. Valid default
huge page size is architecture dependent.

View File

@ -31,6 +31,7 @@ the Linux memory management.
idle_page_tracking
ksm
memory-hotplug
nommu-mmap
numa_memory_policy
numaperf
pagemap

View File

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

View File

@ -129,7 +129,7 @@ will create the following directory::
/sys/devices/system/node/nodeX/memory_side_cache/
If that directory is not present, the system either does not not provide
If that directory is not present, the system either does not provide
a memory-side cache, or that information is not accessible to the kernel.
The attributes for each level of cache is provided under its cache

View File

@ -65,8 +65,8 @@ migrated onto another server by means of the special "fs_locations"
attribute. See `RFC3530 Section 6: Filesystem Migration and Replication`_ and
`Implementation Guide for Referrals in NFSv4`_.
.. _RFC3530 Section 6\: Filesystem Migration and Replication: http://tools.ietf.org/html/rfc3530#section-6
.. _Implementation Guide for Referrals in NFSv4: http://tools.ietf.org/html/draft-ietf-nfsv4-referrals-00
.. _RFC3530 Section 6\: Filesystem Migration and Replication: https://tools.ietf.org/html/rfc3530#section-6
.. _Implementation Guide for Referrals in NFSv4: https://tools.ietf.org/html/draft-ietf-nfsv4-referrals-00
The fs_locations information can take the form of either an ip address and
a path, or a DNS hostname and a path. The latter requires the NFS client to

View File

@ -65,7 +65,7 @@ use with NFS/RDMA.
If the version is less than 1.1.2 or the command does not exist,
you should install the latest version of nfs-utils.
Download the latest package from: http://www.kernel.org/pub/linux/utils/nfs
Download the latest package from: https://www.kernel.org/pub/linux/utils/nfs
Uncompress the package and follow the installation instructions.

View File

@ -264,7 +264,7 @@ They depend on various facilities being available:
access to the floppy drive device, /dev/fd0
For more information on syslinux, including how to create bootdisks
for prebuilt kernels, see http://syslinux.zytor.com/
for prebuilt kernels, see https://syslinux.zytor.com/
.. note::
Previously it was possible to write a kernel directly to
@ -292,7 +292,7 @@ They depend on various facilities being available:
cdrecord dev=ATAPI:1,0,0 arch/x86/boot/image.iso
For more information on isolinux, including how to create bootdisks
for prebuilt kernels, see http://syslinux.zytor.com/
for prebuilt kernels, see https://syslinux.zytor.com/
- Using LILO
@ -346,7 +346,7 @@ They depend on various facilities being available:
see Documentation/admin-guide/serial-console.rst for more information.
For more information on isolinux, including how to create bootdisks
for prebuilt kernels, see http://syslinux.zytor.com/
for prebuilt kernels, see https://syslinux.zytor.com/

View File

@ -8,7 +8,7 @@ to handling all the metadata access to the NFS export also hands out layouts
to the clients to directly access the underlying block devices that are
shared with the client.
To use pNFS block layouts with with the Linux NFS server the exported file
To use pNFS block layouts with the Linux NFS server the exported file
system needs to support the pNFS block layouts (currently just XFS), and the
file system must sit on shared storage (typically iSCSI) that is accessible
to the clients in addition to the MDS. As of now the file system needs to

View File

@ -9,7 +9,7 @@ which in addition to handling all the metadata access to the NFS export,
also hands out layouts to the clients so that they can directly access the
underlying SCSI LUNs that are shared with the client.
To use pNFS SCSI layouts with with the Linux NFS server, the exported file
To use pNFS SCSI layouts with the Linux NFS server, the exported file
system needs to support the pNFS SCSI layouts (currently just XFS), and the
file system must sit on a SCSI LUN that is accessible to the clients in
addition to the MDS. As of now the file system needs to sit directly on the

View File

@ -27,7 +27,7 @@ Crosspoint PMU events require "xp" (index), "bus" (bus number)
and "vc" (virtual channel ID).
Crosspoint watchpoint-based events (special "event" value 0xfe)
require "xp" and "vc" as as above plus "port" (device port index),
require "xp" and "vc" as above plus "port" (device port index),
"dir" (transmit/receive direction), comparator values ("cmp_l"
and "cmp_h") and "mask", being index of the comparator mask.

View File

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

View File

@ -723,7 +723,7 @@ core (for the policies with other scaling governors).
The ``ftrace`` interface can be used for low-level diagnostics of
``intel_pstate``. For example, to check how often the function to set a
P-state is called, the ``ftrace`` filter can be set to to
P-state is called, the ``ftrace`` filter can be set to
:c:func:`intel_pstate_set_pstate`::
# cd /sys/kernel/debug/tracing/

View File

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

View File

@ -261,7 +261,7 @@ directories like /tmp. The common method of exploitation of this flaw
is to cross privilege boundaries when following a given symlink (i.e. a
root process follows a symlink belonging to another user). For a likely
incomplete list of hundreds of examples across the years, please see:
http://cve.mitre.org/cgi-bin/cvekey.cgi?keyword=/tmp
https://cve.mitre.org/cgi-bin/cvekey.cgi?keyword=/tmp
When set to "0", symlink following behavior is unrestricted.

View File

@ -235,7 +235,7 @@ This toggle indicates whether unprivileged users are prevented
from using ``dmesg(8)`` to view messages from the kernel's log
buffer.
When ``dmesg_restrict`` is set to 0 there are no restrictions.
When ``dmesg_restrict`` is set set to 1, users must have
When ``dmesg_restrict`` is set to 1, users must have
``CAP_SYSLOG`` to use ``dmesg(8)``.
The kernel config option ``CONFIG_SECURITY_DMESG_RESTRICT`` sets the
@ -335,8 +335,8 @@ Path for the hotplug policy agent.
Default value is "``/sbin/hotplug``".
hung_task_all_cpu_backtrace:
================
hung_task_all_cpu_backtrace
===========================
If this option is set, the kernel will send an NMI to all CPUs to dump
their backtraces when a hung task is detected. This file shows up if
@ -646,8 +646,8 @@ rate for each task.
scanned for a given scan.
oops_all_cpu_backtrace:
================
oops_all_cpu_backtrace
======================
If this option is set, the kernel will send an NMI to all CPUs to dump
their backtraces when an oops event occurs. It should be used as a last
@ -996,6 +996,38 @@ pty
See Documentation/filesystems/devpts.rst.
random
======
This is a directory, with the following entries:
* ``boot_id``: a UUID generated the first time this is retrieved, and
unvarying after that;
* ``entropy_avail``: the pool's entropy count, in bits;
* ``poolsize``: the entropy pool size, in bits;
* ``urandom_min_reseed_secs``: obsolete (used to determine the minimum
number of seconds between urandom pool reseeding).
* ``uuid``: a UUID generated every time this is retrieved (this can
thus be used to generate UUIDs at will);
* ``write_wakeup_threshold``: when the entropy count drops below this
(as a number of bits), processes waiting to write to ``/dev/random``
are woken up.
If ``drivers/char/random.c`` is built with ``ADD_INTERRUPT_BENCH``
defined, these additional entries are present:
* ``add_interrupt_avg_cycles``: the average number of cycles between
interrupts used to feed the pool;
* ``add_interrupt_avg_deviation``: the standard deviation seen on the
number of cycles between interrupts used to feed the pool.
randomize_va_space
==================

View File

@ -583,7 +583,7 @@ trimming of allocations is initiated.
The default value is 1.
See Documentation/nommu-mmap.txt for more information.
See Documentation/admin-guide/mm/nommu-mmap.rst for more information.
numa_zonelist_order

View File

@ -38,7 +38,7 @@ either letters or blanks. In above example it looks like this::
Tainted: P W O
The meaning of those characters is explained in the table below. In tis case
The meaning of those characters is explained in the table below. In this case
the kernel got tainted earlier because a proprietary Module (``P``) was loaded,
a warning occurred (``W``), and an externally-built module was loaded (``O``).
To decode other letters use the table below.
@ -61,7 +61,7 @@ this on the machine that had the statements in the logs that were quoted earlier
* Proprietary module was loaded (#0)
* Kernel issued warning (#9)
* Externally-built ('out-of-tree') module was loaded (#12)
See Documentation/admin-guide/tainted-kernels.rst in the the Linux kernel or
See Documentation/admin-guide/tainted-kernels.rst in the Linux kernel or
https://www.kernel.org/doc/html/latest/admin-guide/tainted-kernels.html for
a more details explanation of the various taint flags.
Raw taint value as int/string: 4609/'P W O '

View File

@ -133,7 +133,7 @@ When mounting an XFS filesystem, the following options are accepted.
logbsize must be an integer multiple of the log
stripe unit configured at **mkfs(8)** time.
The default value for for version 1 logs is 32768, while the
The default value for version 1 logs is 32768, while the
default value for version 2 logs is MAX(32768, log_sunit).
logdev=device and rtdev=device

View File

@ -128,7 +128,7 @@ it. The recommended placement is in the first 16KiB of RAM.
The boot loader must load a device tree image (dtb) into system ram
at a 64bit aligned address and initialize it with the boot data. The
dtb format is documented in Documentation/devicetree/booting-without-of.txt.
dtb format is documented in Documentation/devicetree/booting-without-of.rst.
The kernel will look for the dtb magic value of 0xd00dfeed at the dtb
physical address to determine if a dtb has been passed instead of a
tagged list.

View File

@ -220,7 +220,7 @@ LPIT Signature Reserved (signature == "LPIT")
x86 only table as of ACPI 5.1; starting with ACPI 6.0, processor
descriptions and power states on ARM platforms should use the DSDT
and define processor container devices (_HID ACPI0010, Section 8.4,
and more specifically 8.4.3 and and 8.4.4).
and more specifically 8.4.3 and 8.4.4).
MADT Section 5.2.12 (signature == "APIC")

View File

@ -273,7 +273,7 @@ only use the _DSD Device Properties UUID [5]:
- UUID: daffd814-6eba-4d8c-8a91-bc9bbf4aa301
- http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf
- https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf
The UEFI Forum provides a mechanism for registering device properties [4]
so that they may be used across all operating systems supporting ACPI.
@ -470,7 +470,7 @@ likely be willing to assist in submitting ECRs.
Linux Code
----------
Individual items specific to Linux on ARM, contained in the the Linux
Individual items specific to Linux on ARM, contained in the Linux
source code, are in the list that follows:
ACPI_OS_NAME

View File

@ -14,6 +14,7 @@ ARM64 Architecture
hugetlbpage
legacy_instructions
memory
perf
pointer-authentication
silicon-errata
sve

View File

@ -1,8 +1,11 @@
.. SPDX-License-Identifier: GPL-2.0
=====================
Perf Event Attributes
=====================
Author: Andrew Murray <andrew.murray@arm.com>
Date: 2019-03-06
:Author: Andrew Murray <andrew.murray@arm.com>
:Date: 2019-03-06
exclude_user
------------

View File

@ -494,7 +494,7 @@ Appendix B. ARMv8-A FP/SIMD programmer's model
Note: This section is for information only and not intended to be complete or
to replace any architectural specification.
Refer to [4] for for more information.
Refer to [4] for more information.
ARMv8-A defines the following floating-point / SIMD register state:

View File

@ -196,7 +196,7 @@ a virtual address mapping (unlike the earlier scheme of virtual address
do not have a corresponding kernel virtual address space mapping) and
low-memory pages.
Note: Please refer to Documentation/DMA-API-HOWTO.txt for a discussion
Note: Please refer to :doc:`/core-api/dma-api-howto` for a discussion
on PCI high mem DMA aspects and mapping of scatter gather lists, and support
for 64 bit PCI.

View File

@ -0,0 +1,153 @@
.. SPDX-License-Identifier: GPL-2.0
================================================
Multi-Queue Block IO Queueing Mechanism (blk-mq)
================================================
The Multi-Queue Block IO Queueing Mechanism is an API to enable fast storage
devices to achieve a huge number of input/output operations per second (IOPS)
through queueing and submitting IO requests to block devices simultaneously,
benefiting from the parallelism offered by modern storage devices.
Introduction
============
Background
----------
Magnetic hard disks have been the de facto standard from the beginning of the
development of the kernel. The Block IO subsystem aimed to achieve the best
performance possible for those devices with a high penalty when doing random
access, and the bottleneck was the mechanical moving parts, a lot slower than
any layer on the storage stack. One example of such optimization technique
involves ordering read/write requests according to the current position of the
hard disk head.
However, with the development of Solid State Drives and Non-Volatile Memories
without mechanical parts nor random access penalty and capable of performing
high parallel access, the bottleneck of the stack had moved from the storage
device to the operating system. In order to take advantage of the parallelism
in those devices' design, the multi-queue mechanism was introduced.
The former design had a single queue to store block IO requests with a single
lock. That did not scale well in SMP systems due to dirty data in cache and the
bottleneck of having a single lock for multiple processors. This setup also
suffered with congestion when different processes (or the same process, moving
to different CPUs) wanted to perform block IO. Instead of this, the blk-mq API
spawns multiple queues with individual entry points local to the CPU, removing
the need for a lock. A deeper explanation on how this works is covered in the
following section (`Operation`_).
Operation
---------
When the userspace performs IO to a block device (reading or writing a file,
for instance), blk-mq takes action: it will store and manage IO requests to
the block device, acting as middleware between the userspace (and a file
system, if present) and the block device driver.
blk-mq has two group of queues: software staging queues and hardware dispatch
queues. When the request arrives at the block layer, it will try the shortest
path possible: send it directly to the hardware queue. However, there are two
cases that it might not do that: if there's an IO scheduler attached at the
layer or if we want to try to merge requests. In both cases, requests will be
sent to the software queue.
Then, after the requests are processed by software queues, they will be placed
at the hardware queue, a second stage queue were the hardware has direct access
to process those requests. However, if the hardware does not have enough
resources to accept more requests, blk-mq will places requests on a temporary
queue, to be sent in the future, when the hardware is able.
Software staging queues
~~~~~~~~~~~~~~~~~~~~~~~
The block IO subsystem adds requests in the software staging queues
(represented by struct :c:type:`blk_mq_ctx`) in case that they weren't sent
directly to the driver. A request is one or more BIOs. They arrived at the
block layer through the data structure struct :c:type:`bio`. The block layer
will then build a new structure from it, the struct :c:type:`request` that will
be used to communicate with the device driver. Each queue has its own lock and
the number of queues is defined by a per-CPU or per-node basis.
The staging queue can be used to merge requests for adjacent sectors. For
instance, requests for sector 3-6, 6-7, 7-9 can become one request for 3-9.
Even if random access to SSDs and NVMs have the same time of response compared
to sequential access, grouped requests for sequential access decreases the
number of individual requests. This technique of merging requests is called
plugging.
Along with that, the requests can be reordered to ensure fairness of system
resources (e.g. to ensure that no application suffers from starvation) and/or to
improve IO performance, by an IO scheduler.
IO Schedulers
^^^^^^^^^^^^^
There are several schedulers implemented by the block layer, each one following
a heuristic to improve the IO performance. They are "pluggable" (as in plug
and play), in the sense of they can be selected at run time using sysfs. You
can read more about Linux's IO schedulers `here
<https://www.kernel.org/doc/html/latest/block/index.html>`_. The scheduling
happens only between requests in the same queue, so it is not possible to merge
requests from different queues, otherwise there would be cache trashing and a
need to have a lock for each queue. After the scheduling, the requests are
eligible to be sent to the hardware. One of the possible schedulers to be
selected is the NONE scheduler, the most straightforward one. It will just
place requests on whatever software queue the process is running on, without
any reordering. When the device starts processing requests in the hardware
queue (a.k.a. run the hardware queue), the software queues mapped to that
hardware queue will be drained in sequence according to their mapping.
Hardware dispatch queues
~~~~~~~~~~~~~~~~~~~~~~~~
The hardware queue (represented by struct :c:type:`blk_mq_hw_ctx`) is a struct
used by device drivers to map the device submission queues (or device DMA ring
buffer), and are the last step of the block layer submission code before the
low level device driver taking ownership of the request. To run this queue, the
block layer removes requests from the associated software queues and tries to
dispatch to the hardware.
If it's not possible to send the requests directly to hardware, they will be
added to a linked list (:c:type:`hctx->dispatch`) of requests. Then,
next time the block layer runs a queue, it will send the requests laying at the
:c:type:`dispatch` list first, to ensure a fairness dispatch with those
requests that were ready to be sent first. The number of hardware queues
depends on the number of hardware contexts supported by the hardware and its
device driver, but it will not be more than the number of cores of the system.
There is no reordering at this stage, and each software queue has a set of
hardware queues to send requests for.
.. note::
Neither the block layer nor the device protocols guarantee
the order of completion of requests. This must be handled by
higher layers, like the filesystem.
Tag-based completion
~~~~~~~~~~~~~~~~~~~~
In order to indicate which request has been completed, every request is
identified by an integer, ranging from 0 to the dispatch queue size. This tag
is generated by the block layer and later reused by the device driver, removing
the need to create a redundant identifier. When a request is completed in the
drive, the tag is sent back to the block layer to notify it of the finalization.
This removes the need to do a linear search to find out which IO has been
completed.
Further reading
---------------
- `Linux Block IO: Introducing Multi-queue SSD Access on Multi-core Systems <http://kernel.dk/blk-mq.pdf>`_
- `NOOP scheduler <https://en.wikipedia.org/wiki/Noop_scheduler>`_
- `Null block device driver <https://www.kernel.org/doc/html/latest/block/null_blk.html>`_
Source code documentation
=========================
.. kernel-doc:: include/linux/blk-mq.h
.. kernel-doc:: block/blk-mq.c

View File

@ -10,6 +10,7 @@ Block
bfq-iosched
biodoc
biovecs
blk-mq
capability
cmdline-partition
data-integrity

View File

@ -9,7 +9,7 @@ access to block devices to specific initiators in a shared storage
setup.
This document gives a general overview of the support ioctl commands.
For a more detailed reference please refer the the SCSI Primary
For a more detailed reference please refer to the SCSI Primary
Commands standard, specifically the section on Reservations and the
"PERSISTENT RESERVE IN" and "PERSISTENT RESERVE OUT" commands.

View File

@ -643,5 +643,6 @@ when:
.. _selftests: ../../tools/testing/selftests/bpf/
.. _Documentation/dev-tools/kselftest.rst:
https://www.kernel.org/doc/html/latest/dev-tools/kselftest.html
.. _Documentation/bpf/btf.rst: btf.rst
Happy BPF hacking!

View File

@ -58,6 +58,14 @@ Testing and debugging BPF
s390
Other
=====
.. toctree::
:maxdepth: 1
ringbuf
.. Links:
.. _Documentation/networking/filter.rst: ../networking/filter.txt
.. _man-pages: https://www.kernel.org/doc/man-pages/

View File

@ -8,7 +8,7 @@ How to access I/O mapped memory from within device drivers
The virt_to_bus() and bus_to_virt() functions have been
superseded by the functionality provided by the PCI DMA interface
(see Documentation/DMA-API-HOWTO.txt). They continue
(see :doc:`/core-api/dma-api-howto`). They continue
to be documented below for historical purposes, but new code
must not use them. --davidm 00/12/12

View File

@ -35,8 +35,8 @@ Command Line Switches
other CPUs later online.
``nr_cpus=n``
Restrict the total amount CPUs the kernel will support. If the number
supplied here is lower than the number of physically available CPUs than
Restrict the total amount of CPUs the kernel will support. If the number
supplied here is lower than the number of physically available CPUs, then
those CPUs can not be brought online later.
``additional_cpus=n``

View File

@ -5,7 +5,7 @@ Dynamic DMA mapping using the generic device
:Author: James E.J. Bottomley <James.Bottomley@HansenPartnership.com>
This document describes the DMA API. For a more gentle introduction
of the API (and actual examples), see Documentation/DMA-API-HOWTO.txt.
of the API (and actual examples), see :doc:`/core-api/dma-api-howto`.
This API is split into two pieces. Part I describes the basic API.
Part II describes extensions for supporting non-consistent memory
@ -479,7 +479,7 @@ without the _attrs suffixes, except that they pass an optional
dma_attrs.
The interpretation of DMA attributes is architecture-specific, and
each attribute should be documented in Documentation/DMA-attributes.txt.
each attribute should be documented in :doc:`/core-api/dma-attributes`.
If dma_attrs are 0, the semantics of each of these functions
is identical to those of the corresponding function
@ -492,7 +492,7 @@ for DMA::
#include <linux/dma-mapping.h>
/* DMA_ATTR_FOO should be defined in linux/dma-mapping.h and
* documented in Documentation/DMA-attributes.txt */
* documented in Documentation/core-api/dma-attributes.rst */
...
unsigned long attr;

View File

@ -17,7 +17,7 @@ To do ISA style DMA you need to include two headers::
#include <asm/dma.h>
The first is the generic DMA API used to convert virtual addresses to
bus addresses (see Documentation/DMA-API.txt for details).
bus addresses (see :doc:`/core-api/dma-api` for details).
The second contains the routines specific to ISA DMA transfers. Since
this is not present on all platforms make sure you construct your

View File

@ -39,6 +39,8 @@ Library functionality that is used throughout the kernel.
rbtree
generic-radix-tree
packing
bus-virt-phys-mapping
this_cpu_ops
timekeeping
errseq
@ -82,6 +84,7 @@ more memory-management documentation in :doc:`/vm/index`.
:maxdepth: 1
memory-allocation
unaligned-memory-access
dma-api
dma-api-howto
dma-attributes

View File

@ -6,7 +6,7 @@ Everything you never wanted to know about kobjects, ksets, and ktypes
:Last updated: December 19, 2007
Based on an original article by Jon Corbet for lwn.net written October 1,
2003 and located at http://lwn.net/Articles/51437/
2003 and located at https://lwn.net/Articles/51437/
Part of the difficulty in understanding the driver model - and the kobject
abstraction upon which it is built - is that there is no obvious starting

View File

@ -84,6 +84,50 @@ driver for a device with such restrictions, avoid using these flags.
And even with hardware with restrictions it is preferable to use
`dma_alloc*` APIs.
GFP flags and reclaim behavior
------------------------------
Memory allocations may trigger direct or background reclaim and it is
useful to understand how hard the page allocator will try to satisfy that
or another request.
* ``GFP_KERNEL & ~__GFP_RECLAIM`` - optimistic allocation without _any_
attempt to free memory at all. The most light weight mode which even
doesn't kick the background reclaim. Should be used carefully because it
might deplete the memory and the next user might hit the more aggressive
reclaim.
* ``GFP_KERNEL & ~__GFP_DIRECT_RECLAIM`` (or ``GFP_NOWAIT``)- optimistic
allocation without any attempt to free memory from the current
context but can wake kswapd to reclaim memory if the zone is below
the low watermark. Can be used from either atomic contexts or when
the request is a performance optimization and there is another
fallback for a slow path.
* ``(GFP_KERNEL|__GFP_HIGH) & ~__GFP_DIRECT_RECLAIM`` (aka ``GFP_ATOMIC``) -
non sleeping allocation with an expensive fallback so it can access
some portion of memory reserves. Usually used from interrupt/bottom-half
context with an expensive slow path fallback.
* ``GFP_KERNEL`` - both background and direct reclaim are allowed and the
**default** page allocator behavior is used. That means that not costly
allocation requests are basically no-fail but there is no guarantee of
that behavior so failures have to be checked properly by callers
(e.g. OOM killer victim is allowed to fail currently).
* ``GFP_KERNEL | __GFP_NORETRY`` - overrides the default allocator behavior
and all allocation requests fail early rather than cause disruptive
reclaim (one round of reclaim in this implementation). The OOM killer
is not invoked.
* ``GFP_KERNEL | __GFP_RETRY_MAYFAIL`` - overrides the default allocator
behavior and all allocation requests try really hard. The request
will fail if the reclaim cannot make any progress. The OOM killer
won't be triggered.
* ``GFP_KERNEL | __GFP_NOFAIL`` - overrides the default allocator behavior
and all allocation requests will loop endlessly until they succeed.
This might be really dangerous especially for larger orders.
Selecting memory allocator
==========================

View File

@ -69,7 +69,7 @@ You can check the current *console_loglevel* with::
The result shows the *current*, *default*, *minimum* and *boot-time-default* log
levels.
To change the current console_loglevel simply write the the desired level to
To change the current console_loglevel simply write the desired level to
``/proc/sys/kernel/printk``. For example, to print all messages to the console::
# echo 8 > /proc/sys/kernel/printk

View File

@ -494,9 +494,11 @@ Time and date
%pt[RT]t HH:MM:SS
%pt[RT][dt][r]
For printing date and time as represented by
For printing date and time as represented by::
R struct rtc_time structure
T time64_t type
in human readable format.
By default year will be incremented by 1900 and month by 1.

View File

@ -1,7 +1,11 @@
.. SPDX-License-Identifier: GPL-2.0
Scatterlist Cryptographic API
=============================
Scatterlist Cryptographic API
=============================
INTRODUCTION
Introduction
============
The Scatterlist Crypto API takes page vectors (scatterlists) as
arguments, and works directly on pages. In some cases (e.g. ECB
@ -13,7 +17,8 @@ so that processing can be applied to paged skb's without the need
for linearization.
DETAILS
Details
=======
At the lowest level are algorithms, which register dynamically with the
API.
@ -23,7 +28,7 @@ of the implementation logic (e.g. manipulating page vectors) and provide an
abstraction to the underlying algorithms. However, at the user
level they are very simple.
Conceptually, the API layering looks like this:
Conceptually, the API layering looks like this::
[transform api] (user interface)
[transform ops] (per-type logic glue e.g. cipher.c, compress.c)
@ -44,7 +49,7 @@ one block while the former can operate on an arbitrary amount of data,
subject to block size requirements (i.e., non-stream ciphers can only
process multiples of blocks).
Here's an example of how to use the API:
Here's an example of how to use the API::
#include <crypto/hash.h>
#include <linux/err.h>
@ -78,7 +83,8 @@ Here's an example of how to use the API:
Many real examples are available in the regression test module (tcrypt.c).
DEVELOPER NOTES
Developer Notes
===============
Transforms may only be allocated in user context, and cryptographic
methods may only be called from softirq and user contexts. For
@ -91,7 +97,8 @@ size (typically 8 bytes). This prevents having to do any copying
across non-aligned page fragment boundaries.
ADDING NEW ALGORITHMS
Adding New Algorithms
=====================
When submitting a new algorithm for inclusion, a mandatory requirement
is that at least a few test vectors from known sources (preferably
@ -119,132 +126,137 @@ Also check the TODO list at the web site listed below to see what people
might already be working on.
BUGS
Bugs
====
Send bug reports to:
linux-crypto@vger.kernel.org
Cc: Herbert Xu <herbert@gondor.apana.org.au>,
linux-crypto@vger.kernel.org
Cc:
Herbert Xu <herbert@gondor.apana.org.au>,
David S. Miller <davem@redhat.com>
FURTHER INFORMATION
Further Information
===================
For further patches and various updates, including the current TODO
list, see:
http://gondor.apana.org.au/~herbert/crypto/
AUTHORS
Authors
=======
James Morris
David S. Miller
Herbert Xu
- James Morris
- David S. Miller
- Herbert Xu
CREDITS
Credits
=======
The following people provided invaluable feedback during the development
of the API:
Alexey Kuznetzov
Rusty Russell
Herbert Valerio Riedel
Jeff Garzik
Michael Richardson
Andrew Morton
Ingo Oeser
Christoph Hellwig
- Alexey Kuznetzov
- Rusty Russell
- Herbert Valerio Riedel
- Jeff Garzik
- Michael Richardson
- Andrew Morton
- Ingo Oeser
- Christoph Hellwig
Portions of this API were derived from the following projects:
Kerneli Cryptoapi (http://www.kerneli.org/)
Alexander Kjeldaas
Herbert Valerio Riedel
Kyle McMartin
Jean-Luc Cooke
David Bryson
Clemens Fruhwirth
Tobias Ringstrom
Harald Welte
- Alexander Kjeldaas
- Herbert Valerio Riedel
- Kyle McMartin
- Jean-Luc Cooke
- David Bryson
- Clemens Fruhwirth
- Tobias Ringstrom
- Harald Welte
and;
Nettle (https://www.lysator.liu.se/~nisse/nettle/)
Niels Möller
- Niels Möller
Original developers of the crypto algorithms:
Dana L. How (DES)
Andrew Tridgell and Steve French (MD4)
Colin Plumb (MD5)
Steve Reid (SHA1)
Jean-Luc Cooke (SHA256, SHA384, SHA512)
Kazunori Miyazawa / USAGI (HMAC)
Matthew Skala (Twofish)
Dag Arne Osvik (Serpent)
Brian Gladman (AES)
Kartikey Mahendra Bhatt (CAST6)
Jon Oberheide (ARC4)
Jouni Malinen (Michael MIC)
NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
- Dana L. How (DES)
- Andrew Tridgell and Steve French (MD4)
- Colin Plumb (MD5)
- Steve Reid (SHA1)
- Jean-Luc Cooke (SHA256, SHA384, SHA512)
- Kazunori Miyazawa / USAGI (HMAC)
- Matthew Skala (Twofish)
- Dag Arne Osvik (Serpent)
- Brian Gladman (AES)
- Kartikey Mahendra Bhatt (CAST6)
- Jon Oberheide (ARC4)
- Jouni Malinen (Michael MIC)
- NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
SHA1 algorithm contributors:
Jean-Francois Dive
- Jean-Francois Dive
DES algorithm contributors:
Raimar Falke
Gisle Sælensminde
Niels Möller
- Raimar Falke
- Gisle Sælensminde
- Niels Möller
Blowfish algorithm contributors:
Herbert Valerio Riedel
Kyle McMartin
- Herbert Valerio Riedel
- Kyle McMartin
Twofish algorithm contributors:
Werner Koch
Marc Mutz
- Werner Koch
- Marc Mutz
SHA256/384/512 algorithm contributors:
Andrew McDonald
Kyle McMartin
Herbert Valerio Riedel
- Andrew McDonald
- Kyle McMartin
- Herbert Valerio Riedel
AES algorithm contributors:
Alexander Kjeldaas
Herbert Valerio Riedel
Kyle McMartin
Adam J. Richter
Fruhwirth Clemens (i586)
Linus Torvalds (i586)
- Alexander Kjeldaas
- Herbert Valerio Riedel
- Kyle McMartin
- Adam J. Richter
- Fruhwirth Clemens (i586)
- Linus Torvalds (i586)
CAST5 algorithm contributors:
Kartikey Mahendra Bhatt (original developers unknown, FSF copyright).
- Kartikey Mahendra Bhatt (original developers unknown, FSF copyright).
TEA/XTEA algorithm contributors:
Aaron Grothe
Michael Ringe
- Aaron Grothe
- Michael Ringe
Khazad algorithm contributors:
Aaron Grothe
- Aaron Grothe
Whirlpool algorithm contributors:
Aaron Grothe
Jean-Luc Cooke
- Aaron Grothe
- Jean-Luc Cooke
Anubis algorithm contributors:
Aaron Grothe
- Aaron Grothe
Tiger algorithm contributors:
Aaron Grothe
- Aaron Grothe
VIA PadLock contributors:
Michal Ludvig
- Michal Ludvig
Camellia algorithm contributors:
NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
- NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com>
Please send any credits updates or corrections to:
Herbert Xu <herbert@gondor.apana.org.au>

View File

@ -1,8 +1,10 @@
=============================================
ASYMMETRIC / PUBLIC-KEY CRYPTOGRAPHY KEY TYPE
=============================================
.. SPDX-License-Identifier: GPL-2.0
Contents:
=============================================
Asymmetric / Public-key Cryptography Key Type
=============================================
.. Contents:
- Overview.
- Key identification.
@ -13,8 +15,7 @@ Contents:
- Keyring link restrictions.
========
OVERVIEW
Overview
========
The "asymmetric" key type is designed to be a container for the keys used in
@ -42,8 +43,7 @@ key, or it may interpret it as a reference to a key held somewhere else in the
system (for example, a TPM).
==================
KEY IDENTIFICATION
Key Identification
==================
If a key is added with an empty name, the instantiation data parsers are given
@ -57,49 +57,48 @@ The asymmetric key type's match function can then perform a wider range of
comparisons than just the straightforward comparison of the description with
the criterion string:
(1) If the criterion string is of the form "id:<hexdigits>" then the match
1) If the criterion string is of the form "id:<hexdigits>" then the match
function will examine a key's fingerprint to see if the hex digits given
after the "id:" match the tail. For instance:
after the "id:" match the tail. For instance::
keyctl search @s asymmetric id:5acc2142
will match a key with fingerprint:
will match a key with fingerprint::
1A00 2040 7601 7889 DE11 882C 3823 04AD 5ACC 2142
(2) If the criterion string is of the form "<subtype>:<hexdigits>" then the
2) If the criterion string is of the form "<subtype>:<hexdigits>" then the
match will match the ID as in (1), but with the added restriction that
only keys of the specified subtype (e.g. tpm) will be matched. For
instance:
instance::
keyctl search @s asymmetric tpm:5acc2142
Looking in /proc/keys, the last 8 hex digits of the key fingerprint are
displayed, along with the subtype:
displayed, along with the subtype::
1a39e171 I----- 1 perm 3f010000 0 0 asymmetric modsign.0: DSA 5acc2142 []
=========================
ACCESSING ASYMMETRIC KEYS
Accessing Asymmetric Keys
=========================
For general access to asymmetric keys from within the kernel, the following
inclusion is required:
inclusion is required::
#include <crypto/public_key.h>
This gives access to functions for dealing with asymmetric / public keys.
Three enums are defined there for representing public-key cryptography
algorithms:
algorithms::
enum pkey_algo
digest algorithms used by those:
digest algorithms used by those::
enum pkey_hash_algo
and key identifier representations:
and key identifier representations::
enum pkey_id_type
@ -110,25 +109,25 @@ PGP-specific metadata, whereas X.509 has arbitrary certificate identifiers.
The operations defined upon a key are:
(1) Signature verification.
1) Signature verification.
Other operations are possible (such as encryption) with the same key data
required for verification, but not currently supported, and others
(eg. decryption and signature generation) require extra key data.
SIGNATURE VERIFICATION
Signature Verification
----------------------
An operation is provided to perform cryptographic signature verification, using
an asymmetric key to provide or to provide access to the public key.
an asymmetric key to provide or to provide access to the public key::
int verify_signature(const struct key *key,
const struct public_key_signature *sig);
The caller must have already obtained the key from some source and can then use
it to check the signature. The caller must have parsed the signature and
transferred the relevant bits to the structure pointed to by sig.
transferred the relevant bits to the structure pointed to by sig::
struct public_key_signature {
u8 *digest;
@ -159,8 +158,7 @@ data; or -ENOMEM if an allocation can't be performed. -EINVAL can be returned
if the key argument is the wrong type or is incompletely set up.
=======================
ASYMMETRIC KEY SUBTYPES
Asymmetric Key Subtypes
=======================
Asymmetric keys have a subtype that defines the set of operations that can be
@ -171,11 +169,11 @@ The subtype is selected by the key data parser and the parser must initialise
the data required for it. The asymmetric key retains a reference on the
subtype module.
The subtype definition structure can be found in:
The subtype definition structure can be found in::
#include <keys/asymmetric-subtype.h>
and looks like the following:
and looks like the following::
struct asymmetric_key_subtype {
struct module *owner;
@ -198,39 +196,37 @@ the subtype. Currently, the name is only used for print statements.
There are a number of operations defined by the subtype:
(1) describe().
1) describe().
Mandatory. This allows the subtype to display something in /proc/keys
against the key. For instance the name of the public key algorithm type
could be displayed. The key type will display the tail of the key
identity string after this.
(2) destroy().
2) destroy().
Mandatory. This should free the memory associated with the key. The
asymmetric key will look after freeing the fingerprint and releasing the
reference on the subtype module.
(3) query().
3) query().
Mandatory. This is a function for querying the capabilities of a key.
(4) eds_op().
4) eds_op().
Optional. This is the entry point for the encryption, decryption and
signature creation operations (which are distinguished by the operation ID
in the parameter struct). The subtype may do anything it likes to
implement an operation, including offloading to hardware.
(5) verify_signature().
5) verify_signature().
Optional. This is the entry point for signature verification. The
subtype may do anything it likes to implement an operation, including
offloading to hardware.
==========================
INSTANTIATION DATA PARSERS
Instantiation Data Parsers
==========================
The asymmetric key type doesn't generally want to store or to deal with a raw
@ -254,11 +250,11 @@ Examples of blob formats for which parsers could be implemented include:
During key instantiation each parser in the list is tried until one doesn't
return -EBADMSG.
The parser definition structure can be found in:
The parser definition structure can be found in::
#include <keys/asymmetric-parser.h>
and looks like the following:
and looks like the following::
struct asymmetric_key_parser {
struct module *owner;
@ -273,7 +269,7 @@ the parser.
There is currently only a single operation defined by the parser, and it is
mandatory:
(1) parse().
1) parse().
This is called to preparse the key from the key creation and update paths.
In particular, it is called during the key creation _before_ a key is
@ -282,7 +278,7 @@ mandatory:
The caller passes a pointer to the following struct with all of the fields
cleared, except for data, datalen and quotalen [see
Documentation/security/keys/core.rst].
Documentation/security/keys/core.rst]::
struct key_preparsed_payload {
char *description;
@ -321,7 +317,7 @@ mandatory:
public-key algorithm such as RSA and DSA this will likely be a printable
hex version of the key's fingerprint.
Functions are provided to register and unregister parsers:
Functions are provided to register and unregister parsers::
int register_asymmetric_key_parser(struct asymmetric_key_parser *parser);
void unregister_asymmetric_key_parser(struct asymmetric_key_parser *subtype);
@ -330,8 +326,7 @@ Parsers may not have the same name. The names are otherwise only used for
displaying in debugging messages.
=========================
KEYRING LINK RESTRICTIONS
Keyring Link Restrictions
=========================
Keyrings created from userspace using add_key can be configured to check the
@ -340,7 +335,7 @@ allowed to link.
Several restriction methods are available:
(1) Restrict using the kernel builtin trusted keyring
1) Restrict using the kernel builtin trusted keyring
- Option string used with KEYCTL_RESTRICT_KEYRING:
- "builtin_trusted"
@ -350,7 +345,7 @@ Several restriction methods are available:
rejected. The ca_keys kernel parameter also affects which keys are used
for signature verification.
(2) Restrict using the kernel builtin and secondary trusted keyrings
2) Restrict using the kernel builtin and secondary trusted keyrings
- Option string used with KEYCTL_RESTRICT_KEYRING:
- "builtin_and_secondary_trusted"
@ -361,7 +356,7 @@ Several restriction methods are available:
kernel parameter also affects which keys are used for signature
verification.
(3) Restrict using a separate key or keyring
3) Restrict using a separate key or keyring
- Option string used with KEYCTL_RESTRICT_KEYRING:
- "key_or_keyring:<key or keyring serial number>[:chain]"
@ -378,7 +373,7 @@ Several restriction methods are available:
certificate in order (starting closest to the root) to a keyring. For
instance, one keyring can be populated with links to a set of root
certificates, with a separate, restricted keyring set up for each
certificate chain to be validated:
certificate chain to be validated::
# Create and populate a keyring for root certificates
root_id=`keyctl add keyring root-certs "" @s`
@ -400,7 +395,7 @@ Several restriction methods are available:
one of the root certificates.
A single keyring can be used to verify a chain of signatures by
restricting the keyring after linking the root certificate:
restricting the keyring after linking the root certificate::
# Create a keyring for the certificate chain and add the root
chain2_id=`keyctl add keyring chain2 "" @s`

View File

@ -1,27 +1,32 @@
Asynchronous Transfers/Transforms API
.. SPDX-License-Identifier: GPL-2.0
1 INTRODUCTION
=====================================
Asynchronous Transfers/Transforms API
=====================================
2 GENEALOGY
.. Contents
3 USAGE
3.1 General format of the API
3.2 Supported operations
3.3 Descriptor management
3.4 When does the operation execute?
3.5 When does the operation complete?
3.6 Constraints
3.7 Example
1. INTRODUCTION
4 DMAENGINE DRIVER DEVELOPER NOTES
4.1 Conformance points
4.2 "My application needs exclusive control of hardware channels"
2 GENEALOGY
5 SOURCE
3 USAGE
3.1 General format of the API
3.2 Supported operations
3.3 Descriptor management
3.4 When does the operation execute?
3.5 When does the operation complete?
3.6 Constraints
3.7 Example
---
4 DMAENGINE DRIVER DEVELOPER NOTES
4.1 Conformance points
4.2 "My application needs exclusive control of hardware channels"
1 INTRODUCTION
5 SOURCE
1. Introduction
===============
The async_tx API provides methods for describing a chain of asynchronous
bulk memory transfers/transforms with support for inter-transactional
@ -31,7 +36,8 @@ that is written to the API can optimize for asynchronous operation and
the API will fit the chain of operations to the available offload
resources.
2 GENEALOGY
2.Genealogy
===========
The API was initially designed to offload the memory copy and
xor-parity-calculations of the md-raid5 driver using the offload engines
@ -39,40 +45,52 @@ present in the Intel(R) Xscale series of I/O processors. It also built
on the 'dmaengine' layer developed for offloading memory copies in the
network stack using Intel(R) I/OAT engines. The following design
features surfaced as a result:
1/ implicit synchronous path: users of the API do not need to know if
1. implicit synchronous path: users of the API do not need to know if
the platform they are running on has offload capabilities. The
operation will be offloaded when an engine is available and carried out
in software otherwise.
2/ cross channel dependency chains: the API allows a chain of dependent
2. cross channel dependency chains: the API allows a chain of dependent
operations to be submitted, like xor->copy->xor in the raid5 case. The
API automatically handles cases where the transition from one operation
to another implies a hardware channel switch.
3/ dmaengine extensions to support multiple clients and operation types
3. dmaengine extensions to support multiple clients and operation types
beyond 'memcpy'
3 USAGE
3. Usage
========
3.1 General format of the API:
struct dma_async_tx_descriptor *
async_<operation>(<op specific parameters>, struct async_submit ctl *submit)
3.1 General format of the API
-----------------------------
3.2 Supported operations:
memcpy - memory copy between a source and a destination buffer
memset - fill a destination buffer with a byte value
xor - xor a series of source buffers and write the result to a
::
struct dma_async_tx_descriptor *
async_<operation>(<op specific parameters>, struct async_submit ctl *submit)
3.2 Supported operations
------------------------
======== ====================================================================
memcpy memory copy between a source and a destination buffer
memset fill a destination buffer with a byte value
xor xor a series of source buffers and write the result to a
destination buffer
xor_val - xor a series of source buffers and set a flag if the
xor_val xor a series of source buffers and set a flag if the
result is zero. The implementation attempts to prevent
writes to memory
pq - generate the p+q (raid6 syndrome) from a series of source buffers
pq_val - validate that a p and or q buffer are in sync with a given series of
pq generate the p+q (raid6 syndrome) from a series of source buffers
pq_val validate that a p and or q buffer are in sync with a given series of
sources
datap - (raid6_datap_recov) recover a raid6 data block and the p block
datap (raid6_datap_recov) recover a raid6 data block and the p block
from the given sources
2data - (raid6_2data_recov) recover 2 raid6 data blocks from the given
2data (raid6_2data_recov) recover 2 raid6 data blocks from the given
sources
======== ====================================================================
3.3 Descriptor management
-------------------------
3.3 Descriptor management:
The return value is non-NULL and points to a 'descriptor' when the operation
has been queued to execute asynchronously. Descriptors are recycled
resources, under control of the offload engine driver, to be reused as
@ -82,12 +100,15 @@ before the dependency is submitted. This requires that all descriptors be
acknowledged by the application before the offload engine driver is allowed to
recycle (or free) the descriptor. A descriptor can be acked by one of the
following methods:
1/ setting the ASYNC_TX_ACK flag if no child operations are to be submitted
2/ submitting an unacknowledged descriptor as a dependency to another
1. setting the ASYNC_TX_ACK flag if no child operations are to be submitted
2. submitting an unacknowledged descriptor as a dependency to another
async_tx call will implicitly set the acknowledged state.
3/ calling async_tx_ack() on the descriptor.
3. calling async_tx_ack() on the descriptor.
3.4 When does the operation execute?
------------------------------------
Operations do not immediately issue after return from the
async_<operation> call. Offload engine drivers batch operations to
improve performance by reducing the number of mmio cycles needed to
@ -98,12 +119,15 @@ channels since the application has no knowledge of channel to operation
mapping.
3.5 When does the operation complete?
-------------------------------------
There are two methods for an application to learn about the completion
of an operation.
1/ Call dma_wait_for_async_tx(). This call causes the CPU to spin while
1. Call dma_wait_for_async_tx(). This call causes the CPU to spin while
it polls for the completion of the operation. It handles dependency
chains and issuing pending operations.
2/ Specify a completion callback. The callback routine runs in tasklet
2. Specify a completion callback. The callback routine runs in tasklet
context if the offload engine driver supports interrupts, or it is
called in application context if the operation is carried out
synchronously in software. The callback can be set in the call to
@ -111,32 +135,36 @@ of an operation.
unknown length it can use the async_trigger_callback() routine to set a
completion interrupt/callback at the end of the chain.
3.6 Constraints:
1/ Calls to async_<operation> are not permitted in IRQ context. Other
3.6 Constraints
---------------
1. Calls to async_<operation> are not permitted in IRQ context. Other
contexts are permitted provided constraint #2 is not violated.
2/ Completion callback routines cannot submit new operations. This
2. Completion callback routines cannot submit new operations. This
results in recursion in the synchronous case and spin_locks being
acquired twice in the asynchronous case.
3.7 Example:
Perform a xor->copy->xor operation where each operation depends on the
result from the previous operation:
3.7 Example
-----------
void callback(void *param)
{
Perform a xor->copy->xor operation where each operation depends on the
result from the previous operation::
void callback(void *param)
{
struct completion *cmp = param;
complete(cmp);
}
}
void run_xor_copy_xor(struct page **xor_srcs,
void run_xor_copy_xor(struct page **xor_srcs,
int xor_src_cnt,
struct page *xor_dest,
size_t xor_len,
struct page *copy_src,
struct page *copy_dest,
size_t copy_len)
{
{
struct dma_async_tx_descriptor *tx;
addr_conv_t addr_conv[xor_src_cnt];
struct async_submit_ctl submit;
@ -158,36 +186,44 @@ void run_xor_copy_xor(struct page **xor_srcs,
async_tx_issue_pending_all();
wait_for_completion(&cmp);
}
}
See include/linux/async_tx.h for more information on the flags. See the
ops_run_* and ops_complete_* routines in drivers/md/raid5.c for more
implementation examples.
4 DRIVER DEVELOPMENT NOTES
4. Driver Development Notes
===========================
4.1 Conformance points
----------------------
4.1 Conformance points:
There are a few conformance points required in dmaengine drivers to
accommodate assumptions made by applications using the async_tx API:
1/ Completion callbacks are expected to happen in tasklet context
2/ dma_async_tx_descriptor fields are never manipulated in IRQ context
3/ Use async_tx_run_dependencies() in the descriptor clean up path to
1. Completion callbacks are expected to happen in tasklet context
2. dma_async_tx_descriptor fields are never manipulated in IRQ context
3. Use async_tx_run_dependencies() in the descriptor clean up path to
handle submission of dependent operations
4.2 "My application needs exclusive control of hardware channels"
-----------------------------------------------------------------
Primarily this requirement arises from cases where a DMA engine driver
is being used to support device-to-memory operations. A channel that is
performing these operations cannot, for many platform specific reasons,
be shared. For these cases the dma_request_channel() interface is
provided.
The interface is:
struct dma_chan *dma_request_channel(dma_cap_mask_t mask,
The interface is::
struct dma_chan *dma_request_channel(dma_cap_mask_t mask,
dma_filter_fn filter_fn,
void *filter_param);
Where dma_filter_fn is defined as:
typedef bool (*dma_filter_fn)(struct dma_chan *chan, void *filter_param);
Where dma_filter_fn is defined as::
typedef bool (*dma_filter_fn)(struct dma_chan *chan, void *filter_param);
When the optional 'filter_fn' parameter is set to NULL
dma_request_channel simply returns the first channel that satisfies the
@ -207,19 +243,28 @@ private. Alternatively, it is set when dma_request_channel() finds an
unused "public" channel.
A couple caveats to note when implementing a driver and consumer:
1/ Once a channel has been privately allocated it will no longer be
1. Once a channel has been privately allocated it will no longer be
considered by the general-purpose allocator even after a call to
dma_release_channel().
2/ Since capabilities are specified at the device level a dma_device
2. Since capabilities are specified at the device level a dma_device
with multiple channels will either have all channels public, or all
channels private.
5 SOURCE
5. Source
---------
include/linux/dmaengine.h: core header file for DMA drivers and api users
drivers/dma/dmaengine.c: offload engine channel management routines
drivers/dma/: location for offload engine drivers
include/linux/async_tx.h: core header file for the async_tx api
crypto/async_tx/async_tx.c: async_tx interface to dmaengine and common code
crypto/async_tx/async_memcpy.c: copy offload
crypto/async_tx/async_xor.c: xor and xor zero sum offload
include/linux/dmaengine.h:
core header file for DMA drivers and api users
drivers/dma/dmaengine.c:
offload engine channel management routines
drivers/dma/:
location for offload engine drivers
include/linux/async_tx.h:
core header file for the async_tx api
crypto/async_tx/async_tx.c:
async_tx interface to dmaengine and common code
crypto/async_tx/async_memcpy.c:
copy offload
crypto/async_tx/async_xor.c:
xor and xor zero sum offload

View File

@ -1,8 +1,20 @@
Below is the original README file from the descore.shar package.
.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>
===========================================
Fast & Portable DES encryption & decryption
===========================================
.. note::
Below is the original README file from the descore.shar package,
converted to ReST format.
------------------------------------------------------------------------------
des - fast & portable DES encryption & decryption.
Copyright (C) 1992 Dana L. How
Copyright |copy| 1992 Dana L. How
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU Library General Public License as published by
@ -20,13 +32,12 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
Author's address: how@isl.stanford.edu
$Id: README,v 1.15 1992/05/20 00:25:32 how E $
==>> To compile after untarring/unsharring, just `make' <<==
.. README,v 1.15 1992/05/20 00:25:32 how E
==>> To compile after untarring/unsharring, just ``make`` <<==
This package was designed with the following goals:
1. Highest possible encryption/decryption PERFORMANCE.
2. PORTABILITY to any byte-addressable host with a 32bit unsigned C type
3. Plug-compatible replacement for KERBEROS's low-level routines.
@ -36,7 +47,7 @@ register-starved machines. My discussions with Richard Outerbridge,
71755.204@compuserve.com, sparked a number of these enhancements.
To more rapidly understand the code in this package, inspect desSmallFips.i
(created by typing `make') BEFORE you tackle desCode.h. The latter is set
(created by typing ``make``) BEFORE you tackle desCode.h. The latter is set
up in a parameterized fashion so it can easily be modified by speed-daemon
hackers in pursuit of that last microsecond. You will find it more
illuminating to inspect one specific implementation,
@ -47,11 +58,13 @@ performance comparison to other available des code which i could
compile on a SPARCStation 1 (cc -O4, gcc -O2):
this code (byte-order independent):
30us per encryption (options: 64k tables, no IP/FP)
33us per encryption (options: 64k tables, FIPS standard bit ordering)
45us per encryption (options: 2k tables, no IP/FP)
48us per encryption (options: 2k tables, FIPS standard bit ordering)
275us to set a new key (uses 1k of key tables)
- 30us per encryption (options: 64k tables, no IP/FP)
- 33us per encryption (options: 64k tables, FIPS standard bit ordering)
- 45us per encryption (options: 2k tables, no IP/FP)
- 48us per encryption (options: 2k tables, FIPS standard bit ordering)
- 275us to set a new key (uses 1k of key tables)
this has the quickest encryption/decryption routines i've seen.
since i was interested in fast des filters rather than crypt(3)
and password cracking, i haven't really bothered yet to speed up
@ -63,15 +76,20 @@ this code (byte-order independent):
are highly variable because of cache effects).
kerberos des replacement from australia (version 1.95):
53us per encryption (uses 2k of tables)
96us to set a new key (uses 2.25k of key tables)
- 53us per encryption (uses 2k of tables)
- 96us to set a new key (uses 2.25k of key tables)
so despite the author's inclusion of some of the performance
improvements i had suggested to him, this package's
encryption/decryption is still slower on the sparc and 68000.
more specifically, 19-40% slower on the 68020 and 11-35% slower
on the sparc, depending on the compiler;
in full gory detail (ALT_ECB is a libdes variant):
=============== ============== =============== =================
compiler machine desCore libdes ALT_ECB slower by
=============== ============== =============== =================
gcc 2.1 -O2 Sun 3/110 304 uS 369.5uS 461.8uS 22%
cc -O1 Sun 3/110 336 uS 436.6uS 399.3uS 19%
cc -O2 Sun 3/110 360 uS 532.4uS 505.1uS 40%
@ -79,10 +97,15 @@ kerberos des replacement from australia (version 1.95):
gcc 2.1 -O2 Sun 4/50 48 uS 53.4uS 57.5uS 11%
cc -O2 Sun 4/50 48 uS 64.6uS 64.7uS 35%
cc -O4 Sun 4/50 48 uS 64.7uS 64.9uS 35%
=============== ============== =============== =================
(my time measurements are not as accurate as his).
the comments in my first release of desCore on version 1.92:
68us per encryption (uses 2k of tables)
96us to set a new key (uses 2.25k of key tables)
- 68us per encryption (uses 2k of tables)
- 96us to set a new key (uses 2.25k of key tables)
this is a very nice package which implements the most important
of the optimizations which i did in my encryption routines.
it's a bit weak on common low-level optimizations which is why
@ -91,48 +114,60 @@ kerberos des replacement from australia (version 1.95):
speed up the key-setting routines with impressive results.
(at some point i may do the same in my package). he also implements
the rest of the mit des library.
(code from eay@psych.psy.uq.oz.au via comp.sources.misc)
fast crypt(3) package from denmark:
the des routine here is buried inside a loop to do the
crypt function and i didn't feel like ripping it out and measuring
performance. his code takes 26 sparc instructions to compute one
des iteration; above, Quick (64k) takes 21 and Small (2k) takes 37.
he claims to use 280k of tables but the iteration calculation seems
to use only 128k. his tables and code are machine independent.
(code from glad@daimi.aau.dk via alt.sources or comp.sources.misc)
swedish reimplementation of Kerberos des library
108us per encryption (uses 34k worth of tables)
134us to set a new key (uses 32k of key tables to get this speed!)
- 108us per encryption (uses 34k worth of tables)
- 134us to set a new key (uses 32k of key tables to get this speed!)
the tables used seem to be machine-independent;
he seems to have included a lot of special case code
so that, e.g., `long' loads can be used instead of 4 `char' loads
so that, e.g., ``long`` loads can be used instead of 4 ``char`` loads
when the machine's architecture allows it.
(code obtained from chalmers.se:pub/des)
crack 3.3c package from england:
as in crypt above, the des routine is buried in a loop. it's
also very modified for crypt. his iteration code uses 16k
of tables and appears to be slow.
(code obtained from aem@aber.ac.uk via alt.sources or comp.sources.misc)
``highly optimized'' and tweaked Kerberos/Athena code (byte-order dependent):
165us per encryption (uses 6k worth of tables)
478us to set a new key (uses <1k of key tables)
``highly optimized`` and tweaked Kerberos/Athena code (byte-order dependent):
- 165us per encryption (uses 6k worth of tables)
- 478us to set a new key (uses <1k of key tables)
so despite the comments in this code, it was possible to get
faster code AND smaller tables, as well as making the tables
machine-independent.
(code obtained from prep.ai.mit.edu)
UC Berkeley code (depends on machine-endedness):
226us per encryption
10848us to set a new key
- 226us per encryption
- 10848us to set a new key
table sizes are unclear, but they don't look very small
(code obtained from wuarchive.wustl.edu)
motivation and history
======================
a while ago i wanted some des routines and the routines documented on sun's
man pages either didn't exist or dumped core. i had heard of kerberos,
@ -142,10 +177,10 @@ it was too convoluted, the code had been written without taking
advantage of the regular structure of operations such as IP, E, and FP
(i.e. the author didn't sit down and think before coding),
it was excessively slow, the author had attempted to clarify the code
by adding MORE statements to make the data movement more `consistent'
by adding MORE statements to make the data movement more ``consistent``
instead of simplifying his implementation and cutting down on all data
movement (in particular, his use of L1, R1, L2, R2), and it was full of
idiotic `tweaks' for particular machines which failed to deliver significant
idiotic ``tweaks`` for particular machines which failed to deliver significant
speedups but which did obfuscate everything. so i took the test data
from his verification program and rewrote everything else.
@ -167,12 +202,13 @@ than versions hand-written in assembly for the sparc!
porting notes
=============
one thing i did not want to do was write an enormous mess
which depended on endedness and other machine quirks,
and which necessarily produced different code and different lookup tables
for different machines. see the kerberos code for an example
of what i didn't want to do; all their endedness-specific `optimizations'
of what i didn't want to do; all their endedness-specific ``optimizations``
obfuscate the code and in the end were slower than a simpler machine
independent approach. however, there are always some portability
considerations of some kind, and i have included some options
@ -184,8 +220,8 @@ perhaps some will still regard the result as a mess!
i assume word pointers can be freely cast to and from char pointers.
note that 99% of C programs make these assumptions.
i always use unsigned char's if the high bit could be set.
2) the typedef `word' means a 32 bit unsigned integral type.
if `unsigned long' is not 32 bits, change the typedef in desCore.h.
2) the typedef ``word`` means a 32 bit unsigned integral type.
if ``unsigned long`` is not 32 bits, change the typedef in desCore.h.
i assume sizeof(word) == 4 EVERYWHERE.
the (worst-case) cost of my NOT doing endedness-specific optimizations
@ -195,40 +231,46 @@ the input and output work areas do not need to be word-aligned.
OPTIONAL performance optimizations
==================================
1) you should define one of `i386,' `vax,' `mc68000,' or `sparc,'
1) you should define one of ``i386,`` ``vax,`` ``mc68000,`` or ``sparc,``
whichever one is closest to the capabilities of your machine.
see the start of desCode.h to see exactly what this selection implies.
note that if you select the wrong one, the des code will still work;
these are just performance tweaks.
2) for those with functional `asm' keywords: you should change the
2) for those with functional ``asm`` keywords: you should change the
ROR and ROL macros to use machine rotate instructions if you have them.
this will save 2 instructions and a temporary per use,
or about 32 to 40 instructions per en/decryption.
note that gcc is smart enough to translate the ROL/R macros into
machine rotates!
these optimizations are all rather persnickety, yet with them you should
be able to get performance equal to assembly-coding, except that:
1) with the lack of a bit rotate operator in C, rotates have to be synthesized
from shifts. so access to `asm' will speed things up if your machine
from shifts. so access to ``asm`` will speed things up if your machine
has rotates, as explained above in (3) (not necessary if you use gcc).
2) if your machine has less than 12 32-bit registers i doubt your compiler will
generate good code.
`i386' tries to configure the code for a 386 by only declaring 3 registers
``i386`` tries to configure the code for a 386 by only declaring 3 registers
(it appears that gcc can use ebx, esi and edi to hold register variables).
however, if you like assembly coding, the 386 does have 7 32-bit registers,
and if you use ALL of them, use `scaled by 8' address modes with displacement
and if you use ALL of them, use ``scaled by 8`` address modes with displacement
and other tricks, you can get reasonable routines for DesQuickCore... with
about 250 instructions apiece. For DesSmall... it will help to rearrange
des_keymap, i.e., now the sbox # is the high part of the index and
the 6 bits of data is the low part; it helps to exchange these.
since i have no way to conveniently test it i have not provided my
shoehorned 386 version. note that with this release of desCore, gcc is able
to put everything in registers(!), and generate about 370 instructions apiece
for the DesQuickCore... routines!
coding notes
============
the en/decryption routines each use 6 necessary register variables,
with 4 being actively used at once during the inner iterations.
@ -236,15 +278,18 @@ if you don't have 4 register variables get a new machine.
up to 8 more registers are used to hold constants in some configurations.
i assume that the use of a constant is more expensive than using a register:
a) additionally, i have tried to put the larger constants in registers.
registering priority was by the following:
anything more than 12 bits (bad for RISC and CISC)
greater than 127 in value (can't use movq or byte immediate on CISC)
9-127 (may not be able to use CISC shift immediate or add/sub quick),
1-8 were never registered, being the cheapest constants.
- anything more than 12 bits (bad for RISC and CISC)
- greater than 127 in value (can't use movq or byte immediate on CISC)
- 9-127 (may not be able to use CISC shift immediate or add/sub quick),
- 1-8 were never registered, being the cheapest constants.
b) the compiler may be too stupid to realize table and table+256 should
be assigned to different constant registers and instead repetitively
do the arithmetic, so i assign these to explicit `m' register variables
do the arithmetic, so i assign these to explicit ``m`` register variables
when possible and helpful.
i assume that indexing is cheaper or equivalent to auto increment/decrement,
@ -253,25 +298,31 @@ this assumption is reversed for 68k and vax.
i assume that addresses can be cheaply formed from two registers,
or from a register and a small constant.
for the 68000, the `two registers and small offset' form is used sparingly.
for the 68000, the ``two registers and small offset`` form is used sparingly.
all index scaling is done explicitly - no hidden shifts by log2(sizeof).
the code is written so that even a dumb compiler
should never need more than one hidden temporary,
increasing the chance that everything will fit in the registers.
KEEP THIS MORE SUBTLE POINT IN MIND IF YOU REWRITE ANYTHING.
(actually, there are some code fragments now which do require two temps,
but fixing it would either break the structure of the macros or
require declaring another temporary).
special efficient data format
==============================
bits are manipulated in this arrangement most of the time (S7 S5 S3 S1)::
bits are manipulated in this arrangement most of the time (S7 S5 S3 S1):
003130292827xxxx242322212019xxxx161514131211xxxx080706050403xxxx
(the x bits are still there, i'm just emphasizing where the S boxes are).
bits are rotated left 4 when computing S6 S4 S2 S0:
bits are rotated left 4 when computing S6 S4 S2 S0::
282726252423xxxx201918171615xxxx121110090807xxxx040302010031xxxx
the rightmost two bits are usually cleared so the lower byte can be used
as an index into an sbox mapping table. the next two x'd bits are set
to various values to access different parts of the tables.
@ -288,7 +339,7 @@ datatypes:
must be long-aligned.
DesQuickInit()
call this before using any other routine with `Quick' in its name.
call this before using any other routine with ``Quick`` in its name.
it generates the special 64k table these routines need.
DesQuickDone()
frees this table
@ -298,6 +349,7 @@ DesMethod(m, k)
which must have odd parity (or -1 is returned) and which must
not be a (semi-)weak key (or -2 is returned).
normally DesMethod() returns 0.
m is filled in from k so that when one of the routines below
is called with m, the routine will act like standard des
en/decryption with the key k. if you use DesMethod,
@ -308,19 +360,26 @@ DesMethod(m, k)
will be set to magic constants which speed up the encryption/decryption
on some machines. and yes, each byte controls
a specific sbox during a specific iteration.
you really shouldn't use the 768bit format directly; i should
provide a routine that converts 128 6-bit bytes (specified in
S-box mapping order or something) into the right format for you.
this would entail some byte concatenation and rotation.
Des{Small|Quick}{Fips|Core}{Encrypt|Decrypt}(d, m, s)
performs des on the 8 bytes at s into the 8 bytes at d. (d,s: char *).
performs des on the 8 bytes at s into the 8 bytes at
``d. (d,s: char *)``.
uses m as a 768bit key as explained above.
the Encrypt|Decrypt choice is obvious.
Fips|Core determines whether a completely standard FIPS initial
and final permutation is done; if not, then the data is loaded
and stored in a nonstandard bit order (FIPS w/o IP/FP).
Fips slows down Quick by 10%, Small by 9%.
Small|Quick determines whether you use the normal routine
or the crazy quick one which gobbles up 64k more of memory.
Small is 50% slower then Quick, but Quick needs 32 times as much
@ -329,15 +388,17 @@ Des{Small|Quick}{Fips|Core}{Encrypt|Decrypt}(d, m, s)
Getting it to compile on your machine
=====================================
there are no machine-dependencies in the code (see porting),
except perhaps the `now()' macro in desTest.c.
except perhaps the ``now()`` macro in desTest.c.
ALL generated tables are machine independent.
you should edit the Makefile with the appropriate optimization flags
for your compiler (MAX optimization).
Speeding up kerberos (and/or its des library)
=============================================
note that i have included a kerberos-compatible interface in desUtil.c
through the functions des_key_sched() and des_ecb_encrypt().
@ -347,6 +408,7 @@ you should not need to #include desCore.h; just include the header
file provided with the kerberos library.
Other uses
==========
the macros in desCode.h would be very useful for putting inline des
functions in more complicated encryption routines.

View File

@ -17,9 +17,14 @@ for cryptographic use cases, as well as programming examples.
:maxdepth: 2
intro
api-intro
architecture
async-tx-api
asymmetric-keys
devel-algos
userspace-if
crypto_engine
api
api-samples
descore-readme

View File

@ -85,7 +85,7 @@ Four basic modes are defined: ``patch``, ``report``, ``context``, and
file:line:column-column: message
- ``context`` highlights lines of interest and their context in a
diff-like style.Lines of interest are indicated with ``-``.
diff-like style. Lines of interest are indicated with ``-``.
- ``org`` generates a report in the Org mode format of Emacs.
@ -119,7 +119,7 @@ For each semantic patch, a commit message is proposed. It gives a
description of the problem being checked by the semantic patch, and
includes a reference to Coccinelle.
As any static code analyzer, Coccinelle produces false
As with any static code analyzer, Coccinelle produces false
positives. Thus, reports must be carefully checked, and patches
reviewed.
@ -135,18 +135,18 @@ the parallelism, set the J= variable. For example, to run across 4 CPUs::
make coccicheck MODE=report J=4
As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization,
As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization;
if support for this is detected you will benefit from parmap parallelization.
When parmap is enabled coccicheck will enable dynamic load balancing by using
``--chunksize 1`` argument, this ensures we keep feeding threads with work
``--chunksize 1`` argument. This ensures we keep feeding threads with work
one by one, so that we avoid the situation where most work gets done by only
a few threads. With dynamic load balancing, if a thread finishes early we keep
feeding it more work.
When parmap is enabled, if an error occurs in Coccinelle, this error
value is propagated back, the return value of the ``make coccicheck``
captures this return value.
value is propagated back, and the return value of the ``make coccicheck``
command captures this return value.
Using Coccinelle with a single semantic patch
---------------------------------------------
@ -183,7 +183,7 @@ To check only newly edited code, use the value 2 for the C flag, i.e.::
make C=2 CHECK="scripts/coccicheck"
In these modes, which works on a file basis, there is no information
In these modes, which work on a file basis, there is no information
about semantic patches displayed, and no commit message proposed.
This runs every semantic patch in scripts/coccinelle by default. The
@ -198,12 +198,12 @@ Debugging Coccinelle SmPL patches
Using coccicheck is best as it provides in the spatch command line
include options matching the options used when we compile the kernel.
You can learn what these options are by using V=1, you could then
You can learn what these options are by using V=1; you could then
manually run Coccinelle with debug options added.
Alternatively you can debug running Coccinelle against SmPL patches
by asking for stderr to be redirected to stderr, by default stderr
is redirected to /dev/null, if you'd like to capture stderr you
by asking for stderr to be redirected to stderr. By default stderr
is redirected to /dev/null; if you'd like to capture stderr you
can specify the ``DEBUG_FILE="file.txt"`` option to coccicheck. For
instance::
@ -211,8 +211,8 @@ instance::
make coccicheck COCCI=scripts/coccinelle/free/kfree.cocci MODE=report DEBUG_FILE=cocci.err
cat cocci.err
You can use SPFLAGS to add debugging flags, for instance you may want to
add both --profile --show-trying to SPFLAGS when debugging. For instance
You can use SPFLAGS to add debugging flags; for instance you may want to
add both --profile --show-trying to SPFLAGS when debugging. For example
you may want to use::
rm -f err.log
@ -229,7 +229,7 @@ DEBUG_FILE support is only supported when using coccinelle >= 1.0.2.
--------------------
Coccinelle supports reading .cocciconfig for default Coccinelle options that
should be used every time spatch is spawned, the order of precedence for
should be used every time spatch is spawned. The order of precedence for
variables for .cocciconfig is as follows:
- Your current user's home directory is processed first
@ -237,7 +237,7 @@ variables for .cocciconfig is as follows:
- The directory provided with the --dir option is processed last, if used
Since coccicheck runs through make, it naturally runs from the kernel
proper dir, as such the second rule above would be implied for picking up a
proper dir; as such the second rule above would be implied for picking up a
.cocciconfig when using ``make coccicheck``.
``make coccicheck`` also supports using M= targets. If you do not supply
@ -260,13 +260,13 @@ If not using the kernel's coccicheck target, keep the above precedence
order logic of .cocciconfig reading. If using the kernel's coccicheck target,
override any of the kernel's .coccicheck's settings using SPFLAGS.
We help Coccinelle when used against Linux with a set of sensible defaults
We help Coccinelle when used against Linux with a set of sensible default
options for Linux with our own Linux .cocciconfig. This hints to coccinelle
git can be used for ``git grep`` queries over coccigrep. A timeout of 200
that git can be used for ``git grep`` queries over coccigrep. A timeout of 200
seconds should suffice for now.
The options picked up by coccinelle when reading a .cocciconfig do not appear
as arguments to spatch processes running on your system, to confirm what
as arguments to spatch processes running on your system. To confirm what
options will be used by Coccinelle run::
spatch --print-options-only
@ -290,7 +290,7 @@ given to it when options are in conflict. ::
Coccinelle supports idutils as well but requires coccinelle >= 1.0.6.
When no ID file is specified coccinelle assumes your ID database file
is in the file .id-utils.index on the top level of the kernel, coccinelle
is in the file .id-utils.index on the top level of the kernel. Coccinelle
carries a script scripts/idutils_index.sh which creates the database with::
mkid -i C --output .id-utils.index
@ -317,7 +317,7 @@ SmPL patch specific options
---------------------------
SmPL patches can have their own requirements for options passed
to Coccinelle. SmPL patch specific options can be provided by
to Coccinelle. SmPL patch-specific options can be provided by
providing them at the top of the SmPL patch, for instance::
// Options: --no-includes --include-headers
@ -327,7 +327,7 @@ SmPL patch Coccinelle requirements
As Coccinelle features get added some more advanced SmPL patches
may require newer versions of Coccinelle. If an SmPL patch requires
at least a version of Coccinelle, this can be specified as follows,
a minimum version of Coccinelle, this can be specified as follows,
as an example if requiring at least Coccinelle >= 1.0.5::
// Requires: 1.0.5

View File

@ -22,7 +22,7 @@ Possible uses:
* minimizing kernel configurations (do I need this option if the
associated code is never run?)
.. _gcov: http://gcc.gnu.org/onlinedocs/gcc/Gcov.html
.. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html
.. _lcov: http://ltp.sourceforge.net/coverage/lcov.php
@ -171,7 +171,7 @@ Note on compilers
GCC and LLVM gcov tools are not necessarily compatible. Use gcov_ to work with
GCC-generated .gcno and .gcda files, and use llvm-cov_ for Clang.
.. _gcov: http://gcc.gnu.org/onlinedocs/gcc/Gcov.html
.. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html
.. _llvm-cov: https://llvm.org/docs/CommandGuide/llvm-cov.html
Build differences between GCC and Clang gcov are handled by Kconfig. It

View File

@ -872,7 +872,7 @@ The kgdboc driver contains logic to configure communications with an
attached keyboard. The keyboard infrastructure is only compiled into the
kernel when ``CONFIG_KDB_KEYBOARD=y`` is set in the kernel configuration.
The core polled keyboard driver driver for PS/2 type keyboards is in
The core polled keyboard driver for PS/2 type keyboards is in
``drivers/char/kdb_keyboard.c``. This driver is hooked into the debug core
when kgdboc populates the callback in the array called
:c:type:`kdb_poll_funcs[]`. The :c:func:`kdb_get_kbd_char` is the top-level

View File

@ -8,8 +8,6 @@ with the difference that the orphan objects are not freed but only
reported via /sys/kernel/debug/kmemleak. A similar method is used by the
Valgrind tool (``memcheck --leak-check``) to detect the memory leaks in
user-space applications.
Kmemleak is supported on x86, arm, arm64, powerpc, sparc, sh, microblaze, mips,
s390, nds32, arc and xtensa.
Usage
-----

View File

@ -9,6 +9,8 @@ Sparse is a semantic checker for C programs; it can be used to find a
number of potential problems with kernel code. See
https://lwn.net/Articles/689907/ for an overview of sparse; this document
contains some kernel-specific sparse information.
More information on sparse, mainly about its internals, can be found in
its official pages at https://sparse.docs.kernel.org.
Using sparse for typechecking
@ -73,8 +75,8 @@ sparse would otherwise report a context imbalance.
Getting sparse
--------------
You can get latest released versions from the Sparse homepage at
https://sparse.wiki.kernel.org/index.php/Main_Page
You can get tarballs of the latest released versions from:
https://www.kernel.org/pub/software/devel/sparse/dist/
Alternatively, you can get snapshots of the latest development version
of sparse using git to clone::

View File

@ -1,15 +1,19 @@
Booting the Linux/ppc kernel without Open Firmware
--------------------------------------------------
.. SPDX-License-Identifier: GPL-2.0
(c) 2005 Benjamin Herrenschmidt <benh at kernel.crashing.org>,
IBM Corp.
(c) 2005 Becky Bruce <becky.bruce at freescale.com>,
Freescale Semiconductor, FSL SOC and 32-bit additions
(c) 2006 MontaVista Software, Inc.
Flash chip node definition
==================================================
Booting the Linux/ppc kernel without Open Firmware
==================================================
Table of Contents
=================
Copyright (c) 2005 Benjamin Herrenschmidt <benh at kernel.crashing.org>,
IBM Corp.
Copyright (c) 2005 Becky Bruce <becky.bruce at freescale.com>,
Freescale Semiconductor, FSL SOC and 32-bit additions
Copyright (c) 2006 MontaVista Software, Inc.
Flash chip node definition
.. Table of Contents
I - Introduction
1) Entry point for arch/arm
@ -61,15 +65,18 @@ Table of Contents
Revision Information
====================
May 18, 2005: Rev 0.1 - Initial draft, no chapter III yet.
May 18, 2005: Rev 0.1
- Initial draft, no chapter III yet.
May 19, 2005: Rev 0.2 - Add chapter III and bits & pieces here or
May 19, 2005: Rev 0.2
- Add chapter III and bits & pieces here or
clarifies the fact that a lot of things are
optional, the kernel only requires a very
small device tree, though it is encouraged
to provide an as complete one as possible.
May 24, 2005: Rev 0.3 - Precise that DT block has to be in RAM
May 24, 2005: Rev 0.3
- Precise that DT block has to be in RAM
- Misc fixes
- Define version 3 and new format version 16
for the DT block (version 16 needs kernel
@ -82,7 +89,8 @@ Revision Information
"name" property is now automatically
deduced from the unit name
June 1, 2005: Rev 0.4 - Correct confusion between OF_DT_END and
June 1, 2005: Rev 0.4
- Correct confusion between OF_DT_END and
OF_DT_END_NODE in structure definition.
- Change version 16 format to always align
property data to 4 bytes. Since tokens are
@ -260,7 +268,7 @@ it with special cases.
b) create your main platform file as
"arch/powerpc/platforms/myplatform/myboard_setup.c" and add it
to the Makefile under the condition of your CONFIG_
to the Makefile under the condition of your ``CONFIG_``
option. This file will define a structure of type "ppc_md"
containing the various callbacks that the generic code will
use to get to your platform specific code
@ -271,7 +279,7 @@ it with special cases.
with classic Powerpc architectures.
3) Entry point for arch/x86
-------------------------------
---------------------------
There is one single 32bit entry point to the kernel at code32_start,
the decompressor (the real mode entry point goes to the same 32bit
@ -280,7 +288,7 @@ it with special cases.
Documentation/x86/boot.rst
The physical pointer to the device-tree block (defined in chapter II)
is passed via setup_data which requires at least boot protocol 2.09.
The type filed is defined as
The type filed is defined as::
#define SETUP_DTB 2
@ -354,9 +362,9 @@ the block to RAM before passing it to the kernel.
The kernel is passed the physical address pointing to an area of memory
that is roughly described in include/linux/of_fdt.h by the structure
boot_param_header:
boot_param_header:::
struct boot_param_header {
struct boot_param_header {
u32 magic; /* magic word OF_DT_HEADER */
u32 totalsize; /* total size of DT block */
u32 off_dt_struct; /* offset to structure */
@ -374,19 +382,19 @@ struct boot_param_header {
/* version 17 fields below */
u32 size_dt_struct; /* size of the DT structure block */
};
};
Along with the constants:
Along with the constants::
/* Definitions used by the flattened device tree */
#define OF_DT_HEADER 0xd00dfeed /* 4: version,
/* Definitions used by the flattened device tree */
#define OF_DT_HEADER 0xd00dfeed /* 4: version,
4: total size */
#define OF_DT_BEGIN_NODE 0x1 /* Start node: full name
#define OF_DT_BEGIN_NODE 0x1 /* Start node: full name
*/
#define OF_DT_END_NODE 0x2 /* End node */
#define OF_DT_PROP 0x3 /* Property: name off,
#define OF_DT_END_NODE 0x2 /* End node */
#define OF_DT_PROP 0x3 /* Property: name off,
size, content */
#define OF_DT_END 0x9
#define OF_DT_END 0x9
All values in this header are in big endian format, the various
fields in this header are defined more precisely below. All
@ -430,7 +438,7 @@ struct boot_param_header {
way to avoid overriding critical things like, on Open Firmware
capable machines, the RTAS instance, or on some pSeries, the TCE
tables used for the iommu. Typically, the reserve map should
contain _at least_ this DT block itself (header,total_size). If
contain **at least** this DT block itself (header,total_size). If
you are passing an initrd to the kernel, you should reserve it as
well. You do not need to reserve the kernel image itself. The map
should be 64-bit aligned.
@ -485,7 +493,7 @@ struct boot_param_header {
So the typical layout of a DT block (though the various parts don't
need to be in that order) looks like this (addresses go from top to
bottom):
bottom)::
------------------------------
@ -600,7 +608,7 @@ discussed in a later chapter. At this point, it is only meant to give
you a idea of what a device-tree looks like. I have purposefully kept
the "name" and "linux,phandle" properties which aren't necessary in
order to give you a better idea of what the tree looks like in
practice.
practice::
/ o device-tree
|- name = "device-tree"
@ -650,6 +658,7 @@ properties and their content.
3) Device tree "structure" block
--------------------------------
The structure of the device tree is a linearized tree structure. The
"OF_DT_BEGIN_NODE" token starts a new node, and the "OF_DT_END_NODE"
@ -666,12 +675,14 @@ Here's the basic structure of a single node:
root node)
* [align gap to next 4 bytes boundary]
* for each property:
* token OF_DT_PROP (that is 0x00000003)
* 32-bit value of property value size in bytes (or 0 if no
value)
* 32-bit value of offset in string block of property name
* property value data if any
* [align gap to next 4 bytes boundary]
* [child nodes if any]
* token OF_DT_END_NODE (that is 0x00000002)
@ -688,6 +699,7 @@ manipulating a flattened tree must take care to preserve this
constraint.
4) Device tree "strings" block
------------------------------
In order to save space, property names, which are generally redundant,
are stored separately in the "strings" block. This block is simply the
@ -700,15 +712,17 @@ strings block.
III - Required content of the device tree
=========================================
WARNING: All "linux,*" properties defined in this document apply only
to a flattened device-tree. If your platform uses a real
implementation of Open Firmware or an implementation compatible with
the Open Firmware client interface, those properties will be created
by the trampoline code in the kernel's prom_init() file. For example,
that's where you'll have to add code to detect your board model and
set the platform number. However, when using the flattened device-tree
entry point, there is no prom_init() pass, and thus you have to
provide those properties yourself.
.. Warning::
All ``linux,*`` properties defined in this document apply only
to a flattened device-tree. If your platform uses a real
implementation of Open Firmware or an implementation compatible with
the Open Firmware client interface, those properties will be created
by the trampoline code in the kernel's prom_init() file. For example,
that's where you'll have to add code to detect your board model and
set the platform number. However, when using the flattened device-tree
entry point, there is no prom_init() pass, and thus you have to
provide those properties yourself.
1) Note about cells and address representation
@ -769,7 +783,7 @@ addresses), all buses must contain a "ranges" property. If the
"ranges" property is missing at a given level, it's assumed that
translation isn't possible, i.e., the registers are not visible on the
parent bus. The format of the "ranges" property for a bus is a list
of:
of::
bus address, parent bus address, size
@ -877,7 +891,7 @@ address which can extend beyond that limit.
This node is the parent of all individual CPU nodes. It doesn't
have any specific requirements, though it's generally good practice
to have at least:
to have at least::
#address-cells = <00000001>
#size-cells = <00000000>
@ -887,7 +901,7 @@ address which can extend beyond that limit.
that format when reading the "reg" properties of a CPU node, see
below
c) The /cpus/* nodes
c) The ``/cpus/*`` nodes
So under /cpus, you are supposed to create a node for every CPU on
the machine. There is no specific restriction on the name of the
@ -903,21 +917,23 @@ address which can extend beyond that limit.
- reg : This is the physical CPU number, it's a single 32-bit cell
and is also used as-is as the unit number for constructing the
unit name in the full path. For example, with 2 CPUs, you would
have the full path:
have the full path::
/cpus/PowerPC,970FX@0
/cpus/PowerPC,970FX@1
(unit addresses do not require leading zeroes)
- d-cache-block-size : one cell, L1 data cache block size in bytes (*)
- d-cache-block-size : one cell, L1 data cache block size in bytes [#]_
- i-cache-block-size : one cell, L1 instruction cache block size in
bytes
- d-cache-size : one cell, size of L1 data cache in bytes
- i-cache-size : one cell, size of L1 instruction cache in bytes
(*) The cache "block" size is the size on which the cache management
instructions operate. Historically, this document used the cache
"line" size here which is incorrect. The kernel will prefer the cache
block size and will fallback to cache line size for backward
compatibility.
.. [#] The cache "block" size is the size on which the cache management
instructions operate. Historically, this document used the cache
"line" size here which is incorrect. The kernel will prefer the cache
block size and will fallback to cache line size for backward
compatibility.
Recommended properties:
@ -963,7 +979,7 @@ compatibility.
#address-cells and #size-cells of the root node. For example,
with both of these properties being 2 like in the example given
earlier, a 970 based machine with 6Gb of RAM could typically
have a "reg" property here that looks like:
have a "reg" property here that looks like::
00000000 00000000 00000000 80000000
00000001 00000000 00000001 00000000
@ -1058,7 +1074,7 @@ compatibility.
on the SOC but are not used by a particular platform. See chapter VI
for more information on how to specify devices that are part of a SOC.
Example SOC node for the MPC8540:
Example SOC node for the MPC8540::
soc8540@e0000000 {
#address-cells = <1>;
@ -1079,18 +1095,20 @@ IV - "dtc", the device tree compiler
dtc source code can be found at
<http://git.jdl.com/gitweb/?p=dtc.git>
WARNING: This version is still in early development stage; the
resulting device-tree "blobs" have not yet been validated with the
kernel. The current generated block lacks a useful reserve map (it will
be fixed to generate an empty one, it's up to the bootloader to fill
it up) among others. The error handling needs work, bugs are lurking,
etc...
.. Warning::
This version is still in early development stage; the
resulting device-tree "blobs" have not yet been validated with the
kernel. The current generated block lacks a useful reserve map (it will
be fixed to generate an empty one, it's up to the bootloader to fill
it up) among others. The error handling needs work, bugs are lurking,
etc...
dtc basically takes a device-tree in a given format and outputs a
device-tree in another format. The currently supported formats are:
Input formats:
-------------
Input formats
-------------
- "dtb": "blob" format, that is a flattened device-tree block
with
@ -1102,8 +1120,8 @@ device-tree in another format. The currently supported formats are:
output of /proc/device-tree, that is nodes are directories and
properties are files
Output formats:
---------------
Output formats
--------------
- "dtb": "blob" format
- "dts": "source" format
@ -1113,7 +1131,7 @@ device-tree in another format. The currently supported formats are:
assembly file exports some symbols that can be used.
The syntax of the dtc tool is
The syntax of the dtc tool is::
dtc [-I <input-format>] [-O <output-format>]
[-o output-filename] [-V output_version] input_filename
@ -1127,15 +1145,17 @@ Additionally, dtc performs various sanity checks on the tree, like the
uniqueness of linux, phandle properties, validity of strings, etc...
The format of the .dts "source" file is "C" like, supports C and C++
style comments.
style comments::
/ {
}
/ {
}
The above is the "device-tree" definition. It's the only statement
supported currently at the toplevel.
/ {
::
/ {
property1 = "string_value"; /* define a property containing a 0
* terminated string
*/
@ -1163,7 +1183,7 @@ supported currently at the toplevel.
* childnode (in this case, a string)
*/
};
};
};
Nodes can contain other nodes etc... thus defining the hierarchical
structure of the tree.
@ -1322,7 +1342,7 @@ phandle of the parent node.
If the interrupt-parent property is not defined for a node, its
interrupt parent is assumed to be an ancestor in the node's
_device tree_ hierarchy.
*device tree* hierarchy.
3) OpenPIC Interrupt Controllers
--------------------------------
@ -1334,10 +1354,12 @@ information.
Sense and level information should be encoded as follows:
0 = low to high edge sensitive type enabled
1 = active low level sensitive type enabled
2 = active high level sensitive type enabled
3 = high to low edge sensitive type enabled
== ========================================
0 low to high edge sensitive type enabled
1 active low level sensitive type enabled
2 active high level sensitive type enabled
3 high to low edge sensitive type enabled
== ========================================
4) ISA Interrupt Controllers
----------------------------
@ -1350,13 +1372,15 @@ information.
ISA PIC interrupt controllers should adhere to the ISA PIC
encodings listed below:
0 = active low level sensitive type enabled
1 = active high level sensitive type enabled
2 = high to low edge sensitive type enabled
3 = low to high edge sensitive type enabled
== ========================================
0 active low level sensitive type enabled
1 active high level sensitive type enabled
2 high to low edge sensitive type enabled
3 low to high edge sensitive type enabled
== ========================================
VIII - Specifying Device Power Management Information (sleep property)
===================================================================
======================================================================
Devices on SOCs often have mechanisms for placing devices into low-power
states that are decoupled from the devices' own register blocks. Sometimes,
@ -1387,6 +1411,7 @@ reasonably grouped in this manner, then create a virtual sleep controller
sleep-map should wait until its necessity is demonstrated).
IX - Specifying dma bus information
===================================
Some devices may have DMA memory range shifted relatively to the beginning of
RAM, or even placed outside of kernel RAM. For example, the Keystone 2 SoC
@ -1404,7 +1429,9 @@ coherent DMA operations. The "dma-coherent" property is intended to be used
for identifying devices supported coherent DMA operations in DT.
* DMA Bus master
Optional property:
- dma-ranges: <prop-encoded-array> encoded as arbitrary number of triplets of
(child-bus-address, parent-bus-address, length). Each triplet specified
describes a contiguous DMA address range.
@ -1416,13 +1443,16 @@ Optional property:
(for more information see the Devicetree Specification)
* DMA Bus child
Optional property:
- dma-ranges: <empty> value. if present - It means that DMA addresses
translation has to be enabled for this device.
- dma-coherent: Present if dma operations are coherent
Example:
soc {
Example::
soc {
compatible = "ti,keystone","simple-bus";
ranges = <0x0 0x0 0x0 0xc0000000>;
dma-ranges = <0x80000000 0x8 0x00000000 0x80000000>;
@ -1435,11 +1465,13 @@ soc {
[...]
dma-coherent;
};
};
};
Appendix A - Sample SOC node for MPC8540
========================================
::
soc@e0000000 {
#address-cells = <1>;
#size-cells = <1>;

View File

@ -15,3 +15,4 @@ Open Firmware and Device Tree
overlay-notes
bindings/index
booting-without-of

View File

@ -26,7 +26,7 @@ netlink based networking for inter-process communication in a significantly
easier way::
int cn_add_callback(struct cb_id *id, char *name, void (*callback) (struct cn_msg *, struct netlink_skb_parms *));
void cn_netlink_send_multi(struct cn_msg *msg, u16 len, u32 portid, u32 __group, int gfp_mask);
void cn_netlink_send_mult(struct cn_msg *msg, u16 len, u32 portid, u32 __group, int gfp_mask);
void cn_netlink_send(struct cn_msg *msg, u32 portid, u32 __group, int gfp_mask);
struct cb_id
@ -48,7 +48,8 @@ be dereferenced to `struct cn_msg *`::
__u32 seq;
__u32 ack;
__u32 len; /* Length of the following data */
__u16 len; /* Length of the following data */
__u16 flags;
__u8 data[0];
};

View File

@ -36,14 +36,14 @@ are starting with one. Physical addresses are of type unsigned long.
This address should not be used directly. Instead, to get an address
suitable for passing to the accessor functions described below, you
should call :c:func:`ioremap()`. An address suitable for accessing
should call ioremap(). An address suitable for accessing
the device will be returned to you.
After you've finished using the device (say, in your module's exit
routine), call :c:func:`iounmap()` in order to return the address
routine), call iounmap() in order to return the address
space to the kernel. Most architectures allocate new address space each
time you call :c:func:`ioremap()`, and they can run out unless you
call :c:func:`iounmap()`.
time you call ioremap(), and they can run out unless you
call iounmap().
Accessing the device
--------------------
@ -60,8 +60,8 @@ readb_relaxed(), readw_relaxed(), readl_relaxed(), readq_relaxed(),
writeb(), writew(), writel() and writeq().
Some devices (such as framebuffers) would like to use larger transfers than
8 bytes at a time. For these devices, the :c:func:`memcpy_toio()`,
:c:func:`memcpy_fromio()` and :c:func:`memset_io()` functions are
8 bytes at a time. For these devices, the memcpy_toio(),
memcpy_fromio() and memset_io() functions are
provided. Do not use memset or memcpy on IO addresses; they are not
guaranteed to copy data in order.
@ -135,15 +135,15 @@ Accessing Port Space
Accesses to this space are provided through a set of functions which
allow 8-bit, 16-bit and 32-bit accesses; also known as byte, word and
long. These functions are :c:func:`inb()`, :c:func:`inw()`,
:c:func:`inl()`, :c:func:`outb()`, :c:func:`outw()` and
:c:func:`outl()`.
long. These functions are inb(), inw(),
inl(), outb(), outw() and
outl().
Some variants are provided for these functions. Some devices require
that accesses to their ports are slowed down. This functionality is
provided by appending a ``_p`` to the end of the function.
There are also equivalents to memcpy. The :c:func:`ins()` and
:c:func:`outs()` functions copy bytes, words or longs to the given
There are also equivalents to memcpy. The ins() and
outs() functions copy bytes, words or longs to the given
port.
Public Functions Provided

View File

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

View File

@ -95,7 +95,7 @@ accommodates that API in some cases, and made some design choices to
ensure that it stayed compatible.
For more information on the Async TX API, please look the relevant
documentation file in Documentation/crypto/async-tx-api.txt.
documentation file in Documentation/crypto/async-tx-api.rst.
DMAEngine APIs
==============

View File

@ -228,8 +228,6 @@ over management of devices from the bootloader, the usage of sync_state() is
not restricted to that. Use it whenever it makes sense to take an action after
all the consumers of a device have probed::
::
int (*remove) (struct device *dev);
remove is called to unbind a driver from a device. This may be

View File

@ -92,7 +92,7 @@ You can obtain somewhat infrequent snapshots of klibc from
https://www.kernel.org/pub/linux/libs/klibc/
For active users, you are better off using the klibc git
repository, at http://git.kernel.org/?p=libs/klibc/klibc.git
repository, at https://git.kernel.org/?p=libs/klibc/klibc.git
The standalone klibc distribution currently provides three components,
in addition to the klibc library:
@ -122,7 +122,7 @@ and a number of other utilities, so you can replace kinit and build
custom initramfs images that meet your needs exactly.
For questions and help, you can sign up for the early userspace
mailing list at http://www.zytor.com/mailman/listinfo/klibc
mailing list at https://www.zytor.com/mailman/listinfo/klibc
How does it work?
=================

View File

@ -14,7 +14,7 @@ collisions are prevented, ...) please have a look at the I3C specification.
This document is just a brief introduction to the I3C protocol and the concepts
it brings to the table. If you need more information, please refer to the MIPI
I3C specification (can be downloaded here
http://resources.mipi.org/mipi-i3c-v1-download).
https://resources.mipi.org/mipi-i3c-v1-download).
Introduction
============

View File

@ -48,6 +48,7 @@ available subsections can be seen below.
scsi
libata
target
mailbox
mtdnand
miscellaneous
mei/index

View File

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

View File

@ -14,7 +14,7 @@ memory devices like
* Pseudo-SRAM devices
GPMC is found on Texas Instruments SoC's (OMAP based)
IP details: http://www.ti.com/lit/pdf/spruh73 section 7.1
IP details: https://www.ti.com/lit/pdf/spruh73 section 7.1
GPMC generic timing calculation:

View File

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

View File

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

View File

@ -73,7 +73,7 @@ DAX:
process address space.
DSM:
Device Specific Method: ACPI method to to control specific
Device Specific Method: ACPI method to control specific
device - in this case the firmware.
DCR:
@ -113,13 +113,13 @@ Supporting Documents
--------------------
ACPI 6:
http://www.uefi.org/sites/default/files/resources/ACPI_6.0.pdf
https://www.uefi.org/sites/default/files/resources/ACPI_6.0.pdf
NVDIMM Namespace:
http://pmem.io/documents/NVDIMM_Namespace_Spec.pdf
https://pmem.io/documents/NVDIMM_Namespace_Spec.pdf
DSM Interface Example:
http://pmem.io/documents/NVDIMM_DSM_Interface_Example.pdf
https://pmem.io/documents/NVDIMM_DSM_Interface_Example.pdf
Driver Writer's Guide:
http://pmem.io/documents/NVDIMM_Driver_Writers_Guide.pdf
https://pmem.io/documents/NVDIMM_Driver_Writers_Guide.pdf
Git Trees
---------
@ -778,7 +778,7 @@ Why the Term "namespace"?
2. The term originated to describe the sub-devices that can be created
within a NVME controller (see the nvme specification:
http://www.nvmexpress.org/specifications/), and NFIT namespaces are
https://www.nvmexpress.org/specifications/), and NFIT namespaces are
meant to parallel the capabilities and configurability of
NVME-namespaces.
@ -786,7 +786,7 @@ Why the Term "namespace"?
LIBNVDIMM/LIBNDCTL: Block Translation Table "btt"
-------------------------------------------------
A BTT (design document: http://pmem.io/2014/09/23/btt.html) is a stacked
A BTT (design document: https://pmem.io/2014/09/23/btt.html) is a stacked
block device driver that fronts either the whole block device or a
partition of a block device emitted by either a PMEM or BLK NAMESPACE.

Some files were not shown because too many files have changed in this diff Show More