diff options
75 files changed, 1015 insertions, 403 deletions
@@ -151,6 +151,7 @@ Mark Brown <broonie@sirena.org.uk> Mark Yao <markyao0591@gmail.com> <mark.yao@rock-chips.com> Martin Kepplinger <martink@posteo.de> <martin.kepplinger@theobroma-systems.com> Martin Kepplinger <martink@posteo.de> <martin.kepplinger@ginzinger.com> +Martin Kepplinger <martink@posteo.de> <martin.kepplinger@puri.sm> Mathieu Othacehe <m.othacehe@gmail.com> Matthew Wilcox <willy@infradead.org> <matthew.r.wilcox@intel.com> Matthew Wilcox <willy@infradead.org> <matthew@wil.cx> @@ -1875,8 +1875,9 @@ S: The Netherlands N: Martin Kepplinger E: martink@posteo.de -E: martin.kepplinger@ginzinger.com +E: martin.kepplinger@puri.sm W: http://www.martinkepplinger.com +P: 4096R/5AB387D3 F208 2B88 0F9E 4239 3468 6E3F 5003 98DF 5AB3 87D3 D: mma8452 accelerators iio driver D: pegasus_notetaker input driver D: Kernel fixes and cleanups diff --git a/Documentation/Makefile b/Documentation/Makefile index e145e4db508b..ce8eb63b523a 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -13,7 +13,7 @@ endif SPHINXBUILD = sphinx-build SPHINXOPTS = SPHINXDIRS = . -_SPHINXDIRS = $(patsubst $(srctree)/Documentation/%/conf.py,%,$(wildcard $(srctree)/Documentation/*/conf.py)) +_SPHINXDIRS = $(patsubst $(srctree)/Documentation/%/index.rst,%,$(wildcard $(srctree)/Documentation/*/index.rst)) SPHINX_CONF = conf.py PAPER = BUILDDIR = $(obj)/output @@ -33,7 +33,7 @@ ifeq ($(HAVE_SPHINX),0) else # HAVE_SPHINX -export SPHINXOPTS = $(shell perl -e 'open IN,"sphinx-build --version 2>&1 |"; while (<IN>) { if (m/([\d\.]+)/) { print "-jauto" if ($$1 >= "1.7") } ;} close IN') +export SPHINX_PARALLEL = $(shell perl -e 'open IN,"sphinx-build --version 2>&1 |"; while (<IN>) { if (m/([\d\.]+)/) { print "auto" if ($$1 >= "1.7") } ;} close IN') # User-friendly check for pdflatex and latexmk HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else echo 0; fi) @@ -68,6 +68,7 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) PYTHONDONTWRITEBYTECODE=1 \ BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \ $(SPHINXBUILD) \ + -j $(shell python $(srctree)/scripts/jobserver-count $(SPHINX_PARALLEL)) \ -b $2 \ -c $(abspath $(srctree)/$(src)) \ -d $(abspath $(BUILDDIR)/.doctrees/$3) \ diff --git a/Documentation/admin-guide/LSM/SafeSetID.rst b/Documentation/admin-guide/LSM/SafeSetID.rst index 212434ef65ad..7bff07ce4fdd 100644 --- a/Documentation/admin-guide/LSM/SafeSetID.rst +++ b/Documentation/admin-guide/LSM/SafeSetID.rst @@ -56,7 +56,7 @@ setid capabilities from the application completely and refactor the process spawning semantics in the application (e.g. by using a privileged helper program to do process spawning and UID/GID transitions). Unfortunately, there are a number of semantics around process spawning that would be affected by this, such -as fork() calls where the program doesn???t immediately call exec() after the +as fork() calls where the program doesn't immediately call exec() after the fork(), parent processes specifying custom environment variables or command line args for spawned child processes, or inheritance of file handles across a fork()/exec(). Because of this, as solution that uses a privileged helper in @@ -72,7 +72,7 @@ own user namespace, and only approved UIDs/GIDs could be mapped back to the initial system user namespace, affectively preventing privilege escalation. Unfortunately, it is not generally feasible to use user namespaces in isolation, without pairing them with other namespace types, which is not always an option. -Linux checks for capabilities based off of the user namespace that ???owns??? some +Linux checks for capabilities based off of the user namespace that "owns" some entity. For example, Linux has the notion that network namespaces are owned by the user namespace in which they were created. A consequence of this is that capability checks for access to a given network namespace are done by checking diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst index 5361ebec3361..ed9123155e03 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -1120,8 +1120,9 @@ PAGE_SIZE multiple when read back. Best-effort memory protection. If the memory usage of a cgroup is within its effective low boundary, the cgroup's - memory won't be reclaimed unless memory can be reclaimed - from unprotected cgroups. Above the effective low boundary (or + memory won't be reclaimed unless there is no reclaimable + memory available in unprotected cgroups. + Above the effective low boundary (or effective min boundary if it is higher), pages are reclaimed proportionally to the overage, reducing reclaim pressure for smaller overages. @@ -1920,7 +1921,7 @@ Cpuset Interface Files It accepts only the following input values when written to. - "root" - a paritition root + "root" - a partition root "member" - a non-root member of a partition When set to be a partition root, the current cgroup is the diff --git a/Documentation/driver-api/dell_rbu.rst b/Documentation/admin-guide/dell_rbu.rst index 5d1ce7bcd04d..085ea129e6ca 100644 --- a/Documentation/driver-api/dell_rbu.rst +++ b/Documentation/admin-guide/dell_rbu.rst @@ -1,11 +1,11 @@ -============================================================= -Usage of the new open sourced rbu (Remote BIOS Update) driver -============================================================= +=========================================
+Dell Remote BIOS Update driver (dell_rbu)
+=========================================
Purpose ======= -Document demonstrating the use of the Dell Remote BIOS Update driver. +Document demonstrating the use of the Dell Remote BIOS Update driver for updating BIOS images on Dell servers and desktops. Scope @@ -37,7 +37,7 @@ maintains a link list of packets for reading them back. If the dell_rbu driver is unloaded all the allocated memory is freed. -The rbu driver needs to have an application (as mentioned above)which will +The rbu driver needs to have an application (as mentioned above) which will inform the BIOS to enable the update in the next system reboot. The user should not unload the rbu driver after downloading the BIOS image @@ -71,7 +71,7 @@ be downloaded. It is done as below:: echo XXXX > /sys/devices/platform/dell_rbu/packet_size In the packet update mechanism, the user needs to create a new file having -packets of data arranged back to back. It can be done as follows +packets of data arranged back to back. It can be done as follows: The user creates packets header, gets the chunk of the BIOS image and places it next to the packetheader; now, the packetheader + BIOS image chunk added together should match the specified packet_size. This makes one @@ -114,7 +114,7 @@ The entries can be recreated by doing the following:: echo init > /sys/devices/platform/dell_rbu/image_type -.. note:: echoing init in image_type does not change it original value. +.. note:: echoing init in image_type does not change its original value. Also the driver provides /sys/devices/platform/dell_rbu/data readonly file to read back the image downloaded. diff --git a/Documentation/admin-guide/device-mapper/dm-dust.txt b/Documentation/admin-guide/device-mapper/dm-dust.rst index 954d402a1f6a..b6e7e7ead831 100644 --- a/Documentation/admin-guide/device-mapper/dm-dust.txt +++ b/Documentation/admin-guide/device-mapper/dm-dust.rst @@ -31,218 +31,233 @@ configured "bad blocks" will be treated as bad, or bypassed. This allows the pre-writing of test data and metadata prior to simulating a "failure" event where bad sectors start to appear. -Table parameters: ------------------ +Table parameters +---------------- <device_path> <offset> <blksz> Mandatory parameters: - <device_path>: path to the block device. - <offset>: offset to data area from start of device_path - <blksz>: block size in bytes + <device_path>: + Path to the block device. + + <offset>: + Offset to data area from start of device_path + + <blksz>: + Block size in bytes + (minimum 512, maximum 1073741824, must be a power of 2) -Usage instructions: -------------------- +Usage instructions +------------------ -First, find the size (in 512-byte sectors) of the device to be used: +First, find the size (in 512-byte sectors) of the device to be used:: -$ sudo blockdev --getsz /dev/vdb1 -33552384 + $ sudo blockdev --getsz /dev/vdb1 + 33552384 Create the dm-dust device: (For a device with a block size of 512 bytes) -$ sudo dmsetup create dust1 --table '0 33552384 dust /dev/vdb1 0 512' + +:: + + $ sudo dmsetup create dust1 --table '0 33552384 dust /dev/vdb1 0 512' (For a device with a block size of 4096 bytes) -$ sudo dmsetup create dust1 --table '0 33552384 dust /dev/vdb1 0 4096' + +:: + + $ sudo dmsetup create dust1 --table '0 33552384 dust /dev/vdb1 0 4096' Check the status of the read behavior ("bypass" indicates that all I/O -will be passed through to the underlying device): -$ sudo dmsetup status dust1 -0 33552384 dust 252:17 bypass +will be passed through to the underlying device):: + + $ sudo dmsetup status dust1 + 0 33552384 dust 252:17 bypass -$ sudo dd if=/dev/mapper/dust1 of=/dev/null bs=512 count=128 iflag=direct -128+0 records in -128+0 records out + $ sudo dd if=/dev/mapper/dust1 of=/dev/null bs=512 count=128 iflag=direct + 128+0 records in + 128+0 records out -$ sudo dd if=/dev/zero of=/dev/mapper/dust1 bs=512 count=128 oflag=direct -128+0 records in -128+0 records out + $ sudo dd if=/dev/zero of=/dev/mapper/dust1 bs=512 count=128 oflag=direct + 128+0 records in + 128+0 records out -Adding and removing bad blocks: -------------------------------- +Adding and removing bad blocks +------------------------------ At any time (i.e.: whether the device has the "bad block" emulation enabled or disabled), bad blocks may be added or removed from the -device via the "addbadblock" and "removebadblock" messages: +device via the "addbadblock" and "removebadblock" messages:: -$ sudo dmsetup message dust1 0 addbadblock 60 -kernel: device-mapper: dust: badblock added at block 60 + $ sudo dmsetup message dust1 0 addbadblock 60 + kernel: device-mapper: dust: badblock added at block 60 -$ sudo dmsetup message dust1 0 addbadblock 67 -kernel: device-mapper: dust: badblock added at block 67 + $ sudo dmsetup message dust1 0 addbadblock 67 + kernel: device-mapper: dust: badblock added at block 67 -$ sudo dmsetup message dust1 0 addbadblock 72 -kernel: device-mapper: dust: badblock added at block 72 + $ sudo dmsetup message dust1 0 addbadblock 72 + kernel: device-mapper: dust: badblock added at block 72 These bad blocks will be stored in the "bad block list". -While the device is in "bypass" mode, reads and writes will succeed: +While the device is in "bypass" mode, reads and writes will succeed:: -$ sudo dmsetup status dust1 -0 33552384 dust 252:17 bypass + $ sudo dmsetup status dust1 + 0 33552384 dust 252:17 bypass -Enabling block read failures: ------------------------------ +Enabling block read failures +---------------------------- -To enable the "fail read on bad block" behavior, send the "enable" message: +To enable the "fail read on bad block" behavior, send the "enable" message:: -$ sudo dmsetup message dust1 0 enable -kernel: device-mapper: dust: enabling read failures on bad sectors + $ sudo dmsetup message dust1 0 enable + kernel: device-mapper: dust: enabling read failures on bad sectors -$ sudo dmsetup status dust1 -0 33552384 dust 252:17 fail_read_on_bad_block + $ sudo dmsetup status dust1 + 0 33552384 dust 252:17 fail_read_on_bad_block With the device in "fail read on bad block" mode, attempting to read a -block will encounter an "Input/output error": +block will encounter an "Input/output error":: -$ sudo dd if=/dev/mapper/dust1 of=/dev/null bs=512 count=1 skip=67 iflag=direct -dd: error reading '/dev/mapper/dust1': Input/output error -0+0 records in -0+0 records out -0 bytes copied, 0.00040651 s, 0.0 kB/s + $ sudo dd if=/dev/mapper/dust1 of=/dev/null bs=512 count=1 skip=67 iflag=direct + dd: error reading '/dev/mapper/dust1': Input/output error + 0+0 records in + 0+0 records out + 0 bytes copied, 0.00040651 s, 0.0 kB/s ...and writing to the bad blocks will remove the blocks from the list, -therefore emulating the "remap" behavior of hard disk drives: +therefore emulating the "remap" behavior of hard disk drives:: -$ sudo dd if=/dev/zero of=/dev/mapper/dust1 bs=512 count=128 oflag=direct -128+0 records in -128+0 records out + $ sudo dd if=/dev/zero of=/dev/mapper/dust1 bs=512 count=128 oflag=direct + 128+0 records in + 128+0 records out -kernel: device-mapper: dust: block 60 removed from badblocklist by write -kernel: device-mapper: dust: block 67 removed from badblocklist by write -kernel: device-mapper: dust: block 72 removed from badblocklist by write -kernel: device-mapper: dust: block 87 removed from badblocklist by write + kernel: device-mapper: dust: block 60 removed from badblocklist by write + kernel: device-mapper: dust: block 67 removed from badblocklist by write + kernel: device-mapper: dust: block 72 removed from badblocklist by write + kernel: device-mapper: dust: block 87 removed from badblocklist by write -Bad block add/remove error handling: ------------------------------------- +Bad block add/remove error handling +----------------------------------- Attempting to add a bad block that already exists in the list will -result in an "Invalid argument" error, as well as a helpful message: +result in an "Invalid argument" error, as well as a helpful message:: -$ sudo dmsetup message dust1 0 addbadblock 88 -device-mapper: message ioctl on dust1 failed: Invalid argument -kernel: device-mapper: dust: block 88 already in badblocklist + $ sudo dmsetup message dust1 0 addbadblock 88 + device-mapper: message ioctl on dust1 failed: Invalid argument + kernel: device-mapper: dust: block 88 already in badblocklist Attempting to remove a bad block that doesn't exist in the list will -result in an "Invalid argument" error, as well as a helpful message: +result in an "Invalid argument" error, as well as a helpful message:: -$ sudo dmsetup message dust1 0 removebadblock 87 -device-mapper: message ioctl on dust1 failed: Invalid argument -kernel: device-mapper: dust: block 87 not found in badblocklist + $ sudo dmsetup message dust1 0 removebadblock 87 + device-mapper: message ioctl on dust1 failed: Invalid argument + kernel: device-mapper: dust: block 87 not found in badblocklist -Counting the number of bad blocks in the bad block list: --------------------------------------------------------- +Counting the number of bad blocks in the bad block list +------------------------------------------------------- To count the number of bad blocks configured in the device, run the -following message command: +following message command:: -$ sudo dmsetup message dust1 0 countbadblocks + $ sudo dmsetup message dust1 0 countbadblocks A message will print with the number of bad blocks currently -configured on the device: +configured on the device:: -kernel: device-mapper: dust: countbadblocks: 895 badblock(s) found + kernel: device-mapper: dust: countbadblocks: 895 badblock(s) found -Querying for specific bad blocks: ---------------------------------- +Querying for specific bad blocks +-------------------------------- To find out if a specific block is in the bad block list, run the -following message command: +following message command:: -$ sudo dmsetup message dust1 0 queryblock 72 + $ sudo dmsetup message dust1 0 queryblock 72 -The following message will print if the block is in the list: -device-mapper: dust: queryblock: block 72 found in badblocklist +The following message will print if the block is in the list:: -The following message will print if the block is in the list: -device-mapper: dust: queryblock: block 72 not found in badblocklist + device-mapper: dust: queryblock: block 72 found in badblocklist + +The following message will print if the block is not in the list:: + + device-mapper: dust: queryblock: block 72 not found in badblocklist The "queryblock" message command will work in both the "enabled" and "disabled" modes, allowing the verification of whether a block will be treated as "bad" without having to issue I/O to the device, or having to "enable" the bad block emulation. -Clearing the bad block list: ----------------------------- +Clearing the bad block list +--------------------------- To clear the bad block list (without needing to individually run a "removebadblock" message command for every block), run the -following message command: +following message command:: -$ sudo dmsetup message dust1 0 clearbadblocks + $ sudo dmsetup message dust1 0 clearbadblocks -After clearing the bad block list, the following message will appear: +After clearing the bad block list, the following message will appear:: -kernel: device-mapper: dust: clearbadblocks: badblocks cleared + kernel: device-mapper: dust: clearbadblocks: badblocks cleared If there were no bad blocks to clear, the following message will -appear: +appear:: -kernel: device-mapper: dust: clearbadblocks: no badblocks found + kernel: device-mapper: dust: clearbadblocks: no badblocks found -Message commands list: ----------------------- +Message commands list +--------------------- Below is a list of the messages that can be sent to a dust device: -Operations on blocks (requires a <blknum> argument): +Operations on blocks (requires a <blknum> argument):: -addbadblock <blknum> -queryblock <blknum> -removebadblock <blknum> + addbadblock <blknum> + queryblock <blknum> + removebadblock <blknum> ...where <blknum> is a block number within range of the device - (corresponding to the block size of the device.) +(corresponding to the block size of the device.) -Single argument message commands: +Single argument message commands:: -countbadblocks -clearbadblocks -disable -enable -quiet + countbadblocks + clearbadblocks + disable + enable + quiet -Device removal: ---------------- +Device removal +-------------- -When finished, remove the device via the "dmsetup remove" command: +When finished, remove the device via the "dmsetup remove" command:: -$ sudo dmsetup remove dust1 + $ sudo dmsetup remove dust1 -Quiet mode: ------------ +Quiet mode +---------- On test runs with many bad blocks, it may be desirable to avoid excessive logging (from bad blocks added, removed, or "remapped"). -This can be done by enabling "quiet mode" via the following message: +This can be done by enabling "quiet mode" via the following message:: -$ sudo dmsetup message dust1 0 quiet + $ sudo dmsetup message dust1 0 quiet This will suppress log messages from add / remove / removed by write operations. Log messages from "countbadblocks" or "queryblock" message commands will still print in quiet mode. -The status of quiet mode can be seen by running "dmsetup status": +The status of quiet mode can be seen by running "dmsetup status":: -$ sudo dmsetup status dust1 -0 33552384 dust 252:17 fail_read_on_bad_block quiet + $ sudo dmsetup status dust1 + 0 33552384 dust 252:17 fail_read_on_bad_block quiet -To disable quiet mode, send the "quiet" message again: +To disable quiet mode, send the "quiet" message again:: -$ sudo dmsetup message dust1 0 quiet + $ sudo dmsetup message dust1 0 quiet -$ sudo dmsetup status dust1 -0 33552384 dust 252:17 fail_read_on_bad_block verbose + $ sudo dmsetup status dust1 + 0 33552384 dust 252:17 fail_read_on_bad_block verbose (The presence of "verbose" indicates normal logging.) diff --git a/Documentation/admin-guide/device-mapper/index.rst b/Documentation/admin-guide/device-mapper/index.rst index c77c58b8f67b..4872fb6d2952 100644 --- a/Documentation/admin-guide/device-mapper/index.rst +++ b/Documentation/admin-guide/device-mapper/index.rst @@ -9,6 +9,7 @@ Device Mapper cache delay dm-crypt + dm-dust dm-flakey dm-init dm-integrity diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 34cc20ee7f3a..4405b7485312 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -57,60 +57,61 @@ configure specific aspects of kernel behavior to your liking. .. toctree:: :maxdepth: 1 - initrd - cgroup-v2 - cgroup-v1/index - serial-console - braille-console - parport - md - module-signing - rapidio - sysrq - unicode - vga-softcursor - binfmt-misc - mono - java - ras - bcache - blockdev/index - ext4 - binderfs - cifs/index - xfs - jfs - ufs - pm/index - thunderbolt - LSM/index - mm/index - namespaces/index - perf-security acpi/index aoe/index + auxdisplay/index + bcache + binderfs + binfmt-misc + blockdev/index + braille-console btmrvl + cgroup-v1/index + cgroup-v2 + cifs/index clearing-warn-once cpu-load cputopology + dell_rbu device-mapper/index efi-stub + ext4 gpio/index highuid hw_random + initrd iostats + java + jfs kernel-per-CPU-kthreads laptops/index - auxdisplay/index lcd-panel-cgram ldm lockup-watchdogs + LSM/index + md + mm/index + module-signing + mono + namespaces/index numastat + parport + perf-security + pm/index pnp + rapidio + ras rtc + serial-console svga - wimax/index + sysrq + thunderbolt + ufs + unicode + vga-softcursor video-output + wimax/index + xfs .. only:: subproject and html diff --git a/Documentation/admin-guide/iostats.rst b/Documentation/admin-guide/iostats.rst index 5d63b18bd6d1..321aae8d7e10 100644 --- a/Documentation/admin-guide/iostats.rst +++ b/Documentation/admin-guide/iostats.rst @@ -46,78 +46,79 @@ each snapshot of your disk statistics. In 2.4, the statistics fields are those after the device name. In the above example, the first field of statistics would be 446216. By contrast, in 2.6+ if you look at ``/sys/block/hda/stat``, you'll -find just the eleven fields, beginning with 446216. If you look at -``/proc/diskstats``, the eleven fields will be preceded by the major and +find just the 15 fields, beginning with 446216. If you look at +``/proc/diskstats``, the 15 fields will be preceded by the major and minor device numbers, and device name. Each of these formats provides -eleven fields of statistics, each meaning exactly the same things. +15 fields of statistics, each meaning exactly the same things. All fields except field 9 are cumulative since boot. Field 9 should go to zero as I/Os complete; all others only increase (unless they -overflow and wrap). Yes, these are (32-bit or 64-bit) unsigned long -(native word size) numbers, and on a very busy or long-lived system they -may wrap. Applications should be prepared to deal with that; unless -your observations are measured in large numbers of minutes or hours, -they should not wrap twice before you notice them. +overflow and wrap). Wrapping might eventually occur on a very busy +or long-lived system; so applications should be prepared to deal with +it. Regarding wrapping, the types of the fields are either unsigned +int (32 bit) or unsigned long (32-bit or 64-bit, depending on your +machine) as noted per-field below. Unless your observations are very +spread in time, these fields should not wrap twice before you notice it. Each set of stats only applies to the indicated device; if you want system-wide stats you'll have to find all the devices and sum them all up. -Field 1 -- # of reads completed +Field 1 -- # of reads completed (unsigned long) This is the total number of reads completed successfully. -Field 2 -- # of reads merged, field 6 -- # of writes merged +Field 2 -- # of reads merged, field 6 -- # of writes merged (unsigned long) Reads and writes which are adjacent to each other may be merged for efficiency. Thus two 4K reads may become one 8K read before it is ultimately handed to the disk, and so it will be counted (and queued) as only one I/O. This field lets you know how often this was done. -Field 3 -- # of sectors read +Field 3 -- # of sectors read (unsigned long) This is the total number of sectors read successfully. -Field 4 -- # of milliseconds spent reading +Field 4 -- # of milliseconds spent reading (unsigned int) This is the total number of milliseconds spent by all reads (as measured from __make_request() to end_that_request_last()). -Field 5 -- # of writes completed +Field 5 -- # of writes completed (unsigned long) This is the total number of writes completed successfully. -Field 6 -- # of writes merged +Field 6 -- # of writes merged (unsigned long) See the description of field 2. -Field 7 -- # of sectors written +Field 7 -- # of sectors written (unsigned long) This is the total number of sectors written successfully. -Field 8 -- # of milliseconds spent writing +Field 8 -- # of milliseconds spent writing (unsigned int) This is the total number of milliseconds spent by all writes (as measured from __make_request() to end_that_request_last()). -Field 9 -- # of I/Os currently in progress +Field 9 -- # of I/Os currently in progress (unsigned int) The only field that should go to zero. Incremented as requests are given to appropriate struct request_queue and decremented as they finish. -Field 10 -- # of milliseconds spent doing I/Os +Field 10 -- # of milliseconds spent doing I/Os (unsigned int) This field increases so long as field 9 is nonzero. Since 5.0 this field counts jiffies when at least one request was started or completed. If request runs more than 2 jiffies then some I/O time will not be accounted unless there are other requests. -Field 11 -- weighted # of milliseconds spent doing I/Os +Field 11 -- weighted # of milliseconds spent doing I/Os (unsigned int) This field is incremented at each I/O start, I/O completion, I/O merge, or read of these stats by the number of I/Os in progress (field 9) times the number of milliseconds spent doing I/O since the last update of this field. This can provide an easy measure of both I/O completion time and the backlog that may be accumulating. -Field 12 -- # of discards completed +Field 12 -- # of discards completed (unsigned long) This is the total number of discards completed successfully. -Field 13 -- # of discards merged +Field 13 -- # of discards merged (unsigned long) See the description of field 2 -Field 14 -- # of sectors discarded +Field 14 -- # of sectors discarded (unsigned long) This is the total number of sectors discarded successfully. -Field 15 -- # of milliseconds spent discarding +Field 15 -- # of milliseconds spent discarding (unsigned int) This is the total number of milliseconds spent by all discards (as measured from __make_request() to end_that_request_last()). diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index a84a83f8881e..dfad762f89b7 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -983,12 +983,14 @@ earlycon= [KNL] Output early console device and options. - [ARM64] The early console is determined by the - stdout-path property in device tree's chosen node, - or determined by the ACPI SPCR table. - - [X86] When used with no options the early console is - determined by the ACPI SPCR table. + When used with no options, the early console is + determined by stdout-path property in device tree's + chosen node or the ACPI SPCR table if supported by + the platform. + + [RISCV] When used with no options, the early + console is determined by the stdout-path + property in the device tree's chosen node. cdns,<addr>[,options] Start an early, polled-mode console on a Cadence diff --git a/Documentation/admin-guide/perf/imx-ddr.rst b/Documentation/admin-guide/perf/imx-ddr.rst index 517a205abad6..92900b851f5d 100644 --- a/Documentation/admin-guide/perf/imx-ddr.rst +++ b/Documentation/admin-guide/perf/imx-ddr.rst @@ -18,7 +18,9 @@ The "format" directory describes format of the config (event ID) and config1 devices/imx8_ddr0/format/. The "events" directory describes the events types hardware supported that can be used with perf tool, see /sys/bus/event_source/ devices/imx8_ddr0/events/. - e.g.:: + + .. code-block:: bash + perf stat -a -e imx8_ddr0/cycles/ cmd perf stat -a -e imx8_ddr0/read/,imx8_ddr0/write/ cmd @@ -31,22 +33,29 @@ in the driver. Filter is defined with two configuration parts: --AXI_ID defines AxID matching value. --AXI_MASKING defines which bits of AxID are meaningful for the matching. - 0：corresponding bit is masked. - 1: corresponding bit is not masked, i.e. used to do the matching. + + - 0: corresponding bit is masked. + - 1: corresponding bit is not masked, i.e. used to do the matching. AXI_ID and AXI_MASKING are mapped on DPCR1 register in performance counter. When non-masked bits are matching corresponding AXI_ID bits then counter is incremented. Perf counter is incremented if - AxID && AXI_MASKING == AXI_ID && AXI_MASKING + AxID && AXI_MASKING == AXI_ID && AXI_MASKING This filter doesn't support filter different AXI ID for axid-read and axid-write event at the same time as this filter is shared between counters. - e.g.:: - perf stat -a -e imx8_ddr0/axid-read,axi_mask=0xMMMM,axi_id=0xDDDD/ cmd - perf stat -a -e imx8_ddr0/axid-write,axi_mask=0xMMMM,axi_id=0xDDDD/ cmd - - NOTE: axi_mask is inverted in userspace(i.e. set bits are bits to mask), and - it will be reverted in driver automatically. so that the user can just specify - axi_id to monitor a specific id, rather than having to specify axi_mask. - e.g.:: - perf stat -a -e imx8_ddr0/axid-read,axi_id=0x12/ cmd, which will monitor ARID=0x12 + + .. code-block:: bash + + perf stat -a -e imx8_ddr0/axid-read,axi_mask=0xMMMM,axi_id=0xDDDD/ cmd + perf stat -a -e imx8_ddr0/axid-write,axi_mask=0xMMMM,axi_id=0xDDDD/ cmd + + .. note:: + + axi_mask is inverted in userspace(i.e. set bits are bits to mask), and + it will be reverted in driver automatically. so that the user can just specify + axi_id to monitor a specific id, rather than having to specify axi_mask. + + .. code-block:: bash + + perf stat -a -e imx8_ddr0/axid-read,axi_id=0x12/ cmd, which will monitor ARID=0x12 diff --git a/Documentation/admin-guide/perf/index.rst b/Documentation/admin-guide/perf/index.rst index ee4bfd2a740f..47c99f40cc16 100644 --- a/Documentation/admin-guide/perf/index.rst +++ b/Documentation/admin-guide/perf/index.rst @@ -8,6 +8,7 @@ Performance monitor support :maxdepth: 1 hisi-pmu + imx-ddr qcom_l2_pmu qcom_l3_pmu arm-ccn diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst index 032c7cd3cede..6e0da29e55f1 100644 --- a/Documentation/admin-guide/sysctl/kernel.rst +++ b/Documentation/admin-guide/sysctl/kernel.rst @@ -831,8 +831,8 @@ printk_ratelimit: ================= Some warning messages are rate limited. printk_ratelimit specifies -the minimum length of time between these messages (in jiffies), by -default we allow one every 5 seconds. +the minimum length of time between these messages (in seconds). +The default value is 5 seconds. A value of 0 will disable rate limiting. @@ -845,6 +845,8 @@ seconds, we do allow a burst of messages to pass through. printk_ratelimit_burst specifies the number of messages we can send before ratelimiting kicks in. +The default value is 10 messages. + printk_devkmsg: =============== diff --git a/Documentation/conf.py b/Documentation/conf.py index a8fe845832bc..3c7bdf4cd31f 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -37,7 +37,8 @@ needs_sphinx = '1.3' # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', - 'kfigure', 'sphinx.ext.ifconfig', 'automarkup'] + 'kfigure', 'sphinx.ext.ifconfig', 'automarkup', + 'maintainers_include'] # The name of the math extension changed on Sphinx 1.4 if (major == 1 and minor > 3) or (major > 1): diff --git a/Documentation/core-api/genalloc.rst b/Documentation/core-api/genalloc.rst index 6b38a39fab24..098a46f55798 100644 --- a/Documentation/core-api/genalloc.rst +++ b/Documentation/core-api/genalloc.rst @@ -23,7 +23,7 @@ begins with the creation of a pool using one of: .. kernel-doc:: lib/genalloc.c :functions: devm_gen_pool_create -A call to :c:func:`gen_pool_create` will create a pool. The granularity of +A call to gen_pool_create() will create a pool. The granularity of allocations is set with min_alloc_order; it is a log-base-2 number like those used by the page allocator, but it refers to bytes rather than pages. So, if min_alloc_order is passed as 3, then all allocations will be a @@ -32,7 +32,7 @@ required to track the memory in the pool. The nid parameter specifies which NUMA node should be used for the allocation of the housekeeping structures; it can be -1 if the caller doesn't care. -The "managed" interface :c:func:`devm_gen_pool_create` ties the pool to a +The "managed" interface devm_gen_pool_create() ties the pool to a specific device. Among other things, it will automatically clean up the pool when the given device is destroyed. @@ -53,32 +53,32 @@ to the pool. That can be done with one of: :functions: gen_pool_add .. kernel-doc:: lib/genalloc.c - :functions: gen_pool_add_virt + :functions: gen_pool_add_owner -A call to :c:func:`gen_pool_add` will place the size bytes of memory +A call to gen_pool_add() will place the size bytes of memory starting at addr (in the kernel's virtual address space) into the given pool, once again using nid as the node ID for ancillary memory allocations. -The :c:func:`gen_pool_add_virt` variant associates an explicit physical +The gen_pool_add_virt() variant associates an explicit physical address with the memory; this is only necessary if the pool will be used for DMA allocations. The functions for allocating memory from the pool (and putting it back) are: -.. kernel-doc:: lib/genalloc.c +.. kernel-doc:: include/linux/genalloc.h :functions: gen_pool_alloc .. kernel-doc:: lib/genalloc.c :functions: gen_pool_dma_alloc .. kernel-doc:: lib/genalloc.c - :functions: gen_pool_free + :functions: gen_pool_free_owner -As one would expect, :c:func:`gen_pool_alloc` will allocate size< bytes -from the given pool. The :c:func:`gen_pool_dma_alloc` variant allocates +As one would expect, gen_pool_alloc() will allocate size< bytes +from the given pool. The gen_pool_dma_alloc() variant allocates memory for use with DMA operations, returning the associated physical address in the space pointed to by dma. This will only work if the memory -was added with :c:func:`gen_pool_add_virt`. Note that this function +was added with gen_pool_add_virt(). Note that this function departs from the usual genpool pattern of using unsigned long values to represent kernel addresses; it returns a void * instead. @@ -89,14 +89,14 @@ return. If that sort of control is needed, the following functions will be of interest: .. kernel-doc:: lib/genalloc.c - :functions: gen_pool_alloc_algo + :functions: gen_pool_alloc_algo_owner .. kernel-doc:: lib/genalloc.c :functions: gen_pool_set_algo -Allocations with :c:func:`gen_pool_alloc_algo` specify an algorithm to be +Allocations with gen_pool_alloc_algo() specify an algorithm to be used to choose the memory to be allocated; the default algorithm can be set -with :c:func:`gen_pool_set_algo`. The data value is passed to the +with gen_pool_set_algo(). The data value is passed to the algorithm; most ignore it, but it is occasionally needed. One can, naturally, write a special-purpose algorithm, but there is a fair set already available: diff --git a/Documentation/core-api/genericirq.rst b/Documentation/core-api/genericirq.rst index 4da67b65cecf..2e6c99e3ce3b 100644 --- a/Documentation/core-api/genericirq.rst +++ b/Documentation/core-api/genericirq.rst @@ -26,7 +26,7 @@ Rationale ========= The original implementation of interrupt handling in Linux uses the -:c:func:`__do_IRQ` super-handler, which is able to deal with every type of +__do_IRQ() super-handler, which is able to deal with every type of interrupt logic. Originally, Russell King identified different types of handlers to build @@ -43,7 +43,7 @@ During the implementation we identified another type: - Fast EOI type -In the SMP world of the :c:func:`__do_IRQ` super-handler another type was +In the SMP world of the __do_IRQ() super-handler another type was identified: - Per CPU type @@ -83,7 +83,7 @@ IRQ-flow implementation for 'level type' interrupts and add a (sub)architecture specific 'edge type' implementation. To make the transition to the new model easier and prevent the breakage -of existing implementations, the :c:func:`__do_IRQ` super-handler is still +of existing implementations, the __do_IRQ() super-handler is still available. This leads to a kind of duality for the time being. Over time the new model should be used in more and more architectures, as it enables smaller and cleaner IRQ subsystems. It's deprecated for three @@ -116,7 +116,7 @@ status information and pointers to the interrupt flow method and the interrupt chip structure which are assigned to this interrupt. Whenever an interrupt triggers, the low-level architecture code calls -into the generic interrupt code by calling :c:func:`desc->handle_irq`. This +into the generic interrupt code by calling desc->handle_irq(). This high-level IRQ handling function only uses desc->irq_data.chip primitives referenced by the assigned chip descriptor structure. @@ -125,27 +125,27 @@ High-level Driver API The high-level Driver API consists of following functions: -- :c:func:`request_irq` +- request_irq() -- :c:func:`free_irq` +- free_irq() -- :c:func:`disable_irq` +- disable_irq() -- :c:func:`enable_irq` +- enable_irq() -- :c:func:`disable_irq_nosync` (SMP only) +- disable_irq_nosync() (SMP only) -- :c:func:`synchronize_irq` (SMP only) +- synchronize_irq() (SMP only) -- :c:func:`irq_set_irq_type` +- irq_set_irq_type() -- :c:func:`irq_set_irq_wake` +- irq_set_irq_wake() -- :c:func:`irq_set_handler_data` +- irq_set_handler_data() -- :c:func:`irq_set_chip` +- irq_set_chip() -- :c:func:`irq_set_chip_data` +- irq_set_chip_data() See the autogenerated function documentation for details. @@ -154,19 +154,19 @@ High-level IRQ flow handlers The generic layer provides a set of pre-defined irq-flow methods: -- :c:func:`handle_level_irq` +- handle_level_irq() -- :c:func:`handle_edge_irq` +- handle_edge_irq() -- :c:func:`handle_fasteoi_irq` +- handle_fasteoi_irq() -- :c:func:`handle_simple_irq` +- handle_simple_irq() -- :c:func:`handle_percpu_irq` +- handle_percpu_irq() -- :c:func:`handle_edge_eoi_irq` +- handle_edge_eoi_irq() -- :c:func:`handle_bad_irq` +- handle_bad_irq() The interrupt flow handlers (either pre-defined or architecture specific) are assigned to specific interrupts by the architecture either @@ -325,14 +325,14 @@ Delayed interrupt disable This per interrupt selectable feature, which was introduced by Russell King in the ARM interrupt implementation, does not mask an interrupt at -the hardware level when :c:func:`disable_irq` is called. The interrupt is kept +the hardware level when disable_irq() is called. The interrupt is kept enabled and is masked in the flow handler when an interrupt event happens. This prevents losing edge interrupts on hardware which does not store an edge interrupt event while the interrupt is disabled at the hardware level. When an interrupt arrives while the IRQ_DISABLED flag is set, then the interrupt is masked at the hardware level and the IRQ_PENDING bit is set. When the interrupt is re-enabled by -:c:func:`enable_irq` the pending bit is checked and if it is set, the interrupt +enable_irq() the pending bit is checked and if it is set, the interrupt is resent either via hardware or by a software resend mechanism. (It's necessary to enable CONFIG_HARDIRQS_SW_RESEND when you want to use the delayed interrupt disable feature and your hardware is not capable @@ -369,7 +369,7 @@ handler(s) to use these basic units of low-level functionality. __do_IRQ entry point ==================== -The original implementation :c:func:`__do_IRQ` was an alternative entry point +The original implementation __do_IRQ() was an alternative entry point for all types of interrupts. It no longer exists. This handler turned out to be not suitable for all interrupt hardware diff --git a/Documentation/core-api/mm-api.rst b/Documentation/core-api/mm-api.rst index 128e8a721c1e..be726986ff75 100644 --- a/Documentation/core-api/mm-api.rst +++ b/Documentation/core-api/mm-api.rst @@ -11,7 +11,7 @@ User Space Memory Access .. kernel-doc:: arch/x86/lib/usercopy_32.c :export: -.. kernel-doc:: mm/util.c +.. kernel-doc:: mm/gup.c :functions: get_user_pages_fast .. _mm-api-gfp-flags: diff --git a/Documentation/core-api/refcount-vs-atomic.rst b/Documentation/core-api/refcount-vs-atomic.rst index 976e85adffe8..79a009ce11df 100644 --- a/Documentation/core-api/refcount-vs-atomic.rst +++ b/Documentation/core-api/refcount-vs-atomic.rst @@ -35,7 +35,7 @@ atomics & refcounters only provide atomicity and program order (po) relation (on the same CPU). It guarantees that each ``atomic_*()`` and ``refcount_*()`` operation is atomic and instructions are executed in program order on a single CPU. -This is implemented using :c:func:`READ_ONCE`/:c:func:`WRITE_ONCE` and +This is implemented using READ_ONCE()/WRITE_ONCE() and compare-and-swap primitives. A strong (full) memory ordering guarantees that all prior loads and @@ -44,7 +44,7 @@ before any po-later instruction is executed on the same CPU. It also guarantees that all po-earlier stores on the same CPU and all propagated stores from other CPUs must propagate to all other CPUs before any po-later instruction is executed on the original -CPU (A-cumulative property). This is implemented using :c:func:`smp_mb`. +CPU (A-cumulative property). This is implemented using smp_mb(). A RELEASE memory ordering guarantees that all prior loads and stores (all po-earlier instructions) on the same CPU are completed @@ -52,14 +52,14 @@ before the operation. It also guarantees that all po-earlier stores on the same CPU and all propagated stores from other CPUs must propagate to all other CPUs before the release operation (A-cumulative property). This is implemented using -:c:func:`smp_store_release`. +smp_store_release(). An ACQUIRE memory ordering guarantees that all post loads and stores (all po-later instructions) on the same CPU are completed after the acquire operation. It also guarantees that all po-later stores on the same CPU must propagate to all other CPUs after the acquire operation executes. This is implemented using -:c:func:`smp_acquire__after_ctrl_dep`. +smp_acquire__after_ctrl_dep(). A control dependency (on success) for refcounters guarantees that if a reference for an object was successfully obtained (reference @@ -78,8 +78,8 @@ case 1) - non-"Read/Modify/Write" (RMW) ops Function changes: - * :c:func:`atomic_set` --> :c:func:`refcount_set` - * :c:func:`atomic_read` --> :c:func:`refcount_read` + * atomic_set() --> refcount_set() + * atomic_read() --> refcount_read() Memory ordering guarantee changes: @@ -91,8 +91,8 @@ case 2) - increment-based ops that return no value Function changes: - * :c:func:`atomic_inc` --> :c:func:`refcount_inc` - * :c:func:`atomic_add` --> :c:func:`refcount_add` + * atomic_inc() --> refcount_inc() + * atomic_add() --> refcount_add() Memory ordering guarantee changes: @@ -103,7 +103,7 @@ case 3) - decrement-based RMW ops that return no value Function changes: - * :c:func:`atomic_dec` --> :c:func:`refcount_dec` + * atomic_dec() --> refcount_dec() Memory ordering guarantee changes: @@ -115,8 +115,8 @@ case 4) - increment-based RMW ops that return a value Function changes: - * :c:func:`atomic_inc_not_zero` --> :c:func:`refcount_inc_not_zero` - * no atomic counterpart --> :c:func:`refcount_add_not_zero` + * atomic_inc_not_zero() --> refcount_inc_not_zero() + * no atomic counterpart --> refcount_add_not_zero() Memory ordering guarantees changes: @@ -131,8 +131,8 @@ case 5) - generic dec/sub decrement-based RMW ops that return a value Function changes: - * :c:func:`atomic_dec_and_test` --> :c:func:`refcount_dec_and_test` - * :c:func:`atomic_sub_and_test` --> :c:func:`refcount_sub_and_test` + * atomic_dec_and_test() --> refcount_dec_and_test() + * atomic_sub_and_test() --> refcount_sub_and_test() Memory ordering guarantees changes: @@ -144,14 +144,14 @@ case 6) other decrement-based RMW ops that return a value Function changes: - * no atomic counterpart --> :c:func:`refcount_dec_if_one` + * no atomic counterpart --> refcount_dec_if_one() * ``atomic_add_unless(&var, -1, 1)`` --> ``refcount_dec_not_one(&var)`` Memory ordering guarantees changes: * fully ordered --> RELEASE ordering + control dependency -.. note:: :c:func:`atomic_add_unless` only provides full order on success. +.. note:: atomic_add_unless() only provides full order on success. case 7) - lock-based RMW @@ -159,10 +159,10 @@ case 7) - lock-based RMW Function changes: - * :c:func:`atomic_dec_and_lock` --> :c:func:`refcount_dec_and_lock` - * :c:func:`atomic_dec_and_mutex_lock` --> :c:func:`refcount_dec_and_mutex_lock` + * atomic_dec_and_lock() --> refcount_dec_and_lock() + * atomic_dec_and_mutex_lock() --> refcount_dec_and_mutex_lock() Memory ordering guarantees changes: * fully ordered --> RELEASE ordering + control dependency + hold - :c:func:`spin_lock` on success + spin_lock() on success diff --git a/Documentation/dev-tools/kmemleak.rst b/Documentation/dev-tools/kmemleak.rst index 3621cd5e1eef..3a289e8a1d12 100644 --- a/Documentation/dev-tools/kmemleak.rst +++ b/Documentation/dev-tools/kmemleak.rst @@ -69,7 +69,7 @@ the kernel command line. Memory may be allocated or freed before kmemleak is initialised and these actions are stored in an early log buffer. The size of this buffer -is configured via the CONFIG_DEBUG_KMEMLEAK_EARLY_LOG_SIZE option. +is configured via the CONFIG_DEBUG_KMEMLEAK_MEM_POOL_SIZE option. If CONFIG_DEBUG_KMEMLEAK_DEFAULT_OFF are enabled, the kmemleak is disabled by default. Passing ``kmemleak=on`` on the kernel command diff --git a/Documentation/devicetree/bindings/cpu/cpu-topology.txt b/Documentation/devicetree/bindings/cpu/cpu-topology.txt index 99918189403c..9bd530a35d14 100644 --- a/Documentation/devicetree/bindings/cpu/cpu-topology.txt +++ b/Documentation/devicetree/bindings/cpu/cpu-topology.txt @@ -549,5 +549,5 @@ Example 3: HiFive Unleashed (RISC-V 64 bit, 4 core system) [2] Devicetree NUMA binding description Documentation/devicetree/bindings/numa.txt [3] RISC-V Linux kernel documentation - Documentation/devicetree/bindings/riscv/cpus.txt + Documentation/devicetree/bindings/riscv/cpus.yaml [4] https://www.devicetree.org/specifications/ diff --git a/Documentation/devicetree/bindings/timer/ingenic,tcu.txt b/Documentation/devicetree/bindings/timer/ingenic,tcu.txt index 5a4b9ddd9470..7f6fe20503f5 100644 --- a/Documentation/devicetree/bindings/timer/ingenic,tcu.txt +++ b/Documentation/devicetree/bindings/timer/ingenic,tcu.txt @@ -2,7 +2,7 @@ Ingenic JZ47xx SoCs Timer/Counter Unit devicetree bindings ========================================================== For a description of the TCU hardware and drivers, have a look at -Documentation/mips/ingenic-tcu.txt. +Documentation/mips/ingenic-tcu.rst. Required properties: diff --git a/Documentation/driver-api/dma-buf.rst b/Documentation/driver-api/dma-buf.rst index b541e97c7ab1..c78db28519f7 100644 --- a/Documentation/driver-api/dma-buf.rst +++ b/Documentation/driver-api/dma-buf.rst @@ -118,13 +118,13 @@ Kernel Functions and Structures Reference Reservation Objects ------------------- -.. kernel-doc:: drivers/dma-buf/reservation.c +.. kernel-doc:: drivers/dma-buf/dma-resv.c :doc: Reservation Object Overview -.. kernel-doc:: drivers/dma-buf/reservation.c +.. kernel-doc:: drivers/dma-buf/dma-resv.c :export: -.. kernel-doc:: include/linux/reservation.h +.. kernel-doc:: include/linux/dma-resv.h :internal: DMA Fences diff --git a/Documentation/driver-api/gpio/driver.rst b/Documentation/driver-api/gpio/driver.rst index 3fdb32422f8a..9076cc76d5bf 100644 --- a/Documentation/driver-api/gpio/driver.rst +++ b/Documentation/driver-api/gpio/driver.rst @@ -493,7 +493,7 @@ available but we try to move away from this: gpiochip. It will pass the struct gpio_chip* for the chip to all IRQ callbacks, so the callbacks need to embed the gpio_chip in its state container and obtain a pointer to the container using container_of(). - (See Documentation/driver-model/design-patterns.txt) + (See Documentation/driver-api/driver-model/design-patterns.rst) - gpiochip_irqchip_add_nested(): adds a nested cascaded irqchip to a gpiochip, as discussed above regarding different types of cascaded irqchips. The diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index 38e638abe3eb..46d6a165b5a5 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -73,7 +73,6 @@ available subsections can be seen below. connector console dcdbas - dell_rbu edid eisa ipmb @@ -93,7 +92,6 @@ available subsections can be seen below. pwm rfkill serial/index - sgi-ioc4 sm501 smsc_ece1099 switchtec diff --git a/Documentation/driver-api/infrastructure.rst b/Documentation/driver-api/infrastructure.rst index 6172f3cc3d0b..06d98c4526df 100644 --- a/Documentation/driver-api/infrastructure.rst +++ b/Documentation/driver-api/infrastructure.rst @@ -49,9 +49,6 @@ Device Drivers Base Device Drivers DMA Management ----------------------------- -.. kernel-doc:: kernel/dma/coherent.c - :export: - .. kernel-doc:: kernel/dma/mapping.c :export: diff --git a/Documentation/driver-api/pti_intel_mid.rst b/Documentation/driver-api/pti_intel_mid.rst index 20f1cff42d5f..bacc2a4ee89f 100644 --- a/Documentation/driver-api/pti_intel_mid.rst +++ b/Documentation/driver-api/pti_intel_mid.rst @@ -49,7 +49,9 @@ but is not just blindly executing as 'root'. Keep in mind the use of ioctl(,TIOCSETD,) is not specific to the n_tracerouter and n_tracesink line discpline drivers but is a generic operation for a program to use a line discpline driver -on a tty port other than the default n_tty:: +on a tty port other than the default n_tty: + +.. code-block:: c /////////// To hook up n_tracerouter and n_tracesink ///////// diff --git a/Documentation/filesystems/debugfs.txt b/Documentation/filesystems/debugfs.txt index 9e27c843d00e..2ca99152cb6e 100644 --- a/Documentation/filesystems/debugfs.txt +++ b/Documentation/filesystems/debugfs.txt @@ -93,8 +93,8 @@ the following functions can be used instead: These functions are useful as long as the developer knows the size of the value to be exported. Some types can have different widths on different -architectures, though, complicating the situation somewhat. There is a -function meant to help out in one special case: +architectures, though, complicating the situation somewhat. There are +functions meant to help out in such special cases: struct dentry *debugfs_create_size_t(const char *name, umode_t mode, struct dentry *parent, @@ -103,6 +103,12 @@ function meant to help out in one special case: As might be expected, this function will create a debugfs file to represent a variable of type size_t. +Similarly, there is a helper for variables of type unsigned long: + + struct dentry *debugfs_create_ulong(const char *name, umode_t mode, + struct dentry *parent, + unsigned long *value); + Boolean values can be placed in debugfs with: struct dentry *debugfs_create_bool(const char *name, umode_t mode, diff --git a/Documentation/hwmon/inspur-ipsps1.rst b/Documentation/hwmon/inspur-ipsps1.rst index 292c0c26bdd1..4825046ecb25 100644 --- a/Documentation/hwmon/inspur-ipsps1.rst +++ b/Documentation/hwmon/inspur-ipsps1.rst @@ -17,7 +17,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. Sysfs entries diff --git a/Documentation/i2c/busses/index.rst b/Documentation/i2c/busses/index.rst index 97ca4d510816..2a26e251a335 100644 --- a/Documentation/i2c/busses/index.rst +++ b/Documentation/i2c/busses/index.rst @@ -1,4 +1,4 @@ -. SPDX-License-Identifier: GPL-2.0 +.. SPDX-License-Identifier: GPL-2.0 =============== I2C Bus Drivers diff --git a/Documentation/i2c/index.rst b/Documentation/i2c/index.rst index cd8d020f7ac5..a0fbaf6d0675 100644 --- a/Documentation/i2c/index.rst +++ b/Documentation/i2c/index.rst @@ -1,4 +1,4 @@ -. SPDX-License-Identifier: GPL-2.0 +.. SPDX-License-Identifier: GPL-2.0 =================== I2C/SMBus Subsystem diff --git a/Documentation/index.rst b/Documentation/index.rst index b843e313d2f2..dbf0951a0abe 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -57,7 +57,6 @@ the kernel interface as seen by application developers. :maxdepth: 2 userspace-api/index - ioctl/index Introduction to kernel development diff --git a/Documentation/mips/ingenic-tcu.rst b/Documentation/mips/ingenic-tcu.rst index c4ef4c45aade..c5a646b14450 100644 --- a/Documentation/mips/ingenic-tcu.rst +++ b/Documentation/mips/ingenic-tcu.rst @@ -68,4 +68,4 @@ and frameworks can be controlled from the same registers, all of these drivers access their registers through the same regmap. For more information regarding the devicetree bindings of the TCU drivers, -have a look at Documentation/devicetree/bindings/mfd/ingenic,tcu.txt. +have a look at Documentation/devicetree/bindings/timer/ingenic,tcu.txt. diff --git a/Documentation/misc-devices/xilinx_sdfec.rst b/Documentation/misc-devices/xilinx_sdfec.rst new file mode 100644 index 000000000000..2245fcfa224d --- /dev/null +++ b/Documentation/misc-devices/xilinx_sdfec.rst @@ -0,0 +1,291 @@ +.. SPDX-License-Identifier: GPL-2.0+ +==================== +Xilinx SD-FEC Driver +==================== + +Overview +======== + +This driver supports SD-FEC Integrated Block for Zynq |Ultrascale+ (TM)| RFSoCs. + +.. |Ultrascale+ (TM)| unicode:: Ultrascale+ U+2122 + .. with trademark sign + +For a full description of SD-FEC core features, see the `SD-FEC Product Guide (PG256) <https://www.xilinx.com/cgi-bin/docs/ipdoc?c=sd_fec;v=latest;d=pg256-sdfec-integrated-block.pdf>`_ + +This driver supports the following features: + + - Retrieval of the Integrated Block configuration and status information + - Configuration of LDPC codes + - Configuration of Turbo decoding + - Monitoring errors + +Missing features, known issues, and limitations of the SD-FEC driver are as +follows: + + - Only allows a single open file handler to any instance of the driver at any time + - Reset of the SD-FEC Integrated Block is not controlled by this driver + - Does not support shared LDPC code table wraparound + +The device tree entry is described in: +`linux-xlnx/Documentation/devicetree/bindings/misc/xlnx,sd-fec.txt <https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/devicetree/bindings/misc/xlnx%2Csd-fec.txt>`_ + + +Modes of Operation +------------------ + +The driver works with the SD-FEC core in two modes of operation: + + - Run-time configuration + - Programmable Logic (PL) initialization + + +Run-time Configuration +~~~~~~~~~~~~~~~~~~~~~~ + +For Run-time configuration the role of driver is to allow the software application to do the following: + + - Load the configuration parameters for either Turbo decode or LDPC encode or decode + - Activate the SD-FEC core + - Monitor the SD-FEC core for errors + - Retrieve the status and configuration of the SD-FEC core + +Programmable Logic (PL) Initialization +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For PL initialization, supporting logic loads configuration parameters for either +the Turbo decode or LDPC encode or decode. The role of the driver is to allow +the software application to do the following: + + - Activate the SD-FEC core + - Monitor the SD-FEC core for errors + - Retrieve the status and configuration of the SD-FEC core + + +Driver Structure +================ + +The driver provides a platform device where the ``probe`` and ``remove`` +operations are provided. + + - probe: Updates configuration register with device-tree entries plus determines the current activate state of the core, for example, is the core bypassed or has the core been started. + + +The driver defines the following driver file operations to provide user +application interfaces: + + - open: Implements restriction that only a single file descriptor can be open per SD-FEC instance at any time + - release: Allows another file descriptor to be open, that is after current file descriptor is closed + - poll: Provides a method to monitor for SD-FEC Error events + - unlocked_ioctl: Provides the the following ioctl commands that allows the application configure the SD-FEC core: + + - :c:macro:`XSDFEC_START_DEV` + - :c:macro:`XSDFEC_STOP_DEV` + - :c:macro:`XSDFEC_GET_STATUS` + - :c:macro:`XSDFEC_SET_IRQ` + - :c:macro:`XSDFEC_SET_TURBO` + - :c:macro:`XSDFEC_ADD_LDPC_CODE_PARAMS` + - :c:macro:`XSDFEC_GET_CONFIG` + - :c:macro:`XSDFEC_SET_ORDER` + - :c:macro:`XSDFEC_SET_BYPASS` + - :c:macro:`XSDFEC_IS_ACTIVE` + - :c:macro:`XSDFEC_CLEAR_STATS` + - :c:macro:`XSDFEC_SET_DEFAULT_CONFIG` + + +Driver Usage +============ + + +Overview +-------- + +After opening the driver, the user should find out what operations need to be +performed to configure and activate the SD-FEC core and determine the +configuration of the driver. +The following outlines the flow the user should perform: + + - Determine Configuration + - Set the order, if not already configured as desired + - Set Turbo decode, LPDC encode or decode parameters, depending on how the + SD-FEC core is configured plus if the SD-FEC has not been configured for PL + initialization + - Enable interrupts, if not already enabled + - Bypass the SD-FEC core, if required + - Start the SD-FEC core if not already started + - Get the SD-FEC core status + - Monitor for interrupts + - Stop the SD-FEC core + + +Note: When monitoring for interrupts if a critical error is detected where a reset is required, the driver will be required to load the default configuration. + + +Determine Configuration +----------------------- + +Determine the configuration of the SD-FEC core by using the ioctl +:c:macro:`XSDFEC_GET_CONFIG`. + +Set the Order +------------- + +Setting the order determines how the order of Blocks can change from input to output. + +Setting the order is done by using the ioctl :c:macro:`XSDFEC_SET_ORDER` + +Setting the order can only be done if the following restrictions are met: + + - The ``state`` member of struct :c:type:`xsdfec_status <xsdfec_status>` filled by the ioctl :c:macro:`XSDFEC_GET_STATUS` indicates the SD-FEC core has not STARTED + + +Add LDPC Codes +-------------- + +The following steps indicate how to add LDPC codes to the SD-FEC core: + + - Use the auto-generated parameters to fill the :c:type:`struct xsdfec_ldpc_params <xsdfec_ldpc_params>` for the desired LDPC code. + - Set the SC, QA, and LA table offsets for the LPDC parameters and the parameters in the structure :c:type:`struct xsdfec_ldpc_params <xsdfec_ldpc_params>` + - Set the desired Code Id value in the structure :c:type:`struct xsdfec_ldpc_params <xsdfec_ldpc_params>` + - Add the LPDC Code Parameters using the ioctl :c:macro:`XSDFEC_ADD_LDPC_CODE_PARAMS` + - For the applied LPDC Code Parameter use the function :c:func:`xsdfec_calculate_shared_ldpc_table_entry_size` to calculate the size of shared LPDC code tables. This allows the user to determine the shared table usage so when selecting the table offsets for the next LDPC code parameters unused table areas can be selected. + - Repeat for each LDPC code parameter. + +Adding LDPC codes can only be done if the following restrictions are met: + + - The ``code`` member of :c:type:`struct xsdfec_config <xsdfec_config>` filled by the ioctl :c:macro:`XSDFEC_GET_CONFIG` indicates the SD-FEC core is configured as LDPC + - The ``code_wr_protect`` of :c:type:`struct xsdfec_config <xsdfec_config>` filled by the ioctl :c:macro:`XSDFEC_GET_CONFIG` indicates that write protection is not enabled + - The ``state`` member of struct :c:type:`xsdfec_status <xsdfec_status>` filled by the ioctl :c:macro:`XSDFEC_GET_STATUS` indicates the SD-FEC core has not started + +Set Turbo Decode +---------------- + +Configuring the Turbo decode parameters is done by using the ioctl :c:macro:`XSDFEC_SET_TURBO` using auto-generated parameters to fill the :c:type:`struct xsdfec_turbo <xsdfec_turbo>` for the desired Turbo code. + +Adding Turbo decode can only be done if the following restrictions are met: + + - The ``code`` member of :c:type:`struct xsdfec_config <xsdfec_config>` filled by the ioctl :c:macro:`XSDFEC_GET_CONFIG` indicates the SD-FEC core is configured as TURBO + - The ``state`` member of struct :c:type:`xsdfec_status <xsdfec_status>` filled by the ioctl :c:macro:`XSDFEC_GET_STATUS` indicates the SD-FEC core has not STARTED + +Enable Interrupts +----------------- + +Enabling or disabling interrupts is done by using the ioctl :c:macro:`XSDFEC_SET_IRQ`. The members of the parameter passed, :c:type:`struct xsdfec_irq <xsdfec_irq>`, to the ioctl are used to set and clear different categories of interrupts. The category of interrupt is controlled as following: + + - ``enable_isr`` controls the ``tlast`` interrupts + - ``enable_ecc_isr`` controls the ECC interrupts + +If the ``code`` member of :c:type:`struct xsdfec_config <xsdfec_config>` filled by the ioctl :c:macro:`XSDFEC_GET_CONFIG` indicates the SD-FEC core is configured as TURBO then the enabling ECC errors is not required. + +Bypass the SD-FEC +----------------- + +Bypassing the SD-FEC is done by using the ioctl :c:macro:`XSDFEC_SET_BYPASS` + +Bypassing the SD-FEC can only be done if the following restrictions are met: + + - The ``state`` member of :c:type:`struct xsdfec_status <xsdfec_status>` filled by the ioctl :c:macro:`XSDFEC_GET_STATUS` indicates the SD-FEC core has not STARTED + +Start the SD-FEC core +--------------------- + +Start the SD-FEC core by using the ioctl :c:macro:`XSDFEC_START_DEV` + +Get SD-FEC Status +----------------- + +Get the SD-FEC status of the device by using the ioctl :c:macro:`XSDFEC_GET_STATUS`, which will fill the :c:type:`struct xsdfec_status <xsdfec_status>` + +Monitor for Interrupts +---------------------- + + - Use the poll system call to monitor for an interrupt. The poll system call waits for an interrupt to wake it up or times out if no interrupt occurs. + - On return Poll ``revents`` will indicate whether stats and/or state have been updated + - ``POLLPRI`` indicates a critical error and the user should use :c:macro:`XSDFEC_GET_STATUS` and :c:macro:`XSDFEC_GET_STATS` to confirm + - ``POLLRDNORM`` indicates a non-critical error has occurred and the user should use :c:macro:`XSDFEC_GET_STATS` to confirm + - Get stats by using the ioctl :c:macro:`XSDFEC_GET_STATS` + - For critical error the ``isr_err_count`` or ``uecc_count`` member of :c:type:`struct xsdfec_stats <xsdfec_stats>` is non-zero + - For non-critical errors the ``cecc_count`` member of :c:type:`struct xsdfec_stats <xsdfec_stats>` is non-zero + - Get state by using the ioctl :c:macro:`XSDFEC_GET_STATUS` + - For a critical error the ``state`` of :c:type:`xsdfec_status <xsdfec_status>` will indicate a Reset Is Required + - Clear stats by using the ioctl :c:macro:`XSDFEC_CLEAR_STATS` + +If a critical error is detected where a reset is required. The application is required to call the ioctl :c:macro:`XSDFEC_SET_DEFAULT_CONFIG`, after the reset and it is not required to call the ioctl :c:macro:`XSDFEC_STOP_DEV` + +Note: Using poll system call prevents busy looping using :c:macro:`XSDFEC_GET_STATS` and :c:macro:`XSDFEC_GET_STATUS` + +Stop the SD-FEC Core +--------------------- + +Stop the device by using the ioctl :c:macro:`XSDFEC_STOP_DEV` + +Set the Default Configuration +----------------------------- + +Load default configuration by using the ioctl :c:macro:`XSDFEC_SET_DEFAULT_CONFIG` to restore the driver. + +Limitations +----------- + +Users should not duplicate SD-FEC device file handlers, for example fork() or dup() a process that has a created an SD-FEC file handler. + +Driver IOCTLs +============== + +.. c:macro:: XSDFEC_START_DEV +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h + :doc: XSDFEC_START_DEV + +.. c:macro:: XSDFEC_STOP_DEV +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h + :doc: XSDFEC_STOP_DEV + +.. c:macro:: XSDFEC_GET_STATUS +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h + :doc: XSDFEC_GET_STATUS + +.. c:macro:: XSDFEC_SET_IRQ +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h + :doc: XSDFEC_SET_IRQ + +.. c:macro:: XSDFEC_SET_TURBO +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h + :doc: XSDFEC_SET_TURBO + +.. c:macro:: XSDFEC_ADD_LDPC_CODE_PARAMS +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h + :doc: XSDFEC_ADD_LDPC_CODE_PARAMS + +.. c:macro:: XSDFEC_GET_CONFIG +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h + :doc: XSDFEC_GET_CONFIG + +.. c:macro:: XSDFEC_SET_ORDER +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h + :doc: XSDFEC_SET_ORDER + +.. c:macro:: XSDFEC_SET_BYPASS +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h + :doc: XSDFEC_SET_BYPASS + +.. c:macro:: XSDFEC_IS_ACTIVE +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h + :doc: XSDFEC_IS_ACTIVE + +.. c:macro:: XSDFEC_CLEAR_STATS +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h + :doc: XSDFEC_CLEAR_STATS + +.. c:macro:: XSDFEC_GET_STATS +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h + :doc: XSDFEC_GET_STATS + +.. c:macro:: XSDFEC_SET_DEFAULT_CONFIG +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h + :doc: XSDFEC_SET_DEFAULT_CONFIG + +Driver Type Definitions +======================= + +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h + :internal: diff --git a/Documentation/networking/device_drivers/intel/e100.rst b/Documentation/networking/device_drivers/intel/e100.rst index 2b9f4887beda..5a26a0e326ea 100644 --- a/Documentation/networking/device_drivers/intel/e100.rst +++ b/Documentation/networking/device_drivers/intel/e100.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -============================================================== -Linux* Base Driver for the Intel(R) PRO/100 Family of Adapters -============================================================== +=============================================================
+Linux Base Driver for the Intel(R) PRO/100 Family of Adapters
+=============================================================
June 1, 2018 @@ -21,7 +21,7 @@ Contents In This Release =============== -This file describes the Linux* Base Driver for the Intel(R) PRO/100 Family of +This file describes the Linux Base Driver for the Intel(R) PRO/100 Family of
Adapters. This driver includes support for Itanium(R)2-based systems. For questions related to hardware requirements, refer to the documentation @@ -138,9 +138,9 @@ version 1.6 or later is required for this functionality. The latest release of ethtool can be found from https://www.kernel.org/pub/software/network/ethtool/ -Enabling Wake on LAN* (WoL) ---------------------------- -WoL is provided through the ethtool* utility. For instructions on +Enabling Wake on LAN (WoL)
+--------------------------
+WoL is provided through the ethtool utility. For instructions on
enabling WoL with ethtool, refer to the ethtool man page. WoL will be enabled on the system during the next shut down or reboot. For this driver version, in order to enable WoL, the e100 driver must be loaded diff --git a/Documentation/networking/device_drivers/intel/e1000.rst b/Documentation/networking/device_drivers/intel/e1000.rst index 956560b6e745..f146201f66a2 100644 --- a/Documentation/networking/device_drivers/intel/e1000.rst +++ b/Documentation/networking/device_drivers/intel/e1000.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -=========================================================== -Linux* Base Driver for Intel(R) Ethernet Network Connection -=========================================================== +==========================================================
+Linux Base Driver for Intel(R) Ethernet Network Connection
+==========================================================
Intel Gigabit Linux driver. Copyright(c) 1999 - 2013 Intel Corporation. @@ -438,10 +438,10 @@ ethtool The latest release of ethtool can be found from https://www.kernel.org/pub/software/network/ethtool/ -Enabling Wake on LAN* (WoL) ---------------------------- +Enabling Wake on LAN (WoL)
+--------------------------
- WoL is configured through the ethtool* utility. + WoL is configured through the ethtool utility.
WoL will be enabled on the system during the next shut down or reboot. For this driver version, in order to enable WoL, the e1000 driver must be diff --git a/Documentation/networking/device_drivers/intel/e1000e.rst b/Documentation/networking/device_drivers/intel/e1000e.rst index 01999f05509c..c3205d43be56 100644 --- a/Documentation/networking/device_drivers/intel/e1000e.rst +++ b/Documentation/networking/device_drivers/intel/e1000e.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -====================================================== -Linux* Driver for Intel(R) Ethernet Network Connection -====================================================== +=====================================================
+Linux Driver for Intel(R) Ethernet Network Connection
+=====================================================
Intel Gigabit Linux driver. Copyright(c) 2008-2018 Intel Corporation. @@ -338,7 +338,7 @@ and higher cannot be forced. Use the autonegotiation advertising setting to manually set devices for 1 Gbps and higher. Speed, duplex, and autonegotiation advertising are configured through the -ethtool* utility. +ethtool utility.
Caution: Only experienced network administrators should force speed and duplex or change autonegotiation advertising manually. The settings at the switch must @@ -351,9 +351,9 @@ will not attempt to auto-negotiate with its link partner since those adapters operate only in full duplex and only at their native speed. -Enabling Wake on LAN* (WoL) ---------------------------- -WoL is configured through the ethtool* utility. +Enabling Wake on LAN (WoL)
+--------------------------
+WoL is configured through the ethtool utility.
WoL will be enabled on the system during the next shut down or reboot. For this driver version, in order to enable WoL, the e1000e driver must be loaded diff --git a/Documentation/networking/device_drivers/intel/fm10k.rst b/Documentation/networking/device_drivers/intel/fm10k.rst index ac3269e34f55..d165ac5c1403 100644 --- a/Documentation/networking/device_drivers/intel/fm10k.rst +++ b/Documentation/networking/device_drivers/intel/fm10k.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -============================================================== -Linux* Base Driver for Intel(R) Ethernet Multi-host Controller -============================================================== +=============================================================
+Linux Base Driver for Intel(R) Ethernet Multi-host Controller
+=============================================================
August 20, 2018 Copyright(c) 2015-2018 Intel Corporation. @@ -120,8 +120,8 @@ rx-flow-hash tcp4|udp4|ah4|esp4|sctp4|tcp6|udp6|ah6|esp6|sctp6 m|v|t|s|d|f|n|r Known Issues/Troubleshooting ============================ -Enabling SR-IOV in a 64-bit Microsoft* Windows Server* 2012/R2 guest OS under Linux KVM ---------------------------------------------------------------------------------------- +Enabling SR-IOV in a 64-bit Microsoft Windows Server 2012/R2 guest OS under Linux KVM
+-------------------------------------------------------------------------------------
KVM Hypervisor/VMM supports direct assignment of a PCIe device to a VM. This includes traditional PCIe devices, as well as SR-IOV-capable devices based on the Intel Ethernet Controller XL710. diff --git a/Documentation/networking/device_drivers/intel/i40e.rst b/Documentation/networking/device_drivers/intel/i40e.rst index 848fd388fa6e..3331d8960cca 100644 --- a/Documentation/networking/device_drivers/intel/i40e.rst +++ b/Documentation/networking/device_drivers/intel/i40e.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -================================================================== -Linux* Base Driver for the Intel(R) Ethernet Controller 700 Series -================================================================== +=================================================================
+Linux Base Driver for the Intel(R) Ethernet Controller 700 Series
+=================================================================
Intel 40 Gigabit Linux driver. Copyright(c) 1999-2018 Intel Corporation. @@ -384,7 +384,7 @@ NOTE: You cannot set the speed for devices based on the Intel(R) Ethernet Network Adapter XXV710 based devices. Speed, duplex, and autonegotiation advertising are configured through the -ethtool* utility. +ethtool utility.
Caution: Only experienced network administrators should force speed and duplex or change autonegotiation advertising manually. The settings at the switch must diff --git a/Documentation/networking/device_drivers/intel/iavf.rst b/Documentation/networking/device_drivers/intel/iavf.rst index cfc08842e32c..f963598cce61 100644 --- a/Documentation/networking/device_drivers/intel/iavf.rst +++ b/Documentation/networking/device_drivers/intel/iavf.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -================================================================== -Linux* Base Driver for Intel(R) Ethernet Adaptive Virtual Function -================================================================== +=================================================================
+Linux Base Driver for Intel(R) Ethernet Adaptive Virtual Function
+=================================================================
Intel Ethernet Adaptive Virtual Function Linux driver. Copyright(c) 2013-2018 Intel Corporation. @@ -19,7 +19,7 @@ Contents Overview ======== -This file describes the iavf Linux* Base Driver. This driver was formerly +This file describes the iavf Linux Base Driver. This driver was formerly
called i40evf. The iavf driver supports the below mentioned virtual function devices and diff --git a/Documentation/networking/device_drivers/intel/ice.rst b/Documentation/networking/device_drivers/intel/ice.rst index c220aa2711c6..1b866d4d497a 100644 --- a/Documentation/networking/device_drivers/intel/ice.rst +++ b/Documentation/networking/device_drivers/intel/ice.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -=================================================================== -Linux* Base Driver for the Intel(R) Ethernet Connection E800 Series -=================================================================== +==================================================================
+Linux Base Driver for the Intel(R) Ethernet Connection E800 Series
+==================================================================
Intel ice Linux driver. Copyright(c) 2018 Intel Corporation. diff --git a/Documentation/networking/device_drivers/intel/igb.rst b/Documentation/networking/device_drivers/intel/igb.rst index fc8cfaa5dcfa..fe914a0384b5 100644 --- a/Documentation/networking/device_drivers/intel/igb.rst +++ b/Documentation/networking/device_drivers/intel/igb.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -=========================================================== -Linux* Base Driver for Intel(R) Ethernet Network Connection -=========================================================== +==========================================================
+Linux Base Driver for Intel(R) Ethernet Network Connection
+==========================================================
Intel Gigabit Linux driver. Copyright(c) 1999-2018 Intel Corporation. @@ -129,9 +129,9 @@ version is required for this functionality. Download it at: https://www.kernel.org/pub/software/network/ethtool/ -Enabling Wake on LAN* (WoL) ---------------------------- -WoL is configured through the ethtool* utility. +Enabling Wake on LAN (WoL)
+--------------------------
+WoL is configured through the ethtool utility.
WoL will be enabled on the system during the next shut down or reboot. For this driver version, in order to enable WoL, the igb driver must be loaded diff --git a/Documentation/networking/device_drivers/intel/igbvf.rst b/Documentation/networking/device_drivers/intel/igbvf.rst index 9cddabe8108e..3aae181be091 100644 --- a/Documentation/networking/device_drivers/intel/igbvf.rst +++ b/Documentation/networking/device_drivers/intel/igbvf.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -============================================================ -Linux* Base Virtual Function Driver for Intel(R) 1G Ethernet -============================================================ +===========================================================
+Linux Base Virtual Function Driver for Intel(R) 1G Ethernet
+===========================================================
Intel Gigabit Virtual Function Linux driver. Copyright(c) 1999-2018 Intel Corporation. diff --git a/Documentation/networking/device_drivers/intel/ixgbe.rst b/Documentation/networking/device_drivers/intel/ixgbe.rst index c7d25483fedb..4e5a35a4f241 100644 --- a/Documentation/networking/device_drivers/intel/ixgbe.rst +++ b/Documentation/networking/device_drivers/intel/ixgbe.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -============================================================================= -Linux* Base Driver for the Intel(R) Ethernet 10 Gigabit PCI Express Adapters -============================================================================= +===========================================================================
+Linux Base Driver for the Intel(R) Ethernet 10 Gigabit PCI Express Adapters
+===========================================================================
Intel 10 Gigabit Linux driver. Copyright(c) 1999-2018 Intel Corporation. @@ -519,8 +519,8 @@ The offload is also supported for ixgbe's VFs, but the VF must be set as Known Issues/Troubleshooting ============================ -Enabling SR-IOV in a 64-bit Microsoft* Windows Server* 2012/R2 guest OS ------------------------------------------------------------------------ +Enabling SR-IOV in a 64-bit Microsoft Windows Server 2012/R2 guest OS
+---------------------------------------------------------------------
Linux KVM Hypervisor/VMM supports direct assignment of a PCIe device to a VM. This includes traditional PCIe devices, as well as SR-IOV-capable devices based on the Intel Ethernet Controller XL710. diff --git a/Documentation/networking/device_drivers/intel/ixgbevf.rst b/Documentation/networking/device_drivers/intel/ixgbevf.rst index 5d4977360157..69b3c2c9935c 100644 --- a/Documentation/networking/device_drivers/intel/ixgbevf.rst +++ b/Documentation/networking/device_drivers/intel/ixgbevf.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -============================================================= -Linux* Base Virtual Function Driver for Intel(R) 10G Ethernet -============================================================= +============================================================
+Linux Base Virtual Function Driver for Intel(R) 10G Ethernet
+============================================================
Intel 10 Gigabit Virtual Function Linux driver. Copyright(c) 1999-2018 Intel Corporation. diff --git a/Documentation/networking/device_drivers/mellanox/mlx5.rst b/Documentation/networking/device_drivers/mellanox/mlx5.rst index d071c6b49e1f..a74422058351 100644 --- a/Documentation/networking/device_drivers/mellanox/mlx5.rst +++ b/Documentation/networking/device_drivers/mellanox/mlx5.rst @@ -258,7 +258,7 @@ mlx5 tracepoints ================ mlx5 driver provides internal trace points for tracking and debugging using -kernel tracepoints interfaces (refer to Documentation/trace/ftrase.rst). +kernel tracepoints interfaces (refer to Documentation/trace/ftrace.rst). For the list of support mlx5 events check /sys/kernel/debug/tracing/events/mlx5/ diff --git a/Documentation/networking/device_drivers/pensando/ionic.rst b/Documentation/networking/device_drivers/pensando/ionic.rst index 13935896bee6..ec3c981124ea 100644 --- a/Documentation/networking/device_drivers/pensando/ionic.rst +++ b/Documentation/networking/device_drivers/pensando/ionic.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -========================================================== -Linux* Driver for the Pensando(R) Ethernet adapter family -========================================================== +========================================================
+Linux Driver for the Pensando(R) Ethernet adapter family
+========================================================
Pensando Linux Ethernet driver. Copyright(c) 2019 Pensando Systems, Inc diff --git a/Documentation/networking/devlink-trap.rst b/Documentation/networking/devlink-trap.rst index 8e90a85f3bd5..5c04cc542bcf 100644 --- a/Documentation/networking/devlink-trap.rst +++ b/Documentation/networking/devlink-trap.rst @@ -172,7 +172,7 @@ help debug packet drops caused by these exceptions. The following list includes links to the description of driver-specific traps registered by various device drivers: - * :doc:`/devlink-trap-netdevsim` + * :doc:`devlink-trap-netdevsim` Generic Packet Trap Groups ========================== diff --git a/Documentation/networking/phy.rst b/Documentation/networking/phy.rst index a689966bc4be..3f5bd83034df 100644 --- a/Documentation/networking/phy.rst +++ b/Documentation/networking/phy.rst @@ -73,7 +73,7 @@ The Reduced Gigabit Medium Independent Interface (RGMII) is a 12-pin electrical signal interface using a synchronous 125Mhz clock signal and several data lines. Due to this design decision, a 1.5ns to 2ns delay must be added between the clock line (RXC or TXC) and the data lines to let the PHY (clock -sink) have enough setup and hold times to sample the data lines correctly. The +sink) have a large enough setup and hold time to sample the data lines correctly. The PHY library offers different types of PHY_INTERFACE_MODE_RGMII* values to let the PHY driver and optionally the MAC driver, implement the required delay. The values of phy_interface_t must be understood from the perspective of the PHY diff --git a/Documentation/ioctl/botching-up-ioctls.rst b/Documentation/process/botching-up-ioctls.rst index ac697fef3545..2d4829b2fb09 100644 --- a/Documentation/ioctl/botching-up-ioctls.rst +++ b/Documentation/process/botching-up-ioctls.rst @@ -46,7 +46,7 @@ will need to add a 32-bit compat layer: conversion or worse, fiddle the raw __u64 through your code since that diminishes the checking tools like sparse can provide. The macro u64_to_user_ptr can be used in the kernel to avoid warnings about integers - and pointres of different sizes. + and pointers of different sizes. Basics diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index e2c9ffc682c5..21aa7d5358e6 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -46,6 +46,7 @@ Other guides to the community that are of interest to most developers are: kernel-docs deprecated embargoed-hardware-issues + maintainers These are some overall technical guides that have been put here for now for lack of a better place. @@ -57,6 +58,7 @@ lack of a better place. adding-syscalls magic-number volatile-considered-harmful + botching-up-ioctls clang-format .. only:: subproject and html diff --git a/Documentation/process/maintainers.rst b/Documentation/process/maintainers.rst new file mode 100644 index 000000000000..6174cfb4138f --- /dev/null +++ b/Documentation/process/maintainers.rst @@ -0,0 +1 @@ +.. maintainers-include:: diff --git a/Documentation/riscv/boot-image-header.rst b/Documentation/riscv/boot-image-header.rst index 7b4d1d747585..518d46d2389d 100644 --- a/Documentation/riscv/boot-image-header.rst +++ b/Documentation/riscv/boot-image-header.rst @@ -21,7 +21,7 @@ The following 64-byte header is present in decompressed Linux kernel image:: u32 res1 = 0; /* Reserved */ u64 res2 = 0; /* Reserved */ u64 magic = 0x5643534952; /* Magic number, little endian, "RISCV" */ - u32 magic2 = 0x56534905; /* Magic number 2, little endian, "RSC\x05" */ + u32 magic2 = 0x05435352; /* Magic number 2, little endian, "RSC\x05" */ u32 res4; /* Reserved for PE COFF offset */ This header format is compliant with PE/COFF header and largely inspired from diff --git a/Documentation/scheduler/sched-stats.rst b/Documentation/scheduler/sched-stats.rst index 0cb0aa714545..dd9b99a025f7 100644 --- a/Documentation/scheduler/sched-stats.rst +++ b/Documentation/scheduler/sched-stats.rst @@ -28,7 +28,7 @@ of these will need to start with a baseline observation and then calculate the change in the counters at each subsequent observation. A perl script which does this for many of the fields is available at - http://eaglet.rain.com/rick/linux/schedstat/ + http://eaglet.pdxhosts.com/rick/linux/schedstat/ Note that any such script will necessarily be version-specific, as the main reason to change versions is changes in the output format. For those wishing @@ -164,4 +164,4 @@ report on how well a particular process or set of processes is faring under the scheduler's policies. A simple version of such a program is available at - http://eaglet.rain.com/rick/linux/schedstat/v12/latency.c + http://eaglet.pdxhosts.com/rick/linux/schedstat/v12/latency.c diff --git a/Documentation/security/lsm.rst b/Documentation/security/lsm.rst index ad4dfd020e0d..aadf47c808c0 100644 --- a/Documentation/security/lsm.rst +++ b/Documentation/security/lsm.rst @@ -56,7 +56,7 @@ the infrastructure to support security modules. The LSM kernel patch also moves most of the capabilities logic into an optional security module, with the system defaulting to the traditional superuser logic. This capabilities module is discussed further in -`LSM Capabilities Module <#cap>`__. +`LSM Capabilities Module`_. The LSM kernel patch adds security fields to kernel data structures and inserts calls to hook functions at critical points in the kernel code to diff --git a/Documentation/sphinx-static/theme_overrides.css b/Documentation/sphinx-static/theme_overrides.css index e21e36cd6761..459ec5b29d68 100644 --- a/Documentation/sphinx-static/theme_overrides.css +++ b/Documentation/sphinx-static/theme_overrides.css @@ -53,6 +53,16 @@ div[class^="highlight"] pre { line-height: normal; } +/* Keep fields from being strangely far apart due to inheirited table CSS. */ +.rst-content table.field-list th.field-name { + padding-top: 1px; + padding-bottom: 1px; +} +.rst-content table.field-list td.field-body { + padding-top: 1px; + padding-bottom: 1px; +} + @media screen { /* content column diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py new file mode 100755 index 000000000000..dc8fed48d3c2 --- /dev/null +++ b/Documentation/sphinx/maintainers_include.py @@ -0,0 +1,197 @@ +#!/usr/bin/env python +# SPDX-License-Identifier: GPL-2.0 +# -*- coding: utf-8; mode: python -*- +# pylint: disable=R0903, C0330, R0914, R0912, E0401 + +u""" + maintainers-include + ~~~~~~~~~~~~~~~~~~~ + + Implementation of the ``maintainers-include`` reST-directive. + + :copyright: Copyright (C) 2019 Kees Cook <keescook@chromium.org> + :license: GPL Version 2, June 1991 see linux/COPYING for details. + + The ``maintainers-include`` reST-directive performs extensive parsing + specific to the Linux kernel's standard "MAINTAINERS" file, in an + effort to avoid needing to heavily mark up the original plain text. +""" + +import sys +import re +import os.path + +from docutils import statemachine +from docutils.utils.error_reporting import ErrorString +from docutils.parsers.rst import Directive +from docutils.parsers.rst.directives.misc import Include + +__version__ = '1.0' + +def setup(app): + app.add_directive("maintainers-include", MaintainersInclude) + return dict( + version = __version__, + parallel_read_safe = True, + parallel_write_safe = True + ) + +class MaintainersInclude(Include): + u"""MaintainersInclude (``maintainers-include``) directive""" + required_arguments = 0 + + def parse_maintainers(self, path): + """Parse all the MAINTAINERS lines into ReST for human-readability""" + + result = list() + result.append(".. _maintainers:") + result.append("") + + # Poor man's state machine. + descriptions = False + maintainers = False + subsystems = False + + # Field letter to field name mapping. + field_letter = None + fields = dict() + + prev = None + field_prev = "" + field_content = "" + + for line in open(path): + if sys.version_info.major == 2: + line = unicode(line, 'utf-8') + # Have we reached the end of the preformatted Descriptions text? + if descriptions and line.startswith('Maintainers'): + descriptions = False + # Ensure a blank line following the last "|"-prefixed line. + result.append("") + + # Start subsystem processing? This is to skip processing the text + # between the Maintainers heading and the first subsystem name. + if maintainers and not subsystems: + if re.search('^[A-Z0-9]', line): + subsystems = True + + # Drop needless input whitespace. + line = line.rstrip() + + # Linkify all non-wildcard refs to ReST files in Documentation/. + pat = '(Documentation/([^\s\?\*]*)\.rst)' + m = re.search(pat, line) + if m: + # maintainers.rst is in a subdirectory, so include "../". + line = re.sub(pat, ':doc:`%s <../%s>`' % (m.group(2), m.group(2)), line) + + # Check state machine for output rendering behavior. + output = None + if descriptions: + # Escape the escapes in preformatted text. + output = "| %s" % (line.replace("\\", "\\\\")) + # Look for and record field letter to field name mappings: + # R: Designated *reviewer*: FullName <address@domain> + m = re.search("\s(\S):\s", line) + if m: + field_letter = m.group(1) + if field_letter and not field_letter in fields: + m = re.search("\*([^\*]+)\*", line) + if m: + fields[field_letter] = m.group(1) + elif subsystems: + # Skip empty lines: subsystem parser adds them as needed. + if len(line) == 0: + continue + # Subsystem fields are batched into "field_content" + if line[1] != ':': + # Render a subsystem entry as: + # SUBSYSTEM NAME + # ~~~~~~~~~~~~~~ + + # Flush pending field content. + output = field_content + "\n\n" + field_content = "" + + # Collapse whitespace in subsystem name. + heading = re.sub("\s+", " ", line) + output = output + "%s\n%s" % (heading, "~" * len(heading)) + field_prev = "" + else: + # Render a subsystem field as: + # :Field: entry + # entry... + field, details = line.split(':', 1) + details = details.strip() + + # Mark paths (and regexes) as literal text for improved + # readability and to escape any escapes. + if field in ['F', 'N', 'X', 'K']: + # But only if not already marked :) + if not ':doc:' in details: + details = '``%s``' % (details) + + # Comma separate email field continuations. + if field == field_prev and field_prev in ['M', 'R', 'L']: + field_content = field_content + "," + + # Do not repeat field names, so that field entries + # will be collapsed together. + if field != field_prev: + output = field_content + "\n" + field_content = ":%s:" % (fields.get(field, field)) + field_content = field_content + "\n\t%s" % (details) + field_prev = field + else: + output = line + + # Re-split on any added newlines in any above parsing. + if output != None: + for separated in output.split('\n'): + result.append(separated) + + # Update the state machine when we find heading separators. + if line.startswith('----------'): + if prev.startswith('Descriptions'): + descriptions = True + if prev.startswith('Maintainers'): + maintainers = True + + # Retain previous line for state machine transitions. + prev = line + + # Flush pending field contents. + if field_content != "": + for separated in field_content.split('\n'): + result.append(separated) + + output = "\n".join(result) + # For debugging the pre-rendered results... + #print(output, file=open("/tmp/MAINTAINERS.rst", "w")) + + self.state_machine.insert_input( + statemachine.string2lines(output), path) + + def run(self): + """Include the MAINTAINERS file as part of this reST file.""" + if not self.state.document.settings.file_insertion_enabled: + raise self.warning('"%s" directive disabled.' % self.name) + + # Walk up source path directories to find Documentation/../ + path = self.state_machine.document.attributes['source'] + path = os.path.realpath(path) + tail = path + while tail != "Documentation" and tail != "": + (path, tail) = os.path.split(path) + + # Append "MAINTAINERS" + path = os.path.join(path, "MAINTAINERS") + + try: + self.state.document.settings.record_dependencies.add(path) + lines = self.parse_maintainers(path) + except IOError as error: + raise self.severe('Problems with "%s" directive path:\n%s.' % + (self.name, ErrorString(error))) + + return [] diff --git a/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst b/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst index 118fb4153e8f..f3c8e8d377ee 100644 --- a/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst +++ b/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst @@ -455,7 +455,7 @@ soluzioni disponibili: `GnuK`_ della FSIJ. Questo è uno dei pochi dispositivi a supportare le chiavi ECC ED25519, ma offre meno funzionalità di sicurezza (come la resistenza alla manomissione o alcuni attacchi ad un canale laterale). -- `Nitrokey Pro`_: è simile alla Nitrokey Start, ma è più resistente alla +- `Nitrokey Pro 2`_: è simile alla Nitrokey Start, ma è più resistente alla manomissione e offre più funzionalità di sicurezza. La Pro 2 supporta la crittografia ECC (NISTP). - `Yubikey 5`_: l'hardware e il software sono proprietari, ma è più economica diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst index ad494da40009..e983488b48b1 100644 --- a/Documentation/userspace-api/index.rst +++ b/Documentation/userspace-api/index.rst @@ -21,6 +21,7 @@ place where this information is gathered. unshare spec_ctrl accelerators/ocxl + ioctl/index .. only:: subproject and html diff --git a/Documentation/ioctl/cdrom.rst b/Documentation/userspace-api/ioctl/cdrom.rst index 3b4c0506de46..3b4c0506de46 100644 --- a/Documentation/ioctl/cdrom.rst +++ b/Documentation/userspace-api/ioctl/cdrom.rst diff --git a/Documentation/ioctl/hdio.rst b/Documentation/userspace-api/ioctl/hdio.rst index e822e3dff176..e822e3dff176 100644 --- a/Documentation/ioctl/hdio.rst +++ b/Documentation/userspace-api/ioctl/hdio.rst diff --git a/Documentation/ioctl/index.rst b/Documentation/userspace-api/ioctl/index.rst index 0f0a857f6615..475675eae086 100644 --- a/Documentation/ioctl/index.rst +++ b/Documentation/userspace-api/ioctl/index.rst @@ -9,7 +9,6 @@ IOCTLs ioctl-number - botching-up-ioctls ioctl-decoding cdrom diff --git a/Documentation/ioctl/ioctl-decoding.rst b/Documentation/userspace-api/ioctl/ioctl-decoding.rst index 380d6bb3e3ea..380d6bb3e3ea 100644 --- a/Documentation/ioctl/ioctl-decoding.rst +++ b/Documentation/userspace-api/ioctl/ioctl-decoding.rst diff --git a/Documentation/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst index bef79cd4c6b4..bef79cd4c6b4 100644 --- a/Documentation/ioctl/ioctl-number.rst +++ b/Documentation/userspace-api/ioctl/ioctl-number.rst diff --git a/Documentation/w1/index.rst b/Documentation/w1/index.rst index 57cba81865e2..156279f17553 100644 --- a/Documentation/w1/index.rst +++ b/Documentation/w1/index.rst @@ -1,4 +1,4 @@ -. SPDX-License-Identifier: GPL-2.0 +.. SPDX-License-Identifier: GPL-2.0 ================ 1-Wire Subsystem diff --git a/MAINTAINERS b/MAINTAINERS index e51a68bf8ca8..dada80b45d4c 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1,12 +1,14 @@ - - - List of maintainers and how to submit kernel changes +List of maintainers and how to submit kernel changes +==================================================== Please try to follow the guidelines below. This will make things easier on the maintainers. Not all of these guidelines matter for every trivial patch so apply some common sense. -1. Always _test_ your changes, however small, on at least 4 or +Tips for patch submitters +------------------------- + +1. Always *test* your changes, however small, on at least 4 or 5 people, preferably many more. 2. Try to release a few ALPHA test versions to the net. Announce @@ -25,7 +27,7 @@ trivial patch so apply some common sense. testing and await feedback. 5. Make a patch available to the relevant maintainer in the list. Use - 'diff -u' to make the patch easy to merge. Be prepared to get your + ``diff -u`` to make the patch easy to merge. Be prepared to get your changes sent back with seemingly silly requests about formatting and variable names. These aren't as silly as they seem. One job the maintainers (and especially Linus) do is to keep things @@ -38,7 +40,7 @@ trivial patch so apply some common sense. See Documentation/process/coding-style.rst for guidance here. PLEASE CC: the maintainers and mailing lists that are generated - by scripts/get_maintainer.pl. The results returned by the + by ``scripts/get_maintainer.pl.`` The results returned by the script will be best if you have git installed and are making your changes in a branch derived from Linus' latest git tree. See Documentation/process/submitting-patches.rst for details. @@ -70,26 +72,27 @@ trivial patch so apply some common sense. not represent an immediate threat and are better handled publicly, and ideally, should come with a patch proposal. Please do not send automated reports to this list either. Such bugs will be handled - better and faster in the usual public places. + better and faster in the usual public places. See + Documentation/admin-guide/security-bugs.rst for details. 8. Happy hacking. -Descriptions of section entries: +Descriptions of section entries +------------------------------- - P: Person (obsolete) - M: Mail patches to: FullName <address@domain> - R: Designated reviewer: FullName <address@domain> + M: *Mail* patches to: FullName <address@domain> + R: Designated *Reviewer*: FullName <address@domain> These reviewers should be CCed on patches. - L: Mailing list that is relevant to this area - W: Web-page with status/info - B: URI for where to file bugs. A web-page with detailed bug + L: *Mailing list* that is relevant to this area + W: *Web-page* with status/info + B: URI for where to file *bugs*. A web-page with detailed bug filing info, a direct bug tracker link, or a mailto: URI. - C: URI for chat protocol, server and channel where developers + C: URI for *chat* protocol, server and channel where developers usually hang out, for example irc://server/channel. - Q: Patchwork web based patch tracking system site - T: SCM tree type and location. + Q: *Patchwork* web based patch tracking system site + T: *SCM* tree type and location. Type is one of: git, hg, quilt, stgit, topgit - S: Status, one of the following: + S: *Status*, one of the following: Supported: Someone is actually paid to look after this. Maintained: Someone actually looks after it. Odd Fixes: It has a maintainer but they don't have time to do @@ -99,13 +102,13 @@ Descriptions of section entries: Obsolete: Old code. Something tagged obsolete generally means it has been replaced by a better system and you should be using that. - F: Files and directories with wildcard patterns. + F: *Files* and directories wildcard patterns. A trailing slash includes all files and subdirectory files. F: drivers/net/ all files in and below drivers/net F: drivers/net/* all files in drivers/net, but not below F: */net/* all files in "any top level directory"/net One pattern per line. Multiple F: lines acceptable. - N: Files and directories with regex patterns. + N: Files and directories *Regex* patterns. N: [^a-z]tegra all files whose path contains the word tegra One pattern per line. Multiple N: lines acceptable. scripts/get_maintainer.pl has different behavior for files that @@ -113,14 +116,14 @@ Descriptions of section entries: get_maintainer will not look at git log history when an F: pattern match occurs. When an N: match occurs, git log history is used to also notify the people that have git commit signatures. - X: Files and directories that are NOT maintained, same rules as F: - Files exclusions are tested before file matches. + X: *Excluded* files and directories that are NOT maintained, same + rules as F:. Files exclusions are tested before file matches. Can be useful for excluding a specific subdirectory, for instance: F: net/ X: net/ipv6/ matches all files in and below net excluding net/ipv6/ - K: Keyword perl extended regex pattern to match content in a - patch or file. For instance: + K: *Content regex* (perl extended) pattern match in a patch or file. + For instance: K: of_get_profile matches patches or files that contain "of_get_profile" K: \b(printk|pr_(info|err))\b @@ -128,13 +131,12 @@ Descriptions of section entries: printk, pr_info or pr_err One regex pattern per line. Multiple K: lines acceptable. -Note: For the hard of thinking, this list is meant to remain in alphabetical -order. If you could add yourselves to it in alphabetical order that would be -so much easier [Ed] - -Maintainers List (try to look for most precise areas first) +Maintainers List +---------------- - ----------------------------------- +.. note:: When reading this list, please look for the most precise areas + first. When adding to this list, please keep the entries in + alphabetical order. 3C59X NETWORK DRIVER M: Steffen Klassert <klassert@kernel.org> @@ -3677,7 +3679,7 @@ M: Oleksij Rempel <o.rempel@pengutronix.de> R: Pengutronix Kernel Team <kernel@pengutronix.de> L: linux-can@vger.kernel.org S: Maintained -F: Documentation/networking/j1939.txt +F: Documentation/networking/j1939.rst F: net/can/j1939/ F: include/uapi/linux/can/j1939.h @@ -15543,7 +15545,7 @@ SUN4I LOW RES ADC ATTACHED TABLET KEYS DRIVER M: Hans de Goede <hdegoede@redhat.com> L: linux-input@vger.kernel.org S: Maintained -F: Documentation/devicetree/bindings/input/sun4i-lradc-keys.txt +F: Documentation/devicetree/bindings/input/allwinner,sun4i-a10-lradc-keys.yaml F: drivers/input/keyboard/sun4i-lradc-keys.c SUNDANCE NETWORK DRIVER diff --git a/drivers/net/ethernet/faraday/ftgmac100.c b/drivers/net/ethernet/faraday/ftgmac100.c index 9b7af94a40bb..8abe5e90d268 100644 --- a/drivers/net/ethernet/faraday/ftgmac100.c +++ b/drivers/net/ethernet/faraday/ftgmac100.c @@ -1835,7 +1835,7 @@ static int ftgmac100_probe(struct platform_device *pdev) } /* Indicate that we support PAUSE frames (see comment in - * Documentation/networking/phy.txt) + * Documentation/networking/phy.rst) */ phy_support_asym_pause(phy); diff --git a/drivers/net/ethernet/pensando/ionic/ionic_if.h b/drivers/net/ethernet/pensando/ionic/ionic_if.h index 5bfdda19f64d..80028f781c83 100644 --- a/drivers/net/ethernet/pensando/ionic/ionic_if.h +++ b/drivers/net/ethernet/pensando/ionic/ionic_if.h @@ -596,8 +596,8 @@ enum ionic_txq_desc_opcode { * the @encap is set, the device will * offload the outer header checksums using * LCO (local checksum offload) (see - * Documentation/networking/checksum- - * offloads.txt for more info). + * Documentation/networking/checksum-offloads.rst + * for more info). * * IONIC_TXQ_DESC_OPCODE_CSUM_HW: * diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig index ae21d08c65e8..a890f47fbeec 100644 --- a/drivers/platform/x86/Kconfig +++ b/drivers/platform/x86/Kconfig @@ -259,7 +259,7 @@ config DELL_RBU DELL system. Note you need a Dell OpenManage or Dell Update package (DUP) supporting application to communicate with the BIOS regarding the new image for the image update to take effect. - See <file:Documentation/driver-api/dell_rbu.rst> for more details on the driver. + See <file:Documentation/admin-guide/dell_rbu.rst> for more details on the driver. config FUJITSU_LAPTOP diff --git a/drivers/platform/x86/dell_rbu.c b/drivers/platform/x86/dell_rbu.c index 3691391fea6b..7d5453326b43 100644 --- a/drivers/platform/x86/dell_rbu.c +++ b/drivers/platform/x86/dell_rbu.c @@ -24,7 +24,7 @@ * on every time the packet data is written. This driver requires an * application to break the BIOS image in to fixed sized packet chunks. * - * See Documentation/driver-api/dell_rbu.rst for more info. + * See Documentation/admin-guide/dell_rbu.rst for more info. */ #include <linux/init.h> #include <linux/module.h> diff --git a/fs/cifs/cifsfs.c b/fs/cifs/cifsfs.c index c049c7b3aa87..0fa1e9cbdfdb 100644 --- a/fs/cifs/cifsfs.c +++ b/fs/cifs/cifsfs.c @@ -1537,7 +1537,7 @@ init_cifs(void) /* * Consider in future setting limit!=0 maybe to min(num_of_cores - 1, 3) * so that we don't launch too many worker threads but - * Documentation/workqueue.txt recommends setting it to 0 + * Documentation/core-api/workqueue.rst recommends setting it to 0 */ /* WQ_UNBOUND allows decrypt tasks to run on any CPU */ diff --git a/lib/genalloc.c b/lib/genalloc.c index 9fc31292cfa1..24d20ca7e91b 100644 --- a/lib/genalloc.c +++ b/lib/genalloc.c @@ -472,7 +472,7 @@ void *gen_pool_dma_zalloc_align(struct gen_pool *pool, size_t size, EXPORT_SYMBOL(gen_pool_dma_zalloc_align); /** - * gen_pool_free - free allocated special memory back to the pool + * gen_pool_free_owner - free allocated special memory back to the pool * @pool: pool to free to * @addr: starting address of memory to free back to pool * @size: size in bytes of memory to free diff --git a/scripts/jobserver-count b/scripts/jobserver-count new file mode 100755 index 000000000000..0b482d6884d2 --- /dev/null +++ b/scripts/jobserver-count @@ -0,0 +1,58 @@ +#!/usr/bin/env python +# SPDX-License-Identifier: GPL-2.0+ +# +# This determines how many parallel tasks "make" is expecting, as it is +# not exposed via an special variables. +# https://www.gnu.org/software/make/manual/html_node/POSIX-Jobserver.html#POSIX-Jobserver +from __future__ import print_function +import os, sys, fcntl, errno + +# Default parallelism is "1" unless overridden on the command-line. +default="1" +if len(sys.argv) > 1: + default=sys.argv[1] + +# Set non-blocking for a given file descriptor. +def nonblock(fd): + flags = fcntl.fcntl(fd, fcntl.F_GETFL) + fcntl.fcntl(fd, fcntl.F_SETFL, flags | os.O_NONBLOCK) + return fd + +# Extract and prepare jobserver file descriptors from envirnoment. +try: + # Fetch the make environment options. + flags = os.environ['MAKEFLAGS'] + + # Look for "--jobserver=R,W" + opts = [x for x in flags.split(" ") if x.startswith("--jobserver")] + + # Parse out R,W file descriptor numbers and set them nonblocking. + fds = opts[0].split("=", 1)[1] + reader, writer = [int(x) for x in fds.split(",", 1)] + reader = nonblock(reader) +except (KeyError, IndexError, ValueError, IOError): + # Any missing environment strings or bad fds should result in just + # using the default specified parallelism. + print(default) + sys.exit(0) + +# Read out as many jobserver slots as possible. +jobs = b"" +while True: + try: + slot = os.read(reader, 1) + jobs += slot + except (OSError, IOError) as e: + if e.errno == errno.EWOULDBLOCK: + # Stop when reach the end of the jobserver queue. + break + raise e +# Return all the reserved slots. +os.write(writer, jobs) + +# If the jobserver was (impossibly) full or communication failed, use default. +if len(jobs) < 1: + print(default) + +# Report available slots (with a bump for our caller's reserveration). +print(len(jobs) + 1) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 81dc91760b23..a529375c8536 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1062,7 +1062,7 @@ sub dump_struct($$) { my $x = shift; my $file = shift; - if ($x =~ /(struct|union)\s+(\w+)\s*\{(.*)\}(\s*(__packed|__aligned|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*/) { + if ($x =~ /(struct|union)\s+(\w+)\s*\{(.*)\}(\s*(__packed|__aligned|____cacheline_aligned_in_smp|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*/) { my $decl_type = $1; $declaration_name = $2; my $members = $3; @@ -1073,10 +1073,11 @@ sub dump_struct($$) { # strip comments: $members =~ s/\/\*.*?\*\///gos; # strip attributes - $members =~ s/\s*__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)//gi; - $members =~ s/\s*__aligned\s*\([^;]*\)//gos; - $members =~ s/\s*__packed\s*//gos; - $members =~ s/\s*CRYPTO_MINALIGN_ATTR//gos; + $members =~ s/\s*__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)/ /gi; + $members =~ s/\s*__aligned\s*\([^;]*\)/ /gos; + $members =~ s/\s*__packed\s*/ /gos; + $members =~ s/\s*CRYPTO_MINALIGN_ATTR/ /gos; + $members =~ s/\s*____cacheline_aligned_in_smp/ /gos; # replace DECLARE_BITMAP $members =~ s/DECLARE_BITMAP\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos; # replace DECLARE_HASHTABLE diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index 3b638c0e1a4f..68385fa62ff4 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -124,11 +124,13 @@ sub add_package($$) sub check_missing_file($$$) { - my $file = shift; + my $files = shift; my $package = shift; my $is_optional = shift; - return if(-e $file); + for (@$files) { + return if(-e $_); + } add_package($package, $is_optional); } @@ -343,10 +345,11 @@ sub give_debian_hints() ); if ($pdf) { - check_missing_file("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf", + check_missing_file(["/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"], "fonts-dejavu", 2); - check_missing_file("/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc", + check_missing_file(["/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc", + "/usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc"], "fonts-noto-cjk", 2); } @@ -413,7 +416,7 @@ sub give_redhat_hints() } if ($pdf) { - check_missing_file("/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc", + check_missing_file(["/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc"], "google-noto-sans-cjk-ttc-fonts", 2); } @@ -498,7 +501,7 @@ sub give_mageia_hints() $map{"latexmk"} = "texlive-collection-basic"; if ($pdf) { - check_missing_file("/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc", + check_missing_file(["/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc"], "google-noto-sans-cjk-ttc-fonts", 2); } @@ -528,7 +531,7 @@ sub give_arch_linux_hints() check_pacman_missing(\@archlinux_tex_pkgs, 2) if ($pdf); if ($pdf) { - check_missing_file("/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc", + check_missing_file(["/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc"], "noto-fonts-cjk", 2); } @@ -549,11 +552,11 @@ sub give_gentoo_hints() "rsvg-convert" => "gnome-base/librsvg", ); - check_missing_file("/usr/share/fonts/dejavu/DejaVuSans.ttf", + check_missing_file(["/usr/share/fonts/dejavu/DejaVuSans.ttf"], "media-fonts/dejavu", 2) if ($pdf); if ($pdf) { - check_missing_file("/usr/share/fonts/noto-cjk/NotoSansCJKsc-Regular.otf", + check_missing_file(["/usr/share/fonts/noto-cjk/NotoSansCJKsc-Regular.otf"], "media-fonts/noto-cjk", 2); } @@ -645,6 +648,12 @@ sub check_distros() # Common dependencies # +sub deactivate_help() +{ + printf "\tIf you want to exit the virtualenv, you can use:\n"; + printf "\tdeactivate\n"; +} + sub check_needs() { # Check for needed programs/tools @@ -686,6 +695,7 @@ sub check_needs() if ($need_sphinx && scalar @activates > 0 && $activates[0] ge $min_activate) { printf "\nNeed to activate a compatible Sphinx version on virtualenv with:\n"; printf "\t. $activates[0]\n"; + deactivate_help(); exit (1); } else { my $rec_activate = "$virtenv_dir/bin/activate"; @@ -697,6 +707,7 @@ sub check_needs() printf "\t$virtualenv $virtenv_dir\n"; printf "\t. $rec_activate\n"; printf "\tpip install -r $requirement_file\n"; + deactivate_help(); $need++ if (!$rec_sphinx_upgrade); } |