Skip to content

L
linux
Commit ff613595 authored by Linus Torvalds's avatar Linus Torvalds
Browse files
Options

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

Pull documentation updates from Jonathan Corbet:
 "A much quieter cycle for documentation (happily), with, one hopes, the
  bulk of the churn behind us. Significant stuff in this pull includes:

   - A set of new Chinese translations

   - Italian translation updates

   - A mechanism from Mauro to automatically format
     Documentation/features for the built docs

   - Automatic cross references without explicit :ref: markup

   - A new reset-controller document

   - An extensive new document on reporting problems from Thorsten

  That last patch also adds the CC-BY-4.0 license to LICENSES/dual;
  there was some discussion on this, but we seem to have consensus and
  an ack from Greg for that addition"

* tag 'docs-5.11' of git://git.lwn.net/linux: (50 commits)
  docs: fix broken cross reference in translations/zh_CN
  docs: Note that sphinx 1.7 will be required soon
  docs: update requirements to install six module
  docs: reporting-issues: move 'outdated, need help' note to proper place
  docs: Update documentation to reflect what TAINT_CPU_OUT_OF_SPEC means
  docs: add a reset controller chapter to the driver API docs
  docs: make reporting-bugs.rst obsolete
  docs: Add a new text describing how to report bugs
  LICENSES: Add the CC-BY-4.0 license
  Documentation: fix multiple typos found in the admin-guide subdirectory
  Documentation: fix typos found in admin-guide subdirectory
  kernel-doc: Fix example in Nested structs/unions
  docs: clean up sysctl/kernel: titles, version
  docs: trace: fix event state structure name
  docs: nios2: add missing ReST file
  scripts: get_feat.pl: reduce table width for all features output
  scripts: get_feat.pl: change the group by order
  scripts: get_feat.pl: make complete table more coincise
  scripts: kernel-doc: fix parsing function-like typedefs
  Documentation: fix typos found in process, dev-tools, and doc-guide subdirectories
  ...
parents f9b4240b 47e44ed0
Hide whitespace changes
Inline Side-by-side
Showing with 4228 additions and 444 deletions
Documentation/ABI/testing/configfs-usb-gadget-ecm
View file @ ff613595
......@@ -7,7 +7,7 @@ Description:
ifname
- network device interface name associated with
this function instance
qmult
qmult
- queue length multiplier for high and
super speed
host_addr
......
Documentation/ABI/testing/procfs-attr-current 0 → 100644
View file @ ff613595
What: /proc/*/attr/current
Contact: linux-security-module@vger.kernel.org,
selinux@vger.kernel.org,
apparmor@lists.ubuntu.com
Description: The current security information used by a Linux
security module (LSM) that is active on the system.
The details of permissions required to read from
this interface and hence obtain the security state
of the task identified is LSM dependent.
A process cannot write to this interface unless it
refers to itself.
The other details of permissions required to write to
this interface and hence change the security state of
the task identified are LSM dependent.
The format of the data used by this interface is LSM
dependent.
SELinux, Smack and AppArmor provide this interface.
Users: SELinux user-space
Smack user-space
AppArmor user-space
Documentation/ABI/testing/procfs-attr-exec 0 → 100644
View file @ ff613595
What: /proc/*/attr/exec
Contact: linux-security-module@vger.kernel.org,
selinux@vger.kernel.org,
apparmor@lists.ubuntu.com
Description: The security information to be used on the process
by a Linux security module (LSM) active on the system
after a subsequent exec() call.
The details of permissions required to read from
this interface and hence obtain the security state
of the task identified is LSM dependent.
A process cannot write to this interface unless it
refers to itself.
The other details of permissions required to write to
this interface and hence change the security state of
the task identified are LSM dependent.
The format of the data used by this interface is LSM
dependent.
SELinux and AppArmor provide this interface.
Users: SELinux user-space
AppArmor user-space
Documentation/ABI/testing/procfs-attr-prev 0 → 100644
View file @ ff613595
What: /proc/*/attr/prev
Contact: linux-security-module@vger.kernel.org,
selinux@vger.kernel.org,
apparmor@lists.ubuntu.com
Description: The security information used on the process by
a Linux security module (LSM) active on the system
prior to the most recent exec() call.
The details of permissions required to read from
this interface is LSM dependent.
A process cannot write to this interface unless it
refers to itself.
The other details of permissions required to write to
this interface are LSM dependent.
The format of the data used by this interface is LSM
dependent.
SELinux and AppArmor provide this interface.
Users: SELinux user-space
AppArmor user-space
Documentation/ABI/testing/sysfs-devices-memory
View file @ ff613595
......@@ -19,7 +19,7 @@ Description:
identify removable sections of the memory before attempting
potentially expensive hot-remove memory operation
Users: hotplug memory remove tools
http://www.ibm.com/developerworks/wikis/display/LinuxP/powerpc-utils
http://www.ibm.com/developerworks/wikis/display/LinuxP/powerpc-utils
What: /sys/devices/system/memory/memoryX/phys_device
Date: September 2008
......
Documentation/ABI/testing/sysfs-fs-ext4
View file @ ff613595
......@@ -33,7 +33,7 @@ What: /sys/fs/ext4/<disk>/mb_order2_req
Date: March 2008
Contact: "Theodore Ts'o" <tytso@mit.edu>
Description:
Tuning parameter which controls the minimum size for
Tuning parameter which controls the minimum size for
requests (as a power of 2) where the buddy cache is
used
......
Documentation/ABI/testing/sysfs-module
View file @ ff613595
......@@ -25,7 +25,7 @@ Description: Maximum time allowed for periodic transfers per microframe (μs)
However there are cases, when 80% max isochronous bandwidth is
too limiting. For example two video streams could require 110
microseconds of isochronous bandwidth per microframe to work
together.
together.
Through this setting it is possible to raise the limit so that
the host controller would allow allocating more than 100
......
Documentation/ABI/testing/sysfs-platform-renesas_usb3
View file @ ff613595
......@@ -12,6 +12,6 @@ Description:
- "peripheral" - switching mode from host to peripheral.
Read the file, then it shows the following strings:
- "host" - The mode is host now.
- "peripheral" - The mode is peripheral now.
Documentation/admin-guide/README.rst
View file @ ff613595
......@@ -398,8 +398,8 @@ If something goes wrong
If you for some reason cannot do the above (you have a pre-compiled
kernel image or similar), telling me as much about your setup as
possible will help. Please read the :ref:`admin-guide/reporting-bugs.rst <reportingbugs>`
document for details.
possible will help. Please read
'Documentation/admin-guide/reporting-issues.rst' for details.
- Alternatively, you can use gdb on a running kernel. (read-only; i.e. you
cannot change values or set break points.) To do this, first compile the
......
Documentation/admin-guide/acpi/cppc_sysfs.rst
View file @ ff613595
......@@ -8,7 +8,7 @@ CPPC
====
CPPC defined in the ACPI spec describes a mechanism for the OS to manage the
performance of a logical processor on a contigious and abstract performance
performance of a logical processor on a contiguous and abstract performance
scale. CPPC exposes a set of registers to describe abstract performance scale,
to request performance levels and to measure per-cpu delivered performance.
......@@ -45,7 +45,7 @@ for each cpu X::
* lowest_freq : CPU frequency corresponding to lowest_perf (in MHz).
* nominal_freq : CPU frequency corresponding to nominal_perf (in MHz).
The above frequencies should only be used to report processor performance in
freqency instead of abstract scale. These values should not be used for any
frequency instead of abstract scale. These values should not be used for any
functional decisions.
* feedback_ctrs : Includes both Reference and delivered performance counter.
......
Documentation/admin-guide/binderfs.rst
View file @ ff613595
......@@ -70,5 +70,5 @@ Deleting binder Devices
Binderfs binder devices can be deleted via `unlink() <unlink_>`_. This means
that the `rm() <rm_>`_ tool can be used to delete them. Note that the
``binder-control`` device cannot be deleted since this would make the binderfs
instance unuseable. The ``binder-control`` device will be deleted when the
instance unusable. The ``binder-control`` device will be deleted when the
binderfs instance is unmounted and all references to it have been dropped.
Documentation/admin-guide/blockdev/paride.rst
View file @ ff613595
......@@ -220,7 +220,7 @@ example::
Finally, you can load high-level drivers for each kind of device that
you have connected. By default, each driver will autoprobe for a single
device, but you can support up to four similar devices by giving their
individual co-ordinates when you load the driver.
individual coordinates when you load the driver.
For example, if you had two no-name CD-ROM drives both using the
KingByte KBIC-951A adapter, one on port 0x378 and the other on 0x3bc
......
Documentation/admin-guide/blockdev/zram.rst
View file @ ff613595
......@@ -360,7 +360,7 @@ like below::
/sys/block/zram0/writeback_limit.
$ echo 1 > /sys/block/zram0/writeback_limit_enable
If admins want to allow further write again once the bugdet is exhausted,
If admins want to allow further write again once the budget is exhausted,
he could do it like below::
$ echo $((400<<MB_SHIFT>>4K_SHIFT)) > \
......
Documentation/admin-guide/bug-bisect.rst
View file @ ff613595
......@@ -15,7 +15,7 @@ give up. Report as much as you have found to the relevant maintainer. See
MAINTAINERS for who that is for the subsystem you have worked on.
Before you submit a bug report read
:ref:`Documentation/admin-guide/reporting-bugs.rst <reportingbugs>`.
'Documentation/admin-guide/reporting-issues.rst'.
Devices not appearing
=====================
......
Documentation/admin-guide/bug-hunting.rst
View file @ ff613595
......@@ -263,7 +263,7 @@ Please notice that it will point to:
- The last developers that touched the source code (if this is done inside
a git tree). On the above example, Tejun and Bhaktipriya (in this
specific case, none really envolved on the development of this file);
specific case, none really involved on the development of this file);
- The driver maintainer (Hans Verkuil);
- The subsystem maintainer (Mauro Carvalho Chehab);
- The driver and/or subsystem mailing list (linux-media@vger.kernel.org);
......
Documentation/admin-guide/cifs/introduction.rst
View file @ ff613595
......@@ -9,7 +9,7 @@ Introduction
PC operating systems. New and improved versions of CIFS are now
called SMB2 and SMB3. Use of SMB3 (and later, including SMB3.1.1)
is strongly preferred over using older dialects like CIFS due to
security reaasons. All modern dialects, including the most recent,
security reasons. All modern dialects, including the most recent,
SMB3.1.1 are supported by the CIFS VFS module. The SMB3 protocol
is implemented and supported by all major file servers
such as all modern versions of Windows (including Windows 2016
......
Documentation/admin-guide/cifs/usage.rst
View file @ ff613595
......@@ -115,7 +115,7 @@ later source tree in docs/manpages/mount.cifs.8
Allowing User Unmounts
======================
To permit users to ummount directories that they have user mounted (see above),
To permit users to unmount directories that they have user mounted (see above),
the utility umount.cifs may be used. It may be invoked directly, or if
umount.cifs is placed in /sbin, umount can invoke the cifs umount helper
(at least for most versions of the umount utility) for umount of cifs
......@@ -197,7 +197,7 @@ that is ignored by local server applications and non-cifs clients and that will
not be traversed by the Samba server). This is opaque to the Linux client
application using the cifs vfs. Absolute symlinks will work to Samba 3.0.5 or
later, but only for remote clients using the CIFS Unix extensions, and will
be invisbile to Windows clients and typically will not affect local
be invisible to Windows clients and typically will not affect local
applications running on the same server as Samba.
Use instructions
......@@ -267,7 +267,7 @@ would be forbidden for Windows/CIFS semantics) as long as the server is
configured for Unix Extensions (and the client has not disabled
/proc/fs/cifs/LinuxExtensionsEnabled). In addition the mount option
``mapposix`` can be used on CIFS (vers=1.0) to force the mapping of
illegal Windows/NTFS/SMB characters to a remap range (this mount parm
illegal Windows/NTFS/SMB characters to a remap range (this mount parameter
is the default for SMB3). This remap (``mapposix``) range is also
compatible with Mac (and "Services for Mac" on some older Windows).
......
Documentation/admin-guide/device-mapper/dm-crypt.rst
View file @ ff613595
......@@ -46,7 +46,7 @@ Parameters::
capi:authenc(hmac(sha256),xts(aes))-random
capi:rfc7539(chacha20,poly1305)-random
The /proc/crypto contains a list of curently loaded crypto modes.
The /proc/crypto contains a list of currently loaded crypto modes.
<key>
Key used for encryption. It is encoded either as a hexadecimal number
......@@ -92,7 +92,7 @@ Parameters::
<#opt_params>
Number of optional parameters. If there are no optional parameters,
the optional paramaters section can be skipped or #opt_params can be zero.
the optional parameters section can be skipped or #opt_params can be zero.
Otherwise #opt_params is the number of following arguments.
Example of optional parameters section:
......
Documentation/admin-guide/device-mapper/dm-integrity.rst
View file @ ff613595
......@@ -117,7 +117,7 @@ journal_watermark:number
commit_time:number
Commit time in milliseconds. When this time passes, the journal is
written. The journal is also written immediatelly if the FLUSH
written. The journal is also written immediately if the FLUSH
request is received.
internal_hash:algorithm(:key) (the key is optional)
......@@ -147,7 +147,7 @@ journal_crypt:algorithm(:key) (the key is optional)
"salsa20" or "ctr(aes)").
The journal contains history of last writes to the block device,
an attacker reading the journal could see the last sector nubmers
an attacker reading the journal could see the last sector numbers
that were written. From the sector numbers, the attacker can infer
the size of files that were written. To protect against this
situation, you can encrypt the journal.
......
Documentation/admin-guide/device-mapper/dm-raid.rst
View file @ ff613595
......@@ -418,6 +418,6 @@ Version History
specific devices are requested via rebuild. Fix RAID leg
rebuild errors.
1.15.0 Fix size extensions not being synchronized in case of new MD bitmap
pages allocated; also fix those not occuring after previous reductions
pages allocated; also fix those not occurring after previous reductions
1.15.1 Fix argument count and arguments for rebuild/write_mostly/journal_(dev|mode)
on the status line.
Documentation/admin-guide/device-mapper/dm-zoned.rst
View file @ ff613595
......@@ -24,7 +24,7 @@ The dm-zoned implementation is simple and minimizes system overhead (CPU
and memory usage as well as storage capacity loss). For a 10TB
host-managed disk with 256 MB zones, dm-zoned memory usage per disk
instance is at most 4.5 MB and as little as 5 zones will be used
internally for storing metadata and performaing reclaim operations.
internally for storing metadata and performing reclaim operations.
dm-zoned target devices are formatted and checked using the dmzadm
utility available at:
......@@ -102,7 +102,7 @@ the buffer zone assigned. If the accessed chunk has no mapping, or the
accessed blocks are invalid, the read buffer is zeroed and the read
operation terminated.
After some time, the limited number of convnetional zones available may
After some time, the limited number of conventional zones available may
be exhausted (all used to map chunks or buffer sequential zones) and
unaligned writes to unbuffered chunks become impossible. To avoid this
situation, a reclaim process regularly scans used conventional zones and
......@@ -158,7 +158,7 @@ Ex::
dmzadm --format /dev/sdxx /dev/sdyy
Fomatted device(s) can be started with the dmzadm utility, too.:
Formatted device(s) can be started with the dmzadm utility, too.:
Ex::
......
Documentation/admin-guide/device-mapper/verity.rst
View file @ ff613595
......@@ -69,7 +69,7 @@ Construction Parameters
<#opt_params>
Number of optional parameters. If there are no optional parameters,
the optional paramaters section can be skipped or #opt_params can be zero.
the optional parameters section can be skipped or #opt_params can be zero.
Otherwise #opt_params is the number of following arguments.
Example of optional parameters section:
......
Documentation/admin-guide/device-mapper/writecache.rst
View file @ ff613595
......@@ -37,10 +37,10 @@ Constructor parameters:
autocommit_blocks n (default: 64 for pmem, 65536 for ssd)
when the application writes this amount of blocks without
issuing the FLUSH request, the blocks are automatically
commited
committed
autocommit_time ms (default: 1000)
autocommit time in milliseconds. The data is automatically
commited if this time passes and no FLUSH request is
committed if this time passes and no FLUSH request is
received
fua (by default on)
applicable only to persistent memory - use the FUA flag
......
Documentation/admin-guide/features.rst 0 → 100644
View file @ ff613595
.. SPDX-License-Identifier: GPL-2.0
.. kernel-feat:: $srctree/Documentation/features
Documentation/admin-guide/hw-vuln/tsx_async_abort.rst
View file @ ff613595
......@@ -60,7 +60,7 @@ Hyper-Thread attacks are possible.
The victim of a malicious actor does not need to make use of TSX. Only the
attacker needs to begin a TSX transaction and raise an asynchronous abort
which in turn potenitally leaks data stored in the buffers.
which in turn potentially leaks data stored in the buffers.
More detailed technical information is available in the TAA specific x86
architecture section: :ref:`Documentation/x86/tsx_async_abort.rst <tsx_async_abort>`.
......
Documentation/admin-guide/index.rst
View file @ ff613595
......@@ -19,6 +19,7 @@ etc.
sysctl/index
abi
features
This section describes CPU vulnerabilities and their mitigations.
......@@ -33,7 +34,8 @@ problems and bugs in particular.
.. toctree::
:maxdepth: 1
reporting-bugs
reporting-issues
Reporting bugs (obsolete) <reporting-bugs>
security-bugs
bug-hunting
bug-bisect
......
Documentation/admin-guide/kernel-parameters.rst
View file @ ff613595
......@@ -172,6 +172,7 @@ parameter is applicable::
X86 Either 32-bit or 64-bit x86 (same as X86-32+X86-64)
X86_UV SGI UV support is enabled.
XEN Xen support is enabled
XTENSA xtensa architecture is enabled.
In addition, the following text indicates that the option::
......
Documentation/admin-guide/kernel-parameters.txt
View file @ ff613595
......@@ -2709,7 +2709,7 @@
option description.
memmap=nn[KMG]@ss[KMG]
[KNL] Force usage of a specific region of memory.
[KNL, X86, MIPS, XTENSA] Force usage of a specific region of memory.
Region of memory to be used is from ss to ss+nn.
If @ss[KMG] is omitted, it is equivalent to mem=nn[KMG],
which limits max address to nn[KMG].
......
Documentation/admin-guide/md.rst
View file @ ff613595
......@@ -221,7 +221,7 @@ All md devices contain:
layout
The ``layout`` for the array for the particular level. This is
simply a number that is interpretted differently by different
simply a number that is interpreted differently by different
levels. It can be written while assembling an array.
array_size
......
Documentation/admin-guide/media/bttv.rst
View file @ ff613595
......@@ -77,7 +77,7 @@ the Subsystem ID in the second line, looks like this:
only bt878-based cards can have a subsystem ID (which does not mean
that every card really has one). bt848 cards can't have a Subsystem
ID and therefore can't be autodetected. There is a list with the ID's
at :doc:`bttv-cardlist` (in case you are intrested or want to mail
at :doc:`bttv-cardlist` (in case you are interested or want to mail
patches with updates).
......
Documentation/admin-guide/media/dvb_references.rst
View file @ ff613595
......@@ -10,7 +10,7 @@ The DVB mailing list linux-dvb is hosted at vger. Please see
http://vger.kernel.org/vger-lists.html#linux-media for details.
There are also some other old lists hosted at:
https://linuxtv.org/lists.php. If you're insterested on that for historic
https://linuxtv.org/lists.php. If you're interested on that for historic
reasons, please check the archive at https://linuxtv.org/pipermail/linux-dvb/.
The media subsystem Wiki is hosted at https://linuxtv.org/wiki/.
......
Documentation/admin-guide/media/frontend-cardlist.rst
View file @ ff613595
......@@ -68,7 +68,7 @@ cx24116 Conexant CX24116 based
cx24117 Conexant CX24117 based
cx24120 Conexant CX24120 based
cx24123 Conexant CX24123 based
ds3000 Montage Tehnology DS3000 based
ds3000 Montage Technology DS3000 based
mb86a16 Fujitsu MB86A16 based
mt312 Zarlink VP310/MT312/ZL10313 based
s5h1420 Samsung S5H1420 based
......@@ -83,7 +83,7 @@ tda10086 Philips TDA10086 based
tda8083 Philips TDA8083 based
tda8261 Philips TDA8261 based
tda826x Philips TDA826X silicon tuner
ts2020 Montage Tehnology TS2020 based tuners
ts2020 Montage Technology TS2020 based tuners
tua6100 Infineon TUA6100 PLL
cx24113 Conexant CX24113/CX24128 tuner for DVB-S/DSS
itd1000 Integrant ITD1000 Zero IF tuner for DVB-S/DSS
......
Documentation/admin-guide/media/gspca-cardlist.rst
View file @ ff613595
......@@ -305,7 +305,7 @@ pac7302 093a:2625 Genius iSlim 310
pac7302 093a:2626 Labtec 2200
pac7302 093a:2627 Genius FaceCam 300
pac7302 093a:2628 Genius iLook 300
pac7302 093a:2629 Genious iSlim 300
pac7302 093a:2629 Genius iSlim 300
pac7302 093a:262a Webcam 300k
pac7302 093a:262c Philips SPC 230 NC
jl2005bcd 0979:0227 Various brands, 19 known cameras supported
......
Documentation/admin-guide/media/ipu3.rst
View file @ ff613595
......@@ -86,7 +86,7 @@ raw Bayer format that is specific to IPU3.
Let us take the example of ov5670 sensor connected to CSI2 port 0, for a
2592x1944 image capture.
Using the media contorller APIs, the ov5670 sensor is configured to send
Using the media controller APIs, the ov5670 sensor is configured to send
frames in packed raw Bayer format to IPU3 CSI2 receiver.
.. code-block:: none
......@@ -313,8 +313,8 @@ configuration steps of 0.03125 (1/32).
**Geometric Distortion Correction**
Geometric Distortion Correction is used to performe correction of distortions
and image filtering. It needs some extra filter and envelop padding pixels to
Geometric Distortion Correction is used to perform correction of distortions
and image filtering. It needs some extra filter and envelope padding pixels to
work, so the input resolution of GDC should be larger than the output
resolution.
......
Documentation/admin-guide/media/remote-controller.rst
View file @ ff613595
......@@ -68,7 +68,7 @@ Using without lircd
Xorg recognizes several IR keycodes that have its numerical value lower
than 247. With the advent of Wayland, the input driver got updated too,
and should now accept all keycodes. Yet, you may want to just reasign
and should now accept all keycodes. Yet, you may want to just reassign
the keycodes to something that your favorite media application likes.
This can be done by setting
......
Documentation/admin-guide/mm/index.rst
View file @ ff613595
......@@ -3,9 +3,9 @@ Memory Management
=================
Linux memory management subsystem is responsible, as the name implies,
for managing the memory in the system. This includes implemnetation of
for managing the memory in the system. This includes implementation of
virtual memory and demand paging, memory allocation both for kernel
internal structures and user space programms, mapping of files into
internal structures and user space programs, mapping of files into
processes address space and many other cool things.
Linux memory management is a complex system with many configurable
......
Documentation/admin-guide/mm/numaperf.rst
View file @ ff613595
......@@ -74,7 +74,7 @@ memory node's access class 0 initiators as follows::
/sys/devices/system/node/nodeY/access0/initiators/
These attributes apply only when accessed from nodes that have the
are linked under the this access's inititiators.
are linked under the this access's initiators.
The performance characteristics the kernel provides for the local initiators
are exported are as follows::
......
Documentation/admin-guide/mm/userfaultfd.rst
View file @ ff613595
......@@ -114,7 +114,7 @@ Notes:
you must provide some kind of page in your thread after reading from
the uffd. You must provide either ``UFFDIO_COPY`` or ``UFFDIO_ZEROPAGE``.
The normal behavior of the OS automatically providing a zero page on
an annonymous mmaping is not in place.
an anonymous mmaping is not in place.
- None of the page-delivering ioctls default to the range that you
registered with. You must fill in all fields for the appropriate
......
Documentation/admin-guide/module-signing.rst
View file @ ff613595
......@@ -106,7 +106,7 @@ This has a number of options available:
certificate and a private key.
If the PEM file containing the private key is encrypted, or if the
PKCS#11 token requries a PIN, this can be provided at build time by
PKCS#11 token requires a PIN, this can be provided at build time by
means of the ``KBUILD_SIGN_PIN`` variable.
......
Documentation/admin-guide/perf/imx-ddr.rst
View file @ ff613595
......@@ -4,7 +4,7 @@ Freescale i.MX8 DDR Performance Monitoring Unit (PMU)
There are no performance counters inside the DRAM controller, so performance
signals are brought out to the edge of the controller where a set of 4 x 32 bit
counters is implemented. This is controlled by the CSV modes programed in counter
counters is implemented. This is controlled by the CSV modes programmed in counter
control register which causes a large number of PERF signals to be generated.
Selection of the value for each counter is done via the config registers. There
......
Documentation/admin-guide/pm/intel-speed-select.rst
View file @ ff613595
......@@ -57,7 +57,7 @@ To get help on a command, another level of help is provided. For example for the
Summary of platform capability
------------------------------
To check the current platform and driver capaibilities, execute::
To check the current platform and driver capabilities, execute::
#intel-speed-select --info
......@@ -658,7 +658,7 @@ If -a option is not used, then the following steps are required before enabling
Intel(R) SST-BF:
- Discover Intel(R) SST-BF and note low and high priority base frequency
- Note the high prioity CPU list
- Note the high priority CPU list
- Enable CLOS using core-power feature set
- Configure CLOS parameters. Use CLOS.min to set to minimum performance
- Subscribe desired CPUs to CLOS groups
......
Documentation/admin-guide/pm/intel_pstate.rst
View file @ ff613595
......@@ -56,7 +56,7 @@ Operation Modes
``intel_pstate`` can operate in two different modes, active or passive. In the
active mode, it uses its own internal performance scaling governor algorithm or
allows the hardware to do preformance scaling by itself, while in the passive
allows the hardware to do performance scaling by itself, while in the passive
mode it responds to requests made by a generic ``CPUFreq`` governor implementing
a certain performance scaling algorithm. Which of them will be in effect
depends on what kernel command line options are used and on the capabilities of
......@@ -380,13 +380,13 @@ argument is passed to the kernel in the command line.
``no_turbo``
If set (equal to 1), the driver is not allowed to set any turbo P-states
(see `Turbo P-states Support`_). If unset (equalt to 0, which is the
(see `Turbo P-states Support`_). If unset (equal to 0, which is the
default), turbo P-states can be set by the driver.
[Note that ``intel_pstate`` does not support the general ``boost``
attribute (supported by some other scaling drivers) which is replaced
by this one.]
This attrubute does not affect the maximum supported frequency value
This attribute does not affect the maximum supported frequency value
supplied to the ``CPUFreq`` core and exposed via the policy interface,
but it affects the maximum possible value of per-policy P-state limits
(see `Interpretation of Policy Attributes`_ below for details).
......
Documentation/admin-guide/ramoops.rst
View file @ ff613595
......@@ -22,7 +22,7 @@ and type of the memory area are set using three variables:
* ``mem_address`` for the start
* ``mem_size`` for the size. The memory size will be rounded down to a
power of two.
* ``mem_type`` to specifiy if the memory type (default is pgprot_writecombine).
* ``mem_type`` to specify if the memory type (default is pgprot_writecombine).
Typically the default value of ``mem_type=0`` should be used as that sets the pstore
mapping to pgprot_writecombine. Setting ``mem_type=1`` attempts to use
......
Documentation/admin-guide/reporting-bugs.rst
View file @ ff613595
.. _reportingbugs:
.. note::
This document is obsolete, and will be replaced by
'Documentation/admin-guide/reporting-issues.rst' in the near future.
Reporting bugs
++++++++++++++
......
Documentation/admin-guide/reporting-issues.rst 0 → 100644
View file @ ff613595
.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0)
..
If you want to distribute this text under CC-BY-4.0 only, please use 'The
Linux kernel developers' for author attribution and link this as source:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/reporting-issues.rst
..
Note: Only the content of this RST file as found in the Linux kernel sources
is available under CC-BY-4.0, as versions of this text that were processed
(for example by the kernel's build system) might contain content taken from
files which use a more restrictive license.
.. important::
This document is being prepared to replace
'Documentation/admin-guide/reporting-bugs.rst'. The main work is done and
you are already free to follow its instructions when reporting issues to the
Linux kernel developers. But keep in mind, below text still needs a few
finishing touches and review. It was merged to the Linux kernel sources at
this stage to make this process easier and increase the text's visibility.
Any improvements for the text or other feedback is thus very much welcome.
Please send it to 'Thorsten Leemhuis <linux@leemhuis.info>' and 'Jonathan
Corbet <corbet@lwn.net>', ideally with 'Linux kernel mailing list (LKML)
<linux-kernel@vger.kernel.org>' and the 'Linux Kernel Documentation List
<linux-doc@vger.kernel.org>' in CC.
Areas in the text that still need work or discussion contain a hint like this
which point out the remaining issues; all of them start with the word "FIXME"
to make them easy to find.
Reporting issues
++++++++++++++++
The short guide (aka TL;DR)
===========================
If you're facing multiple issues with the Linux kernel at once, report each
separately to its developers. Try your best guess which kernel part might be
causing the issue. Check the :ref:`MAINTAINERS <maintainers>` file for how its
developers expect to be told about issues. Note, it's rarely
`bugzilla.kernel.org <https://bugzilla.kernel.org/>`_, as in almost all cases
the report needs to be sent by email!
Check the destination thoroughly for existing reports; also search the LKML
archives and the web. Join existing discussion if you find matches. If you
don't find any, install `the latest Linux mainline kernel
<https://kernel.org/>`_. Make sure it's vanilla, thus is not patched or using
add-on kernel modules. Also ensure the kernel is running in a healthy
environment and is not already tainted before the issue occurs.
If you can reproduce your issue with the mainline kernel, send a report to the
destination you determined earlier. Make sure it includes all relevant
information, which in case of a regression should mention the change that's
causing it which can often can be found with a bisection. Also ensure the
report reaches all people that need to know about it, for example the security
team, the stable maintainers or the developers of the patch that causes a
regression. Once the report is out, answer any questions that might be raised
and help where you can. That includes keeping the ball rolling: every time a
new rc1 mainline kernel is released, check if the issue is still happening
there and attach a status update to your initial report.
If you can not reproduce the issue with the mainline kernel, consider sticking
with it; if you'd like to use an older version line and want to see it fixed
there, first make sure it's still supported. Install its latest release as
vanilla kernel. If you cannot reproduce the issue there, try to find the commit
that fixed it in mainline or any discussion preceding it: those will often
mention if backporting is planed or considered too complex. If backporting was
not discussed, ask if it's in the cards. In case you don't find any commits or
a preceding discussion, see the Linux-stable mailing list archives for existing
reports, as it might be a regression specific to the version line. If it is,
report it like you would report a problem in mainline (including the
bisection).
If you reached this point without a solution, ask for advice one the
subsystem's mailing list.
Step-by-step guide how to report issues to the kernel maintainers
=================================================================
The above TL;DR outlines roughly how to report issues to the Linux kernel
developers. It might be all that's needed for people already familiar with
reporting issues to Free/Libre & Open Source Software (FLOSS) projects. For
everyone else there is this section. It is more detailed and uses a
step-by-step approach. It still tries to be brief for readability and leaves
out a lot of details; those are described below the step-by-step guide in a
reference section, which explains each of the steps in more detail.
Note: this section covers a few more aspects than the TL;DR and does things in
a slightly different order. That's in your interest, to make sure you notice
early if an issue that looks like a Linux kernel problem is actually caused by
something else. These steps thus help to ensure the time you invest in this
process won't feel wasted in the end:
* Stop reading this document and report the problem to your vendor instead,
unless you are running the latest mainline kernel already or are willing to
install it. This kernel must not be modified or enhanced in any way, and
thus be considered 'vanilla'.
* See if the issue you are dealing with qualifies as regression, security
issue, or a really severe problem: those are 'issues of high priority' that
need special handling in some steps that are about to follow.
* Check if your kernel was 'tainted' when the issue occurred, as the event
that made the kernel set this flag might be causing the issue you face.
* Locate the driver or kernel subsystem that seems to be causing the issue.
Find out how and where its developers expect reports. Note: most of the
time this won't be bugzilla.kernel.org, as issues typically need to be sent
by mail to a maintainer and a public mailing list.
* Search the archives of the bug tracker or mailing list in question
thoroughly for reports that might match your issue. Also check if you find
something with your favorite internet search engine or in the Linux Kernel
Mailing List (LKML) archives. If you find anything, join the discussion
instead of sending a new report.
* Create a fresh backup and put system repair and restore tools at hand.
* Ensure your system does not enhance its kernels by building additional
kernel modules on-the-fly, which solutions like DKMS might be doing locally
without your knowledge.
* Make sure it's not the kernel's surroundings that are causing the issue
you face.
* Write down coarsely how to reproduce the issue. If you deal with multiple
issues at once, create separate notes for each of them and make sure they
work independently on a freshly booted system. That's needed, as each issue
needs to get reported to the kernel developers separately, unless they are
strongly entangled.
After these preparations you'll now enter the main part:
* Install the latest Linux mainline kernel: that's where all issues get
fixed first, because it's the version line the kernel developers mainly
care about. Testing and reporting with the latest Linux stable kernel can
be an acceptable alternative in some situations, for example during the
merge window; but during that period you might want to suspend your efforts
till its end anyway.
* Ensure the kernel you just installed does not 'taint' itself when
running.
* Reproduce the issue with the kernel you just installed. If it doesn't show
up there, head over to the instructions for issues only happening with
stable and longterm kernels.
* Optimize your notes: try to find and write the most straightforward way to
reproduce your issue. Make sure the end result has all the important
details, and at the same time is easy to read and understand for others
that hear about it for the first time. And if you learned something in this
process, consider searching again for existing reports about the issue.
* If the failure includes a stack dump, like an Oops does, consider decoding
it to find the offending line of code.
* If your problem is a regression, try to narrow down when the issue was
introduced as much as possible.
* Start to compile the report by writing a detailed description about the
issue. Always mention a few things: the latest kernel version you installed
for reproducing, the Linux Distribution used, and your notes on how to
reproduce the issue. Ideally, make the kernel's build configuration
(.config) and the output from ``dmesg`` available somewhere on the net and
link to it. Include or upload all other information that might be relevant,
like the output/screenshot of an Oops or the output from ``lspci``. Once
you wrote this main part, insert a normal length paragraph on top of it
outlining the issue and the impact quickly. On top of this add one sentence
that briefly describes the problem and gets people to read on. Now give the
thing a descriptive title or subject that yet again is shorter. Then you're
ready to send or file the report like the MAINTAINERS file told you, unless
you are dealing with one of those 'issues of high priority': they need
special care which is explained in 'Special handling for high priority
issues' below.
* Wait for reactions and keep the thing rolling until you can accept the
outcome in one way or the other. Thus react publicly and in a timely manner
to any inquiries. Test proposed fixes. Do proactive testing: retest with at
least every first release candidate (RC) of a new mainline version and
report your results. Send friendly reminders if things stall. And try to
help yourself, if you don't get any help or if it's unsatisfying.
Reporting issues only occurring in older kernel version lines
-------------------------------------------------------------
This section is for you, if you tried the latest mainline kernel as outlined
above, but failed to reproduce your issue there; at the same time you want to
see the issue fixed in older version lines or a vendor kernel that's regularly
rebased on new stable or longterm releases. If that case follow these steps:
* Prepare yourself for the possibility that going through the next few steps
might not get the issue solved in older releases: the fix might be too big
or risky to get backported there.
* Check if the kernel developers still maintain the Linux kernel version
line you care about: go to the front page of kernel.org and make sure it
mentions the latest release of the particular version line without an
'[EOL]' tag.
* Check the archives of the Linux stable mailing list for existing reports.
* Install the latest release from the particular version line as a vanilla
kernel. Ensure this kernel is not tainted and still shows the problem, as
the issue might have already been fixed there.
* Search the Linux kernel version control system for the change that fixed
the issue in mainline, as its commit message might tell you if the fix is
scheduled for backporting already. If you don't find anything that way,
search the appropriate mailing lists for posts that discuss such an issue
or peer-review possible fixes; then check the discussions if the fix was
deemed unsuitable for backporting. If backporting was not considered at
all, join the newest discussion, asking if it's in the cards.
* Check if you're dealing with a regression that was never present in
mainline by installing the first release of the version line you care
about. If the issue doesn't show up with it, you basically need to report
the issue with this version like you would report a problem with mainline
(see above). This ideally includes a bisection followed by a search for
existing reports on the net; with the help of the subject and the two
relevant commit-ids. If that doesn't turn up anything, write the report; CC
or forward the report to the stable maintainers, the stable mailing list,
and those who authored the change. Include the shortened commit-id if you
found the change that causes it.
* One of the former steps should lead to a solution. If that doesn't work
out, ask the maintainers for the subsystem that seems to be causing the
issue for advice; CC the mailing list for the particular subsystem as well
as the stable mailing list.
Reference section: Reporting issues to the kernel maintainers
=============================================================
The detailed guides above outline all the major steps in brief fashion, which
should be enough for most people. But sometimes there are situations where even
experienced users might wonder how to actually do one of those steps. That's
what this section is for, as it will provide a lot more details on each of the
above steps. Consider this as reference documentation: it's possible to read it
from top to bottom. But it's mainly meant to skim over and a place to look up
details how to actually perform those steps.
A few words of general advice before digging into the details:
* The Linux kernel developers are well aware this process is complicated and
demands more than other FLOSS projects. We'd love to make it simpler. But
that would require work in various places as well as some infrastructure,
which would need constant maintenance; nobody has stepped up to do that
work, so that's just how things are for now.
* A warranty or support contract with some vendor doesn't entitle you to
request fixes from developers in the upstream Linux kernel community: such
contracts are completely outside the scope of the Linux kernel, its
development community, and this document. That's why you can't demand
anything such a contract guarantees in this context, not even if the
developer handling the issue works for the vendor in question. If you want
to claim your rights, use the vendor's support channel instead. When doing
so, you might want to mention you'd like to see the issue fixed in the
upstream Linux kernel; motivate them by saying it's the only way to ensure
the fix in the end will get incorporated in all Linux distributions.
* If you never reported an issue to a FLOSS project before you should consider
reading `How to Report Bugs Effectively
<https://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_, `How To Ask
Questions The Smart Way
<http://www.catb.org/esr/faqs/smart-questions.html>`_, and `How to ask good
questions <https://jvns.ca/blog/good-questions/>`_.
With that off the table, find below the details on how to properly report
issues to the Linux kernel developers.
Make sure you're using the upstream Linux kernel
------------------------------------------------
*Stop reading this document and report the problem to your vendor instead,
unless you are running the latest mainline kernel already or are willing to
install it. This kernel must not be modified or enhanced in any way, and
thus be considered 'vanilla'.*
Like most programmers, Linux kernel developers don't like to spend time dealing
with reports for issues that don't even happen with the source code they
maintain: it's just a waste everybody's time, yours included. That's why you
later will have to test your issue with the latest 'vanilla' kernel: a kernel
that was build using the Linux sources taken straight from `kernel.org
<https://kernel.org/>`_ and not modified or enhanced in any way.
Almost all kernels used in devices (Computers, Laptops, Smartphones, Routers,
…) and most kernels shipped by Linux distributors are ancient from the point of
kernel development and heavily modified. They thus do not qualify for reporting
an issue to the Linux kernel developers: the issue you face with such a kernel
might be fixed already or caused by the changes or additions, even if they look
small or totally unrelated. That's why issues with such kernels need to be
reported to the vendor that distributed it. Its developers should look into the
report and, in case it turns out to be an upstream issue, fix it directly
upstream or report it there. In practice that sometimes does not work out. If
that the case, you might want to circumvent the vendor by installing the latest
mainline kernel yourself and reporting the issue as outlined in this document;
just make sure to use really fresh kernel (see below).
.. note::
FIXME: Should we accept reports for issues with kernel images that are pretty
close to vanilla? But when are they close enough and how to put that line in
words? Maybe something like this?
*Note: Some Linux kernel developers accept reports from vendor kernels that
are known to be close to upstream. That for example is often the case for
the kernels that Debian GNU/Linux Sid or Fedora Rawhide ship, which are
normally following mainline closely and carry only a few patches. So a
report with one of these might be accepted by the developers that need to
handle it. But if they do, depends heavily on the individual developers and
the issue at hand. That's why installing a mainline vanilla kernel is the
safe bet.*
*Arch Linux, other Fedora releases, and openSUSE Tumbleweed often use quite
recent stable kernels that are pretty close to upstream, too. Some
developers accept bugs from them as well. But note that you normally should
avoid stable kernels for reporting issues and use a mainline kernel instead
(see below).*
Are there any other major Linux distributions that should be mentioned here?
Issue of high priority?
-----------------------
*See if the issue you are dealing with qualifies as regression, security
issue, or a really severe problem: those are 'issues of high priority' that
need special handling in some steps that are about to follow.*
Linus Torvalds and the leading Linux kernel developers want to see some issues
fixed as soon as possible, hence there are 'issues of high priority' that get
handled slightly differently in the reporting process. Three type of cases
qualify: regressions, security issues, and really severe problems.
You deal with a 'regression' if something that worked with an older version of
the Linux kernel does not work with a newer one or somehow works worse with it.
It thus is a regression when a WiFi driver that did a fine job with Linux 5.7
somehow misbehaves with 5.8 or doesn't work at all. It's also a regression if
an application shows erratic behavior with a newer kernel, which might happen
due to incompatible changes in the interface between the kernel and the
userland (like procfs and sysfs). Significantly reduced performance or
increased power consumption also qualify as regression. But keep in mind: the
new kernel needs to be built with a configuration that is similar to the one
from the old kernel (see below how to achieve that). That's because the kernel
developers sometimes can not avoid incompatibilities when implementing new
features; but to avoid regressions such features have to be enabled explicitly
during build time configuration.
What qualifies as security issue is left to your judgment. Consider reading
'Documentation/admin-guide/security-bugs.rst' before proceeding, as it
provides additional details how to best handle security issues.
An issue is a 'really severe problem' when something totally unacceptably bad
happens. That's for example the case when a Linux kernel corrupts the data it's
handling or damages hardware it's running on. You're also dealing with a severe
issue when the kernel suddenly stops working with an error message ('kernel
panic') or without any farewell note at all. Note: do not confuse a 'panic' (a
fatal error where the kernel stop itself) with a 'Oops' (a recoverable error),
as the kernel remains running after the latter.
Check 'taint' flag
------------------
*Check if your kernel was 'tainted' when the issue occurred, as the event
that made the kernel set this flag might be causing the issue you face.*
The kernel marks itself with a 'taint' flag when something happens that might
lead to follow-up errors that look totally unrelated. The issue you face might
be such an error if your kernel is tainted. That's why it's in your interest to
rule this out early before investing more time into this process. This is the
only reason why this step is here, as this process later will tell you to
install the latest mainline kernel; you will need to check the taint flag again
then, as that's when it matters because it's the kernel the report will focus
on.
On a running system is easy to check if the kernel tainted itself: if ``cat
/proc/sys/kernel/tainted`` returns '0' then the kernel is not tainted and
everything is fine. Checking that file is impossible in some situations; that's
why the kernel also mentions the taint status when it reports an internal
problem (a 'kernel bug'), a recoverable error (a 'kernel Oops') or a
non-recoverable error before halting operation (a 'kernel panic'). Look near
the top of the error messages printed when one of these occurs and search for a
line starting with 'CPU:'. It should end with 'Not tainted' if the kernel was
not tainted when it noticed the problem; it was tainted if you see 'Tainted:'
followed by a few spaces and some letters.
If your kernel is tainted, study 'Documentation/admin-guide/tainted-kernels.rst'
to find out why. Try to eliminate the reason. Often it's caused by one these
three things:
1. A recoverable error (a 'kernel Oops') occurred and the kernel tainted
itself, as the kernel knows it might misbehave in strange ways after that
point. In that case check your kernel or system log and look for a section
that starts with this::
Oops: 0000 [#1] SMP
That's the first Oops since boot-up, as the '#1' between the brackets shows.
Every Oops and any other problem that happens after that point might be a
follow-up problem to that first Oops, even if both look totally unrelated.
Rule this out by getting rid of the cause for the first Oops and reproducing
the issue afterwards. Sometimes simply restarting will be enough, sometimes
a change to the configuration followed by a reboot can eliminate the Oops.
But don't invest too much time into this at this point of the process, as
the cause for the Oops might already be fixed in the newer Linux kernel
version you are going to install later in this process.
2. Your system uses a software that installs its own kernel modules, for
example Nvidia's proprietary graphics driver or VirtualBox. The kernel
taints itself when it loads such module from external sources (even if
they are Open Source): they sometimes cause errors in unrelated kernel
areas and thus might be causing the issue you face. You therefore have to
prevent those modules from loading when you want to report an issue to the
Linux kernel developers. Most of the time the easiest way to do that is:
temporarily uninstall such software including any modules they might have
installed. Afterwards reboot.
3. The kernel also taints itself when it's loading a module that resides in
the staging tree of the Linux kernel source. That's a special area for
code (mostly drivers) that does not yet fulfill the normal Linux kernel
quality standards. When you report an issue with such a module it's
obviously okay if the kernel is tainted; just make sure the module in
question is the only reason for the taint. If the issue happens in an
unrelated area reboot and temporarily block the module from being loaded
by specifying ``foo.blacklist=1`` as kernel parameter (replace 'foo' with
the name of the module in question).
Locate kernel area that causes the issue
----------------------------------------
*Locate the driver or kernel subsystem that seems to be causing the issue.
Find out how and where its developers expect reports. Note: most of the
time this won't be bugzilla.kernel.org, as issues typically need to be sent
by mail to a maintainer and a public mailing list.*
It's crucial to send your report to the right people, as the Linux kernel is a
big project and most of its developers are only familiar with a small subset of
it. Quite a few programmers for example only care for just one driver, for
example one for a WiFi chip; its developer likely will only have small or no
knowledge about the internals of remote or unrelated "subsystems", like the TCP
stack, the PCIe/PCI subsystem, memory management or file systems.
Problem is: the Linux kernel lacks a central bug tracker where you can simply
file your issue and make it reach the developers that need to know about it.
That's why you have to find the right place and way to report issues yourself.
You can do that with the help of a script (see below), but it mainly targets
kernel developers and experts. For everybody else the MAINTAINERS file is the
better place.
How to read the MAINTAINERS file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To illustrate how to use the :ref:`MAINTAINERS <maintainers>` file, lets assume
the WiFi in your Laptop suddenly misbehaves after updating the kernel. In that
case it's likely an issue in the WiFi driver. Obviously it could also be some
code it builds upon, but unless you suspect something like that stick to the
driver. If it's really something else, the driver's developers will get the
right people involved.
Sadly, there is no way to check which code is driving a particular hardware
component that is both universal and easy.
In case of a problem with the WiFi driver you for example might want to look at
the output of ``lspci -k``, as it lists devices on the PCI/PCIe bus and the
kernel module driving it::
[user@something ~]$ lspci -k
[...]
3a:00.0 Network controller: Qualcomm Atheros QCA6174 802.11ac Wireless Network Adapter (rev 32)
Subsystem: Bigfoot Networks, Inc. Device 1535
Kernel driver in use: ath10k_pci
Kernel modules: ath10k_pci
[...]
But this approach won't work if your WiFi chip is connected over USB or some
other internal bus. In those cases you might want to check your WiFi manager or
the output of ``ip link``. Look for the name of the problematic network
interface, which might be something like 'wlp58s0'. This name can be used like
this to find the module driving it::
[user@something ~]$ realpath --relative-to=/sys/module/ /sys/class/net/wlp58s0/device/driver/module
ath10k_pci
In case tricks like these don't bring you any further, try to search the
internet on how to narrow down the driver or subsystem in question. And if you
are unsure which it is: just try your best guess, somebody will help you if you
guessed poorly.
Once you know the driver or subsystem, you want to search for it in the
MAINTAINERS file. In the case of 'ath10k_pci' you won't find anything, as the
name is too specific. Sometimes you will need to search on the net for help;
but before doing so, try a somewhat shorted or modified name when searching the
MAINTAINERS file, as then you might find something like this::
QUALCOMM ATHEROS ATH10K WIRELESS DRIVER
Mail: A. Some Human <shuman@example.com>
Mailing list: ath10k@lists.infradead.org
Status: Supported
Web-page: https://wireless.wiki.kernel.org/en/users/Drivers/ath10k
SCM: git git://git.kernel.org/pub/scm/linux/kernel/git/kvalo/ath.git
Files: drivers/net/wireless/ath/ath10k/
Note: the line description will be abbreviations, if you read the plain
MAINTAINERS file found in the root of the Linux source tree. 'Mail:' for
example will be 'M:', 'Mailing list:' will be 'L', and 'Status:' will be 'S:'.
A section near the top of the file explains these and other abbreviations.
First look at the line 'Status'. Ideally it should be 'Supported' or
'Maintained'. If it states 'Obsolete' then you are using some outdated approach
that was replaced by a newer solution you need to switch to. Sometimes the code
only has someone who provides 'Odd Fixes' when feeling motivated. And with
'Orphan' you are totally out of luck, as nobody takes care of the code anymore.
That only leaves these options: arrange yourself to live with the issue, fix it
yourself, or find a programmer somewhere willing to fix it.
After checking the status, look for a line starting with 'bugs:': it will tell
you where to find a subsystem specific bug tracker to file your issue. The
example above does not have such a line. That is the case for most sections, as
Linux kernel development is completely driven by mail. Very few subsystems use
a bug tracker, and only some of those rely on bugzilla.kernel.org.
.. note::
FIXME: The old text took a totally different approach to bugzilla.kernel.org,
as it mentions it as the place to file issue for people that don't known how
to contact the appropriate people. The new one mentions it rarely; and when
it does like here, it warns users that it's often the wrong place to go.
This approach was chosen as the main author of this document noticed quite a
few users (or even a lot?) get no reply to the bugs they file in bugzilla.
That's kind of expected, as quite a few (many? most?) of the maintainers
don't even get notified when reports for their subsystem get filed there. And
not getting a single reply to report is something that is just annoying for
users and might make them angry. Improving bugzilla.k.o would be an option,
but on the kernel and maintainers summit 2017 it was agreed on to first go
this route (sorry it took so long): it's easier to achieve and less
controversial, as putting additional burden on already overworked maintainers
is unlikely to get well received.
In this and many other cases you thus have to look for lines starting with
'Mail:' instead. Those mention the name and the email addresses for the
maintainers of the particular code. Also look for a line starting with 'Mailing
list:', which tells you the public mailing list where the code is developed.
Your report later needs to go by mail to those addresses. Additionally, for all
issue reports sent by email, make sure to add the Linux Kernel Mailing List
(LKML) <linux-kernel@vger.kernel.org> to CC. Don't omit either of the mailing
lists when sending your issue report by mail later! Maintainers are busy people
and might leave some work for other developers on the subsystem specific list;
and LKML is important to have one place where all issue reports can be found.
.. note::
FIXME: Above section tells users to always CC LKML. These days it's a kind of
"catch-all" list anyway, which nearly nobody seems to follow closely. So it
seems appropriate to go "all in" and make people send their reports here,
too, as everything (reports, fixes, ...) then can be found in one place (at
least for all reports sent by mail and all subsystems that CC LKML).
Related: Should we create mailing list like 'linux-issues@vger.kernel.org'
and tell users above to always CC it when reporting issues? Then there would
be one central place reporters could search for existing reports (at least
for issues reported by mail) without getting regular LKML traffic mixed into
the results.
Finding the maintainers with the help of a script
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For people that have the Linux sources at hand there is a second option to find
the proper place to report: the script 'scripts/get_maintainer.pl' which tries
to find all people to contact. It queries the MAINTAINERS file and needs to be
called with a path to the source code in question. For drivers compiled as
module if often can be found with a command like this::
$ modinfo ath10k_pci | grep filename | sed 's!/lib/modules/.*/kernel/!!; s!filename:!!; s!\.ko\(\|\.xz\)!!'
drivers/net/wireless/ath/ath10k/ath10k_pci.ko
Pass parts of this to the script::
$ ./scripts/get_maintainer.pl -f drivers/net/wireless/ath/ath10k*
Some Human <shuman@example.com> (supporter:QUALCOMM ATHEROS ATH10K WIRELESS DRIVER)
Another S. Human <asomehuman@example.com> (maintainer:NETWORKING DRIVERS)
ath10k@lists.infradead.org (open list:QUALCOMM ATHEROS ATH10K WIRELESS DRIVER)
linux-wireless@vger.kernel.org (open list:NETWORKING DRIVERS (WIRELESS))
netdev@vger.kernel.org (open list:NETWORKING DRIVERS)
linux-kernel@vger.kernel.org (open list)
Don't sent your report to all of them. Send it to the maintainers, which the
script calls "supporter:"; additionally CC the most specific mailing list for
the code as well as the Linux Kernel Mailing List (LKML). In this case you thus
would need to send the report to 'Some Human <shuman@example.com>' with
'ath10k@lists.infradead.org' and 'linux-kernel@vger.kernel.org' in CC.
Note: in case you cloned the Linux sources with git you might want to call
``get_maintainer.pl`` a second time with ``--git``. The script then will look
at the commit history to find which people recently worked on the code in
question, as they might be able to help. But use these results with care, as it
can easily send you in a wrong direction. That for example happens quickly in
areas rarely changed (like old or unmaintained drivers): sometimes such code is
modified during tree-wide cleanups by developers that do not care about the
particular driver at all.
Search for existing reports
---------------------------
*Search the archives of the bug tracker or mailing list in question
thoroughly for reports that might match your issue. Also check if you find
something with your favorite internet search engine or in the Linux Kernel
Mailing List (LKML) archives. If you find anything, join the discussion
instead of sending a new report.*
Reporting an issue that someone else already brought forward is often a waste
of time for everyone involved, especially you as the reporter. So it's in your
own interest to thoroughly check if somebody reported the issue already. Thus
do not hurry with this step of the reporting process. Spending 30 to 60 minutes
or even more time can save you and others quite a lot of time and trouble.
The best place to search is the bug tracker or the mailing list where your
report needs to be filed. You'll find quite a few of those lists on
`lore.kernel.org <https://lore.kernel.org/>`_, but some are hosted in
different places. That for example is the case for the ath10k WiFi driver used
as example in the previous step. But you'll often find the archives for these
lists easily on the net. Searching for 'archive ath10k@lists.infradead.org' for
example will quickly lead you to the `Info page for the ath10k mailing list
<https://lists.infradead.org/mailman/listinfo/ath10k>`_, which at the top links
to its `list archives <https://lists.infradead.org/pipermail/ath10k/>`_.
Sadly this and quite a few other lists miss a way to search the archives. In
those cases use a regular internet search engine and add something like
'site:lists.infradead.org/pipermail/ath10k/' to your search terms, which limits
the results to the archives at that URL.
Additionally, search the internet and the `Linux Kernel Mailing List (LKML)
archives <https://lore.kernel.org/lkml/>`_, as maybe the real culprit might be
in some other subsystem. Searching in `bugzilla.kernel.org
<https://bugzilla.kernel.org/>`_ might also be a good idea, but if you find
anything there keep in mind: most subsystems expect reports in different
places, hence those you find there might have not even reached the people
responsible for the subsystem in question. Nevertheless, the data there might
provide valuable insights.
If you get flooded with results consider telling your search engine to limit
search timeframe to the past month or year. And wherever you search, make sure
to use good search terms; vary them a few times, too. While doing so try to
look at the issue from the perspective of someone else: that will help you to
come up with other words to use as search terms. Also make sure not to use too
many search terms at once. Remember to search with and without information like
the name of the kernel driver or the name of the affected hardware component.
But its exact brand name (say 'ASUS Red Devil Radeon RX 5700 XT Gaming OC')
often is not much helpful, as it is too specific. Instead try search terms like
the model line (Radeon 5700 or Radeon 5000) and the code name of the main chip
('Navi' or 'Navi10') with and without its manufacturer ('AMD').
In case you find an existing report about your issue, join the discussion, as
you might be able to provide valuable additional information. That can be
important even when a fix is prepared or in its final stages already, as
developers might look for people that can provide additional information or
test a proposed fix. Jump to the section 'Duties after the report went out' for
details on how to get properly involved.
Prepare for emergencies
-----------------------
*Create a fresh backup and put system repair and restore tools at hand.*
Reminder, you are dealing with computers, which sometimes do unexpected things,
especially if you fiddle with crucial parts like the kernel of its operating
system. That's what you are about to do in this process. Thus, make sure to
create a fresh backup; also ensure you have all tools at hand to repair or
reinstall the operating system as well as everything you need to restore the
backup.
Make sure your kernel doesn't get enhanced
------------------------------------------
*Ensure your system does not enhance its kernels by building additional
kernel modules on-the-fly, which solutions like DKMS might be doing locally
without your knowledge.*
Your kernel must be 'vanilla' when reporting an issue, but stops being pure as
soon as it loads a kernel module not built from the sources used to compile the
kernel image itself. That's why you need to ensure your Linux kernel stays
vanilla by removing or disabling mechanisms like akmods and DKMS: those might
build additional kernel modules automatically, for example when your boot into
a newly installed Linux kernel the first time. Reboot after removing them and
any modules they installed.
Note, you might not be aware that your system is using one of these solutions:
they often get set up silently when you install Nvidia's proprietary graphics
driver, VirtualBox, or other software that requires a some support from a
module not part of the Linux kernel. That why your might need to uninstall the
packages with such software to get rid of any 3rd party kernel module.
Ensure a healthy environment
----------------------------
*Make sure it's not the kernel's surroundings that are causing the issue
you face.*
Problems that look a lot like a kernel issue are sometimes caused by build or
runtime environment. It's hard to rule out that problem completely, but you
should minimize it:
* Use proven tools when building your kernel, as bugs in the compiler or the
binutils can cause the resulting kernel to misbehave.
* Ensure your computer components run within their design specifications;
that's especially important for the main processor, the main memory, and the
motherboard. Therefore, stop undervolting or overclocking when facing a
potential kernel issue.
* Try to make sure it's not faulty hardware that is causing your issue. Bad
main memory for example can result in a multitude of issues that will
manifest itself in problems looking like kernel issues.
* If you're dealing with a filesystem issue, you might want to check the file
system in question with ``fsck``, as it might be damaged in a way that leads
to unexpected kernel behavior.
* When dealing with a regression, make sure it's not something else that
changed in parallel to updating the kernel. The problem for example might be
caused by other software that was updated at the same time. It can also
happen that a hardware component coincidentally just broke when you rebooted
into a new kernel for the first time. Updating the systems BIOS or changing
something in the BIOS Setup can also lead to problems that on look a lot
like a kernel regression.
Document how to reproduce issue
-------------------------------
*Write down coarsely how to reproduce the issue. If you deal with multiple
issues at once, create separate notes for each of them and make sure they
work independently on a freshly booted system. That's needed, as each issue
needs to get reported to the kernel developers separately, unless they are
strongly entangled.*
If you deal with multiple issues at once, you'll have to report each of them
separately, as they might be handled by different developers. Describing
various issues in one report also makes it quite difficult for others to tear
it apart. Hence, only combine issues in one report if they are very strongly
entangled.
Additionally, during the reporting process you will have to test if the issue
happens with other kernel versions. Therefore, it will make your work easier if
you know exactly how to reproduce an issue quickly on a freshly booted system.
Note: it's often fruitless to report issues that only happened once, as they
might be caused by a bit flip due to cosmic radiation. That's why you should
try to rule that out by reproducing the issue before going further. Feel free
to ignore this advice if you are experienced enough to tell a one-time error
due to faulty hardware apart from a kernel issue that rarely happens and thus
is hard to reproduce.
Install a fresh kernel for testing
----------------------------------
*Install the latest Linux mainline kernel: that's where all issues get
fixed first, because it's the version line the kernel developers mainly
care about. Testing and reporting with the latest Linux stable kernel can
be an acceptable alternative in some situations, for example during the
merge window; but during that period you might want to suspend your efforts
till its end anyway.*
Reporting an issue to the Linux kernel developers they fixed weeks or months
ago is annoying for them and wasting their and your time. That's why it's in
everybody's interest to check if the issue occurs with the latest codebase
before reporting it.
In the scope of the Linux kernel the term 'latest' means: a kernel version
recently created from the main line of development, as this 'mainline' tree is
where developers first apply fixes; only after that are they are allowed to get
backported to older, still supported version lines called 'stable' and
'longterm' kernels. That's why you should check a recent mainline kernel, even
if you deal with an issue you only want to see fixed in an older version line.
Another reason: some fixes are only applied to mainline or recent version
lines, as it's too hard or risky to backport them to older versions. If that
the case, reporting the issue again is unlikely to change anything.
Longterm kernels (sometimes called "LTS kernels") are therefore unsuitable for
testing; they simply are too distant from current development. Even the latest
Linux 'stable' kernel is a significant bit behind and thus better avoided. At
least most of the time, as sometimes a stable kernel can the best choice; but
in those situations you might want to wait a few days anyway:
Choosing between mainline, stable and waiting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Head over to `kernel.org <https://kernel.org/>`_ to decide which version to
use. Ignore the big yellow button that says 'Latest release' and look a little
lower for a table. At its top you'll see a line starting with 'mainline', which
most of the time will point to a pre-release with a version number like
'5.8-rc2'. If that's the case, you'll want to use this mainline kernel for
testing. Do not let that 'rc' scare you, these 'development kernels' are pretty
reliable — and you made a backup, as you were instructed above, didn't you?
In about two out of every nine to ten weeks, 'mainline' might point you to a
proper release with a version number like '5.7'. If that happens, consider
suspending the reporting process until the first pre-release of the next
version (5.8-rc1) shows up on kernel.org. That's because the Linux development
cycle then is in its two-week long 'merge window'. The bulk of the changes and
all intrusive ones get merged for the next release during this time. It's a bit
more risky to use mainline during this period. Kernel developers are also often
quite busy then and might have no spare time to deal with issue reports. It's
also quite possible that one of the many changes applied during the merge
window fixes the issue you face; that's why you soon would have to retest with
a newer kernel version anyway, as outlined below in the section 'Duties after
the report went out'.
That's why it might make sense to wait till the merge window is over. But don't
to that if you're dealing with something that shouldn't wait. In that case
consider obtaining the latest mainline kernel via git (see below) or use the
latest stable version offered on kernel.org. Using that is also acceptable in
case mainline for some reason does currently not work for you. An in general:
using it for reproducing the issue is also better than not reporting it issue
at all.
How to obtain a fresh Linux kernel
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can use pre-built or self-compiled kernel for testing; if you choose the
latter approach, you can either obtain the source code using git or download it
as tar archive.
Using a pre-compiled kernel for testing is often the quickest, easiest, and
safest way – especially is you are unfamiliar with the Linux kernel. But it
needs to be a vanilla kernel, which can be hard to come buy. You are in luck if
you are using a popular Linux distribution: for quite a few of them you'll find
repositories on the net that contain packages with the latest mainline or
stable kernels in vanilla fashion. It's totally okay to use these, just make
sure from the repository's documentation they are really vanilla. And ensure
the packages contain the latest versions as offered on kernel.org; they are
likely unsuitable if the package is older than a week, as new mainline and
stable kernels typically get released at least once a week. And be aware that
you might need to get build your own kernel later anyway when it comes to
helping test fixes, as described later in this document.
Developers and experienced Linux users familiar with git are often best served
by obtaining the latest Linux kernel sources straight from the `official
development repository on kernel.org
<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/>`_.
Those are likely a bit ahead of the latest mainline pre-release. Don't worry
about it: they are as reliable as a proper pre-release, unless the kernel's
development cycle is currently in the middle of a merge window. But even then
they are quite reliable.
People unfamiliar with git are often best served by downloading the sources as
tarball from `kernel.org <https://kernel.org/>`_.
How to actually build a kernel isnot described here, as many websites explain
the necessary steps already. If you are new to it, consider following one of
those how-to's that suggest to use ``make localmodconfig``, as that tries to
pick up the configuration of your current kernel and then tries to adjust it
somewhat for your system. That does not make the resulting kernel any better,
but quicker to compile.
Check 'taint' flag
------------------
*Ensure the kernel you just installed does not 'taint' itself when
running.*
As outlined above in more detail already: the kernel sets a 'taint' flag when
something happens that can lead to follow-up errors that look totally
unrelated. That's why you need to check if the kernel you just installed does
not set this flag. And if it does, you in almost all the cases needs to
eliminate the reason for it before you reporting issues that occur with it. See
the section above for details how to do that.
Reproduce issue with the fresh kernel
-------------------------------------
*Reproduce the issue with the kernel you just installed. If it doesn't show
up there, head over to the instructions for issues only happening with
stable and longterm kernels.*
Check if the issue occurs with the fresh Linux kernel version you just
installed. If it was fixed there already, consider sticking with this version
line and abandoning your plan to report the issue. But keep in mind that other
users might still be plagued by it, as long as it's not fixed in either stable
and longterm version from kernel.org (and thus vendor kernels derived from
those). If you prefer to use one of those or just want to help their users,
head over to the section "Details about reporting issues only occurring in
older kernel version lines" below.
Optimize description to reproduce issue
---------------------------------------
*Optimize your notes: try to find and write the most straightforward way to
reproduce your issue. Make sure the end result has all the important
details, and at the same time is easy to read and understand for others
that hear about it for the first time. And if you learned something in this
process, consider searching again for existing reports about the issue.*
An unnecessarily complex report will make it hard for others to understand your
report. Thus try to find a reproducer that's straight forward to describe and
thus easy to understand in written form. Include all important details, but at
the same time try to keep it as short as possible.
In this in the previous steps you likely have learned a thing or two about the
issue you face. Use this knowledge and search again for existing reports
instead you can join.
Decode failure messages
-----------------------
.. note::
FIXME: The text in this section is a placeholder for now and quite similar to
the old text found in 'Documentation/admin-guide/reporting-bugs.rst'
currently. It and the document it references are known to be outdated and
thus need to be revisited. Thus consider this note a request for help: if you
are familiar with this topic, please write a few lines that would fit here.
Alternatively, simply outline the current situation roughly to the main
authors of this document (see intro), as they might be able to write
something then.
This section in the end should answer questions like "when is this actually
needed", "what .config options to ideally set earlier to make this step easy
or unnecessary?" (likely CONFIG_UNWINDER_ORC when it's available, otherwise
CONFIG_UNWINDER_FRAME_POINTER; but is there anything else needed?).
..
*If the failure includes a stack dump, like an Oops does, consider decoding
it to find the offending line of code.*
When the kernel detects an error, it will print a stack dump that allows to
identify the exact line of code where the issue happens. But that information
sometimes needs to get decoded to be readable, which is explained in
admin-guide/bug-hunting.rst.
Special care for regressions
----------------------------
*If your problem is a regression, try to narrow down when the issue was
introduced as much as possible.*
Linux lead developer Linus Torvalds insists that the Linux kernel never
worsens, that's why he deems regressions as unacceptable and wants to see them
fixed quickly. That's why changes that introduced a regression are often
promptly reverted if the issue they cause can't get solved quickly any other
way. Reporting a regression is thus a bit like playing a kind of trump card to
get something quickly fixed. But for that to happen the change that's causing
the regression needs to be known. Normally it's up to the reporter to track
down the culprit, as maintainers often won't have the time or setup at hand to
reproduce it themselves.
To find the change there is a process called 'bisection' which the document
'Documentation/admin-guide/bug-bisect.rst' describes in detail. That process
will often require you to build about ten to twenty kernel images, trying to
reproduce the issue with each of them before building the next. Yes, that takes
some time, but don't worry, it works a lot quicker than most people assume.
Thanks to a 'binary search' this will lead you to the one commit in the source
code management system that's causing the regression. Once you find it, search
the net for the subject of the change, its commit id and the shortened commit id
(the first 12 characters of the commit id). This will lead you to existing
reports about it, if there are any.
Note, a bisection needs a bit of know-how, which not everyone has, and quite a
bit of effort, which not everyone is willing to invest. Nevertheless, it's
highly recommended performing a bisection yourself. If you really can't or
don't want to go down that route at least find out which mainline kernel
introduced the regression. If something for example breaks when switching from
5.5.15 to 5.8.4, then try at least all the mainline releases in that area (5.6,
5.7 and 5.8) to check when it first showed up. Unless you're trying to find a
regression in a stable or longterm kernel, avoid testing versions which number
has three sections (5.6.12, 5.7.8), as that makes the outcome hard to
interpret, which might render your testing useless. Once you found the major
version which introduced the regression, feel free to move on in the reporting
process. But keep in mind: it depends on the issue at hand if the developers
will be able to help without knowing the culprit. Sometimes they might
recognize from the report want went wrong and can fix it; other times they will
be unable to help unless you perform a bisection.
When dealing with regressions make sure the issue you face is really caused by
the kernel and not by something else, as outlined above already.
In the whole process keep in mind: an issue only qualifies as regression if the
older and the newer kernel got built with a similar configuration. The best way
to archive this: copy the configuration file (``.config``) from the old working
kernel freshly to each newer kernel version you try. Afterwards run ``make
oldnoconfig`` to adjust it for the needs of the new version without enabling
any new feature, as those are allowed to cause regressions.
Write and send the report
-------------------------
*Start to compile the report by writing a detailed description about the
issue. Always mention a few things: the latest kernel version you installed
for reproducing, the Linux Distribution used, and your notes on how to
reproduce the issue. Ideally, make the kernel's build configuration
(.config) and the output from ``dmesg`` available somewhere on the net and
link to it. Include or upload all other information that might be relevant,
like the output/screenshot of an Oops or the output from ``lspci``. Once
you wrote this main part, insert a normal length paragraph on top of it
outlining the issue and the impact quickly. On top of this add one sentence
that briefly describes the problem and gets people to read on. Now give the
thing a descriptive title or subject that yet again is shorter. Then you're
ready to send or file the report like the MAINTAINERS file told you, unless
you are dealing with one of those 'issues of high priority': they need
special care which is explained in 'Special handling for high priority
issues' below.*
Now that you have prepared everything it's time to write your report. How to do
that is partly explained by the three documents linked to in the preface above.
That's why this text will only mention a few of the essentials as well as
things specific to the Linux kernel.
There is one thing that fits both categories: the most crucial parts of your
report are the title/subject, the first sentence, and the first paragraph.
Developers often get quite a lot of mail. They thus often just take a few
seconds to skim a mail before deciding to move on or look closer. Thus: the
better the top section of your report, the higher are the chances that someone
will look into it and help you. And that is why you should ignore them for now
and write the detailed report first. ;-)
Things each report should mention
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Describe in detail how your issue happens with the fresh vanilla kernel you
installed. Try to include the step-by-step instructions you wrote and optimized
earlier that outline how you and ideally others can reproduce the issue; in
those rare cases where that's impossible try to describe what you did to
trigger it.
Also include all the relevant information others might need to understand the
issue and its environment. What's actually needed depends a lot on the issue,
but there are some things you should include always:
* the output from ``cat /proc/version``, which contains the Linux kernel
version number and the compiler it was built with.
* the Linux distribution the machine is running (``hostnamectl | grep
"Operating System"``)
* the architecture of the CPU and the operating system (``uname -mi``)
* if you are dealing with a regression and performed a bisection, mention the
subject and the commit-id of the change that is causing it.
In a lot of cases it's also wise to make two more things available to those
that read your report:
* the configuration used for building your Linux kernel (the '.config' file)
* the kernel's messages that you get from ``dmesg`` written to a file. Make
sure that it starts with a line like 'Linux version 5.8-1
(foobar@example.com) (gcc (GCC) 10.2.1, GNU ld version 2.34) #1 SMP Mon Aug
3 14:54:37 UTC 2020' If it's missing, then important messages from the first
boot phase already got discarded. In this case instead consider using
``journalctl -b 0 -k``; alternatively you can also reboot, reproduce the
issue and call ``dmesg`` right afterwards.
These two files are big, that's why it's a bad idea to put them directly into
your report. If you are filing the issue in a bug tracker then attach them to
the ticket. If you report the issue by mail do not attach them, as that makes
the mail too large; instead do one of these things:
* Upload the files somewhere public (your website, a public file paste
service, a ticket created just for this purpose on `bugzilla.kernel.org
<https://bugzilla.kernel.org/>`_, ...) and include a link to them in your
report. Ideally use something where the files stay available for years, as
they could be useful to someone many years from now; this for example can
happen if five or ten years from now a developer works on some code that was
changed just to fix your issue.
* Put the files aside and mention you will send them later in individual
replies to your own mail. Just remember to actually do that once the report
went out. ;-)
Things that might be wise to provide
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Depending on the issue you might need to add more background data. Here are a
few suggestions what often is good to provide:
* If you are dealing with a 'warning', an 'OOPS' or a 'panic' from the kernel,
include it. If you can't copy'n'paste it, try to capture a netconsole trace
or at least take a picture of the screen.
* If the issue might be related to your computer hardware, mention what kind
of system you use. If you for example have problems with your graphics card,
mention its manufacturer, the card's model, and what chip is uses. If it's a
laptop mention its name, but try to make sure it's meaningful. 'Dell XPS 13'
for example is not, because it might be the one from 2012; that one looks
not that different from the one sold today, but apart from that the two have
nothing in common. Hence, in such cases add the exact model number, which
for example are '9380' or '7390' for XPS 13 models introduced during 2019.
Names like 'Lenovo Thinkpad T590' are also somewhat ambiguous: there are
variants of this laptop with and without a dedicated graphics chip, so try
to find the exact model name or specify the main components.
* Mention the relevant software in use. If you have problems with loading
modules, you want to mention the versions of kmod, systemd, and udev in use.
If one of the DRM drivers misbehaves, you want to state the versions of
libdrm and Mesa; also specify your Wayland compositor or the X-Server and
its driver. If you have a filesystem issue, mention the version of
corresponding filesystem utilities (e2fsprogs, btrfs-progs, xfsprogs, ...).
* Gather additional information from the kernel that might be of interest. The
output from ``lspci -nn`` will for example help others to identify what
hardware you use. If you have a problem with hardware you even might want to
make the output from ``sudo lspci -vvv`` available, as that provides
insights how the components were configured. For some issues it might be
good to include the contents of files like ``/proc/cpuinfo``,
``/proc/ioports``, ``/proc/iomem``, ``/proc/modules``, or
``/proc/scsi/scsi``. Some subsystem also offer tools to collect relevant
information. One such tool is ``alsa-info.sh`` `which the audio/sound
subsystem developers provide <https://www.alsa-project.org/wiki/AlsaInfo>`_.
Those examples should give your some ideas of what data might be wise to
attach, but you have to think yourself what will be helpful for others to know.
Don't worry too much about forgetting something, as developers will ask for
additional details they need. But making everything important available from
the start increases the chance someone will take a closer look.
The important part: the head of your report
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Now that you have the detailed part of the report prepared let's get to the
most important section: the first few sentences. Thus go to the top, add
something like 'The detailed description:' before the part you just wrote and
insert two newlines at the top. Now write one normal length paragraph that
describes the issue roughly. Leave out all boring details and focus on the
crucial parts readers need to know to understand what this is all about; if you
think this bug affects a lot of users, mention this to get people interested.
Once you did that insert two more lines at the top and write a one sentence
summary that explains quickly what the report is about. After that you have to
get even more abstract and write an even shorter subject/title for the report.
Now that you have written this part take some time to optimize it, as it is the
most important parts of your report: a lot of people will only read this before
they decide if reading the rest is time well spent.
Now send or file the report like the :ref:`MAINTAINERS <maintainers>` file told
you, unless it's one of those 'issues of high priority' outlined earlier: in
that case please read the next subsection first before sending the report on
its way.
Special handling for high priority issues
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Reports for high priority issues need special handling.
**Severe bugs**: make sure the subject or ticket title as well as the first
paragraph makes the severeness obvious.
**Regressions**: If the issue is a regression add [REGRESSION] to the mail's
subject or the title in the bug-tracker. If you did not perform a bisection
mention at least the latest mainline version you tested that worked fine (say
5.7) and the oldest where the issue occurs (say 5.8). If you did a successful
bisection mention the commit id and subject of the change that causes the
regression. Also make sure to add the author of that change to your report; if
you need to file your bug in a bug-tracker forward the report to him in a
private mail and mention where your filed it.
**Security issues**: for these issues your will have to evaluate if a
short-term risk to other users would arise if details were publicly disclosed.
If that's not the case simply proceed with reporting the issue as described.
For issues that bear such a risk you will need to adjust the reporting process
slightly:
* If the MAINTAINERS file instructed you to report the issue by mail, do not
CC any public mailing lists.
* If you were supposed to file the issue in a bug tracker make sure to mark
the ticket as 'private' or 'security issue'. If the bug tracker does not
offer a way to keep reports private, forget about it and send your report as
a private mail to the maintainers instead.
In both cases make sure to also mail your report to the addresses the
MAINTAINERS file lists in the section 'security contact'. Ideally directly CC
them when sending the report by mail. If you filed it in a bug tracker, forward
the report's text to these addresses; but on top of it put a small note where
you mention that you filed it with a link to the ticket.
See 'Documentation/admin-guide/security-bugs.rst' for more information.
Duties after the report went out
--------------------------------
*Wait for reactions and keep the thing rolling until you can accept the
outcome in one way or the other. Thus react publicly and in a timely manner
to any inquiries. Test proposed fixes. Do proactive testing: retest with at
least every first release candidate (RC) of a new mainline version and
report your results. Send friendly reminders if things stall. And try to
help yourself, if you don't get any help or if it's unsatisfying.*
If your report was good and you are really lucky then one of the developers
might immediately spot what's causing the issue; they then might write a patch
to fix it, test it, and send it straight for integration in mainline while
tagging it for later backport to stable and longterm kernels that need it. Then
all you need to do is reply with a 'Thank you very much' and switch to a version
with the fix once it gets released.
But this ideal scenario rarely happens. That's why the job is only starting
once you got the report out. What you'll have to do depends on the situations,
but often it will be the things listed below. But before digging into the
details, here are a few important things you need to keep in mind for this part
of the process.
General advice for further interactions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Always reply in public**: When you filed the issue in a bug tracker, always
reply there and do not contact any of the developers privately about it. For
mailed reports always use the 'Reply-all' function when replying to any mails
you receive. That includes mails with any additional data you might want to add
to your report: go to your mail applications 'Sent' folder and use 'reply-all'
on your mail with the report. This approach will make sure the public mailing
list(s) and everyone else that gets involved over time stays in the loop; it
also keeps the mail thread intact, which among others is really important for
mailing lists to group all related mails together.
There are just two situations where a comment in a bug tracker or a 'Reply-all'
is unsuitable:
* Someone tells you to send something privately.
* You were told to send something, but noticed it contains sensitive
information that needs to be kept private. In that case it's okay to send it
in private to the developer that asked for it. But note in the ticket or a
mail that you did that, so everyone else knows you honored the request.
**Do research before asking for clarifications or help**: In this part of the
process someone might tell you to do something that requires a skill you might
not have mastered yet. For example, you might be asked to use some test tools
you never have heard of yet; or you might be asked to apply a patch to the
Linux kernel sources to test if it helps. In some cases it will be fine sending
a reply asking for instructions how to do that. But before going that route try
to find the answer own your own by searching the internet; alternatively
consider asking in other places for advice. For example ask a fried or post
about it to a chatroom or forum you normally hang out.
**Be patient**: If you are really lucky you might get a reply to your report
within a few hours. But most of the time it will take longer, as maintainers
are scattered around the globe and thus might be in a different time zone – one
where they already enjoy their night away from keyboard.
In general, kernel developers will take one to five business days to respond to
reports. Sometimes it will take longer, as they might be busy with the merge
windows, other work, visiting developer conferences, or simply enjoying a long
summer holiday.
The 'issues of high priority' (see above for an explanation) are an exception
here: maintainers should address them as soon as possible; that's why you
should wait a week at maximum (or just two days if it's something urgent)
before sending a friendly reminder.
Sometimes the maintainer might not be responding in a timely manner; other
times there might be disagreements, for example if an issue qualifies as
regression or not. In such cases raise your concerns on the mailing list and
ask others for public or private replies how to move on. If that fails, it
might be appropriate to get a higher authority involved. In case of a WiFi
driver that would be the wireless maintainers; if there are no higher level
maintainers or all else fails, it might be one of those rare situations where
it's okay to get Linus Torvalds involved.
**Proactive testing**: Every time the first pre-release (the 'rc1') of a new
mainline kernel version gets released, go and check if the issue is fixed there
or if anything of importance changed. Mention the outcome in the ticket or in a
mail you sent as reply to your report (make sure it has all those in the CC
that up to that point participated in the discussion). This will show your
commitment and that you are willing to help. It also tells developers if the
issue persists and makes sure they do not forget about it. A few other
occasional retests (for example with rc3, rc5 and the final) are also a good
idea, but only report your results if something relevant changed or if you are
writing something anyway.
With all these general things off the table let's get into the details of how
to help to get issues resolved once they were reported.
Inquires and testing request
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Here are your duties in case you got replies to your report:
**Check who you deal with**: Most of the time it will be the maintainer or a
developer of the particular code area that will respond to your report. But as
issues are normally reported in public it could be anyone that's replying —
including people that want to help, but in the end might guide you totally off
track with their questions or requests. That rarely happens, but it's one of
many reasons why it's wise to quickly run an internet search to see who you're
interacting with. By doing this you also get aware if your report was heard by
the right people, as a reminder to the maintainer (see below) might be in order
later if discussion fades out without leading to a satisfying solution for the
issue.
**Inquiries for data**: Often you will be asked to test something or provide
additional details. Try to provide the requested information soon, as you have
the attention of someone that might help and risk losing it the longer you
wait; that outcome is even likely if you do not provide the information within
a few business days.
**Requests for testing**: When you are asked to test a diagnostic patch or a
possible fix, try to test it in timely manner, too. But do it properly and make
sure to not rush it: mixing things up can happen easily and can lead to a lot
of confusion for everyone involved. A common mistake for example is thinking a
proposed patch with a fix was applied, but in fact wasn't. Things like that
happen even to experienced testers occasionally, but they most of the time will
notice when the kernel with the fix behaves just as one without it.
What to do when nothing of substance happens
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Some reports will not get any reaction from the responsible Linux kernel
developers; or a discussion around the issue evolved, but faded out with
nothing of substance coming out of it.
In these cases wait two (better: three) weeks before sending a friendly
reminder: maybe the maintainer was just away from keyboard for a while when
your report arrived or had something more important to take care of. When
writing the reminder, kindly ask if anything else from your side is needed to
get the ball running somehow. If the report got out by mail, do that in the
first lines of a mail that is a reply to your initial mail (see above) which
includes a full quote of the original report below: that's on of those few
situations where such a 'TOFU' (Text Over, Fullquote Under) is the right
approach, as then all the recipients will have the details at hand immediately
in the proper order.
After the reminder wait three more weeks for replies. If you still don't get a
proper reaction, you first should reconsider your approach. Did you maybe try
to reach out to the wrong people? Was the report maybe offensive or so
confusing that people decided to completely stay away from it? The best way to
rule out such factors: show the report to one or two people familiar with FLOSS
issue reporting and ask for their opinion. Also ask them for their advice how
to move forward. That might mean: prepare a better report and make those people
review it before you send it out. Such an approach is totally fine; just
mention that this is the second and improved report on the issue and include a
link to the first report.
If the report was proper you can send a second reminder; in it ask for advice
why the report did not get any replies. A good moment for this second reminder
mail is shortly after the first pre-release (the 'rc1') of a new Linux kernel
version got published, as you should retest and provide a status update at that
point anyway (see above).
If the second reminder again results in no reaction within a week, try to
contact a higher-level maintainer asking for advice: even busy maintainers by
then should at least have sent some kind of acknowledgment.
Remember to prepare yourself for a disappointment: maintainers ideally should
react somehow to every issue report, but they are only obliged to fix those
'issues of high priority' outlined earlier. So don't be too devastating if you
get a reply along the lines of 'thanks for the report, I have more important
issues to deal with currently and won't have time to look into this for the
foreseeable future'.
It's also possible that after some discussion in the bug tracker or on a list
nothing happens anymore and reminders don't help to motivate anyone to work out
a fix. Such situations can be devastating, but is within the cards when it
comes to Linux kernel development. This and several other reasons for not
getting help are explained in 'Why some issues won't get any reaction or remain
unfixed after being reported' near the end of this document.
Don't get devastated if you don't find any help or if the issue in the end does
not get solved: the Linux kernel is FLOSS and thus you can still help yourself.
You for example could try to find others that are affected and team up with
them to get the issue resolved. Such a team could prepare a fresh report
together that mentions how many you are and why this is something that in your
option should get fixed. Maybe together you can also narrow down the root cause
or the change that introduced a regression, which often makes developing a fix
easier. And with a bit of luck there might be someone in the team that knows a
bit about programming and might be able to write a fix.
Details about reporting issues only occurring in older kernel version lines
---------------------------------------------------------------------------
This subsection provides details for steps you need to take if you could not
reproduce your issue with a mainline kernel, but want to see it fixed in older
version lines (aka stable and longterm kernels).
Some fixes are too complex
~~~~~~~~~~~~~~~~~~~~~~~~~~
*Prepare yourself for the possibility that going through the next few steps
might not get the issue solved in older releases: the fix might be too big
or risky to get backported there.*
Even small and seemingly obvious code-changes sometimes introduce new and
totally unexpected problems. The maintainers of the stable and longterm kernels
are very aware of that and thus only apply changes to these kernels that are
within rules outlined in 'Documentation/process/stable-kernel-rules.rst'.
Complex or risky changes for example do not qualify and thus only get applied
to mainline. Other fixes are easy to get backported to the newest stable and
longterm kernels, but too risky to integrate into older ones. So be aware the
fix you are hoping for might be one of those that won't be backported to the
version line your care about. In that case you'll have no other choice then to
live with the issue or switch to a newer Linux version, unless you want to
patch the fix into your kernels yourself.
Make sure the particular version line still gets support
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*Check if the kernel developers still maintain the Linux kernel version
line you care about: go to the front page of kernel.org and make sure it
mentions the latest release of the particular version line without an
'[EOL]' tag.*
Most kernel version lines only get supported for about three months, as
maintaining them longer is quite a lot of work. Hence, only one per year is
chosen and gets supported for at least two years (often six). That's why you
need to check if the kernel developers still support the version line you care
for.
Note, if kernel.org lists two 'stable' version lines on the front page, you
should consider switching to the newer one and forget about the older one:
support for it is likely to be abandoned soon. Then it will get a "end-of-life"
(EOL) stamp. Version lines that reached that point still get mentioned on the
kernel.org front page for a week or two, but are unsuitable for testing and
reporting.
Search stable mailing list
~~~~~~~~~~~~~~~~~~~~~~~~~~
*Check the archives of the Linux stable mailing list for existing reports.*
Maybe the issue you face is already known and was fixed or is about to. Hence,
`search the archives of the Linux stable mailing list
<https://lore.kernel.org/stable/>`_ for reports about an issue like yours. If
you find any matches, consider joining the discussion, unless the fix is
already finished and scheduled to get applied soon.
Reproduce issue with the newest release
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*Install the latest release from the particular version line as a vanilla
kernel. Ensure this kernel is not tainted and still shows the problem, as
the issue might have already been fixed there.*
Before investing any more time in this process you want to check if the issue
was already fixed in the latest release of version line you're interested in.
This kernel needs to be vanilla and shouldn't be tainted before the issue
happens, as detailed outlined already above in the process of testing mainline.
Check code history and search for existing discussions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*Search the Linux kernel version control system for the change that fixed
the issue in mainline, as its commit message might tell you if the fix is
scheduled for backporting already. If you don't find anything that way,
search the appropriate mailing lists for posts that discuss such an issue
or peer-review possible fixes; then check the discussions if the fix was
deemed unsuitable for backporting. If backporting was not considered at
all, join the newest discussion, asking if it's in the cards.*
In a lot of cases the issue you deal with will have happened with mainline, but
got fixed there. The commit that fixed it would need to get backported as well
to get the issue solved. That's why you want to search for it or any
discussions abound it.
* First try to find the fix in the Git repository that holds the Linux kernel
sources. You can do this with the web interfaces `on kernel.org
<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/>`_
or its mirror `on GitHub <https://github.com/torvalds/linux>`_; if you have
a local clone you alternatively can search on the command line with ``git
log --grep=<pattern>``.
If you find the fix, look if the commit message near the end contains a
'stable tag' that looks like this:
Cc: <stable@vger.kernel.org> # 5.4+
If that's case the developer marked the fix safe for backporting to version
line 5.4 and later. Most of the time it's getting applied there within two
weeks, but sometimes it takes a bit longer.
* If the commit doesn't tell you anything or if you can't find the fix, look
again for discussions about the issue. Search the net with your favorite
internet search engine as well as the archives for the `Linux kernel
developers mailing list <https://lore.kernel.org/lkml/>`_. Also read the
section `Locate kernel area that causes the issue` above and follow the
instructions to find the subsystem in question: its bug tracker or mailing
list archive might have the answer you are looking for.
* If you see a proposed fix, search for it in the version control system as
outlined above, as the commit might tell you if a backport can be expected.
* Check the discussions for any indicators the fix might be too risky to get
backported to the version line you care about. If that's the case you have
to live with the issue or switch to the kernel version line where the fix
got applied.
* If the fix doesn't contain a stable tag and backporting was not discussed,
join the discussion: mention the version where you face the issue and that
you would like to see it fixed, if suitable.
Check if it's a regression specific to stable or longterm kernels
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*Check if you're dealing with a regression that was never present in
mainline by installing the first release of the version line you care
about. If the issue doesn't show up with it, you basically need to report
the issue with this version like you would report a problem with mainline
(see above). This ideally includes a bisection followed by a search for
existing reports on the net; with the help of the subject and the two
relevant commit-ids. If that doesn't turn up anything, write the report; CC
or forward the report to the stable maintainers, the stable mailing list,
and those who authored the change. Include the shortened commit-id if you
found the change that causes it.*
Sometimes you won't find anything in the previous step: the issue you face
might have never occurred in mainline, as it is caused by some change that is
incomplete or not correctly applied. To check this, install the first release
from version line you care about, e.g., if you care about 5.4.x, install 5.4.
If the issue doesn't show itself there, it's a regression specific to the
particular version line. In that case you need to report it like an issue
happening in mainline, like the last few steps in the main section in the above
outline.
One of them suggests doing a bisection, which you are strongly advised to do in
this case. After finding the culprit, search the net for existing reports
again: not only search for the exact subject and the commit-id (proper and
shortened to twelve characters) of the change, but also for the commit-id
(proper and shortened) mentioned as 'Upstream commit' in the commit message.
Write the report; just keep a few specialties in mind: CC or forward the report
to the stable maintainers, the stable mailing list, which the :ref:`MAINTAINERS
<maintainers>` file mentions in the section "STABLE BRANCH". If you performed a
successful bisection, CC the author of the change and include its subject and
the shortened commit-id.
Ask for advice
~~~~~~~~~~~~~~
*One of the former steps should lead to a solution. If that doesn't work
out, ask the maintainers for the subsystem that seems to be causing the
issue for advice; CC the mailing list for the particular subsystem as well
as the stable mailing list.*
If the previous three steps didn't get you closer to a solution there is only
one option left: ask for advice. Do that in a mail you sent to the maintainers
for the subsystem where the issue seems to have its roots; CC the mailing list
for the subsystem as well as the stable mailing list the :ref:`MAINTAINERS
<maintainers>` file mention in the section "STABLE BRANCH".
Why some issues won't get any reaction or remain unfixed after being reported
=============================================================================
When reporting a problem to the Linux developers, be aware only 'issues of high
priority' (regressions, security issues, severe problems) are definitely going
to get resolved. The maintainers or if all else fails Linus Torvalds himself
will make sure of that. They and the other kernel developers will fix a lot of
other issues as well. But be aware that sometimes they can't or won't help; and
sometimes there isn't even anyone to send a report to.
This is best explained with kernel developers that contribute to the Linux
kernel in their spare time. Quite a few of the drivers in the kernel were
written by such programmers, often because they simply wanted to make their
hardware usable on their favorite operating system.
These programmers most of the time will happily fix problems other people
report. But nobody can force them to do, as they are contributing voluntarily.
Then there are situations where such developers really want to fix an issue,
but can't: sometimes they lack hardware programming documentation to do so.
This often happens when the publicly available docs are superficial or the
driver was written with the help of reverse engineering.
Sooner or later spare time developers will also stop caring for the driver.
Maybe their test hardware broke, got replaced by something more fancy, or is so
old that it's something you don't find much outside of computer museums
anymore. Sometimes developer stops caring for their code and Linux at all, as
something different in their life became way more important. In some cases
nobody is willing to take over the job as maintainer – and nobody can be forced
to, as contributing to the Linux kernel is done on a voluntary basis. Abandoned
drivers nevertheless remain in the kernel: they are still useful for people and
removing would be a regression.
The situation is not that different with developers that are paid for their
work on the Linux kernel. Those contribute most changes these days. But their
employers sooner or later also stop caring for their code or make its
programmer focus on other things. Hardware vendors for example earn their money
mainly by selling new hardware; quite a few of them hence are not investing
much time and energy in maintaining a Linux kernel driver for something they
stopped selling years ago. Enterprise Linux distributors often care for a
longer time period, but in new versions often leave support for old and rare
hardware aside to limit the scope. Often spare time contributors take over once
a company orphans some code, but as mentioned above: sooner or later they will
leave the code behind, too.
Priorities are another reason why some issues are not fixed, as maintainers
quite often are forced to set those, as time to work on Linux is limited.
That's true for spare time or the time employers grant their developers to
spend on maintenance work on the upstream kernel. Sometimes maintainers also
get overwhelmed with reports, even if a driver is working nearly perfectly. To
not get completely stuck, the programmer thus might have no other choice than
to prioritize issue reports and reject some of them.
But don't worry too much about all of this, a lot of drivers have active
maintainers who are quite interested in fixing as many issues as possible.
Closing words
=============
Compared with other Free/Libre & Open Source Software it's hard to report
issues to the Linux kernel developers: the length and complexity of this
document and the implications between the lines illustrate that. But that's how
it is for now. The main author of this text hopes documenting the state of the
art will lay some groundwork to improve the situation over time.
Documentation/admin-guide/security-bugs.rst
View file @ ff613595
......@@ -21,7 +21,7 @@ understand and fix the security vulnerability.
As it is with any bug, the more information provided the easier it
will be to diagnose and fix. Please review the procedure outlined in
:doc:`reporting-bugs` if you are unclear about what
'Documentation/admin-guide/reporting-issues.rst' if you are unclear about what
information is helpful. Any exploit code is very helpful and will not
be released without consent from the reporter unless it has already been
made public.
......
Documentation/admin-guide/sysctl/abi.rst
View file @ ff613595
......@@ -28,7 +28,7 @@ vsyscall32 (x86)
Determines whether the kernels maps a vDSO page into 32-bit processes;
can be set to 1 to enable, or 0 to disable. Defaults to enabled if
``CONFIG_COMPAT_VDSO`` is set, disabled otherwide.
``CONFIG_COMPAT_VDSO`` is set, disabled otherwise.
This controls the same setting as the ``vdso32`` kernel boot
parameter.
Documentation/admin-guide/sysctl/kernel.rst
View file @ ff613595
......@@ -14,7 +14,7 @@ For general info and legal blurb, please look in :doc:`index`.
------------------------------------------------------------------------------
This file contains documentation for the sysctl files in
``/proc/sys/kernel/`` and is valid for Linux kernel version 2.2.
``/proc/sys/kernel/``.
The files in this directory can be used to tune and monitor
miscellaneous and general things in the operation of the Linux
......@@ -879,7 +879,7 @@ The default value is 127.
perf_event_mlock_kb
===================
Control size of per-cpu ring buffer not counted agains mlock limit.
Control size of per-cpu ring buffer not counted against mlock limit.
The default value is 512 + 1 page
......@@ -1095,8 +1095,8 @@ Enables/disables scheduler statistics. Enabling this feature
incurs a small amount of overhead in the scheduler but is
useful for debugging and performance tuning.
sched_util_clamp_min:
=====================
sched_util_clamp_min
====================
Max allowed *minimum* utilization.
......@@ -1106,8 +1106,8 @@ It means that any requested uclamp.min value cannot be greater than
sched_util_clamp_min, i.e., it is restricted to the range
[0:sched_util_clamp_min].
sched_util_clamp_max:
=====================
sched_util_clamp_max
====================
Max allowed *maximum* utilization.
......@@ -1117,8 +1117,8 @@ It means that any requested uclamp.max value cannot be greater than
sched_util_clamp_max, i.e., it is restricted to the range
[0:sched_util_clamp_max].
sched_util_clamp_min_rt_default:
================================
sched_util_clamp_min_rt_default
===============================
By default Linux is tuned for performance. Which means that RT tasks always run
at the highest frequency and most capable (highest capacity) CPU (in
......@@ -1336,7 +1336,7 @@ ORed together. The letters are seen in "Tainted" line of Oops reports.
====== ===== ==============================================================
1 `(P)` proprietary module was loaded
2 `(F)` module was force loaded
4 `(S)` SMP kernel oops on an officially SMP incapable processor
4 `(S)` kernel running on an out of specification system
8 `(R)` module was force unloaded
16 `(M)` processor reported a Machine Check Exception (MCE)
32 `(B)` bad page referenced or some unexpected page flags
......
Documentation/admin-guide/sysctl/vm.rst
View file @ ff613595
......@@ -146,7 +146,7 @@ This should be used on systems where stalls for minor page faults are an
acceptable trade for large contiguous free memory. Set to 0 to prevent
compaction from moving pages that are unevictable. Default value is 1.
On CONFIG_PREEMPT_RT the default value is 0 in order to avoid a page fault, due
to compaction, which would block the task from becomming active until the fault
to compaction, which would block the task from becoming active until the fault
is resolved.
......
Documentation/admin-guide/tainted-kernels.rst
View file @ ff613595
......@@ -84,7 +84,7 @@ Bit Log Number Reason that got the kernel tainted
=== === ====== ========================================================
0 G/P 1 proprietary module was loaded
1 _/F 2 module was force loaded
2 _/S 4 SMP kernel oops on an officially SMP incapable processor
2 _/S 4 kernel running on an out of specification system
3 _/R 8 module was force unloaded
4 _/M 16 processor reported a Machine Check Exception (MCE)
5 _/B 32 bad page referenced or some unexpected page flags
......@@ -116,10 +116,23 @@ More detailed explanation for tainting
1) ``F`` if any module was force loaded by ``insmod -f``, ``' '`` if all
modules were loaded normally.
2) ``S`` if the oops occurred on an SMP kernel running on hardware that
hasn't been certified as safe to run multiprocessor.
Currently this occurs only on various Athlons that are not
SMP capable.
2) ``S`` if the kernel is running on a processor or system that is out of
specification: hardware has been put into an unsupported configuration,
therefore proper execution cannot be guaranteed.
Kernel will be tainted if, for example:
- on x86: PAE is forced through forcepae on intel CPUs (such as Pentium M)
which do not report PAE but may have a functional implementation, an SMP
kernel is running on non officially capable SMP Athlon CPUs, MSRs are
being poked at from userspace.
- on arm: kernel running on certain CPUs (such as Keystone 2) without
having certain kernel features enabled.
- on arm64: there are mismatched hardware features between CPUs, the
bootloader has booted CPUs in different modes.
- certain drivers are being used on non supported architectures (such as
scsi/snic on something else than x86_64, scsi/ips on non
x86/x86_64/itanium, have broken firmware settings for the
irqchip/irq-gic on arm64 ...).
3) ``R`` if a module was force unloaded by ``rmmod -f``, ``' '`` if all
modules were unloaded normally.
......
Documentation/arm/features.rst 0 → 100644
View file @ ff613595
.. SPDX-License-Identifier: GPL-2.0
.. kernel-feat:: $srctree/Documentation/features arm
Documentation/arm/index.rst
View file @ ff613595
......@@ -23,6 +23,8 @@ ARM Architecture
vlocks
porting
features
SoC-specific documents
======================
......
Documentation/arm/sunxi.rst
View file @ ff613595
......@@ -158,3 +158,13 @@ SunXi family
* User Manual
https://linux-sunxi.org/images/4/46/Allwinner_H6_V200_User_Manual_V1.1.pdf
- Allwinner H616
* Datasheet
https://linux-sunxi.org/images/b/b9/H616_Datasheet_V1.0_cleaned.pdf
* User Manual
https://linux-sunxi.org/images/2/24/H616_User_Manual_V1.0_cleaned.pdf
Documentation/arm64/elf_hwcaps.rst
View file @ ff613595
.. _elf_hwcaps_index:
================
ARM64 ELF hwcaps
================
......
Documentation/arm64/features.rst 0 → 100644
View file @ ff613595
.. SPDX-License-Identifier: GPL-2.0
.. kernel-feat:: $srctree/Documentation/features arm64
Documentation/arm64/index.rst
View file @ ff613595
......@@ -24,6 +24,8 @@ ARM64 Architecture
tagged-address-abi
tagged-pointers
features
.. only:: subproject and html
Indices
......
Documentation/arm64/perf.rst
View file @ ff613595
.. SPDX-License-Identifier: GPL-2.0
.. _perf_index:
=====================
Perf Event Attributes
=====================
......
Documentation/conf.py
View file @ ff613595
......@@ -39,7 +39,7 @@ needs_sphinx = '1.3'
extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
'kfigure', 'sphinx.ext.ifconfig', 'automarkup',
'maintainers_include', 'sphinx.ext.autosectionlabel',
'kernel_abi']
'kernel_abi', 'kernel_feat']
#
# cdomain is badly broken in Sphinx 3+. Leaving it out generates *most*
......@@ -112,6 +112,9 @@ if major >= 3:
else:
extensions.append('cdomain')
if major == 1 and minor < 7:
sys.stderr.write('WARNING: Sphinx 1.7 or greater will be required as of '
'the 5.12 release\n')
# Ensure that autosectionlabel will produce unique names
autosectionlabel_prefix_document = True
......
Documentation/core-api/printk-formats.rst
View file @ ff613595
......@@ -531,7 +531,9 @@ For printing bitmap and its derivatives such as cpumask and nodemask,
%*pb outputs the bitmap with field width as the number of bits and %*pbl
output the bitmap as range list with field width as the number of bits.
Passed by reference.
The field width is passed by value, the bitmap is passed by reference.
Helper macros cpumask_pr_args() and nodemask_pr_args() are available to ease
printing cpumask and nodemask.
Flags bitfields such as page flags, gfp_flags
---------------------------------------------
......
Documentation/dev-tools/coccinelle.rst
View file @ ff613595
......@@ -224,14 +224,21 @@ you may want to use::
rm -f err.log
export COCCI=scripts/coccinelle/misc/irqf_oneshot.cocci
make coccicheck DEBUG_FILE="err.log" MODE=report SPFLAGS="--profile --show-trying" M=./drivers/mfd/arizona-irq.c
make coccicheck DEBUG_FILE="err.log" MODE=report SPFLAGS="--profile --show-trying" M=./drivers/mfd
err.log will now have the profiling information, while stdout will
provide some progress information as Coccinelle moves forward with
work.
NOTE:
DEBUG_FILE support is only supported when using coccinelle >= 1.0.2.
Currently, DEBUG_FILE support is only available to check folders, and
not single files. This is because checking a single file requires spatch
to be called twice leading to DEBUG_FILE being set both times to the same value,
giving rise to an error.
.cocciconfig support
--------------------
......
Documentation/dev-tools/kasan.rst
View file @ ff613595
......@@ -330,7 +330,7 @@ using something like insmod or modprobe. The module is called ``test_kasan``.
~~~~~~~~~~~~~
With ``CONFIG_KUNIT`` built-in, ``CONFIG_KASAN_KUNIT_TEST`` can be built-in
on any architecure that supports KASAN. These and any other KUnit
on any architecture that supports KASAN. These and any other KUnit
tests enabled will run and print the results at boot as a late-init
call.
......@@ -351,5 +351,5 @@ converted to KUnit. These tests can be run only as a module with
``CONFIG_KASAN`` built-in. The type of error expected and the
function being run is printed before the expression expected to give
an error. Then the error is printed, if found, and that test
should be interpretted to pass only if the error was the one expected
should be interpreted to pass only if the error was the one expected
by the test.
Documentation/dev-tools/kcov.rst
View file @ ff613595
......@@ -243,7 +243,7 @@ handles as they don't belong to a particular subsystem. The bytes 4-7 are
currently reserved and must be zero. In the future the number of bytes
used for the subsystem or handle ids might be increased.
When a particular userspace proccess collects coverage via a common
When a particular userspace process collects coverage via a common
handle, kcov will collect coverage for each code section that is annotated
to use the common handle obtained as kcov_handle from the current
task_struct. However non common handles allow to collect coverage
......
Documentation/dev-tools/kgdb.rst
View file @ ff613595
......@@ -63,10 +63,9 @@ will want to turn on ``CONFIG_DEBUG_INFO`` which is called
It is advised, but not required, that you turn on the
``CONFIG_FRAME_POINTER`` kernel option which is called :menuselection:`Compile
the kernel with frame pointers` in the config menu. This option inserts code
to into the compiled executable which saves the frame information in
registers or on the stack at different points which allows a debugger
such as gdb to more accurately construct stack back traces while
debugging the kernel.
into the compiled executable which saves the frame information in registers
or on the stack at different points which allows a debugger such as gdb to
more accurately construct stack back traces while debugging the kernel.
If the architecture that you are using supports the kernel option
``CONFIG_STRICT_KERNEL_RWX``, you should consider turning it off. This
......
Documentation/devicetree/bindings/submitting-patches.rst
View file @ ff613595
......@@ -25,7 +25,8 @@ I. For patch submitters
make dt_binding_check
See ../writing-schema.rst for more details about schema and tools setup.
See Documentation/devicetree/writing-schema.rst for more details about
schema and tools setup.
3) DT binding files should be dual licensed. The preferred license tag is
(GPL-2.0-only OR BSD-2-Clause).
......
Documentation/doc-guide/kernel-doc.rst
View file @ ff613595
......@@ -247,12 +247,12 @@ It is possible to document nested structs and unions, like::
struct {
int memb1;
int memb2;
}
};
struct {
void *memb3;
int memb4;
}
}
};
};
union {
struct {
int memb1;
......
Documentation/doc-guide/sphinx.rst
View file @ ff613595
......@@ -375,7 +375,7 @@ image format use SVG (:ref:`svg_image_example`)::
SVG image example
The kernel figure (and image) directive support **DOT** formated files, see
The kernel figure (and image) directive support **DOT** formatted files, see
* DOT: http://graphviz.org/pdf/dotguide.pdf
* Graphviz: http://www.graphviz.org/content/dot-language
......
Documentation/driver-api/index.rst
View file @ ff613595
......@@ -29,6 +29,7 @@ available subsections can be seen below.
infiniband
frame-buffer
regulator
reset
iio/index
input
usb/index
......
Documentation/driver-api/mtd/intel-spi.rst
View file @ ff613595
......@@ -52,7 +52,7 @@ Linux.
16384+0 records out
8388608 bytes (8.4 MB) copied, 10.0269 s, 837 kB/s
6) Verify the backup:
6) Verify the backup::
# sha1sum /dev/mtd0ro bios.bak
fdbb011920572ca6c991377c4b418a0502668b73 /dev/mtd0ro
......@@ -66,7 +66,7 @@ Linux.
# flash_erase /dev/mtd0 0 0
Erasing 4 Kibyte @ 7ff000 -- 100 % complete
8) Once completed without errors you can write the new BIOS image:
8) Once completed without errors you can write the new BIOS image::
# dd if=MNW2MAX1.X64.0092.R01.1605221712.bin of=/dev/mtd0
......
Documentation/driver-api/mtd/spi-nor.rst
View file @ ff613595
......@@ -34,7 +34,8 @@ Before this framework, the layer is like::
------------------------
SPI NOR chip
After this framework, the layer is like:
After this framework, the layer is like::
MTD
------------------------
SPI NOR framework
......@@ -45,7 +46,8 @@ Before this framework, the layer is like::
------------------------
SPI NOR chip
With the SPI NOR controller driver (Freescale QuadSPI), it looks like:
With the SPI NOR controller driver (Freescale QuadSPI), it looks like::
MTD
------------------------
SPI NOR framework
......
Documentation/driver-api/reset.rst 0 → 100644
View file @ ff613595
.. SPDX-License-Identifier: GPL-2.0-only
====================
Reset controller API
====================
Introduction
============
Reset controllers are central units that control the reset signals to multiple
peripherals.
The reset controller API is split into two parts:
the `consumer driver interface <#consumer-driver-interface>`__ (`API reference
<#reset-consumer-api>`__), which allows peripheral drivers to request control
over their reset input signals, and the `reset controller driver interface
<#reset-controller-driver-interface>`__ (`API reference
<#reset-controller-driver-api>`__), which is used by drivers for reset
controller devices to register their reset controls to provide them to the
consumers.
While some reset controller hardware units also implement system restart
functionality, restart handlers are out of scope for the reset controller API.
Glossary
--------
The reset controller API uses these terms with a specific meaning:
Reset line
Physical reset line carrying a reset signal from a reset controller
hardware unit to a peripheral module.
Reset control
Control method that determines the state of one or multiple reset lines.
Most commonly this is a single bit in reset controller register space that
either allows direct control over the physical state of the reset line, or
is self-clearing and can be used to trigger a predetermined pulse on the
reset line.
In more complicated reset controls, a single trigger action can launch a
carefully timed sequence of pulses on multiple reset lines.
Reset controller
A hardware module that provides a number of reset controls to control a
number of reset lines.
Reset consumer
Peripheral module or external IC that is put into reset by the signal on a
reset line.
Consumer driver interface
=========================
This interface provides an API that is similar to the kernel clock framework.
Consumer drivers use get and put operations to acquire and release reset
controls.
Functions are provided to assert and deassert the controlled reset lines,
trigger reset pulses, or to query reset line status.
When requesting reset controls, consumers can use symbolic names for their
reset inputs, which are mapped to an actual reset control on an existing reset
controller device by the core.
A stub version of this API is provided when the reset controller framework is
not in use in order to minimize the need to use ifdefs.
Shared and exclusive resets
---------------------------
The reset controller API provides either reference counted deassertion and
assertion or direct, exclusive control.
The distinction between shared and exclusive reset controls is made at the time
the reset control is requested, either via devm_reset_control_get_shared() or
via devm_reset_control_get_exclusive().
This choice determines the behavior of the API calls made with the reset
control.
Shared resets behave similarly to clocks in the kernel clock framework.
They provide reference counted deassertion, where only the first deassert,
which increments the deassertion reference count to one, and the last assert
which decrements the deassertion reference count back to zero, have a physical
effect on the reset line.
Exclusive resets on the other hand guarantee direct control.
That is, an assert causes the reset line to be asserted immediately, and a
deassert causes the reset line to be deasserted immediately.
Assertion and deassertion
-------------------------
Consumer drivers use the reset_control_assert() and reset_control_deassert()
functions to assert and deassert reset lines.
For shared reset controls, calls to the two functions must be balanced.
Note that since multiple consumers may be using a shared reset control, there
is no guarantee that calling reset_control_assert() on a shared reset control
will actually cause the reset line to be asserted.
Consumer drivers using shared reset controls should assume that the reset line
may be kept deasserted at all times.
The API only guarantees that the reset line can not be asserted as long as any
consumer has requested it to be deasserted.
Triggering
----------
Consumer drivers use reset_control_reset() to trigger a reset pulse on a
self-deasserting reset control.
In general, these resets can not be shared between multiple consumers, since
requesting a pulse from any consumer driver will reset all connected
peripherals.
The reset controller API allows requesting self-deasserting reset controls as
shared, but for those only the first trigger request causes an actual pulse to
be issued on the reset line.
All further calls to this function have no effect until all consumers have
called reset_control_rearm().
For shared reset controls, calls to the two functions must be balanced.
This allows devices that only require an initial reset at any point before the
driver is probed or resumed to share a pulsed reset line.
Querying
--------
Only some reset controllers support querying the current status of a reset
line, via reset_control_status().
If supported, this function returns a positive non-zero value if the given
reset line is asserted.
The reset_control_status() function does not accept a
`reset control array <#reset-control-arrays>`__ handle as its input parameter.
Optional resets
---------------
Often peripherals require a reset line on some platforms but not on others.
For this, reset controls can be requested as optional using
devm_reset_control_get_optional_exclusive() or
devm_reset_control_get_optional_shared().
These functions return a NULL pointer instead of an error when the requested
reset control is not specified in the device tree.
Passing a NULL pointer to the reset_control functions causes them to return
quietly without an error.
Reset control arrays
--------------------
Some drivers need to assert a bunch of reset lines in no particular order.
devm_reset_control_array_get() returns an opaque reset control handle that can
be used to assert, deassert, or trigger all specified reset controls at once.
The reset control API does not guarantee the order in which the individual
controls therein are handled.
Reset controller driver interface
=================================
Drivers for reset controller modules provide the functionality necessary to
assert or deassert reset signals, to trigger a reset pulse on a reset line, or
to query its current state.
All functions are optional.
Initialization
--------------
Drivers fill a struct :c:type:`reset_controller_dev` and register it with
reset_controller_register() in their probe function.
The actual functionality is implemented in callback functions via a struct
:c:type:`reset_control_ops`.
API reference
=============
The reset controller API is documented here in two parts:
the `reset consumer API <#reset-consumer-api>`__ and the `reset controller
driver API <#reset-controller-driver-api>`__.
Reset consumer API
------------------
Reset consumers can control a reset line using an opaque reset control handle,
which can be obtained from devm_reset_control_get_exclusive() or
devm_reset_control_get_shared().
Given the reset control, consumers can call reset_control_assert() and
reset_control_deassert(), trigger a reset pulse using reset_control_reset(), or
query the reset line status using reset_control_status().
.. kernel-doc:: include/linux/reset.h
:internal:
.. kernel-doc:: drivers/reset/core.c
:functions: reset_control_reset
reset_control_assert
reset_control_deassert
reset_control_status
reset_control_acquire
reset_control_release
reset_control_rearm
reset_control_put
of_reset_control_get_count
of_reset_control_array_get
devm_reset_control_array_get
reset_control_get_count
Reset controller driver API
---------------------------
Reset controller drivers are supposed to implement the necessary functions in
a static constant structure :c:type:`reset_control_ops`, allocate and fill out
a struct :c:type:`reset_controller_dev`, and register it using
devm_reset_controller_register().
.. kernel-doc:: include/linux/reset-controller.h
:internal:
.. kernel-doc:: drivers/reset/core.c
:functions: of_reset_simple_xlate
reset_controller_register
reset_controller_unregister
devm_reset_controller_register
reset_controller_add_lookup
Documentation/features/list-arch.sh
View file @ ff613595
# SPDX-License-Identifier: GPL-2.0
#
# Small script that visualizes the kernel feature support status
# of an architecture.
......@@ -7,18 +8,4 @@
ARCH=${1:-$(uname -m | sed 's/x86_64/x86/' | sed 's/i386/x86/')}
cd $(dirname $0)
echo "#"
echo "# Kernel feature support matrix of the '$ARCH' architecture:"
echo "#"
for F in */*/arch-support.txt; do
SUBSYS=$(echo $F | cut -d/ -f1)
N=$(grep -h "^# Feature name:" $F | cut -c25-)
C=$(grep -h "^# Kconfig:" $F | cut -c25-)
D=$(grep -h "^# description:" $F | cut -c25-)
S=$(grep -hv "^#" $F | grep -w $ARCH | cut -d\| -f3)
printf "%10s/%-22s:%s| %35s # %s\n" "$SUBSYS" "$N" "$S" "$C" "$D"
done
$(dirname $0)/../../scripts/get_feat.pl list --arch $ARCH
Documentation/features/locking/queued-rwlocks/arch-support.txt
View file @ ff613595
......@@ -22,7 +22,7 @@
| nios2: | TODO |
| openrisc: | ok |
| parisc: | TODO |
| powerpc: | TODO |
| powerpc: | ok |
| riscv: | TODO |
| s390: | TODO |
| sh: | TODO |
......
Documentation/features/locking/queued-spinlocks/arch-support.txt
View file @ ff613595
......@@ -22,7 +22,7 @@
| nios2: | TODO |
| openrisc: | ok |
| parisc: | TODO |
| powerpc: | TODO |
| powerpc: | ok |
| riscv: | TODO |
| s390: | TODO |
| sh: | TODO |
......
Documentation/features/seccomp/seccomp-filter/arch-support.txt
View file @ ff613595
......@@ -11,7 +11,7 @@
| arm: | ok |
| arm64: | ok |
| c6x: | TODO |
| csky: | TODO |
| csky: | ok |
| h8300: | TODO |
| hexagon: | TODO |
| ia64: | TODO |
......@@ -25,7 +25,7 @@
| powerpc: | ok |
| riscv: | ok |
| s390: | ok |
| sh: | TODO |
| sh: | ok |
| sparc: | TODO |
| um: | ok |
| x86: | ok |
......
Documentation/features/time/context-tracking/arch-support.txt
View file @ ff613595
......@@ -11,7 +11,7 @@
| arm: | ok |
| arm64: | ok |
| c6x: | TODO |
| csky: | TODO |
| csky: | ok |
| h8300: | TODO |
| hexagon: | TODO |
| ia64: | TODO |
......
Documentation/features/time/virt-cpuacct/arch-support.txt
View file @ ff613595
......@@ -11,7 +11,7 @@
| arm: | ok |
| arm64: | ok |
| c6x: | TODO |
| csky: | TODO |
| csky: | ok |
| h8300: | TODO |
| hexagon: | TODO |
| ia64: | ok |
......
Documentation/filesystems/index.rst
View file @ ff613595
......@@ -113,7 +113,7 @@ Documentation for filesystem implementations.
sysv-fs
tmpfs
ubifs
ubifs-authentication.rst
ubifs-authentication
udf
virtiofs
vfat
......
Documentation/filesystems/mount_api.rst
View file @ ff613595
......@@ -774,7 +774,7 @@ process the parameters it is given.
should just be set to lie inside the low-to-high range.
If all is good, true is returned. If the table is invalid, errors are
logged to dmesg and false is returned.
logged to the kernel log buffer and false is returned.
* ::
......@@ -782,7 +782,7 @@ process the parameters it is given.
This performs some validation checks on a parameter description. It
returns true if the description is good and false if it is not. It will
log errors to dmesg if validation fails.
log errors to the kernel log buffer if validation fails.
* ::
......
Documentation/filesystems/proc.rst
View file @ ff613595
......@@ -546,6 +546,7 @@ encoded manner. The codes are the following:
nh no huge page advise flag
mg mergable advise flag
bt arm64 BTI guarded page
mt arm64 MTE allocation tags are enabled
== =======================================
Note that there is no guarantee that every flag and associated mnemonic will
......
Documentation/ia64/features.rst 0 → 100644
View file @ ff613595
.. SPDX-License-Identifier: GPL-2.0
.. kernel-feat:: $srctree/Documentation/features ia64
Documentation/ia64/index.rst
View file @ ff613595
......@@ -15,3 +15,5 @@ IA-64 Architecture
irq-redir
mca
serial
features
Documentation/index.rst
View file @ ff613595
......@@ -160,7 +160,7 @@ implementation.
ia64/index
m68k/index
mips/index
nios2/nios2
nios2/index
openrisc/index
parisc/index
powerpc/index
......
Documentation/m68k/features.rst 0 → 100644
View file @ ff613595
.. SPDX-License-Identifier: GPL-2.0
.. kernel-feat:: $srctree/Documentation/features m68k
Documentation/m68k/index.rst
View file @ ff613595
......@@ -10,6 +10,8 @@ m68k Architecture
kernel-options
buddha-driver
features
.. only:: subproject and html
Indices
......
Documentation/mips/features.rst 0 → 100644
View file @ ff613595
.. SPDX-License-Identifier: GPL-2.0
.. kernel-feat:: $srctree/Documentation/features mips
Documentation/mips/index.rst
View file @ ff613595
......@@ -11,6 +11,8 @@ MIPS-specific Documentation
booting
ingenic-tcu
features
.. only:: subproject and html
Indices
......
Documentation/networking/device_drivers/ethernet/3com/vortex.rst
View file @ ff613595
......@@ -374,8 +374,8 @@ steps you should take:
email address will be in the driver source or in the MAINTAINERS file.
- The contents of your report will vary a lot depending upon the
problem. If it's a kernel crash then you should refer to the
admin-guide/reporting-bugs.rst file.
problem. If it's a kernel crash then you should refer to
'Documentation/admin-guide/reporting-issues.rst'.
But for most problems it is useful to provide the following:
......
Documentation/nios2/features.rst 0 → 100644
View file @ ff613595
.. SPDX-License-Identifier: GPL-2.0
.. kernel-feat:: $srctree/Documentation/features nios2
Documentation/nios2/index.rst 0 → 100644
View file @ ff613595
.. SPDX-License-Identifier: GPL-2.0
==============================
Nios II Specific Documentation
==============================
.. toctree::
:maxdepth: 2
:numbered:
nios2
features
Documentation/openrisc/features.rst 0 → 100644
View file @ ff613595
.. SPDX-License-Identifier: GPL-2.0
.. kernel-feat:: $srctree/Documentation/features openrisc
Documentation/openrisc/index.rst
View file @ ff613595
......@@ -10,6 +10,8 @@ OpenRISC Architecture
openrisc_port
todo
features
.. only:: subproject and html
Indices
......
Documentation/parisc/features.rst 0 → 100644
View file @ ff613595
.. SPDX-License-Identifier: GPL-2.0
.. kernel-feat:: $srctree/Documentation/features parisc
Documentation/parisc/index.rst
View file @ ff613595
......@@ -10,6 +10,8 @@ PA-RISC Architecture
debugging
registers
features
.. only:: subproject and html
Indices
......
Documentation/powerpc/features.rst 0 → 100644
View file @ ff613595
.. SPDX-License-Identifier: GPL-2.0
.. kernel-feat:: $srctree/Documentation/features powerpc
Documentation/powerpc/index.rst
View file @ ff613595
......@@ -34,6 +34,8 @@ powerpc
vas-api
vcpudispatch_stats
features
.. only:: subproject and html
Indices
......
Documentation/process/clang-format.rst
View file @ ff613595
......@@ -97,7 +97,7 @@ it can be very useful.
There are integrations for many popular text editors. For some of them,
like vim, emacs, BBEdit and Visual Studio you can find support built-in.
For instructions, read the appropiate section at:
For instructions, read the appropriate section at:
https://clang.llvm.org/docs/ClangFormat.html
......
Documentation/process/embargoed-hardware-issues.rst
View file @ ff613595
......@@ -152,7 +152,7 @@ The disclosing party should provide a list of contacts for all other
entities who have already been, or should be, informed about the issue.
This serves several purposes:
- The list of disclosed entities allows communication accross the
- The list of disclosed entities allows communication across the
industry, e.g. other OS vendors, HW vendors, etc.
- The disclosed entities can be contacted to name experts who should
......
Documentation/process/howto.rst
View file @ ff613595
......@@ -348,11 +348,10 @@ tool. For details on how to use the kernel bugzilla, please see:
https://bugzilla.kernel.org/page.cgi?id=faq.html
The file :ref:`admin-guide/reporting-bugs.rst <reportingbugs>`
in the main kernel source directory has a good
template for how to report a possible kernel bug, and details what kind
of information is needed by the kernel developers to help track down the
problem.
The file 'Documentation/admin-guide/reporting-issues.rst' in the main kernel
source directory has a good template for how to report a possible kernel bug,
and details what kind of information is needed by the kernel developers to help
track down the problem.
Managing bug reports
......
Documentation/process/kernel-docs.rst
View file @ ff613595
......@@ -90,7 +90,7 @@ On-line docs
:Date: 2008
:Keywords: patches, review process, types of submissions, basic rules, case studies
:Description: This paper gives several experience values on what types of patches
there are and how likley they get merged.
there are and how likely they get merged.
:Abstract:
[...]. This paper examines some common problems for
submitting larger changes and some strategies to avoid problems.
......@@ -328,7 +328,7 @@ On-line docs
block devices, hardware interrupts, scsi, DMA, access to user memory,
memory allocation, timers.
:Description: A guide designed to help you get up to speed on the
concepts that are not intuitevly obvious, and to document the internal
concepts that are not intuitively obvious, and to document the internal
structures of Linux.
* Title: **Dynamic Kernels: Modularized Device Drivers**
......
Documentation/process/submitting-patches.rst
View file @ ff613595
......@@ -404,6 +404,8 @@ then you just add a line saying::
using your real name (sorry, no pseudonyms or anonymous contributions.)
This will be done for you automatically if you use ``git commit -s``.
Reverts should also include "Signed-off-by". ``git revert -s`` does that
for you.
Some people also put extra tags at the end. They'll just be ignored for
now, but you can do this to mark internal company procedures or just
......
Documentation/riscv/features.rst 0 → 100644
View file @ ff613595
.. SPDX-License-Identifier: GPL-2.0
.. kernel-feat:: $srctree/Documentation/features riscv
Documentation/riscv/index.rst
View file @ ff613595
......@@ -9,6 +9,8 @@ RISC-V architecture
pmu
patch-acceptance
features
.. only:: subproject and html
Indices
......
Documentation/s390/features.rst 0 → 100644
View file @ ff613595
.. SPDX-License-Identifier: GPL-2.0
.. kernel-feat:: $srctree/Documentation/features s390
Documentation/s390/index.rst
View file @ ff613595
......@@ -19,6 +19,8 @@ s390 Architecture
text_files
features
.. only:: subproject and html
Indices
......
Documentation/sh/features.rst 0 → 100644
View file @ ff613595
.. SPDX-License-Identifier: GPL-2.0
.. kernel-feat:: $srctree/Documentation/features sh
Documentation/sh/index.rst
View file @ ff613595
......@@ -11,6 +11,8 @@ SuperH Interfaces Guide
new-machine
register-banks
features
Memory Management
=================
......
Documentation/sparc/features.rst 0 → 100644
View file @ ff613595
.. SPDX-License-Identifier: GPL-2.0
.. kernel-feat:: $srctree/Documentation/features sparc
Documentation/sparc/index.rst
View file @ ff613595
......@@ -9,3 +9,5 @@ Sparc Architecture
adi
oradax/oracle-dax
features
Documentation/sphinx/automarkup.py
View file @ ff613595
......@@ -53,6 +53,8 @@ RE_typedef = re.compile(r'\b(typedef)\s+([a-zA-Z_]\w+)', flags=ascii_p3)
#
RE_doc = re.compile(r'\bDocumentation(/[\w\-_/]+)(\.\w+)*')
RE_namespace = re.compile(r'^\s*..\s*c:namespace::\s*(\S+)\s*$')
#
# Reserved C words that we should skip when cross-referencing
#
......@@ -70,6 +72,8 @@ Skipfuncs = [ 'open', 'close', 'read', 'write', 'fcntl', 'mmap',
'select', 'poll', 'fork', 'execve', 'clone', 'ioctl',
'socket' ]
c_namespace = ''
def markup_refs(docname, app, node):
t = node.astext()
done = 0
......@@ -128,30 +132,38 @@ def markup_func_ref_sphinx3(docname, app, match):
#
# Go through the dance of getting an xref out of the C domain
#
target = match.group(2)
base_target = match.group(2)
target_text = nodes.Text(match.group(0))
xref = None
if not (target in Skipfuncs or target in Skipnames):
for class_s, reftype_s in zip(class_str, reftype_str):
lit_text = nodes.literal(classes=['xref', 'c', class_s])
lit_text += target_text
pxref = addnodes.pending_xref('', refdomain = 'c',
reftype = reftype_s,
reftarget = target, modname = None,
classname = None)
#
# XXX The Latex builder will throw NoUri exceptions here,
# work around that by ignoring them.
#
try:
xref = cdom.resolve_xref(app.env, docname, app.builder,
reftype_s, target, pxref,
lit_text)
except NoUri:
xref = None
possible_targets = [base_target]
# Check if this document has a namespace, and if so, try
# cross-referencing inside it first.
if c_namespace:
possible_targets.insert(0, c_namespace + "." + base_target)
if xref:
return xref
if base_target not in Skipnames:
for target in possible_targets:
if target not in Skipfuncs:
for class_s, reftype_s in zip(class_str, reftype_str):
lit_text = nodes.literal(classes=['xref', 'c', class_s])
lit_text += target_text
pxref = addnodes.pending_xref('', refdomain = 'c',
reftype = reftype_s,
reftarget = target, modname = None,
classname = None)
#
# XXX The Latex builder will throw NoUri exceptions here,
# work around that by ignoring them.
#
try:
xref = cdom.resolve_xref(app.env, docname, app.builder,
reftype_s, target, pxref,
lit_text)
except NoUri:
xref = None
if xref:
return xref
return target_text
......@@ -179,34 +191,39 @@ def markup_c_ref(docname, app, match):
#
# Go through the dance of getting an xref out of the C domain
#
target = match.group(2)
base_target = match.group(2)
target_text = nodes.Text(match.group(0))
xref = None
if not ((match.re == RE_function and target in Skipfuncs)
or (target in Skipnames)):
lit_text = nodes.literal(classes=['xref', 'c', class_str[match.re]])
lit_text += target_text
pxref = addnodes.pending_xref('', refdomain = 'c',
reftype = reftype_str[match.re],
reftarget = target, modname = None,
classname = None)
#
# XXX The Latex builder will throw NoUri exceptions here,
# work around that by ignoring them.
#
try:
xref = cdom.resolve_xref(app.env, docname, app.builder,
reftype_str[match.re], target, pxref,
lit_text)
except NoUri:
xref = None
#
# Return the xref if we got it; otherwise just return the plain text.
#
if xref:
return xref
else:
return target_text
possible_targets = [base_target]
# Check if this document has a namespace, and if so, try
# cross-referencing inside it first.
if c_namespace:
possible_targets.insert(0, c_namespace + "." + base_target)
if base_target not in Skipnames:
for target in possible_targets:
if not (match.re == RE_function and target in Skipfuncs):
lit_text = nodes.literal(classes=['xref', 'c', class_str[match.re]])
lit_text += target_text
pxref = addnodes.pending_xref('', refdomain = 'c',
reftype = reftype_str[match.re],
reftarget = target, modname = None,
classname = None)
#
# XXX The Latex builder will throw NoUri exceptions here,
# work around that by ignoring them.
#
try:
xref = cdom.resolve_xref(app.env, docname, app.builder,
reftype_str[match.re], target, pxref,
lit_text)
except NoUri:
xref = None
if xref:
return xref
return target_text
#
# Try to replace a documentation reference of the form Documentation/... with a
......@@ -239,7 +256,18 @@ def markup_doc_ref(docname, app, match):
else:
return nodes.Text(match.group(0))
def get_c_namespace(app, docname):
source = app.env.doc2path(docname)
with open(source) as f:
for l in f:
match = RE_namespace.search(l)
if match:
return match.group(1)
return ''
def auto_markup(app, doctree, name):
global c_namespace
c_namespace = get_c_namespace(app, name)
#
# This loop could eventually be improved on. Someday maybe we
# want a proper tree traversal with a lot of awareness of which
......
Documentation/sphinx/kernel_feat.py 0 → 100644
View file @ ff613595
# coding=utf-8
# SPDX-License-Identifier: GPL-2.0
#
u"""
kernel-feat
~~~~~~~~~~~
Implementation of the ``kernel-feat`` reST-directive.
:copyright: Copyright (C) 2016 Markus Heiser
:copyright: Copyright (C) 2016-2019 Mauro Carvalho Chehab
:maintained-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
:license: GPL Version 2, June 1991 see Linux/COPYING for details.
The ``kernel-feat`` (:py:class:`KernelFeat`) directive calls the
scripts/get_feat.pl script to parse the Kernel ABI files.
Overview of directive's argument and options.
.. code-block:: rst
.. kernel-feat:: <ABI directory location>
:debug:
The argument ``<ABI directory location>`` is required. It contains the
location of the ABI files to be parsed.
``debug``
Inserts a code-block with the *raw* reST. Sometimes it is helpful to see
what reST is generated.
"""
import codecs
import os
import subprocess
import sys
from os import path
from docutils import nodes, statemachine
from docutils.statemachine import ViewList
from docutils.parsers.rst import directives, Directive
from docutils.utils.error_reporting import ErrorString
#
# AutodocReporter is only good up to Sphinx 1.7
#
import sphinx
Use_SSI = sphinx.__version__[:3] >= '1.7'
if Use_SSI:
from sphinx.util.docutils import switch_source_input
else:
from sphinx.ext.autodoc import AutodocReporter
__version__ = '1.0'
def setup(app):
app.add_directive("kernel-feat", KernelFeat)
return dict(
version = __version__
, parallel_read_safe = True
, parallel_write_safe = True
)
class KernelFeat(Directive):
u"""KernelFeat (``kernel-feat``) directive"""
required_arguments = 1
optional_arguments = 2
has_content = False
final_argument_whitespace = True
option_spec = {
"debug" : directives.flag
}
def warn(self, message, **replace):
replace["fname"] = self.state.document.current_source
replace["line_no"] = replace.get("line_no", self.lineno)
message = ("%(fname)s:%(line_no)s: [kernel-feat WARN] : " + message) % replace
self.state.document.settings.env.app.warn(message, prefix="")
def run(self):
doc = self.state.document
if not doc.settings.file_insertion_enabled:
raise self.warning("docutils: file insertion disabled")
env = doc.settings.env
cwd = path.dirname(doc.current_source)
cmd = "get_feat.pl rest --dir "
cmd += self.arguments[0]
if len(self.arguments) > 1:
cmd += " --arch " + self.arguments[1]
srctree = path.abspath(os.environ["srctree"])
fname = cmd
# extend PATH with $(srctree)/scripts
path_env = os.pathsep.join([
srctree + os.sep + "scripts",
os.environ["PATH"]
])
shell_env = os.environ.copy()
shell_env["PATH"] = path_env
shell_env["srctree"] = srctree
lines = self.runCmd(cmd, shell=True, cwd=cwd, env=shell_env)
nodeList = self.nestedParse(lines, fname)
return nodeList
def runCmd(self, cmd, **kwargs):
u"""Run command ``cmd`` and return it's stdout as unicode."""
try:
proc = subprocess.Popen(
cmd
, stdout = subprocess.PIPE
, stderr = subprocess.PIPE
, **kwargs
)
out, err = proc.communicate()
out, err = codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-8')
if proc.returncode != 0:
raise self.severe(
u"command '%s' failed with return code %d"
% (cmd, proc.returncode)
)
except OSError as exc:
raise self.severe(u"problems with '%s' directive: %s."
% (self.name, ErrorString(exc)))
return out
def nestedParse(self, lines, fname):
content = ViewList()
node = nodes.section()
if "debug" in self.options:
code_block = "\n\n.. code-block:: rst\n :linenos:\n"
for l in lines.split("\n"):
code_block += "\n " + l
lines = code_block + "\n\n"
for c, l in enumerate(lines.split("\n")):
content.append(l, fname, c)
buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
if Use_SSI:
with switch_source_input(self.state, content):
self.state.nested_parse(content, 0, node, match_titles=1)
else:
self.state.memo.title_styles = []
self.state.memo.section_level = 0
self.state.memo.reporter = AutodocReporter(content, self.state.memo.reporter)
try:
self.state.nested_parse(content, 0, node, match_titles=1)
finally:
self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf
return node.children
Documentation/sphinx/requirements.txt
View file @ ff613595
docutils
Sphinx==2.4.4
sphinx_rtd_theme
six
Documentation/trace/events.rst
View file @ ff613595
......@@ -798,13 +798,13 @@ To trace a synthetic using the piecewise method described above, the
synth_event_trace_start() function is used to 'open' the synthetic
event trace::
struct synth_trace_state trace_state;
struct synth_event_trace_state trace_state;
ret = synth_event_trace_start(schedtest_event_file, &trace_state);
It's passed the trace_event_file representing the synthetic event
using the same methods as described above, along with a pointer to a
struct synth_trace_state object, which will be zeroed before use and
struct synth_event_trace_state object, which will be zeroed before use and
used to maintain state between this and following calls.
Once the event has been opened, which means space for it has been
......@@ -816,7 +816,7 @@ lookup per field.
To assign the values one after the other without lookups,
synth_event_add_next_val() should be used. Each call is passed the
same synth_trace_state object used in the synth_event_trace_start(),
same synth_event_trace_state object used in the synth_event_trace_start(),
along with the value to set the next field in the event. After each
field is set, the 'cursor' points to the next field, which will be set
by the subsequent call, continuing until all the fields have been set
......@@ -845,7 +845,7 @@ this method would be (without error-handling code)::
ret = synth_event_add_next_val(395, &trace_state);
To assign the values in any order, synth_event_add_val() should be
used. Each call is passed the same synth_trace_state object used in
used. Each call is passed the same synth_event_trace_state object used in
the synth_event_trace_start(), along with the field name of the field
to set and the value to set it to. The same sequence of calls as in
the above examples using this method would be (without error-handling
......@@ -867,7 +867,7 @@ can be used but not both at the same time.
Finally, the event won't be actually traced until it's 'closed',
which is done using synth_event_trace_end(), which takes only the
struct synth_trace_state object used in the previous calls::
struct synth_event_trace_state object used in the previous calls::
ret = synth_event_trace_end(&trace_state);
......
Documentation/translations/it_IT/doc-guide/kernel-doc.rst
View file @ ff613595
......@@ -419,26 +419,24 @@ del `dominio Sphinx per il C`_.
Riferimenti usando reStructuredText
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Per fare riferimento a funzioni e tipi di dato definiti nei commenti kernel-doc
all'interno dei documenti reStructuredText, utilizzate i riferimenti dal
`dominio Sphinx per il C`_. Per esempio::
Nei documenti reStructuredText non serve alcuna sintassi speciale per
fare riferimento a funzioni e tipi definiti nei commenti
kernel-doc. Sarà sufficiente terminare i nomi di funzione con ``()``,
e scrivere ``struct``, ``union``, ``enum``, o ``typedef`` prima di un
tipo. Per esempio::
See function :c:func:`foo` and struct/union/enum/typedef :c:type:`bar`.
See foo()
See struct foo.
See union bar.
See enum baz.
See typedef meh.
Nonostante il riferimento ai tipi di dato funzioni col solo nome,
ovvero senza specificare struct/union/enum/typedef, potreste preferire il
seguente::
Tuttavia, la personalizzazione dei collegamenti è possibile solo con
la seguente sintassi::
See :c:type:`struct foo <foo>`.
See :c:type:`union bar <bar>`.
See :c:type:`enum baz <baz>`.
See :c:type:`typedef meh <meh>`.
See :c:func:`my custom link text for function foo <foo>`.
See :c:type:`my custom link text for struct bar <bar>`.
Questo produce dei collegamenti migliori, ed è in linea con il modo in cui
kernel-doc gestisce i riferimenti.
Per maggiori informazioni, siete pregati di consultare la documentazione
del `dominio Sphinx per il C`_.
Commenti per una documentazione generale
----------------------------------------
......
Documentation/translations/it_IT/doc-guide/sphinx.rst
View file @ ff613595
......@@ -364,6 +364,26 @@ Che verrà rappresentata nel seguente modo:
- column 3
Riferimenti incrociati
----------------------
Per fare dei riferimenti incrociati da una pagina ad un'altra
specificando il percorso a partire dalla cartella *Documentation*.
Per esempio, se volete aggiungere un riferimento a questa pagina
(l'estensione .rst è opzionale)::
See Documentation/translations/it_IT/doc-guide/sphinx.rst.
Se preferite usare un percorso relative allora vi serve la direttiva
Sphinx ``doc``. Per esempio, se volete aggiungere un riferimento a
questa pagina dalla stessa cartella::
See :doc:`sphinx`.
Per maggiori informazioni su come aggiungere riferimenti incrociati a
commenti kernel-doc di funzioni o tipi, leggete
Documentation/translations/it_IT/doc-guide/sphinx.rst.
.. _it_sphinx_kfigure:
Figure ed immagini
......
Documentation/translations/it_IT/process/2.Process.rst
View file @ ff613595
......@@ -123,7 +123,7 @@ iniziale, i kernel ricevono aggiornamenti per più di un ciclo di sviluppo.
Quindi, per esempio, la storia del kernel 5.2 appare così (anno 2019):
============== ===============================
15 settembre 5.2 rilascio stabile FIXME settembre è sbagliato
7 luglio 5.2 rilascio stabile
14 luglio 5.2.1
21 luglio 5.2.2
26 luglio 5.2.3
......@@ -434,7 +434,7 @@ l'elenco principale lo si trova sul sito:
http://vger.kernel.org/vger-lists.html
Esistono liste gestite altrove; un certo numero di queste sono in
lists.redhat.com.
redhat.com/mailman/listinfo.
La lista di discussione principale per lo sviluppo del kernel è, ovviamente,
linux-kernel. Questa lista è un luogo ostile dove trovarsi; i volumi possono
......
Documentation/translations/it_IT/process/changes.rst
View file @ ff613595
......@@ -32,9 +32,10 @@ PC Card, per esempio, probabilmente non dovreste preoccuparvi di pcmciautils.
====================== ================= ========================================
Programma Versione minima Comando per verificare la versione
====================== ================= ========================================
GNU C 4.6 gcc --version
GNU C 4.9 gcc --version
Clang/LLVM (optional) 10.0.1 clang --version
GNU make 3.81 make --version
binutils 2.21 ld -v
binutils 2.23 ld -v
flex 2.5.35 flex --version
bison 2.0 bison --version
util-linux 2.10o fdformat --version
......@@ -71,6 +72,16 @@ GCC
La versione necessaria di gcc potrebbe variare a seconda del tipo di CPU nel
vostro calcolatore.
Clang/LLVM (opzionale)
----------------------
L'ultima versione di clang e *LLVM utils* (secondo `releases.llvm.org
<https://releases.llvm.org>`_) sono supportati per la generazione del
kernel. Non garantiamo che anche i rilasci più vecchi funzionino, inoltre
potremmo rimuovere gli espedienti che abbiamo implementato per farli
funzionare. Per maggiori informazioni
:ref:`Building Linux with Clang/LLVM <kbuild_llvm>`.
Make
----
......@@ -79,7 +90,7 @@ Per compilare il kernel vi servirà GNU make 3.81 o successivo.
Binutils
--------
Per generare il kernel è necessario avere Binutils 2.21 o superiore.
Per generare il kernel è necessario avere Binutils 2.23 o superiore.
pkg-config
----------
......@@ -338,6 +349,11 @@ gcc
- <ftp://ftp.gnu.org/gnu/gcc/>
Clang/LLVM
----------
- :ref:`Getting LLVM <getting_llvm>`.
Make
----
......
Documentation/translations/it_IT/process/coding-style.rst
View file @ ff613595
......@@ -92,16 +92,22 @@ delle righe.
Lo stile del codice riguarda la leggibilità e la manutenibilità utilizzando
strumenti comuni.
Il limite delle righe è di 80 colonne e questo e un limite fortemente
desiderato.
Espressioni più lunghe di 80 colonne saranno spezzettate in pezzi più piccoli,
a meno che eccedere le 80 colonne non aiuti ad aumentare la leggibilità senza
nascondere informazioni. I pezzi derivati sono sostanzialmente più corti degli
originali e vengono posizionati più a destra. Lo stesso si applica, nei file
d'intestazione, alle funzioni con una lista di argomenti molto lunga. Tuttavia,
non spezzettate mai le stringhe visibili agli utenti come i messaggi di
printk, questo perché inibireste la possibilità d'utilizzare grep per cercarle.
Come limite di riga si preferiscono le 80 colonne.
Espressioni più lunghe di 80 colonne dovrebbero essere spezzettate in
pezzi più piccoli, a meno che eccedere le 80 colonne non aiuti ad
aumentare la leggibilità senza nascondere informazioni.
I nuovi pezzi derivati sono sostanzialmente più corti degli originali
e vengono posizionati più a destra. Uno stile molto comune è quello di
allineare i nuovi pezzi alla parentesi aperta di una funzione.
Lo stesso si applica, nei file d'intestazione, alle funzioni con una
lista di argomenti molto lunga.
Tuttavia, non spezzettate mai le stringhe visibili agli utenti come i
messaggi di printk, questo perché inibireste la possibilità
d'utilizzare grep per cercarle.
3) Posizionamento di parentesi graffe e spazi
---------------------------------------------
......
Documentation/translations/it_IT/process/deprecated.rst
View file @ ff613595
......@@ -95,6 +95,11 @@ Invece, usate la seguente funzione::
header = kzalloc(struct_size(header, item, count), GFP_KERNEL);
.. note:: Se per caso state usando struct_size() su una struttura dati che
in coda contiene un array di lunghezza zero o uno, allora siete
invitati a riorganizzare il vostro codice usando il
`flexible array member <#zero-length-and-one-element-arrays>`_.
Per maggiori dettagli fate riferimento a array_size(),
array3_size(), e struct_size(), così come la famiglia di
funzioni check_add_overflow() e check_mul_overflow().
......@@ -116,7 +121,11 @@ di destinazione. Questo può portare ad un overflow oltre i limiti del
buffer e generare svariati tipi di malfunzionamenti. Nonostante l'opzione
`CONFIG_FORTIFY_SOURCE=y` e svariate opzioni del compilatore aiutano
a ridurne il rischio, non c'è alcuna buona ragione per continuare ad usare
questa funzione. La versione sicura da usare è strscpy().
questa funzione. La versione sicura da usare è strscpy(), tuttavia va
prestata attenzione a tutti quei casi dove viene usato il valore di
ritorno di strcpy(). La funzione strscpy() non ritorna un puntatore
alla destinazione, ma un contatore dei byte non NUL copiati (oppure
un errno negativo se la stringa è stata troncata).
strncpy() su stringe terminate con NUL
--------------------------------------
......@@ -127,8 +136,12 @@ causati, appunto, dalla mancanza del terminatore. Questa estende la
terminazione nel buffer di destinazione quando la stringa d'origine è più
corta; questo potrebbe portare ad una penalizzazione delle prestazioni per
chi usa solo stringe terminate. La versione sicura da usare è
strscpy(). (chi usa strscpy() e necessita di estendere la
terminazione con NUL deve aggiungere una chiamata a memset())
strscpy(), tuttavia va prestata attenzione a tutti quei casi dove
viene usato il valore di ritorno di strncpy(). La funzione strscpy()
non ritorna un puntatore alla destinazione, ma un contatore dei byte
non NUL copiati (oppure un errno negativo se la stringa è stata
troncata). Tutti i casi che necessitano di estendere la
terminazione con NUL dovrebbero usare strscpy_pad().
Se il chiamate no usa stringhe terminate con NUL, allore strncpy()
può continuare ad essere usata, ma i buffer di destinazione devono essere
......@@ -140,7 +153,10 @@ strlcpy()
La funzione strlcpy(), per prima cosa, legge interamente il buffer di
origine, magari leggendo più di quanto verrà effettivamente copiato. Questo
è inefficiente e può portare a overflow di lettura quando la stringa non è
terminata con NUL. La versione sicura da usare è strscpy().
terminata con NUL. La versione sicura da usare è strscpy(), tuttavia
va prestata attenzione a tutti quei casi dove viene usato il valore di
ritorno di strlcpy(), dato che strscpy() ritorna un valore di errno
negativo quanto la stringa viene troncata.
Segnaposto %p nella stringa di formato
--------------------------------------
......@@ -227,3 +243,126 @@ modi:
* ``continue;``
* ``goto <label>;``
* ``return [expression];``
Array di lunghezza zero o con un solo elemento
----------------------------------------------
All'interno del kernel ricorre spesso la necessita di avere membri
di dimensione variabile all'interno di una struttura dati. In questi
casi il codice del kernel dovrebbe usare sempre i `"flexible array
member" <https://en.wikipedia.org/wiki/Flexible_array_member>`_. La
tecnica degli array a lunghezza nulla o di un solo elemento non
dovrebbe essere più usata.
Nel codice C più vecchio, la dichiarazione di un membro di dimensione
variabile in coda ad una struttura dati veniva fatto dichiarando un
array di un solo elemento posizionato alla fine della struttura dati::
struct something {
size_t count;
struct foo items[1];
};
Questo ha portato ad un calcolo di sizeof() traballante (dovrebbe
rimuovere la dimensione del singolo elemento in coda per calcolare la
dimensione esatta dell' "intestazione"). Per evitare questi problemi è
stata introdotta un' `estensione a GNU C
<https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_ che
permettesse la dichiarazione di array a lungezza zero::
struct something {
size_t count;
struct foo items[0];
};
Ma questo ha portato nuovi problemi, e non ha risolto alcuni dei
problemi che affliggono entrambe le tecniche: per esempio
l'impossibilità di riconoscere se un array di quel tipo viene usato
nel mezzo di una struttura dati e _non_ alla fine (potrebbe accadere
sia direttamente, sia indirettamente quando si usano le unioni o le
strutture di strutture).
Lo standard C99 introduce i "flexible array members". Questi array non
hanno una dimensione nella loro dichiarazione::
struct something {
size_t count;
struct foo items[];
};
Questo è il modo con cui ci si aspetta che vengano dichiarati gli
elementi di lunghezza variabile in coda alle strutture dati. Permette
al compilatore di produrre errori quando gli array flessibili non si
trovano alla fine della struttura dati, il che permette di prevenire
alcuni tipi di bachi dovuti a `comportamenti inaspettati
<https://git.kernel.org/linus/76497732932f15e7323dc805e8ea8dc11bb587cf>`_.
Inoltre, permette al compilatore di analizzare correttamente le
dimensioni degli array (attraverso sizeof(), `CONFIG_FORTIFY_SOURCE`,
e `CONFIG_UBSAN_BOUNDS`). Per esempio, non esiste alcun meccanismo in
grado di avvisarci che il seguente uso di sizeof() dia sempre come
zero come risultato::
struct something {
size_t count;
struct foo items[0];
};
struct something *instance;
instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL);
instance->count = count;
size = sizeof(instance->items) * instance->count;
memcpy(instance->items, source, size);
Il valore di ``size`` nell'ultima riga sarà ``zero``, quando uno
invece si aspetterebbe che il suo valore sia la dimensione totale in
byte dell'allocazione dynamica che abbiamo appena fatto per l'array
``items``. Qui un paio di esempi reali del problema: `collegamento 1
<https://git.kernel.org/linus/f2cd32a443da694ac4e28fbf4ac6f9d5cc63a539>`_,
`collegamento 2
<https://git.kernel.org/linus/ab91c2a89f86be2898cee208d492816ec238b2cf>`_.
Invece, `i flexible array members hanno un tipo incompleto, e quindi
sizeof() non può essere applicato
<https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_; dunque ogni
uso scorretto di questo operatore verrà identificato immediatamente
durante la compilazione.
Per quanto riguarda gli array di un solo elemento, bisogna essere
consapevoli che `questi array occupano almeno quanto lo spazio di un
singolo oggetti dello stesso tipo
<https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_, e quindi
contribuiscono al calcolo della dimensione della struttura che li
contiene. In questo caso è facile commettere errori quando si vuole
calcolare la dimensione totale della memoria totale da allocare per
una struttura dati::
struct something {
size_t count;
struct foo items[1];
};
struct something *instance;
instance = kmalloc(struct_size(instance, items, count - 1), GFP_KERNEL);
instance->count = count;
size = sizeof(instance->items) * instance->count;
memcpy(instance->items, source, size);
In questo esempio ci siamo dovuti ricordare di usare ``count - 1`` in
struct_size(), altrimenti avremmo --inavvertitamente-- allocato
memoria per un oggetti ``items`` in più. Il modo più pulito e meno
propenso agli errori è quello di usare i `flexible array member`, in
combinazione con struct_size() e flex_array_size()::
struct something {
size_t count;
struct foo items[];
};
struct something *instance;
instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL);
instance->count = count;
memcpy(instance->items, source, flex_array_size(instance, items, instance->count));
Documentation/translations/it_IT/process/email-clients.rst
View file @ ff613595
......@@ -32,6 +32,11 @@ impostato come ``text/plain``. Tuttavia, generalmente gli allegati non sono
ben apprezzati perché rende più difficile citare porzioni di patch durante il
processo di revisione.
Inoltre, è vivamente raccomandato l'uso di puro testo nel corpo del
messaggio, sia per la patch che per qualsiasi altro messaggio. Il sito
https://useplaintext.email/ può esservi d'aiuto per configurare il
vostro programma di posta elettronica.
I programmi di posta elettronica che vengono usati per inviare le patch per il
kernel Linux dovrebbero inviarle senza alterazioni. Per esempio, non
dovrebbero modificare o rimuovere tabulazioni o spazi, nemmeno all'inizio o
......
Documentation/translations/it_IT/process/programming-language.rst
View file @ ff613595
......@@ -11,13 +11,15 @@ Linguaggio di programmazione
Il kernel è scritto nel linguaggio di programmazione C [it-c-language]_.
Più precisamente, il kernel viene compilato con ``gcc`` [it-gcc]_ usando
l'opzione ``-std=gnu89`` [it-gcc-c-dialect-options]_: il dialetto GNU
dello standard ISO C90 (con l'aggiunta di alcune funzionalità da C99)
dello standard ISO C90 (con l'aggiunta di alcune funzionalità da C99).
Linux supporta anche ``clang`` [it-clang]_, leggete la documentazione
:ref:`Building Linux with Clang/LLVM <kbuild_llvm>`.
Questo dialetto contiene diverse estensioni al linguaggio [it-gnu-extensions]_,
e molte di queste vengono usate sistematicamente dal kernel.
Il kernel offre un certo livello di supporto per la compilazione con ``clang``
[it-clang]_ e ``icc`` [it-icc]_ su diverse architetture, tuttavia in questo momento
Il kernel offre un certo livello di supporto per la compilazione con
``icc`` [it-icc]_ su diverse architetture, tuttavia in questo momento
il supporto non è completo e richiede delle patch aggiuntive.
Attributi
......
Documentation/translations/it_IT/process/submitting-patches.rst
View file @ ff613595
......@@ -16,21 +16,19 @@ vostre patch accettate.
Questo documento contiene un vasto numero di suggerimenti concisi. Per
maggiori dettagli su come funziona il processo di sviluppo del kernel leggete
:ref:`Documentation/translations/it_IT/process <it_development_process_main>`.
Leggete anche :ref:`Documentation/translations/it_IT/process/submit-checklist.rst <it_submitchecklist>`
per una lista di punti da verificare prima di inviare del codice. Se state
inviando un driver, allora leggete anche :ref:`Documentation/translations/it_IT/process/submitting-drivers.rst <it_submittingdrivers>`;
per delle patch relative alle associazioni per Device Tree leggete
Documentation/devicetree/bindings/submitting-patches.rst.
Molti di questi passi descrivono il comportamento di base del sistema di
controllo di versione ``git``; se utilizzate ``git`` per preparare le vostre
patch molto del lavoro più ripetitivo lo troverete già fatto per voi, tuttavia
dovete preparare e documentare un certo numero di patch. Generalmente, l'uso
di ``git`` renderà la vostra vita di sviluppatore del kernel più facile.
0) Ottenere i sorgenti attuali
------------------------------
:doc:`development-process`.
Leggete anche :doc:`submit-checklist` per una lista di punti da
verificare prima di inviare del codice. Se state inviando un driver,
allora leggete anche :doc:`submitting-drivers`; per delle patch
relative alle associazioni per Device Tree leggete
:doc:`submitting-patches`.
Questa documentazione assume che sappiate usare ``git`` per preparare le patch.
Se non siete pratici di ``git``, allora è bene che lo impariate;
renderà la vostra vita di sviluppatore del kernel molto più semplice.
Ottenere i sorgenti attuali
---------------------------
Se non avete un repositorio coi sorgenti del kernel più recenti, allora usate
``git`` per ottenerli. Vorrete iniziare col repositorio principale che può
......@@ -45,69 +43,10 @@ Guardate l'elemento **T:** per un determinato sottosistema nel file MAINTANERS
che troverete nei sorgenti, o semplicemente chiedete al manutentore nel caso
in cui i sorgenti da usare non siano elencati il quel file.
Esiste ancora la possibilità di scaricare un rilascio del kernel come archivio
tar (come descritto in una delle prossime sezioni), ma questa è la via più
complicata per sviluppare per il kernel.
1) ``diff -up``
---------------
Se dovete produrre le vostre patch a mano, usate ``diff -up`` o ``diff -uprN``
per crearle. Git produce di base le patch in questo formato; se state
usando ``git``, potete saltare interamente questa sezione.
Tutte le modifiche al kernel Linux avvengono mediate patch, come descritte
in :manpage:`diff(1)`. Quando create la vostra patch, assicuratevi di
crearla nel formato "unified diff", come l'argomento ``-u`` di
:manpage:`diff(1)`.
Inoltre, per favore usate l'argomento ``-p`` per mostrare la funzione C
alla quale si riferiscono le diverse modifiche - questo rende il risultato
di ``diff`` molto più facile da leggere. Le patch dovrebbero essere basate
sulla radice dei sorgenti del kernel, e non sulle sue sottocartelle.
Per creare una patch per un singolo file, spesso è sufficiente fare::
SRCTREE=linux
MYFILE=drivers/net/mydriver.c
cd $SRCTREE
cp $MYFILE $MYFILE.orig
vi $MYFILE # make your change
cd ..
diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch
Per creare una patch per molteplici file, dovreste spacchettare i sorgenti
"vergini", o comunque non modificati, e fare un ``diff`` coi vostri.
Per esempio::
MYSRC=/devel/linux
tar xvfz linux-3.19.tar.gz
mv linux-3.19 linux-3.19-vanilla
diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \
linux-3.19-vanilla $MYSRC > /tmp/patch
``dontdiff`` è una lista di file che sono generati durante il processo di
compilazione del kernel; questi dovrebbero essere ignorati in qualsiasi
patch generata con :manpage:`diff(1)`.
Assicuratevi che la vostra patch non includa file che non ne fanno veramente
parte. Al fine di verificarne la correttezza, assicuratevi anche di
revisionare la vostra patch -dopo- averla generata con :manpage:`diff(1)`.
Se le vostre modifiche producono molte differenze, allora dovrete dividerle
in patch indipendenti che modificano le cose in passi logici; leggete
:ref:`split_changes`. Questo faciliterà la revisione da parte degli altri
sviluppatori, il che è molto importante se volete che la patch venga accettata.
Se state utilizzando ``git``, ``git rebase -i`` può aiutarvi nel procedimento.
Se non usate ``git``, un'alternativa popolare è ``quilt``
<http://savannah.nongnu.org/projects/quilt>.
.. _it_describe_changes:
2) Descrivete le vostre modifiche
---------------------------------
Descrivete le vostre modifiche
------------------------------
Descrivete il vostro problema. Esiste sempre un problema che via ha spinto
ha fare il vostro lavoro, che sia la correzione di un baco da una riga o una
......@@ -208,10 +147,15 @@ precedente::
[pretty]
fixes = Fixes: %h (\"%s\")
Un esempio::
$ git log -1 --pretty=fixes 54a4f0239f2e
Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed")
.. _it_split_changes:
3) Separate le vostre modifiche
-------------------------------
Separate le vostre modifiche
----------------------------
Separate ogni **cambiamento logico** in patch distinte.
......@@ -312,7 +256,8 @@ sfruttato, inviatela a security@kernel.org. Per bachi importanti, un breve
embargo potrebbe essere preso in considerazione per dare il tempo alle
distribuzioni di prendere la patch e renderla disponibile ai loro utenti;
in questo caso, ovviamente, la patch non dovrebbe essere inviata su alcuna
lista di discussione pubblica.
lista di discussione pubblica. Leggete anche
:doc:`/admin-guide/security-bugs`.
Patch che correggono bachi importanti su un kernel già rilasciato, dovrebbero
essere inviate ai manutentori dei kernel stabili aggiungendo la seguente riga::
......@@ -354,8 +299,8 @@ Le patch banali devono rientrare in una delle seguenti categorie:
"patch monkey" in modalità ritrasmissione)
6) Niente: MIME, links, compressione, allegati. Solo puro testo
----------------------------------------------------------------
Niente: MIME, links, compressione, allegati. Solo puro testo
-------------------------------------------------------------
Linus e gli altri sviluppatori del kernel devono poter commentare
le modifiche che sottomettete. Per uno sviluppatore è importante
......@@ -364,7 +309,11 @@ programmi di posta elettronica, cosicché sia possibile commentare
una porzione specifica del vostro codice.
Per questa ragione tutte le patch devono essere inviate via e-mail
come testo.
come testo. Il modo più facile, e quello raccomandato, è con ``git
send-email``. Al sito https://git-send-email.io è disponibile una
guida interattiva sull'uso di ``git send-email``.
Se decidete di non usare ``git send-email``:
.. warning::
......@@ -381,28 +330,20 @@ così la possibilità che il vostro allegato-MIME venga accettato.
Eccezione: se il vostro servizio di posta storpia le patch, allora qualcuno
potrebbe chiedervi di rinviarle come allegato MIME.
Leggete :ref:`Documentation/translations/it_IT/process/email-clients.rst <it_email_clients>`
Leggete :doc:`/translations/it_IT/process/email-clients`
per dei suggerimenti sulla configurazione del programmi di posta elettronica
per l'invio di patch intatte.
7) Dimensione delle e-mail
--------------------------
Le grosse modifiche non sono adatte ad una lista di discussione, e nemmeno
per alcuni manutentori. Se la vostra patch, non compressa, eccede i 300 kB
di spazio, allora caricatela in una spazio accessibile su internet fornendo
l'URL (collegamento) ad essa. Ma notate che se la vostra patch eccede i 300 kB
è quasi certo che necessiti comunque di essere spezzettata.
8) Rispondere ai commenti di revisione
--------------------------------------
Rispondere ai commenti di revisione
-----------------------------------
Quasi certamente i revisori vi invieranno dei commenti su come migliorare
la vostra patch. Dovete rispondere a questi commenti; ignorare i revisori
è un ottimo modo per essere ignorati. Riscontri o domande che non conducono
ad una modifica del codice quasi certamente dovrebbero portare ad un commento
nel changelog cosicché il prossimo revisore potrà meglio comprendere cosa stia
accadendo.
In risposta alla vostra email, quasi certamente i revisori vi
invieranno dei commenti su come migliorare la vostra patch. Dovete
rispondere a questi commenti; ignorare i revisori è un ottimo modo per
essere ignorati. Riscontri o domande che non conducono ad una
modifica del codice quasi certamente dovrebbero portare ad un commento
nel changelog cosicché il prossimo revisore potrà meglio comprendere
cosa stia accadendo.
Assicuratevi di dire ai revisori quali cambiamenti state facendo e di
ringraziarli per il loro tempo. Revisionare codice è un lavoro faticoso e che
......@@ -410,8 +351,12 @@ richiede molto tempo, e a volte i revisori diventano burberi. Tuttavia, anche
in questo caso, rispondete con educazione e concentratevi sul problema che
hanno evidenziato.
9) Non scoraggiatevi - o impazientitevi
---------------------------------------
Leggete :doc:`/translations/it_IT/process/email-clients` per
le raccomandazioni sui programmi di posta elettronica e l'etichetta da usare
sulle liste di discussione.
Non scoraggiatevi - o impazientitevi
------------------------------------
Dopo che avete inviato le vostre modifiche, siate pazienti e aspettate.
I revisori sono persone occupate e potrebbero non ricevere la vostra patch
......@@ -424,17 +369,19 @@ aver inviato le patch correttamente. Aspettate almeno una settimana prima di
rinviare le modifiche o sollecitare i revisori - probabilmente anche di più
durante la finestra d'integrazione.
10) Aggiungete PATCH nell'oggetto
---------------------------------
Aggiungete PATCH nell'oggetto
-----------------------------
Dato l'alto volume di e-mail per Linus, e la lista linux-kernel, è prassi
prefiggere il vostro oggetto con [PATCH]. Questo permette a Linus e agli
altri sviluppatori del kernel di distinguere facilmente le patch dalle altre
discussioni.
``git send-email`` lo fa automaticamente.
11) Firmate il vostro lavoro - Il certificato d'origine dello sviluppatore
--------------------------------------------------------------------------
Firmate il vostro lavoro - Il certificato d'origine dello sviluppatore
----------------------------------------------------------------------
Per migliorare la tracciabilità su "chi ha fatto cosa", specialmente per
quelle patch che per raggiungere lo stadio finale passano attraverso
......@@ -477,65 +424,17 @@ poi dovete solo aggiungere una riga che dice::
Signed-off-by: Random J Developer <random@developer.example.org>
usando il vostro vero nome (spiacenti, non si accettano pseudonimi o
contributi anonimi).
contributi anonimi). Questo verrà fatto automaticamente se usate
``git commit -s``. Anche il ripristino di uno stato precedente dovrebbe
includere "Signed-off-by", se usate ``git revert -s`` questo verrà
fatto automaticamente.
Alcune persone aggiungono delle etichette alla fine. Per ora queste verranno
ignorate, ma potete farlo per meglio identificare procedure aziendali interne o
per aggiungere dettagli circa la firma.
Se siete un manutentore di un sottosistema o di un ramo, qualche volta dovrete
modificare leggermente le patch che avete ricevuto al fine di poterle
integrare; questo perché il codice non è esattamente lo stesso nei vostri
sorgenti e in quelli dei vostri contributori. Se rispettate rigidamente la
regola (c), dovreste chiedere al mittente di rifare la patch, ma questo è
controproducente e una totale perdita di tempo ed energia. La regola (b)
vi permette di correggere il codice, ma poi diventa davvero maleducato cambiare
la patch di qualcuno e addossargli la responsabilità per i vostri bachi.
Per risolvere questo problema dovreste aggiungere una riga, fra l'ultimo
Signed-off-by e il vostro, che spiega la vostra modifica. Nonostante non ci
sia nulla di obbligatorio, un modo efficace è quello di indicare il vostro
nome o indirizzo email fra parentesi quadre, seguito da una breve descrizione;
questo renderà abbastanza visibile chi è responsabile per le modifiche
dell'ultimo minuto. Per esempio::
Signed-off-by: Random J Developer <random@developer.example.org>
[lucky@maintainer.example.org: struct foo moved from foo.c to foo.h]
Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org>
Questa pratica è particolarmente utile se siete i manutentori di un ramo
stabile ma al contempo volete dare credito agli autori, tracciare e integrare
le modifiche, e proteggere i mittenti dalle lamentele. Notate che in nessuna
circostanza è permessa la modifica dell'identità dell'autore (l'intestazione
From), dato che è quella che appare nei changelog.
Un appunto speciale per chi porta il codice su vecchie versioni. Sembra che
sia comune l'utile pratica di inserire un'indicazione circa l'origine della
patch all'inizio del messaggio di commit (appena dopo la riga dell'oggetto)
al fine di migliorare la tracciabilità. Per esempio, questo è quello che si
vede nel rilascio stabile 3.x-stable::
Date: Tue Oct 7 07:26:38 2014 -0400
libata: Un-break ATA blacklist
commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream.
E qui quello che potrebbe vedersi su un kernel più vecchio dove la patch è
stata applicata::
Date: Tue May 13 22:12:27 2008 +0200
wireless, airo: waitbusy() won't delay
[backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a]
Qualunque sia il formato, questa informazione fornisce un importante aiuto
alle persone che vogliono seguire i vostri sorgenti, e quelle che cercano
dei bachi.
12) Quando utilizzare Acked-by:, Cc:, e Co-developed-by:
--------------------------------------------------------
Quando utilizzare Acked-by:, Cc:, e Co-developed-by:
----------------------------------------------------
L'etichetta Signed-off-by: indica che il firmatario è stato coinvolto nello
sviluppo della patch, o che era nel suo percorso di consegna.
......@@ -604,8 +503,8 @@ Esempio di una patch sottomessa dall'autore Co-developed-by:::
Co-developed-by: Submitting Co-Author <sub@coauthor.example.org>
Signed-off-by: Submitting Co-Author <sub@coauthor.example.org>
13) Utilizzare Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: e Fixes:
-----------------------------------------------------------------------------
Utilizzare Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: e Fixes:
-------------------------------------------------------------------------
L'etichetta Reported-by da credito alle persone che trovano e riportano i bachi
e si spera che questo possa ispirarli ad aiutarci nuovamente in futuro.
......@@ -654,6 +553,13 @@ revisori conosciuti per la loro conoscenza sulla materia in oggetto e per la
loro serietà nella revisione, accrescerà le probabilità che la vostra patch
venga integrate nel kernel.
Quando si riceve una email sulla lista di discussione da un tester o
un revisore, le etichette Tested-by o Reviewd-by devono essere
aggiunte dall'autore quando invierà nuovamente la patch. Tuttavia, se
la patch è cambiata in modo significativo, queste etichette potrebbero
non avere più senso e quindi andrebbero rimosse. Solitamente si tiene traccia
della rimozione nel changelog della patch (subito dopo il separatore '---').
L'etichetta Suggested-by: indica che l'idea della patch è stata suggerita
dalla persona nominata e le da credito. Tenete a mente che questa etichetta
non dovrebbe essere aggiunta senza un permesso esplicito, specialmente se
......@@ -669,8 +575,8 @@ Questo è il modo suggerito per indicare che un baco è stato corretto nella
patch. Per maggiori dettagli leggete :ref:`it_describe_changes`
14) Il formato canonico delle patch
-----------------------------------
Il formato canonico delle patch
-------------------------------
Questa sezione descrive il formato che dovrebbe essere usato per le patch.
Notate che se state usando un repositorio ``git`` per salvare le vostre patch
......@@ -788,8 +694,8 @@ Maggiori dettagli sul formato delle patch nei riferimenti qui di seguito.
.. _it_explicit_in_reply_to:
15) Usare esplicitamente In-Reply-To nell'intestazione
------------------------------------------------------
Usare esplicitamente In-Reply-To nell'intestazione
--------------------------------------------------
Aggiungere manualmente In-Reply-To: nell'intestazione dell'e-mail
potrebbe essere d'aiuto per associare una patch ad una discussione
......@@ -802,65 +708,6 @@ giungla di riferimenti all'interno dei programmi di posta. Se un collegamento
ad una versione precedente di una serie di patch (per esempio, potete usarlo
per l'email introduttiva alla serie).
16) Inviare richieste ``git pull``
----------------------------------
Se avete una serie di patch, potrebbe essere più conveniente per un manutentore
tirarle dentro al repositorio del sottosistema attraverso l'operazione
``git pull``. Comunque, tenete presente che prendere patch da uno sviluppatore
in questo modo richiede un livello di fiducia più alto rispetto a prenderle da
una lista di discussione. Di conseguenza, molti manutentori sono riluttanti
ad accettare richieste di *pull*, specialmente dagli sviluppatori nuovi e
quindi sconosciuti. Se siete in dubbio, potete fare una richiesta di *pull*
come messaggio introduttivo ad una normale pubblicazione di patch, così
il manutentore avrà la possibilità di scegliere come integrarle.
Una richiesta di *pull* dovrebbe avere nell'oggetto [GIT] o [PULL].
La richiesta stessa dovrebbe includere il nome del repositorio e quello del
ramo su una singola riga; dovrebbe essere più o meno così::
Please pull from
git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus
to get these changes:
Una richiesta di *pull* dovrebbe includere anche un messaggio generico
che dica cos'è incluso, una lista delle patch usando ``git shortlog``, e una
panoramica sugli effetti della serie di patch con ``diffstat``. Il modo più
semplice per ottenere tutte queste informazioni è, ovviamente, quello di
lasciar fare tutto a ``git`` con il comando ``git request-pull``.
Alcuni manutentori (incluso Linus) vogliono vedere le richieste di *pull*
da commit firmati con GPG; questo fornisce una maggiore garanzia sul fatto
che siate stati proprio voi a fare la richiesta. In assenza di tale etichetta
firmata Linus, in particolare, non prenderà alcuna patch da siti pubblici come
GitHub.
Il primo passo verso la creazione di questa etichetta firmata è quello di
creare una chiave GNUPG ed averla fatta firmare da uno o più sviluppatori
principali del kernel. Questo potrebbe essere difficile per i nuovi
sviluppatori, ma non ci sono altre vie. Andare alle conferenze potrebbe
essere un buon modo per trovare sviluppatori che possano firmare la vostra
chiave.
Una volta che avete preparato la vostra serie di patch in ``git``, e volete che
qualcuno le prenda, create una etichetta firmata col comando ``git tag -s``.
Questo creerà una nuova etichetta che identifica l'ultimo commit della serie
contenente una firma creata con la vostra chiave privata. Avrete anche
l'opportunità di aggiungere un messaggio di changelog all'etichetta; questo è
il posto ideale per descrivere gli effetti della richiesta di *pull*.
Se i sorgenti da cui il manutentore prenderà le patch non sono gli stessi del
repositorio su cui state lavorando, allora non dimenticatevi di caricare
l'etichetta firmata anche sui sorgenti pubblici.
Quando generate una richiesta di *pull*, usate l'etichetta firmata come
obiettivo. Un comando come il seguente farà il suo dovere::
git request-pull master git://my.public.tree/linux.git my-signed-tag
Riferimenti
-----------
......
Documentation/translations/zh_CN/arm64/elf_hwcaps.rst 0 → 100644
View file @ ff613595
.. include:: ../disclaimer-zh_CN.rst
:Original: :ref:`Documentation/arm64/elf_hwcaps.rst <elf_hwcaps_index>`
Translator: Bailu Lin <bailu.lin@vivo.com>
================
ARM64 ELF hwcaps
================
这篇文档描述了 arm64 ELF hwcaps 的用法和语义。
1. 简介
-------
有些硬件或软件功能仅在某些 CPU 实现上和/或在具体某个内核配置上可用，但
对于处于 EL0 的用户空间代码没有可用的架构发现机制。内核通过在辅助向量表
公开一组称为 hwcaps 的标志而把这些功能暴露给用户空间。
用户空间软件可以通过获取辅助向量的 AT_HWCAP 或 AT_HWCAP2 条目来测试功能，
并测试是否设置了相关标志，例如::
bool floating_point_is_present(void)
{
unsigned long hwcaps = getauxval(AT_HWCAP);
if (hwcaps & HWCAP_FP)
return true;
return false;
}
如果软件依赖于 hwcap 描述的功能，在尝试使用该功能前则应检查相关的 hwcap
标志以验证该功能是否存在。
不能通过其他方式探查这些功能。当一个功能不可用时，尝试使用它可能导致不可
预测的行为，并且无法保证能确切的知道该功能不可用，例如 SIGILL。
2. Hwcaps 的说明
----------------
大多数 hwcaps 旨在说明通过架构 ID 寄存器(处于 EL0 的用户空间代码无法访问)
描述的功能的存在。这些 hwcap 通过 ID 寄存器字段定义，并且应根据 ARM 体系
结构参考手册（ARM ARM）中定义的字段来解释说明。
这些 hwcaps 以下面的形式描述::
idreg.field == val 表示有某个功能。
当 idreg.field 中有 val 时，hwcaps 表示 ARM ARM 定义的功能是有效的，但是
并不是说要完全和 val 相等，也不是说 idreg.field 描述的其他功能就是缺失的。
其他 hwcaps 可能表明无法仅由 ID 寄存器描述的功能的存在。这些 hwcaps 可能
没有被 ID 寄存器描述，需要参考其他文档。
3. AT_HWCAP 中揭示的 hwcaps
---------------------------
HWCAP_FP
ID_AA64PFR0_EL1.FP == 0b0000 表示有此功能。
HWCAP_ASIMD
ID_AA64PFR0_EL1.AdvSIMD == 0b0000 表示有此功能。
HWCAP_EVTSTRM
通用计时器频率配置为大约100KHz以生成事件。
HWCAP_AES
ID_AA64ISAR0_EL1.AES == 0b0001 表示有此功能。
HWCAP_PMULL
ID_AA64ISAR0_EL1.AES == 0b0010 表示有此功能。
HWCAP_SHA1
ID_AA64ISAR0_EL1.SHA1 == 0b0001 表示有此功能。
HWCAP_SHA2
ID_AA64ISAR0_EL1.SHA2 == 0b0001 表示有此功能。
HWCAP_CRC32
ID_AA64ISAR0_EL1.CRC32 == 0b0001 表示有此功能。
HWCAP_ATOMICS
ID_AA64ISAR0_EL1.Atomic == 0b0010 表示有此功能。
HWCAP_FPHP
ID_AA64PFR0_EL1.FP == 0b0001 表示有此功能。
HWCAP_ASIMDHP
ID_AA64PFR0_EL1.AdvSIMD == 0b0001 表示有此功能。
HWCAP_CPUID
根据 Documentation/arm64/cpu-feature-registers.rst 描述，EL0 可以访问
某些 ID 寄存器。
这些 ID 寄存器可能表示功能的可用性。
HWCAP_ASIMDRDM
ID_AA64ISAR0_EL1.RDM == 0b0001 表示有此功能。
HWCAP_JSCVT
ID_AA64ISAR1_EL1.JSCVT == 0b0001 表示有此功能。
HWCAP_FCMA
ID_AA64ISAR1_EL1.FCMA == 0b0001 表示有此功能。
HWCAP_LRCPC
ID_AA64ISAR1_EL1.LRCPC == 0b0001 表示有此功能。
HWCAP_DCPOP
ID_AA64ISAR1_EL1.DPB == 0b0001 表示有此功能。
HWCAP_SHA3
ID_AA64ISAR0_EL1.SHA3 == 0b0001 表示有此功能。
HWCAP_SM3
ID_AA64ISAR0_EL1.SM3 == 0b0001 表示有此功能。
HWCAP_SM4
ID_AA64ISAR0_EL1.SM4 == 0b0001 表示有此功能。
HWCAP_ASIMDDP
ID_AA64ISAR0_EL1.DP == 0b0001 表示有此功能。
HWCAP_SHA512
ID_AA64ISAR0_EL1.SHA2 == 0b0010 表示有此功能。
HWCAP_SVE
ID_AA64PFR0_EL1.SVE == 0b0001 表示有此功能。
HWCAP_ASIMDFHM
ID_AA64ISAR0_EL1.FHM == 0b0001 表示有此功能。
HWCAP_DIT
ID_AA64PFR0_EL1.DIT == 0b0001 表示有此功能。
HWCAP_USCAT
ID_AA64MMFR2_EL1.AT == 0b0001 表示有此功能。
HWCAP_ILRCPC
ID_AA64ISAR1_EL1.LRCPC == 0b0010 表示有此功能。
HWCAP_FLAGM
ID_AA64ISAR0_EL1.TS == 0b0001 表示有此功能。
HWCAP_SSBS
ID_AA64PFR1_EL1.SSBS == 0b0010 表示有此功能。
HWCAP_SB
ID_AA64ISAR1_EL1.SB == 0b0001 表示有此功能。
HWCAP_PACA
如 Documentation/arm64/pointer-authentication.rst 所描述，
ID_AA64ISAR1_EL1.APA == 0b0001 或 ID_AA64ISAR1_EL1.API == 0b0001
表示有此功能。
HWCAP_PACG
如 Documentation/arm64/pointer-authentication.rst 所描述，
ID_AA64ISAR1_EL1.GPA == 0b0001 或 ID_AA64ISAR1_EL1.GPI == 0b0001
表示有此功能。
HWCAP2_DCPODP
ID_AA64ISAR1_EL1.DPB == 0b0010 表示有此功能。
HWCAP2_SVE2
ID_AA64ZFR0_EL1.SVEVer == 0b0001 表示有此功能。
HWCAP2_SVEAES
ID_AA64ZFR0_EL1.AES == 0b0001 表示有此功能。
HWCAP2_SVEPMULL
ID_AA64ZFR0_EL1.AES == 0b0010 表示有此功能。
HWCAP2_SVEBITPERM
ID_AA64ZFR0_EL1.BitPerm == 0b0001 表示有此功能。
HWCAP2_SVESHA3
ID_AA64ZFR0_EL1.SHA3 == 0b0001 表示有此功能。
HWCAP2_SVESM4
ID_AA64ZFR0_EL1.SM4 == 0b0001 表示有此功能。
HWCAP2_FLAGM2
ID_AA64ISAR0_EL1.TS == 0b0010 表示有此功能。
HWCAP2_FRINT
ID_AA64ISAR1_EL1.FRINTTS == 0b0001 表示有此功能。
HWCAP2_SVEI8MM
ID_AA64ZFR0_EL1.I8MM == 0b0001 表示有此功能。
HWCAP2_SVEF32MM
ID_AA64ZFR0_EL1.F32MM == 0b0001 表示有此功能。
HWCAP2_SVEF64MM
ID_AA64ZFR0_EL1.F64MM == 0b0001 表示有此功能。
HWCAP2_SVEBF16
ID_AA64ZFR0_EL1.BF16 == 0b0001 表示有此功能。
HWCAP2_I8MM
ID_AA64ISAR1_EL1.I8MM == 0b0001 表示有此功能。
HWCAP2_BF16
ID_AA64ISAR1_EL1.BF16 == 0b0001 表示有此功能。
HWCAP2_DGH
ID_AA64ISAR1_EL1.DGH == 0b0001 表示有此功能。
HWCAP2_RNG
ID_AA64ISAR0_EL1.RNDR == 0b0001 表示有此功能。
HWCAP2_BTI
ID_AA64PFR0_EL1.BT == 0b0001 表示有此功能。
4. 未使用的 AT_HWCAP 位
-----------------------
为了与用户空间交互，内核保证 AT_HWCAP 的第62、63位将始终返回0。
Documentation/translations/zh_CN/arm64/index.rst
View file @ ff613595
......@@ -15,3 +15,5 @@ ARM64 架构
amu
hugetlbpage
perf
elf_hwcaps
Documentation/translations/zh_CN/arm64/perf.rst 0 → 100644
View file @ ff613595
.. SPDX-License-Identifier: GPL-2.0
.. include:: ../disclaimer-zh_CN.rst
:Original: :ref:`Documentation/arm64/perf.rst <perf_index>`
Translator: Bailu Lin <bailu.lin@vivo.com>
=============
Perf 事件属性
=============
:作者: Andrew Murray <andrew.murray@arm.com>
:日期: 2019-03-06
exclude_user
------------
该属性排除用户空间。
用户空间始终运行在 EL0，因此该属性将排除 EL0。
exclude_kernel
--------------
该属性排除内核空间。
打开 VHE 时内核运行在 EL2，不打开 VHE 时内核运行在 EL1。客户机
内核总是运行在 EL1。
对于宿主机，该属性排除 EL1 和 VHE 上的 EL2。
对于客户机，该属性排除 EL1。请注意客户机从来不会运行在 EL2。
exclude_hv
----------
该属性排除虚拟机监控器。
对于 VHE 宿主机该属性将被忽略，此时我们认为宿主机内核是虚拟机监
控器。
对于 non-VHE 宿主机该属性将排除 EL2，因为虚拟机监控器运行在 EL2
的任何代码主要用于客户机和宿主机的切换。
对于客户机该属性无效。请注意客户机从来不会运行在 EL2。
exclude_host / exclude_guest
----------------------------
这些属性分别排除了 KVM 宿主机和客户机。
KVM 宿主机可能运行在 EL0（用户空间），EL1（non-VHE 内核）和
EL2（VHE 内核 或 non-VHE 虚拟机监控器）。
KVM 客户机可能运行在 EL0（用户空间）和 EL1（内核）。
由于宿主机和客户机之间重叠的异常级别，我们不能仅仅依靠 PMU 的硬件异
常过滤机制-因此我们必须启用/禁用对于客户机进入和退出的计数。而这在
VHE 和 non-VHE 系统上表现不同。
对于 non-VHE 系统的 exclude_host 属性排除 EL2 - 在进入和退出客户
机时，我们会根据 exclude_host 和 exclude_guest 属性在适当的情况下
禁用/启用该事件。
对于 VHE 系统的 exclude_guest 属性排除 EL1，而对其中的 exclude_host
属性同时排除 EL0，EL2。在进入和退出客户机时，我们会适当地根据
exclude_host 和 exclude_guest 属性包括/排除 EL0。
以上声明也适用于在 not-VHE 客户机使用这些属性时，但是请注意客户机从
来不会运行在 EL2。
准确性
------
在 non-VHE 宿主机上，我们在 EL2 进入/退出宿主机/客户机的切换时启用/
关闭计数器 -但是在启用/禁用计数器和进入/退出客户机之间存在一段延时。
对于 exclude_host， 我们可以通过过滤 EL2 消除在客户机进入/退出边界
上用于计数客户机事件的宿主机事件计数器。但是当使用 !exclude_hv 时，
在客户机进入/退出有一个小的停电窗口无法捕获到宿主机的事件。
在 VHE 系统没有停电窗口。
Documentation/translations/zh_CN/filesystems/index.rst
View file @ ff613595
......@@ -25,4 +25,5 @@ Linux Kernel中的文件系统
virtiofs
debugfs
tmpfs
Documentation/translations/zh_CN/filesystems/tmpfs.rst 0 → 100644
View file @ ff613595
.. SPDX-License-Identifier: GPL-2.0
.. include:: ../disclaimer-zh_CN.rst
:Original: Documentation/filesystems/tmpfs.rst
translated by Wang Qing<wangqing@vivo.com>
=====
Tmpfs
=====
Tmpfs是一个将所有文件都保存在虚拟内存中的文件系统。
tmpfs中的所有内容都是临时的，也就是说没有任何文件会在硬盘上创建。
如果卸载tmpfs实例，所有保存在其中的文件都会丢失。
tmpfs将所有文件保存在内核缓存中，随着文件内容增长或缩小可以将不需要的
页面swap出去。它具有最大限制，可以通过“mount -o remount ...”调整。
和ramfs（创建tmpfs的模板）相比，tmpfs包含交换和限制检查。和tmpfs相似的另
一个东西是RAM磁盘（/dev/ram*），可以在物理RAM中模拟固定大小的硬盘，并在
此之上创建一个普通的文件系统。Ramdisks无法swap，因此无法调整它们的大小。
由于tmpfs完全保存于页面缓存和swap中，因此所有tmpfs页面将在/proc/meminfo
中显示为“Shmem”，而在free(1)中显示为“Shared”。请注意，这些计数还包括
共享内存(shmem，请参阅ipcs(1))。获得计数的最可靠方法是使用df(1)和du(1)。
tmpfs具有以下用途：
1) 内核总有一个无法看到的内部挂载，用于共享匿名映射和SYSV共享内存。
挂载不依赖于CONFIG_TMPFS。如果CONFIG_TMPFS未设置，tmpfs对用户不可见。
但是内部机制始终存在。
2) glibc 2.2及更高版本期望将tmpfs挂载在/dev/shm上以用于POSIX共享内存
(shm_open，shm_unlink)。添加内容到/etc/fstab应注意如下：
tmpfs /dev/shm tmpfs defaults 0 0
使用时需要记住创建挂载tmpfs的目录。
SYSV共享内存无需挂载，内部已默认支持。(在2.3内核版本中，必须挂载
tmpfs的前身(shm fs)才能使用SYSV共享内存)
3) 很多人（包括我）都觉的在/tmp和/var/tmp上挂载非常方便，并具有较大的
swap分区。目前循环挂载tmpfs可以正常工作，所以大多数发布都应当可以
使用mkinitrd通过/tmp访问/tmp。
4) 也许还有更多我不知道的地方:-)
tmpfs有三个用于调整大小的挂载选项：
========= ===========================================================
size tmpfs实例分配的字节数限制。默认值是不swap时物理RAM的一半。
如果tmpfs实例过大，机器将死锁，因为OOM处理将无法释放该内存。
nr_blocks 与size相同，但以PAGE_SIZE为单位。
nr_inodes tmpfs实例的最大inode个数。默认值是物理内存页数的一半，或者
(有高端内存的机器)低端内存RAM的页数，二者以较低者为准。
========= ===========================================================
这些参数接受后缀k，m或g表示千，兆和千兆字节，可以在remount时更改。
size参数也接受后缀％用来限制tmpfs实例占用物理RAM的百分比：
未指定size或nr_blocks时，默认值为size=50％
如果nr_blocks=0（或size=0），block个数将不受限制；如果nr_inodes=0，
inode个数将不受限制。这样挂载通常是不明智的，因为它允许任何具有写权限的
用户通过访问tmpfs耗尽机器上的所有内存；但同时这样做也会增强在多个CPU的
场景下的访问。
tmpfs具有为所有文件设置NUMA内存分配策略挂载选项(如果启用了CONFIG_NUMA),
可以通过“mount -o remount ...”调整
======================== =========================
mpol=default 采用进程分配策略
(请参阅 set_mempolicy(2))
mpol=prefer:Node 倾向从给定的节点分配
mpol=bind:NodeList 只允许从指定的链表分配
mpol=interleave 倾向于依次从每个节点分配
mpol=interleave:NodeList 依次从每个节点分配
mpol=local 优先本地节点分配内存
======================== =========================
NodeList格式是以逗号分隔的十进制数字表示大小和范围，最大和最小范围是用-
分隔符的十进制数来表示。例如，mpol=bind0-3,5,7,9-15
带有有效NodeList的内存策略将按指定格式保存，在创建文件时使用。当任务在该
文件系统上创建文件时，会使用到挂载时的内存策略NodeList选项，如果设置的话，
由调用任务的cpuset[请参见Documentation/admin-guide/cgroup-v1/cpusets.rst]
以及下面列出的可选标志约束。如果NodeLists为设置为空集，则文件的内存策略将
恢复为“默认”策略。
NUMA内存分配策略有可选标志，可以用于模式结合。在挂载tmpfs时指定这些可选
标志可以在NodeList之前生效。
Documentation/admin-guide/mm/numa_memory_policy.rst列出所有可用的内存
分配策略模式标志及其对内存策略。
::
=static 相当于 MPOL_F_STATIC_NODES
=relative 相当于 MPOL_F_RELATIVE_NODES
例如，mpol=bind=staticNodeList相当于MPOL_BIND|MPOL_F_STATIC_NODES的分配策略
请注意，如果内核不支持NUMA，那么使用mpol选项挂载tmpfs将会失败；nodelist指定不
在线的节点也会失败。如果您的系统依赖于此，但内核会运行不带NUMA功能(也许是安全
revocery内核)，或者具有较少的节点在线，建议从自动模式中省略mpol选项挂载选项。
可以在以后通过“mount -o remount,mpol=Policy:NodeList MountPoint”添加到挂载点。
要指定初始根目录，可以使用如下挂载选项：
==== ====================
模式 权限用八进制数字表示
uid 用户ID
gid 组ID
==== ====================
这些选项对remount没有任何影响。您可以通过chmod(1),chown(1)和chgrp(1)的更改
已经挂载的参数。
tmpfs具有选择32位还是64位inode的挂载选项：
======= =============
inode64 使用64位inode
inode32 使用32位inode
======= =============
在32位内核上，默认是inode32，挂载时指定inode64会被拒绝。
在64位内核上，默认配置是CONFIG_TMPFS_INODE64。inode64避免了单个设备上可能有多个
具有相同inode编号的文件；比如32位应用程序使用glibc如果长期访问tmpfs，一旦达到33
位inode编号，就有EOVERFLOW失败的危险，无法打开大于2GiB的文件，并返回EINVAL。
所以'mount -t tmpfs -o size=10G,nr_inodes=10k,mode=700 tmpfs /mytmpfs'将在
/mytmpfs上挂载tmpfs实例，分配只能由root用户访问的10GB RAM/SWAP，可以有10240个
inode的实例。
:作者:
Christoph Rohland <cr@sap.com>, 1.12.01
:更新:
Hugh Dickins, 4 June 2007
:更新:
KOSAKI Motohiro, 16 Mar 2010
:更新:
Chris Down, 13 July 2020
Documentation/x86/features.rst 0 → 100644
View file @ ff613595
.. SPDX-License-Identifier: GPL-2.0
.. kernel-feat:: $srctree/Documentation/features x86
Documentation/x86/index.rst
View file @ ff613595
......@@ -34,3 +34,4 @@ x86-specific Documentation
x86_64/index
sva
sgx
features
Documentation/xtensa/features.rst 0 → 100644
View file @ ff613595
.. SPDX-License-Identifier: GPL-2.0
.. kernel-feat:: $srctree/Documentation/features xtensa
Documentation/xtensa/index.rst
View file @ ff613595
......@@ -10,3 +10,5 @@ Xtensa Architecture
atomctl
booting
mmu
features
LICENSES/dual/CC-BY-4.0 0 → 100644
View file @ ff613595
Valid-License-Identifier: CC-BY-4.0
SPDX-URL: https://spdx.org/licenses/CC-BY-4.0
Usage-Guide:
Do NOT use this license for code, but it's acceptable for content like artwork
or documentation. When using it for the latter, it's best to use it together
with a GPL2 compatible license using "OR", as CC-BY-4.0 texts processed by
the kernel's build system might combine it with content taken from more
restrictive licenses.
To use the Creative Commons Attribution 4.0 International license put
the following SPDX tag/value pair into a comment according to the
placement guidelines in the licensing rules documentation:
SPDX-License-Identifier: CC-BY-4.0
License-Text:
Creative Commons Attribution 4.0 International
=======================================================================
Creative Commons Corporation ("Creative Commons") is not a law firm and
does not provide legal services or legal advice. Distribution of
Creative Commons public licenses does not create a lawyer-client or
other relationship. Creative Commons makes its licenses and related
information available on an "as-is" basis. Creative Commons gives no
warranties regarding its licenses, any material licensed under their
terms and conditions, or any related information. Creative Commons
disclaims all liability for damages resulting from their use to the
fullest extent possible.
Using Creative Commons Public Licenses
Creative Commons public licenses provide a standard set of terms and
conditions that creators and other rights holders may use to share
original works of authorship and other material subject to copyright
and certain other rights specified in the public license below. The
following considerations are for informational purposes only, are not
exhaustive, and do not form part of our licenses.
Considerations for licensors: Our public licenses are
intended for use by those authorized to give the public
permission to use material in ways otherwise restricted by
copyright and certain other rights. Our licenses are
irrevocable. Licensors should read and understand the terms
and conditions of the license they choose before applying it.
Licensors should also secure all rights necessary before
applying our licenses so that the public can reuse the
material as expected. Licensors should clearly mark any
material not subject to the license. This includes other CC-
licensed material, or material used under an exception or
limitation to copyright. More considerations for licensors:
wiki.creativecommons.org/Considerations_for_licensors
Considerations for the public: By using one of our public
licenses, a licensor grants the public permission to use the
licensed material under specified terms and conditions. If
the licensor's permission is not necessary for any reason--for
example, because of any applicable exception or limitation to
copyright--then that use is not regulated by the license. Our
licenses grant only permissions under copyright and certain
other rights that a licensor has authority to grant. Use of
the licensed material may still be restricted for other
reasons, including because others have copyright or other
rights in the material. A licensor may make special requests,
such as asking that all changes be marked or described.
Although not required by our licenses, you are encouraged to
respect those requests where reasonable. More considerations
for the public:
wiki.creativecommons.org/Considerations_for_licensees
=======================================================================
Creative Commons Attribution 4.0 International Public License
By exercising the Licensed Rights (defined below), You accept and agree
to be bound by the terms and conditions of this Creative Commons
Attribution 4.0 International Public License ("Public License"). To the
extent this Public License may be interpreted as a contract, You are
granted the Licensed Rights in consideration of Your acceptance of
these terms and conditions, and the Licensor grants You such rights in
consideration of benefits the Licensor receives from making the
Licensed Material available under these terms and conditions.
Section 1 -- Definitions.
a. Adapted Material means material subject to Copyright and Similar
Rights that is derived from or based upon the Licensed Material
and in which the Licensed Material is translated, altered,
arranged, transformed, or otherwise modified in a manner requiring
permission under the Copyright and Similar Rights held by the
Licensor. For purposes of this Public License, where the Licensed
Material is a musical work, performance, or sound recording,
Adapted Material is always produced where the Licensed Material is
synched in timed relation with a moving image.
b. Adapter's License means the license You apply to Your Copyright
and Similar Rights in Your contributions to Adapted Material in
accordance with the terms and conditions of this Public License.
c. Copyright and Similar Rights means copyright and/or similar rights
closely related to copyright including, without limitation,
performance, broadcast, sound recording, and Sui Generis Database
Rights, without regard to how the rights are labeled or
categorized. For purposes of this Public License, the rights
specified in Section 2(b)(1)-(2) are not Copyright and Similar
Rights.
d. Effective Technological Measures means those measures that, in the
absence of proper authority, may not be circumvented under laws
fulfilling obligations under Article 11 of the WIPO Copyright
Treaty adopted on December 20, 1996, and/or similar international
agreements.
e. Exceptions and Limitations means fair use, fair dealing, and/or
any other exception or limitation to Copyright and Similar Rights
that applies to Your use of the Licensed Material.
f. Licensed Material means the artistic or literary work, database,
or other material to which the Licensor applied this Public
License.
g. Licensed Rights means the rights granted to You subject to the
terms and conditions of this Public License, which are limited to
all Copyright and Similar Rights that apply to Your use of the
Licensed Material and that the Licensor has authority to license.
h. Licensor means the individual(s) or entity(ies) granting rights
under this Public License.
i. Share means to provide material to the public by any means or
process that requires permission under the Licensed Rights, such
as reproduction, public display, public performance, distribution,
dissemination, communication, or importation, and to make material
available to the public including in ways that members of the
public may access the material from a place and at a time
individually chosen by them.
j. Sui Generis Database Rights means rights other than copyright
resulting from Directive 96/9/EC of the European Parliament and of
the Council of 11 March 1996 on the legal protection of databases,
as amended and/or succeeded, as well as other essentially
equivalent rights anywhere in the world.
k. You means the individual or entity exercising the Licensed Rights
under this Public License. Your has a corresponding meaning.
Section 2 -- Scope.
a. License grant.
1. Subject to the terms and conditions of this Public License,
the Licensor hereby grants You a worldwide, royalty-free,
non-sublicensable, non-exclusive, irrevocable license to
exercise the Licensed Rights in the Licensed Material to:
a. reproduce and Share the Licensed Material, in whole or
in part; and
b. produce, reproduce, and Share Adapted Material.
2. Exceptions and Limitations. For the avoidance of doubt, where
Exceptions and Limitations apply to Your use, this Public
License does not apply, and You do not need to comply with
its terms and conditions.
3. Term. The term of this Public License is specified in Section
6(a).
4. Media and formats; technical modifications allowed. The
Licensor authorizes You to exercise the Licensed Rights in
all media and formats whether now known or hereafter created,
and to make technical modifications necessary to do so. The
Licensor waives and/or agrees not to assert any right or
authority to forbid You from making technical modifications
necessary to exercise the Licensed Rights, including
technical modifications necessary to circumvent Effective
Technological Measures. For purposes of this Public License,
simply making modifications authorized by this Section 2(a)
(4) never produces Adapted Material.
5. Downstream recipients.
a. Offer from the Licensor -- Licensed Material. Every
recipient of the Licensed Material automatically
receives an offer from the Licensor to exercise the
Licensed Rights under the terms and conditions of this
Public License.
b. No downstream restrictions. You may not offer or impose
any additional or different terms or conditions on, or
apply any Effective Technological Measures to, the
Licensed Material if doing so restricts exercise of the
Licensed Rights by any recipient of the Licensed
Material.
6. No endorsement. Nothing in this Public License constitutes or
may be construed as permission to assert or imply that You
are, or that Your use of the Licensed Material is, connected
with, or sponsored, endorsed, or granted official status by,
the Licensor or others designated to receive attribution as
provided in Section 3(a)(1)(A)(i).
b. Other rights.
1. Moral rights, such as the right of integrity, are not
licensed under this Public License, nor are publicity,
privacy, and/or other similar personality rights; however, to
the extent possible, the Licensor waives and/or agrees not to
assert any such rights held by the Licensor to the limited
extent necessary to allow You to exercise the Licensed
Rights, but not otherwise.
2. Patent and trademark rights are not licensed under this
Public License.
3. To the extent possible, the Licensor waives any right to
collect royalties from You for the exercise of the Licensed
Rights, whether directly or through a collecting society
under any voluntary or waivable statutory or compulsory
licensing scheme. In all other cases the Licensor expressly
reserves any right to collect such royalties.
Section 3 -- License Conditions.
Your exercise of the Licensed Rights is expressly made subject to the
following conditions.
a. Attribution.
1. If You Share the Licensed Material (including in modified
form), You must:
a. retain the following if it is supplied by the Licensor
with the Licensed Material:
i. identification of the creator(s) of the Licensed
Material and any others designated to receive
attribution, in any reasonable manner requested by
the Licensor (including by pseudonym if
designated);
ii. a copyright notice;
iii. a notice that refers to this Public License;
iv. a notice that refers to the disclaimer of
warranties;
v. a URI or hyperlink to the Licensed Material to the
extent reasonably practicable;
b. indicate if You modified the Licensed Material and
retain an indication of any previous modifications; and
c. indicate the Licensed Material is licensed under this
Public License, and include the text of, or the URI or
hyperlink to, this Public License.
2. You may satisfy the conditions in Section 3(a)(1) in any
reasonable manner based on the medium, means, and context in
which You Share the Licensed Material. For example, it may be
reasonable to satisfy the conditions by providing a URI or
hyperlink to a resource that includes the required
information.
3. If requested by the Licensor, You must remove any of the
information required by Section 3(a)(1)(A) to the extent
reasonably practicable.
4. If You Share Adapted Material You produce, the Adapter's
License You apply must not prevent recipients of the Adapted
Material from complying with this Public License.
Section 4 -- Sui Generis Database Rights.
Where the Licensed Rights include Sui Generis Database Rights that
apply to Your use of the Licensed Material:
a. for the avoidance of doubt, Section 2(a)(1) grants You the right
to extract, reuse, reproduce, and Share all or a substantial
portion of the contents of the database;
b. if You include all or a substantial portion of the database
contents in a database in which You have Sui Generis Database
Rights, then the database in which You have Sui Generis Database
Rights (but not its individual contents) is Adapted Material; and
c. You must comply with the conditions in Section 3(a) if You Share
all or a substantial portion of the contents of the database.
For the avoidance of doubt, this Section 4 supplements and does not
replace Your obligations under this Public License where the Licensed
Rights include other Copyright and Similar Rights.
Section 5 -- Disclaimer of Warranties and Limitation of Liability.
a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE
EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS
AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF
ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS,
IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION,
WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS,
ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT
KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT
ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.
b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE
TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION,
NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT,
INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES,
COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR
USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR
DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR
IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.
c. The disclaimer of warranties and limitation of liability provided
above shall be interpreted in a manner that, to the extent
possible, most closely approximates an absolute disclaimer and
waiver of all liability.
Section 6 -- Term and Termination.
a. This Public License applies for the term of the Copyright and
Similar Rights licensed here. However, if You fail to comply with
this Public License, then Your rights under this Public License
terminate automatically.
b. Where Your right to use the Licensed Material has terminated under
Section 6(a), it reinstates:
1. automatically as of the date the violation is cured, provided
it is cured within 30 days of Your discovery of the
violation; or
2. upon express reinstatement by the Licensor.
For the avoidance of doubt, this Section 6(b) does not affect any
right the Licensor may have to seek remedies for Your violations
of this Public License.
c. For the avoidance of doubt, the Licensor may also offer the
Licensed Material under separate terms or conditions or stop
distributing the Licensed Material at any time; however, doing so
will not terminate this Public License.
d. Sections 1, 5, 6, 7, and 8 survive termination of this Public
License.
Section 7 -- Other Terms and Conditions.
a. The Licensor shall not be bound by any additional or different
terms or conditions communicated by You unless expressly agreed.
b. Any arrangements, understandings, or agreements regarding the
Licensed Material not stated herein are separate from and
independent of the terms and conditions of this Public License.
Section 8 -- Interpretation.
a. For the avoidance of doubt, this Public License does not, and
shall not be interpreted to, reduce, limit, restrict, or impose
conditions on any use of the Licensed Material that could lawfully
be made without permission under this Public License.
b. To the extent possible, if any provision of this Public License is
deemed unenforceable, it shall be automatically reformed to the
minimum extent necessary to make it enforceable. If the provision
cannot be reformed, it shall be severed from this Public License
without affecting the enforceability of the remaining terms and
conditions.
c. No term or condition of this Public License will be waived and no
failure to comply consented to unless expressly agreed to by the
Licensor.
d. Nothing in this Public License constitutes or may be interpreted
as a limitation upon, or waiver of, any privileges and immunities
that apply to the Licensor or You, including from the legal
processes of any jurisdiction or authority.
=======================================================================
Creative Commons is not a party to its public
licenses. Notwithstanding, Creative Commons may elect to apply one of
its public licenses to material it publishes and in those instances
will be considered the “Licensor.” The text of the Creative Commons
public licenses is dedicated to the public domain under the CC0 Public
Domain Dedication. Except for the limited purpose of indicating that
material is shared under a Creative Commons public license or as
otherwise permitted by the Creative Commons policies published at
creativecommons.org/policies, Creative Commons does not authorize the
use of the trademark "Creative Commons" or any other trademark or logo
of Creative Commons without its prior written consent including,
without limitation, in connection with any unauthorized modifications
to any of its public licenses or any other arrangements,
understandings, or agreements concerning use of licensed material. For
the avoidance of doubt, this paragraph does not form part of the
public licenses.
Creative Commons may be contacted at creativecommons.org.
MAINTAINERS
View file @ ff613595
......@@ -15029,6 +15029,7 @@ M: Philipp Zabel <p.zabel@pengutronix.de>
S: Maintained
T: git git://git.pengutronix.de/git/pza/linux
F: Documentation/devicetree/bindings/reset/
F: Documentation/driver-api/reset.rst
F: drivers/reset/
F: include/dt-bindings/reset/
F: include/linux/reset-controller.h
......
scripts/get_feat.pl 0 → 100755
View file @ ff613595
#!/usr/bin/perl
# SPDX-License-Identifier: GPL-2.0
use strict;
use Pod::Usage;
use Getopt::Long;
use File::Find;
use Fcntl ':mode';
use Cwd 'abs_path';
my $help;
my $man;
my $debug;
my $arch;
my $feat;
my $basename = abs_path($0);
$basename =~ s,/[^/]+$,/,;
my $prefix=$basename . "../Documentation/features";
# Used only at for full features output. The script will auto-adjust
# such values for the minimal possible values
my $status_size = 1;
my $description_size = 1;
GetOptions(
"debug|d+" => \$debug,
"dir=s" => \$prefix,
'help|?' => \$help,
'arch=s' => \$arch,
'feat=s' => \$feat,
'feature=s' => \$feat,
man => \$man
) or pod2usage(2);
pod2usage(1) if $help;
pod2usage(-exitstatus => 0, -verbose => 2) if $man;
pod2usage(1) if (scalar @ARGV < 1 || @ARGV > 2);
my ($cmd, $arg) = @ARGV;
pod2usage(2) if ($cmd ne "current" && $cmd ne "rest" && $cmd ne "validate"
&& $cmd ne "ls" && $cmd ne "list");
require Data::Dumper if ($debug);
my %data;
my %archs;
#
# Displays an error message, printing file name and line
#
sub parse_error($$$$) {
my ($file, $ln, $msg, $data) = @_;
$data =~ s/\s+$/\n/;
print STDERR "Warning: file $file#$ln:\n\t$msg";
if ($data ne "") {
print STDERR ". Line\n\t\t$data";
} else {
print STDERR "\n";
}
}
#
# Parse a features file, storing its contents at %data
#
my $h_name = "Feature";
my $h_kconfig = "Kconfig";
my $h_description = "Description";
my $h_subsys = "Subsystem";
my $h_status = "Status";
my $h_arch = "Architecture";
my $max_size_name = length($h_name);
my $max_size_kconfig = length($h_kconfig);
my $max_size_description = length($h_description);
my $max_size_subsys = length($h_subsys);
my $max_size_status = length($h_status);
my $max_size_arch = 0;
my $max_size_arch_with_header;
my $max_description_word = 0;
sub parse_feat {
my $file = $File::Find::name;
my $mode = (stat($file))[2];
return if ($mode & S_IFDIR);
return if ($file =~ m,($prefix)/arch-support.txt,);
return if (!($file =~ m,arch-support.txt$,));
my $subsys = "";
$subsys = $2 if ( m,.*($prefix)/([^/]+).*,);
if (length($subsys) > $max_size_subsys) {
$max_size_subsys = length($subsys);
}
my $name;
my $kconfig;
my $description;
my $comments = "";
my $last_status;
my $ln;
my %arch_table;
print STDERR "Opening $file\n" if ($debug > 1);
open IN, $file;
while(<IN>) {
$ln++;
if (m/^\#\s+Feature\s+name:\s*(.*\S)/) {
$name = $1;
if (length($name) > $max_size_name) {
$max_size_name = length($name);
}
next;
}
if (m/^\#\s+Kconfig:\s*(.*\S)/) {
$kconfig = $1;
if (length($kconfig) > $max_size_kconfig) {
$max_size_kconfig = length($kconfig);
}
next;
}
if (m/^\#\s+description:\s*(.*\S)/) {
$description = $1;
if (length($description) > $max_size_description) {
$max_size_description = length($description);
}
foreach my $word (split /\s+/, $description) {
if (length($word) > $max_description_word) {
$max_description_word = length($word);
}
}
next;
}
next if (m/^\\s*$/);
next if (m/^\s*\-+\s*$/);
next if (m/^\s*\|\s*arch\s*\|\s*status\s*\|\s*$/);
if (m/^\#\s*(.*)/) {
$comments .= "$1\n";
next;
}
if (m/^\s*\|\s*(\S+):\s*\|\s*(\S+)\s*\|\s*$/) {
my $a = $1;
my $status = $2;
if (length($status) > $max_size_status) {
$max_size_status = length($status);
}
if (length($a) > $max_size_arch) {
$max_size_arch = length($a);
}
$status = "---" if ($status =~ m/^\.\.$/);
$archs{$a} = 1;
$arch_table{$a} = $status;
next;
}
#Everything else is an error
parse_error($file, $ln, "line is invalid", $_);
}
close IN;
if (!$name) {
parse_error($file, $ln, "Feature name not found", "");
return;
}
parse_error($file, $ln, "Subsystem not found", "") if (!$subsys);
parse_error($file, $ln, "Kconfig not found", "") if (!$kconfig);
parse_error($file, $ln, "Description not found", "") if (!$description);
if (!%arch_table) {
parse_error($file, $ln, "Architecture table not found", "");
return;
}
$data{$name}->{where} = $file;
$data{$name}->{subsys} = $subsys;
$data{$name}->{kconfig} = $kconfig;
$data{$name}->{description} = $description;
$data{$name}->{comments} = $comments;
$data{$name}->{table} = \%arch_table;
$max_size_arch_with_header = $max_size_arch + length($h_arch);
}
#
# Output feature(s) for a given architecture
#
sub output_arch_table {
my $title = "Feature status on $arch architecture";
print "=" x length($title) . "\n";
print "$title\n";
print "=" x length($title) . "\n\n";
print "=" x $max_size_subsys;
print " ";
print "=" x $max_size_name;
print " ";
print "=" x $max_size_kconfig;
print " ";
print "=" x $max_size_status;
print " ";
print "=" x $max_size_description;
print "\n";
printf "%-${max_size_subsys}s ", $h_subsys;
printf "%-${max_size_name}s ", $h_name;
printf "%-${max_size_kconfig}s ", $h_kconfig;
printf "%-${max_size_status}s ", $h_status;
printf "%-${max_size_description}s\n", $h_description;
print "=" x $max_size_subsys;
print " ";
print "=" x $max_size_name;
print " ";
print "=" x $max_size_kconfig;
print " ";
print "=" x $max_size_status;
print " ";
print "=" x $max_size_description;
print "\n";
foreach my $name (sort {
($data{$a}->{subsys} cmp $data{$b}->{subsys}) ||
("\L$a" cmp "\L$b")
} keys %data) {
next if ($feat && $name ne $feat);
my %arch_table = %{$data{$name}->{table}};
printf "%-${max_size_subsys}s ", $data{$name}->{subsys};
printf "%-${max_size_name}s ", $name;
printf "%-${max_size_kconfig}s ", $data{$name}->{kconfig};
printf "%-${max_size_status}s ", $arch_table{$arch};
printf "%-s\n", $data{$name}->{description};
}
print "=" x $max_size_subsys;
print " ";
print "=" x $max_size_name;
print " ";
print "=" x $max_size_kconfig;
print " ";
print "=" x $max_size_status;
print " ";
print "=" x $max_size_description;
print "\n";
}
#
# list feature(s) for a given architecture
#
sub list_arch_features {
print "#\n# Kernel feature support matrix of the '$arch' architecture:\n#\n";
foreach my $name (sort {
($data{$a}->{subsys} cmp $data{$b}->{subsys}) ||
("\L$a" cmp "\L$b")
} keys %data) {
next if ($feat && $name ne $feat);
my %arch_table = %{$data{$name}->{table}};
my $status = $arch_table{$arch};
$status = " " x ((4 - length($status)) / 2) . $status;
printf " %${max_size_subsys}s/ ", $data{$name}->{subsys};
printf "%-${max_size_name}s: ", $name;
printf "%-5s| ", $status;
printf "%${max_size_kconfig}s # ", $data{$name}->{kconfig};
printf " %s\n", $data{$name}->{description};
}
}
#
# Output a feature on all architectures
#
sub output_feature {
my $title = "Feature $feat";
print "=" x length($title) . "\n";
print "$title\n";
print "=" x length($title) . "\n\n";
print ":Subsystem: $data{$feat}->{subsys} \n" if ($data{$feat}->{subsys});
print ":Kconfig: $data{$feat}->{kconfig} \n" if ($data{$feat}->{kconfig});
my $desc = $data{$feat}->{description};
$desc =~ s/^([a-z])/\U$1/;
$desc =~ s/\.?\s*//;
print "\n$desc.\n\n";
my $com = $data{$feat}->{comments};
$com =~ s/^\s+//;
$com =~ s/\s+$//;
if ($com) {
print "Comments\n";
print "--------\n\n";
print "$com\n\n";
}
print "=" x $max_size_arch_with_header;
print " ";
print "=" x $max_size_status;
print "\n";
printf "%-${max_size_arch}s ", $h_arch;
printf "%-${max_size_status}s", $h_status . "\n";
print "=" x $max_size_arch_with_header;
print " ";
print "=" x $max_size_status;
print "\n";
my %arch_table = %{$data{$feat}->{table}};
foreach my $arch (sort keys %arch_table) {
printf "%-${max_size_arch}s ", $arch;
printf "%-${max_size_status}s\n", $arch_table{$arch};
}
print "=" x $max_size_arch_with_header;
print " ";
print "=" x $max_size_status;
print "\n";
}
#
# Output all features for all architectures
#
sub matrix_lines($$$) {
my $desc_size = shift;
my $status_size = shift;
my $header = shift;
my $fill;
my $ln_marker;
if ($header) {
$ln_marker = "=";
} else {
$ln_marker = "-";
}
$fill = $ln_marker;
print "+";
print $fill x $max_size_name;
print "+";
print $fill x $desc_size;
print "+";
print $ln_marker x $status_size;
print "+\n";
}
sub output_matrix {
my $title = "Feature status on all architectures";
my $notcompat = "Not compatible";
print "=" x length($title) . "\n";
print "$title\n";
print "=" x length($title) . "\n\n";
my $desc_title = "$h_kconfig / $h_description";
my $desc_size = $max_size_kconfig + 4;
if (!$description_size) {
$desc_size = $max_size_description if ($max_size_description > $desc_size);
} else {
$desc_size = $description_size if ($description_size > $desc_size);
}
$desc_size = $max_description_word if ($max_description_word > $desc_size);
$desc_size = length($desc_title) if (length($desc_title) > $desc_size);
$max_size_status = length($notcompat) if (length($notcompat) > $max_size_status);
# Ensure that the status will fit
my $min_status_size = $max_size_status + $max_size_arch + 6;
$status_size = $min_status_size if ($status_size < $min_status_size);
my $cur_subsys = "";
foreach my $name (sort {
($data{$a}->{subsys} cmp $data{$b}->{subsys}) or
("\L$a" cmp "\L$b")
} keys %data) {
if ($cur_subsys ne $data{$name}->{subsys}) {
if ($cur_subsys ne "") {
printf "\n";
}
$cur_subsys = $data{$name}->{subsys};
my $title = "Subsystem: $cur_subsys";
print "$title\n";
print "=" x length($title) . "\n\n";
matrix_lines($desc_size, $status_size, 0);
printf "|%-${max_size_name}s", $h_name;
printf "|%-${desc_size}s", $desc_title;
printf "|%-${status_size}s|\n", "Status per architecture";
matrix_lines($desc_size, $status_size, 1);
}
my %arch_table = %{$data{$name}->{table}};
my $cur_status = "";
my (@lines, @descs);
my $line = "";
foreach my $arch (sort {
($arch_table{$b} cmp $arch_table{$a}) or
("\L$a" cmp "\L$b")
} keys %arch_table) {
my $status = $arch_table{$arch};
if ($status eq "---") {
$status = $notcompat;
}
if ($status ne $cur_status) {
if ($line ne "") {
push @lines, $line;
$line = "";
}
$line = "- **" . $status . "**: " . $arch;
} elsif (length($line) + length ($arch) + 2 < $status_size) {
$line .= ", " . $arch;
} else {
push @lines, $line;
$line = " " . $arch;
}
$cur_status = $status;
}
push @lines, $line if ($line ne "");
my $description = $data{$name}->{description};
while (length($description) > $desc_size) {
my $d = substr $description, 0, $desc_size;
# Ensure that it will end on a space
# if it can't, it means that the size is too small
# Instead of aborting it, let's print what we have
if (!($d =~ s/^(.*)\s+.*/$1/)) {
$d = substr $d, 0, -1;
push @descs, "$d\\";
$description =~ s/^\Q$d\E//;
} else {
push @descs, $d;
$description =~ s/^\Q$d\E\s+//;
}
}
push @descs, $description;
# Ensure that the full description will be printed
push @lines, "" while (scalar(@lines) < 2 + scalar(@descs));
my $ln = 0;
for my $line(@lines) {
if (!$ln) {
printf "|%-${max_size_name}s", $name;
printf "|%-${desc_size}s", "``" . $data{$name}->{kconfig} . "``";
} elsif ($ln >= 2 && scalar(@descs)) {
printf "|%-${max_size_name}s", "";
printf "|%-${desc_size}s", shift @descs;
} else {
printf "|%-${max_size_name}s", "";
printf "|%-${desc_size}s", "";
}
printf "|%-${status_size}s|\n", $line;
$ln++;
}
matrix_lines($desc_size, $status_size, 0);
}
}
#
# Parses all feature files located at $prefix dir
#
find({wanted =>\&parse_feat, no_chdir => 1}, $prefix);
print STDERR Data::Dumper->Dump([\%data], [qw(*data)]) if ($debug);
#
# Handles the command
#
if ($cmd eq "current") {
$arch = qx(uname -m | sed 's/x86_64/x86/' | sed 's/i386/x86/');
$arch =~s/\s+$//;
}
if ($cmd eq "ls" or $cmd eq "list") {
if (!$arch) {
$arch = qx(uname -m | sed 's/x86_64/x86/' | sed 's/i386/x86/');
$arch =~s/\s+$//;
}
list_arch_features;
exit;
}
if ($cmd ne "validate") {
if ($arch) {
output_arch_table;
} elsif ($feat) {
output_feature;
} else {
output_matrix;
}
}
__END__
=head1 NAME
get_feat.pl - parse the Linux Feature files and produce a ReST book.
=head1 SYNOPSIS
B<get_feat.pl> [--debug] [--man] [--help] [--dir=<dir>] [--arch=<arch>]
[--feature=<feature>|--feat=<feature>] <COMAND> [<ARGUMENT>]
Where <COMMAND> can be:
=over 8
B<current> - output table in ReST compatible ASCII format
with features for this machine's architecture
B<rest> - output table(s) in ReST compatible ASCII format
with features in ReST markup language. The output
is affected by --arch or --feat/--feature flags.
B<validate> - validate the contents of the files under
Documentation/features.
B<ls> or B<list> - list features for this machine's architecture,
using an easier to parse format.
The output is affected by --arch flag.
=back
=head1 OPTIONS
=over 8
=item B<--arch>
Output features for an specific architecture, optionally filtering for
a single specific feature.
=item B<--feat> or B<--feature>
Output features for a single specific feature.
=item B<--dir>
Changes the location of the Feature files. By default, it uses
the Documentation/features directory.
=item B<--debug>
Put the script in verbose mode, useful for debugging. Can be called multiple
times, to increase verbosity.
=item B<--help>
Prints a brief help message and exits.
=item B<--man>
Prints the manual page and exits.
=back
=head1 DESCRIPTION
Parse the Linux feature files from Documentation/features (by default),
optionally producing results at ReST format.
It supports output data per architecture, per feature or a
feature x arch matrix.
When used with B<rest> command, it will use either one of the tree formats:
If neither B<--arch> or B<--feature> arguments are used, it will output a
matrix with features per architecture.
If B<--arch> argument is used, it will output the features availability for
a given architecture.
If B<--feat> argument is used, it will output the content of the feature
file using ReStructured Text markup.
=head1 BUGS
Report bugs to Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
=head1 COPYRIGHT
Copyright (c) 2019 by Mauro Carvalho Chehab <mchehab+samsung@kernel.org>.
License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
=cut
scripts/kernel-doc
View file @ ff613595
......@@ -1390,7 +1390,7 @@ sub dump_enum($$) {
$members = $2;
}
if ($declaration_name) {
if ($members) {
my %_members;
$members =~ s/\s+$//;
......@@ -1431,7 +1431,7 @@ sub dump_enum($$) {
}
}
my $typedef_type = qr { ((?:\s+[\w\*]+){1,8})\s* }x;
my $typedef_type = qr { ((?:\s+[\w\*]+\b){1,8})\s* }x;
my $typedef_ident = qr { \*?\s*(\w\S+)\s* }x;
my $typedef_args = qr { \s*\((.*)\); }x;
......
tools/debugging/kernel-chktaint
View file @ ff613595
......@@ -72,7 +72,7 @@ if [ `expr $T % 2` -eq 0 ]; then
addout " "
else
addout "S"
echo " * SMP kernel oops on an officially SMP incapable processor (#2)"
echo " * kernel running on an out of specification system (#2)"
fi
T=`expr $T / 2`
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7