Skip to content

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

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

Pull documentation updates from Jonathan Corbet:
 "A fairly routine cycle for docs - lots of typo fixes, some new
  documents, and more translations. There's also some LICENSES
  adjustments from Thomas"

* tag 'docs-5.1' of git://git.lwn.net/linux: (74 commits)
  docs: Bring some order to filesystem documentation
  Documentation/locking/lockdep: Drop last two chars of sample states
  doc: rcu: Suspicious RCU usage is a warning
  docs: driver-api: iio: fix errors in documentation
  Documentation/process/howto: Update for 4.x -> 5.x versioning
  docs: Explicitly state that the 'Fixes:' tag shouldn't split lines
  doc: security: Add kern-doc for lsm_hooks.h
  doc: sctp: Merge and clean up rst files
  Docs: Correct /proc/stat path
  scripts/spdxcheck.py: fix C++ comment style detection
  doc: fix typos in license-rules.rst
  Documentation: fix admin-guide/README.rst minimum gcc version requirement
  doc: process: complete removal of info about -git patches
  doc: translations: sync translations 'remove info about -git patches'
  perf-security: wrap paragraphs on 72 columns
  perf-security: elaborate on perf_events/Perf privileged users
  perf-security: document collected perf_events/Perf data categories
  perf-security: document perf_events/Perf resource control
  sysfs.txt: add note on available attribute macros
  docs: kernel-doc: typo "if ... if" -> "if ... is"
  ...
parents c4703acd 4064174b
Expand all Show whitespace changes
Inline Side-by-side
Showing with 3741 additions and 1134 deletions
Documentation/DMA-API.txt
View file @ 1a29e857
......@@ -530,8 +530,8 @@ that simply cannot make consistent memory.
dma_free_attrs(struct device *dev, size_t size, void *cpu_addr,
dma_addr_t dma_handle, unsigned long attrs)
Free memory allocated by the dma_alloc_attrs(). All parameters common
parameters must identical to those otherwise passed to dma_fre_coherent,
Free memory allocated by the dma_alloc_attrs(). All common
parameters must be identical to those otherwise passed to dma_free_coherent,
and the attrs argument must be identical to the attrs passed to
dma_alloc_attrs().
......@@ -717,7 +717,7 @@ dma-api/num_free_entries The current number of free dma_debug_entries
dma-api/nr_total_entries The total number of dma_debug_entries in the
allocator, both free and used.
dma-api/driver-filter You can write a name of a driver into this file
dma-api/driver_filter You can write a name of a driver into this file
to limit the debug output to requests from that
particular driver. Write an empty string to
that file to disable the filter and see
......
Documentation/DMA-ISA-LPC.txt
View file @ 1a29e857
......@@ -52,8 +52,8 @@ Address translation
-------------------
To translate the virtual address to a bus address, use the normal DMA
API. Do _not_ use isa_virt_to_phys() even though it does the same
thing. The reason for this is that the function isa_virt_to_phys()
API. Do _not_ use isa_virt_to_bus() even though it does the same
thing. The reason for this is that the function isa_virt_to_bus()
will require a Kconfig dependency to ISA, not just ISA_DMA_API which
is really all you need. Remember that even though the DMA controller
has its origins in ISA it is used elsewhere.
......
Documentation/RCU/lockdep-splat.txt
View file @ 1a29e857
......@@ -14,9 +14,9 @@ being the real world and all that.
So let's look at an example RCU lockdep splat from 3.0-rc5, one that
has long since been fixed:
===============================
[ INFO: suspicious RCU usage. ]
-------------------------------
=============================
WARNING: suspicious RCU usage
-----------------------------
block/cfq-iosched.c:2776 suspicious rcu_dereference_protected() usage!
other info that might help us debug this:
......@@ -24,11 +24,11 @@ other info that might help us debug this:
rcu_scheduler_active = 1, debug_locks = 0
3 locks held by scsi_scan_6/1552:
#0: (&shost->scan_mutex){+.+.+.}, at: [<ffffffff8145efca>]
#0: (&shost->scan_mutex){+.+.}, at: [<ffffffff8145efca>]
scsi_scan_host_selected+0x5a/0x150
#1: (&eq->sysfs_lock){+.+...}, at: [<ffffffff812a5032>]
#1: (&eq->sysfs_lock){+.+.}, at: [<ffffffff812a5032>]
elevator_exit+0x22/0x60
#2: (&(&q->__queue_lock)->rlock){-.-...}, at: [<ffffffff812b6233>]
#2: (&(&q->__queue_lock)->rlock){-.-.}, at: [<ffffffff812b6233>]
cfq_exit_queue+0x43/0x190
stack backtrace:
......
Documentation/admin-guide/README.rst
View file @ 1a29e857
......@@ -251,7 +251,7 @@ Configuring the kernel
Compiling the kernel
--------------------
- Make sure you have at least gcc 3.2 available.
- Make sure you have at least gcc 4.6 available.
For more information, refer to :ref:`Documentation/process/changes.rst <changes>`.
Please note that you can still run a.out user programs with this kernel.
......
Documentation/admin-guide/kernel-parameters.txt
View file @ 1a29e857
......@@ -1197,9 +1197,10 @@
arch/x86/kernel/cpu/cpufreq/elanfreq.c.
elevator= [IOSCHED]
Format: {"cfq" | "deadline" | "noop"}
See Documentation/block/cfq-iosched.txt and
Documentation/block/deadline-iosched.txt for details.
Format: { "mq-deadline" | "kyber" | "bfq" }
See Documentation/block/deadline-iosched.txt,
Documentation/block/kyber-iosched.txt and
Documentation/block/bfq-iosched.txt for details.
elfcorehdr=[size[KMG]@]offset[KMG] [IA64,PPC,SH,X86,S390]
Specifies physical address of start of kernel core
......@@ -1996,6 +1997,12 @@
Built with CONFIG_DEBUG_KMEMLEAK_DEFAULT_OFF=y,
the default is off.
kpti= [ARM64] Control page table isolation of user
and kernel address spaces.
Default: enabled on cores which need mitigation.
0: force disabled
1: force enabled
kvm.ignore_msrs=[KVM] Ignore guest accesses to unhandled MSRs.
Default is 0 (don't ignore, but inject #GP)
......
Documentation/admin-guide/perf-security.rst
View file @ 1a29e857
This diff is collapsed.
Documentation/admin-guide/tainted-kernels.rst
View file @ 1a29e857
Tainted kernels
---------------
Some oops reports contain the string **'Tainted: '** after the program
counter. This indicates that the kernel has been tainted by some
mechanism. The string is followed by a series of position-sensitive
characters, each representing a particular tainted value.
1) ``G`` if all modules loaded have a GPL or compatible license, ``P`` if
The kernel will mark itself as 'tainted' when something occurs that might be
relevant later when investigating problems. Don't worry too much about this,
most of the time it's not a problem to run a tainted kernel; the information is
mainly of interest once someone wants to investigate some problem, as its real
cause might be the event that got the kernel tainted. That's why bug reports
from tainted kernels will often be ignored by developers, hence try to reproduce
problems with an untainted kernel.
Note the kernel will remain tainted even after you undo what caused the taint
(i.e. unload a proprietary kernel module), to indicate the kernel remains not
trustworthy. That's also why the kernel will print the tainted state when it
notices an internal problem (a 'kernel bug'), a recoverable error
('kernel oops') or a non-recoverable error ('kernel panic') and writes debug
information about this to the logs ``dmesg`` outputs. It's also possible to
check the tainted state at runtime through a file in ``/proc/``.
Tainted flag in bugs, oops or panics messages
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You find the tainted state near the top in a line starting with 'CPU:'; if or
why the kernel was tainted is shown after the Process ID ('PID:') and a shortened
name of the command ('Comm:') that triggered the event::
BUG: unable to handle kernel NULL pointer dereference at 0000000000000000
Oops: 0002 [#1] SMP PTI
CPU: 0 PID: 4424 Comm: insmod Tainted: P W O 4.20.0-0.rc6.fc30 #1
Hardware name: Red Hat KVM, BIOS 0.5.1 01/01/2011
RIP: 0010:my_oops_init+0x13/0x1000 [kpanic]
[...]
You'll find a 'Not tainted: ' there if the kernel was not tainted at the
time of the event; if it was, then it will print 'Tainted: ' and characters
either letters or blanks. In above example it looks like this::
Tainted: P W O
The meaning of those characters is explained in the table below. In tis case
the kernel got tainted earlier because a proprietary Module (``P``) was loaded,
a warning occurred (``W``), and an externally-built module was loaded (``O``).
To decode other letters use the table below.
Decoding tainted state at runtime
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
At runtime, you can query the tainted state by reading
``cat /proc/sys/kernel/tainted``. If that returns ``0``, the kernel is not
tainted; any other number indicates the reasons why it is. The easiest way to
decode that number is the script ``tools/debugging/kernel-chktaint``, which your
distribution might ship as part of a package called ``linux-tools`` or
``kernel-tools``; if it doesn't you can download the script from
`git.kernel.org <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/tools/debugging/kernel-chktaint>`_
and execute it with ``sh kernel-chktaint``, which would print something like
this on the machine that had the statements in the logs that were quoted earlier::
Kernel is Tainted for following reasons:
* Proprietary module was loaded (#0)
* Kernel issued warning (#9)
* Externally-built ('out-of-tree') module was loaded (#12)
See Documentation/admin-guide/tainted-kernels.rst in the the Linux kernel or
https://www.kernel.org/doc/html/latest/admin-guide/tainted-kernels.html for
a more details explanation of the various taint flags.
Raw taint value as int/string: 4609/'P W O '
You can try to decode the number yourself. That's easy if there was only one
reason that got your kernel tainted, as in this case you can find the number
with the table below. If there were multiple reasons you need to decode the
number, as it is a bitfield, where each bit indicates the absence or presence of
a particular type of taint. It's best to leave that to the aforementioned
script, but if you need something quick you can use this shell command to check
which bits are set::
$ for i in $(seq 18); do echo $(($i-1)) $(($(cat /proc/sys/kernel/tainted)>>($i-1)&1));done
Table for decoding tainted state
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=== === ====== ========================================================
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
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
6 _/U 64 taint requested by userspace application
7 _/D 128 kernel died recently, i.e. there was an OOPS or BUG
8 _/A 256 ACPI table overridden by user
9 _/W 512 kernel issued warning
10 _/C 1024 staging driver was loaded
11 _/I 2048 workaround for bug in platform firmware applied
12 _/O 4096 externally-built ("out-of-tree") module was loaded
13 _/E 8192 unsigned module was loaded
14 _/L 16384 soft lockup occurred
15 _/K 32768 kernel has been live patched
16 _/X 65536 auxiliary taint, defined for and used by distros
17 _/T 131072 kernel was built with the struct randomization plugin
=== === ====== ========================================================
Note: The character ``_`` is representing a blank in this table to make reading
easier.
More detailed explanation for tainting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0) ``G`` if all modules loaded have a GPL or compatible license, ``P`` if
any proprietary module has been loaded. Modules without a
MODULE_LICENSE or with a MODULE_LICENSE that is not recognised by
insmod as GPL compatible are assumed to be proprietary.
2) ``F`` if any module was force loaded by ``insmod -f``, ``' '`` if all
1) ``F`` if any module was force loaded by ``insmod -f``, ``' '`` if all
modules were loaded normally.
3) ``S`` if the oops occurred on an SMP kernel running on hardware that
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.
4) ``R`` if a module was force unloaded by ``rmmod -f``, ``' '`` if all
3) ``R`` if a module was force unloaded by ``rmmod -f``, ``' '`` if all
modules were unloaded normally.
5) ``M`` if any processor has reported a Machine Check Exception,
4) ``M`` if any processor has reported a Machine Check Exception,
``' '`` if no Machine Check Exceptions have occurred.
6) ``B`` if a page-release function has found a bad page reference or
some unexpected page flags.
5) ``B`` If a page-release function has found a bad page reference or some
unexpected page flags. This indicates a hardware problem or a kernel bug;
there should be other information in the log indicating why this tainting
occured.
7) ``U`` if a user or user application specifically requested that the
6) ``U`` if a user or user application specifically requested that the
Tainted flag be set, ``' '`` otherwise.
8) ``D`` if the kernel has died recently, i.e. there was an OOPS or BUG.
7) ``D`` if the kernel has died recently, i.e. there was an OOPS or BUG.
9) ``A`` if the ACPI table has been overridden.
8) ``A`` if an ACPI table has been overridden.
10) ``W`` if a warning has previously been issued by the kernel.
9) ``W`` if a warning has previously been issued by the kernel.
(Though some warnings may set more specific taint flags.)
11) ``C`` if a staging driver has been loaded.
10) ``C`` if a staging driver has been loaded.
12) ``I`` if the kernel is working around a severe bug in the platform
11) ``I`` if the kernel is working around a severe bug in the platform
firmware (BIOS or similar).
13) ``O`` if an externally-built ("out-of-tree") module has been loaded.
12) ``O`` if an externally-built ("out-of-tree") module has been loaded.
14) ``E`` if an unsigned module has been loaded in a kernel supporting
13) ``E`` if an unsigned module has been loaded in a kernel supporting
module signature.
15) ``L`` if a soft lockup has previously occurred on the system.
14) ``L`` if a soft lockup has previously occurred on the system.
15) ``K`` if the kernel has been live patched.
16) ``K`` if the kernel has been live patched.
16) ``X`` Auxiliary taint, defined for and used by Linux distributors.
The primary reason for the **'Tainted: '** string is to tell kernel
debuggers if this is a clean kernel or if anything unusual has
occurred. Tainting is permanent: even if an offending module is
unloaded, the tainted value remains to indicate that the kernel is not
trustworthy.
17) ``T`` Kernel was build with the randstruct plugin, which can intentionally
produce extremely unusual kernel structure layouts (even performance
pathological ones), which is important to know when debugging. Set at
build time.
Documentation/cgroup-v1/memory.txt
View file @ 1a29e857
......@@ -70,7 +70,7 @@ Brief summary of control files.
memory.soft_limit_in_bytes # set/show soft limit of memory usage
memory.stat # show various statistics
memory.use_hierarchy # set/show hierarchical account enabled
memory.force_empty # trigger forced move charge to parent
memory.force_empty # trigger forced page reclaim
memory.pressure_level # set memory pressure notifications
memory.swappiness # set/show swappiness parameter of vmscan
(See sysctl's vm.swappiness)
......@@ -459,8 +459,9 @@ About use_hierarchy, see Section 6.
the cgroup will be reclaimed and as many pages reclaimed as possible.
The typical use case for this interface is before calling rmdir().
Because rmdir() moves all pages to parent, some out-of-use page caches can be
moved to the parent. If you want to avoid that, force_empty will be useful.
Though rmdir() offlines memcg, but the memcg may still stay there due to
charged file caches. Some out-of-use page caches may keep charged until
memory pressure happens. If you want to avoid that, force_empty will be useful.
Also, note that when memory.kmem.limit_in_bytes is set the charges due to
kernel pages will still be seen. This is not considered a failure and the
......
Documentation/core-api/kernel-api.rst
View file @ 1a29e857
......@@ -356,10 +356,6 @@ Read-Copy Update (RCU)
.. kernel-doc:: include/linux/rcupdate.h
.. kernel-doc:: include/linux/rcupdate_wait.h
.. kernel-doc:: include/linux/rcutree.h
.. kernel-doc:: kernel/rcu/tree.c
.. kernel-doc:: kernel/rcu/tree_plugin.h
......
Documentation/core-api/memory-allocation.rst
View file @ 1a29e857
.. _memory-allocation:
.. _memory_allocation:
=======================
Memory Allocation Guide
......@@ -113,9 +113,11 @@ see :c:func:`kvmalloc_node` reference documentation. Note that
If you need to allocate many identical objects you can use the slab
cache allocator. The cache should be set up with
:c:func:`kmem_cache_create` before it can be used. Afterwards
:c:func:`kmem_cache_alloc` and its convenience wrappers can allocate
memory from that cache.
:c:func:`kmem_cache_create` or :c:func:`kmem_cache_create_usercopy`
before it can be used. The second function should be used if a part of
the cache might be copied to the userspace. After the cache is
created :c:func:`kmem_cache_alloc` and its convenience wrappers can
allocate memory from that cache.
When the allocated memory is no longer needed it must be freed. You
can use :c:func:`kvfree` for the memory allocated with `kmalloc`,
......
Documentation/core-api/mm-api.rst
View file @ 1a29e857
......@@ -35,7 +35,7 @@ users will want to use a plain ``GFP_KERNEL``.
:doc: Reclaim modifiers
.. kernel-doc:: include/linux/gfp.h
:doc: Common combinations
:doc: Useful GFP flag combinations
The Slab Cache
==============
......
Documentation/dev-tools/kcov.rst
View file @ 1a29e857
......@@ -22,7 +22,7 @@ Configure the kernel with::
CONFIG_KCOV=y
CONFIG_KCOV requires gcc built on revision 231296 or later.
CONFIG_KCOV requires gcc 6.1.0 or later.
If the comparison operands need to be collected, set::
......
Documentation/doc-guide/kernel-doc.rst
View file @ 1a29e857
......@@ -490,7 +490,7 @@ doc: *title*
functions: *[ function ...]*
Include documentation for each *function* in *source*.
If no *function* if specified, the documentaion for all functions
If no *function* is specified, the documentation for all functions
and types in the *source* will be included.
Examples::
......@@ -517,4 +517,17 @@ How to use kernel-doc to generate man pages
If you just want to use kernel-doc to generate man pages you can do this
from the kernel git tree::
$ scripts/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man
$ scripts/kernel-doc -man \
$(git grep -l '/\*\*' -- :^Documentation :^tools) \
| scripts/split-man.pl /tmp/man
Some older versions of git do not support some of the variants of syntax for
path exclusion. One of the following commands may work for those versions::
$ scripts/kernel-doc -man \
$(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \
| scripts/split-man.pl /tmp/man
$ scripts/kernel-doc -man \
$(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \
| scripts/split-man.pl /tmp/man
Documentation/doc-guide/sphinx.rst
View file @ 1a29e857
......@@ -27,8 +27,8 @@ Sphinx Install
==============
The ReST markups currently used by the Documentation/ files are meant to be
built with ``Sphinx`` version 1.3 or upper. If you're desiring to build
PDF outputs, it is recommended to use version 1.4.6 or upper.
built with ``Sphinx`` version 1.3 or higher. If you desire to build
PDF output, it is recommended to use version 1.4.6 or higher.
There's a script that checks for the Sphinx requirements. Please see
:ref:`sphinx-pre-install` for further details.
......@@ -37,15 +37,15 @@ Most distributions are shipped with Sphinx, but its toolchain is fragile,
and it is not uncommon that upgrading it or some other Python packages
on your machine would cause the documentation build to break.
A way to get rid of that is to use a different version than the one shipped
on your distributions. In order to do that, it is recommended to install
A way to avoid that is to use a different version than the one shipped
with your distributions. In order to do so, it is recommended to install
Sphinx inside a virtual environment, using ``virtualenv-3``
or ``virtualenv``, depending on how your distribution packaged Python 3.
.. note::
#) Sphinx versions below 1.5 don't work properly with Python's
docutils version 0.13.1 or upper. So, if you're willing to use
docutils version 0.13.1 or higher. So, if you're willing to use
those versions, you should run ``pip install 'docutils==0.12'``.
#) It is recommended to use the RTD theme for html output. Depending
......@@ -82,7 +82,7 @@ output.
PDF and LaTeX builds
--------------------
Such builds are currently supported only with Sphinx versions 1.4 and upper.
Such builds are currently supported only with Sphinx versions 1.4 and higher.
For PDF and LaTeX output, you'll also need ``XeLaTeX`` version 3.14159265.
......
Documentation/driver-api/dmaengine/client.rst
View file @ 1a29e857
......@@ -168,6 +168,13 @@ The details of these operations are:
dmaengine_submit() will not start the DMA operation, it merely adds
it to the pending queue. For this, see step 5, dma_async_issue_pending.
.. note::
After calling ``dmaengine_submit()`` the submitted transfer descriptor
(``struct dma_async_tx_descriptor``) belongs to the DMA engine.
Consequentially, the client must consider invalid the pointer to that
descriptor.
5. Issue pending DMA requests and wait for callback notification
The transactions in the pending queue can be activated by calling the
......
Documentation/driver-api/iio/buffers.rst
View file @ 1a29e857
......@@ -26,7 +26,7 @@ IIO buffer setup
================
The meta information associated with a channel reading placed in a buffer is
called a scan element . The important bits configuring scan elements are
called a scan element. The important bits configuring scan elements are
exposed to userspace applications via the
:file:`/sys/bus/iio/iio:device{X}/scan_elements/*` directory. This file contains
attributes of the following form:
......
Documentation/driver-api/iio/core.rst
View file @ 1a29e857
......@@ -2,8 +2,8 @@
Core elements
=============
The Industrial I/O core offers a unified framework for writing drivers for
many different types of embedded sensors. a standard interface to user space
The Industrial I/O core offers both a unified framework for writing drivers for
many different types of embedded sensors and a standard interface to user space
applications manipulating sensors. The implementation can be found under
:file:`drivers/iio/industrialio-*`
......@@ -11,7 +11,7 @@ Industrial I/O Devices
----------------------
* struct :c:type:`iio_dev` - industrial I/O device
* :c:func:`iio_device_alloc()` - alocate an :c:type:`iio_dev` from a driver
* :c:func:`iio_device_alloc()` - allocate an :c:type:`iio_dev` from a driver
* :c:func:`iio_device_free()` - free an :c:type:`iio_dev` from a driver
* :c:func:`iio_device_register()` - register a device with the IIO subsystem
* :c:func:`iio_device_unregister()` - unregister a device from the IIO
......
Documentation/driver-api/iio/hw-consumer.rst
View file @ 1a29e857
===========
HW consumer
===========
An IIO device can be directly connected to another device in hardware. in this
An IIO device can be directly connected to another device in hardware. In this
case the buffers between IIO provider and IIO consumer are handled by hardware.
The Industrial I/O HW consumer offers a way to bond these IIO devices without
software buffer for data. The implementation can be found under
......
Documentation/fault-injection/fault-injection.txt
View file @ 1a29e857
......@@ -195,7 +195,7 @@ o #include <linux/fault-inject.h>
o define the fault attributes
DECLARE_FAULT_INJECTION(name);
DECLARE_FAULT_ATTR(name);
Please see the definition of struct fault_attr in fault-inject.h
for details.
......
Documentation/filesystems/api-summary.rst 0 → 100644
View file @ 1a29e857
=============================
Linux Filesystems API summary
=============================
This section contains API-level documentation, mostly taken from the source
code itself.
The Linux VFS
=============
The Filesystem types
--------------------
.. kernel-doc:: include/linux/fs.h
:internal:
The Directory Cache
-------------------
.. kernel-doc:: fs/dcache.c
:export:
.. kernel-doc:: include/linux/dcache.h
:internal:
Inode Handling
--------------
.. kernel-doc:: fs/inode.c
:export:
.. kernel-doc:: fs/bad_inode.c
:export:
Registration and Superblocks
----------------------------
.. kernel-doc:: fs/super.c
:export:
File Locks
----------
.. kernel-doc:: fs/locks.c
:export:
.. kernel-doc:: fs/locks.c
:internal:
Other Functions
---------------
.. kernel-doc:: fs/mpage.c
:export:
.. kernel-doc:: fs/namei.c
:export:
.. kernel-doc:: fs/buffer.c
:export:
.. kernel-doc:: block/bio.c
:export:
.. kernel-doc:: fs/seq_file.c
:export:
.. kernel-doc:: fs/filesystems.c
:export:
.. kernel-doc:: fs/fs-writeback.c
:export:
.. kernel-doc:: fs/block_dev.c
:export:
.. kernel-doc:: fs/anon_inodes.c
:export:
.. kernel-doc:: fs/attr.c
:export:
.. kernel-doc:: fs/d_path.c
:export:
.. kernel-doc:: fs/dax.c
:export:
.. kernel-doc:: fs/direct-io.c
:export:
.. kernel-doc:: fs/file_table.c
:export:
.. kernel-doc:: fs/libfs.c
:export:
.. kernel-doc:: fs/posix_acl.c
:export:
.. kernel-doc:: fs/stat.c
:export:
.. kernel-doc:: fs/sync.c
:export:
.. kernel-doc:: fs/xattr.c
:export:
The proc filesystem
===================
sysctl interface
----------------
.. kernel-doc:: kernel/sysctl.c
:export:
proc filesystem interface
-------------------------
.. kernel-doc:: fs/proc/base.c
:internal:
Events based on file descriptors
================================
.. kernel-doc:: fs/eventfd.c
:export:
The Filesystem for Exporting Kernel Objects
===========================================
.. kernel-doc:: fs/sysfs/file.c
:export:
.. kernel-doc:: fs/sysfs/symlink.c
:export:
The debugfs filesystem
======================
debugfs interface
-----------------
.. kernel-doc:: fs/debugfs/inode.c
:export:
.. kernel-doc:: fs/debugfs/file.c
:export:
Documentation/filesystems/binderfs.rst 0 → 100644
View file @ 1a29e857
.. SPDX-License-Identifier: GPL-2.0
The Android binderfs Filesystem
===============================
Android binderfs is a filesystem for the Android binder IPC mechanism. It
allows to dynamically add and remove binder devices at runtime. Binder devices
located in a new binderfs instance are independent of binder devices located in
other binderfs instances. Mounting a new binderfs instance makes it possible
to get a set of private binder devices.
Mounting binderfs
-----------------
Android binderfs can be mounted with::
mkdir /dev/binderfs
mount -t binder binder /dev/binderfs
at which point a new instance of binderfs will show up at ``/dev/binderfs``.
In a fresh instance of binderfs no binder devices will be present. There will
only be a ``binder-control`` device which serves as the request handler for
binderfs. Mounting another binderfs instance at a different location will
create a new and separate instance from all other binderfs mounts. This is
identical to the behavior of e.g. ``devpts`` and ``tmpfs``. The Android
binderfs filesystem can be mounted in user namespaces.
Options
-------
max
binderfs instances can be mounted with a limit on the number of binder
devices that can be allocated. The ``max=<count>`` mount option serves as
a per-instance limit. If ``max=<count>`` is set then only ``<count>`` number
of binder devices can be allocated in this binderfs instance.
Allocating binder Devices
-------------------------
.. _ioctl: http://man7.org/linux/man-pages/man2/ioctl.2.html
To allocate a new binder device in a binderfs instance a request needs to be
sent through the ``binder-control`` device node. A request is sent in the form
of an `ioctl() <ioctl_>`_.
What a program needs to do is to open the ``binder-control`` device node and
send a ``BINDER_CTL_ADD`` request to the kernel. Users of binderfs need to
tell the kernel which name the new binder device should get. By default a name
can only contain up to ``BINDERFS_MAX_NAME`` chars including the terminating
zero byte.
Once the request is made via an `ioctl() <ioctl_>`_ passing a ``struct
binder_device`` with the name to the kernel it will allocate a new binder
device and return the major and minor number of the new device in the struct
(This is necessary because binderfs allocates a major device number
dynamically.). After the `ioctl() <ioctl_>`_ returns there will be a new
binder device located under /dev/binderfs with the chosen name.
Deleting binder Devices
-----------------------
.. _unlink: http://man7.org/linux/man-pages/man2/unlink.2.html
.. _rm: http://man7.org/linux/man-pages/man1/rm.1.html
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
binderfs instance is unmounted and all references to it have been dropped.
Documentation/filesystems/index.rst
View file @ 1a29e857
This diff is collapsed.
Documentation/filesystems/journalling.rst 0 → 100644
View file @ 1a29e857
The Linux Journalling API
=========================
Overview
--------
Details
~~~~~~~
The journalling layer is easy to use. You need to first of all create a
journal_t data structure. There are two calls to do this dependent on
how you decide to allocate the physical media on which the journal
resides. The :c:func:`jbd2_journal_init_inode` call is for journals stored in
filesystem inodes, or the :c:func:`jbd2_journal_init_dev` call can be used
for journal stored on a raw device (in a continuous range of blocks). A
journal_t is a typedef for a struct pointer, so when you are finally
finished make sure you call :c:func:`jbd2_journal_destroy` on it to free up
any used kernel memory.
Once you have got your journal_t object you need to 'mount' or load the
journal file. The journalling layer expects the space for the journal
was already allocated and initialized properly by the userspace tools.
When loading the journal you must call :c:func:`jbd2_journal_load` to process
journal contents. If the client file system detects the journal contents
does not need to be processed (or even need not have valid contents), it
may call :c:func:`jbd2_journal_wipe` to clear the journal contents before
calling :c:func:`jbd2_journal_load`.
Note that jbd2_journal_wipe(..,0) calls
:c:func:`jbd2_journal_skip_recovery` for you if it detects any outstanding
transactions in the journal and similarly :c:func:`jbd2_journal_load` will
call :c:func:`jbd2_journal_recover` if necessary. I would advise reading
:c:func:`ext4_load_journal` in fs/ext4/super.c for examples on this stage.
Now you can go ahead and start modifying the underlying filesystem.
Almost.
You still need to actually journal your filesystem changes, this is done
by wrapping them into transactions. Additionally you also need to wrap
the modification of each of the buffers with calls to the journal layer,
so it knows what the modifications you are actually making are. To do
this use :c:func:`jbd2_journal_start` which returns a transaction handle.
:c:func:`jbd2_journal_start` and its counterpart :c:func:`jbd2_journal_stop`,
which indicates the end of a transaction are nestable calls, so you can
reenter a transaction if necessary, but remember you must call
:c:func:`jbd2_journal_stop` the same number of times as
:c:func:`jbd2_journal_start` before the transaction is completed (or more
accurately leaves the update phase). Ext4/VFS makes use of this feature to
simplify handling of inode dirtying, quota support, etc.
Inside each transaction you need to wrap the modifications to the
individual buffers (blocks). Before you start to modify a buffer you
need to call :c:func:`jbd2_journal_get_create_access()` /
:c:func:`jbd2_journal_get_write_access()` /
:c:func:`jbd2_journal_get_undo_access()` as appropriate, this allows the
journalling layer to copy the unmodified
data if it needs to. After all the buffer may be part of a previously
uncommitted transaction. At this point you are at last ready to modify a
buffer, and once you are have done so you need to call
:c:func:`jbd2_journal_dirty_metadata`. Or if you've asked for access to a
buffer you now know is now longer required to be pushed back on the
device you can call :c:func:`jbd2_journal_forget` in much the same way as you
might have used :c:func:`bforget` in the past.
A :c:func:`jbd2_journal_flush` may be called at any time to commit and
checkpoint all your transactions.
Then at umount time , in your :c:func:`put_super` you can then call
:c:func:`jbd2_journal_destroy` to clean up your in-core journal object.
Unfortunately there a couple of ways the journal layer can cause a
deadlock. The first thing to note is that each task can only have a
single outstanding transaction at any one time, remember nothing commits
until the outermost :c:func:`jbd2_journal_stop`. This means you must complete
the transaction at the end of each file/inode/address etc. operation you
perform, so that the journalling system isn't re-entered on another
journal. Since transactions can't be nested/batched across differing
journals, and another filesystem other than yours (say ext4) may be
modified in a later syscall.
The second case to bear in mind is that :c:func:`jbd2_journal_start` can block
if there isn't enough space in the journal for your transaction (based
on the passed nblocks param) - when it blocks it merely(!) needs to wait
for transactions to complete and be committed from other tasks, so
essentially we are waiting for :c:func:`jbd2_journal_stop`. So to avoid
deadlocks you must treat :c:func:`jbd2_journal_start` /
:c:func:`jbd2_journal_stop` as if they were semaphores and include them in
your semaphore ordering rules to prevent
deadlocks. Note that :c:func:`jbd2_journal_extend` has similar blocking
behaviour to :c:func:`jbd2_journal_start` so you can deadlock here just as
easily as on :c:func:`jbd2_journal_start`.
Try to reserve the right number of blocks the first time. ;-). This will
be the maximum number of blocks you are going to touch in this
transaction. I advise having a look at at least ext4_jbd.h to see the
basis on which ext4 uses to make these decisions.
Another wriggle to watch out for is your on-disk block allocation
strategy. Why? Because, if you do a delete, you need to ensure you
haven't reused any of the freed blocks until the transaction freeing
these blocks commits. If you reused these blocks and crash happens,
there is no way to restore the contents of the reallocated blocks at the
end of the last fully committed transaction. One simple way of doing
this is to mark blocks as free in internal in-memory block allocation
structures only after the transaction freeing them commits. Ext4 uses
journal commit callback for this purpose.
With journal commit callbacks you can ask the journalling layer to call
a callback function when the transaction is finally committed to disk,
so that you can do some of your own management. You ask the journalling
layer for calling the callback by simply setting
``journal->j_commit_callback`` function pointer and that function is
called after each transaction commit. You can also use
``transaction->t_private_list`` for attaching entries to a transaction
that need processing when the transaction commits.
JBD2 also provides a way to block all transaction updates via
:c:func:`jbd2_journal_lock_updates()` /
:c:func:`jbd2_journal_unlock_updates()`. Ext4 uses this when it wants a
window with a clean and stable fs for a moment. E.g.
::
jbd2_journal_lock_updates() //stop new stuff happening..
jbd2_journal_flush() // checkpoint everything.
..do stuff on stable fs
jbd2_journal_unlock_updates() // carry on with filesystem use.
The opportunities for abuse and DOS attacks with this should be obvious,
if you allow unprivileged userspace to trigger codepaths containing
these calls.
Summary
~~~~~~~
Using the journal is a matter of wrapping the different context changes,
being each mount, each modification (transaction) and each changed
buffer to tell the journalling layer about them.
Data Types
----------
The journalling layer uses typedefs to 'hide' the concrete definitions
of the structures used. As a client of the JBD2 layer you can just rely
on the using the pointer as a magic cookie of some sort. Obviously the
hiding is not enforced as this is 'C'.
Structures
~~~~~~~~~~
.. kernel-doc:: include/linux/jbd2.h
:internal:
Functions
---------
The functions here are split into two groups those that affect a journal
as a whole, and those which are used to manage transactions
Journal Level
~~~~~~~~~~~~~
.. kernel-doc:: fs/jbd2/journal.c
:export:
.. kernel-doc:: fs/jbd2/recovery.c
:internal:
Transasction Level
~~~~~~~~~~~~~~~~~~
.. kernel-doc:: fs/jbd2/transaction.c
See also
--------
`Journaling the Linux ext2fs Filesystem, LinuxExpo 98, Stephen
Tweedie <http://kernel.org/pub/linux/kernel/people/sct/ext3/journal-design.ps.gz>`__
`Ext3 Journalling FileSystem, OLS 2000, Dr. Stephen
Tweedie <http://olstrans.sourceforge.net/release/OLS2000-ext3/OLS2000-ext3.html>`__
Documentation/filesystems/path-lookup.rst
View file @ 1a29e857
===============
Pathname lookup
===============
This write-up is based on three articles published at lwn.net:
- <https://lwn.net/Articles/649115/> Pathname lookup in Linux
- <https://lwn.net/Articles/649729/> RCU-walk: faster pathname lookup in Linux
- <https://lwn.net/Articles/650786/> A walk among the symlinks
Written by Neil Brown with help from Al Viro and Jon Corbet.
It has subsequently been updated to reflect changes in the kernel
including:
- per-directory parallel name lookup.
Introduction to pathname lookup
===============================
......@@ -344,7 +359,7 @@ In particular it is held while scanning chains in the dcache hash
table, and the mount point hash table.
Bringing it together with ``struct nameidata``
--------------------------------------------
----------------------------------------------
.. _First edition Unix: http://minnie.tuhs.org/cgi-bin/utree.pl?file=V1/u2.s
......@@ -355,7 +370,7 @@ converts a "name" to an "inode". ``struct nameidata`` contains (among
other fields):
``struct path path``
~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~
A ``path`` contains a ``struct vfsmount`` (which is
embedded in a ``struct mount``) and a ``struct dentry``. Together these
......@@ -366,13 +381,13 @@ step. A reference through ``d_lockref`` and ``mnt_count`` is always
held.
``struct qstr last``
~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~
This is a string together with a length (i.e. _not_ ``nul`` terminated)
that is the "next" component in the pathname.
``int last_type``
~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~
This is one of ``LAST_NORM``, ``LAST_ROOT``, ``LAST_DOT``, ``LAST_DOTDOT``, or
``LAST_BIND``. The ``last`` field is only valid if the type is
......@@ -381,7 +396,7 @@ components of the symlink have been processed yet. Others should be
fairly self-explanatory.
``struct path root``
~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~
This is used to hold a reference to the effective root of the
filesystem. Often that reference won't be needed, so this field is
......@@ -510,7 +525,7 @@ potentially interesting things about these dentries corresponding
to three different flags that might be set in ``dentry->d_flags``:
``DCACHE_MANAGE_TRANSIT``
~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~
If this flag has been set, then the filesystem has requested that the
``d_manage()`` dentry operation be called before handling any possible
......@@ -529,7 +544,7 @@ filesystem, which will then give it a special pass through
``d_manage()`` by returning ``-EISDIR``.
``DCACHE_MOUNTED``
~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~
This flag is set on every dentry that is mounted on. As Linux
supports multiple filesystem namespaces, it is possible that the
......@@ -542,7 +557,7 @@ If this flag is set, and ``d_manage()`` didn't return ``-EISDIR``,
and a new ``dentry`` (both with counted references).
``DCACHE_NEED_AUTOMOUNT``
~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~
If ``d_manage()`` allowed us to get this far, and ``lookup_mnt()`` didn't
find a mount point, then this flag causes the ``d_automount()`` dentry
......@@ -698,7 +713,7 @@ With that little refresher on seqlocks out of the way we can look at
the bigger picture of how RCU-walk uses seqlocks.
``mount_lock`` and ``nd->m_seq``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
We already met the ``mount_lock`` seqlock when REF-walk used it to
ensure that crossing a mount point is performed safely. RCU-walk uses
......@@ -727,7 +742,7 @@ results would have been the same. This ensures the invariant holds,
at least for vfsmount structures.
``dentry->d_seq`` and ``nd->seq``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In place of taking a count or lock on ``d_reflock``, RCU-walk samples
the per-dentry ``d_seq`` seqlock, and stores the sequence number in the
......@@ -774,7 +789,7 @@ getting a counted reference to the new dentry before dropping that for
the old dentry which we saw in REF-walk.
No ``inode->i_rwsem`` or even ``rename_lock``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A semaphore is a fairly heavyweight lock that can only be taken when it is
permissible to sleep. As ``rcu_read_lock()`` forbids sleeping,
......@@ -796,7 +811,7 @@ locking. This neatly handles all cases, so adding extra checks on
rename_lock would bring no significant value.
``unlazy walk()`` and ``complete_walk()``
-------------------------------------
-----------------------------------------
That "dropping down to REF-walk" typically involves a call to
``unlazy_walk()``, so named because "RCU-walk" is also sometimes
......
Documentation/filesystems/splice.rst 0 → 100644
View file @ 1a29e857
================
splice and pipes
================
splice API
==========
splice is a method for moving blocks of data around inside the kernel,
without continually transferring them between the kernel and user space.
.. kernel-doc:: fs/splice.c
pipes API
=========
Pipe interfaces are all for in-kernel (builtin image) use. They are not
exported for use by modules.
.. kernel-doc:: include/linux/pipe_fs_i.h
:internal:
.. kernel-doc:: fs/pipe.c
Documentation/filesystems/sysfs.txt
View file @ 1a29e857
......@@ -116,6 +116,27 @@ static struct device_attribute dev_attr_foo = {
.store = store_foo,
};
Note as stated in include/linux/kernel.h "OTHER_WRITABLE? Generally
considered a bad idea." so trying to set a sysfs file writable for
everyone will fail reverting to RO mode for "Others".
For the common cases sysfs.h provides convenience macros to make
defining attributes easier as well as making code more concise and
readable. The above case could be shortened to:
static struct device_attribute dev_attr_foo = __ATTR_RW(foo);
the list of helpers available to define your wrapper function is:
__ATTR_RO(name): assumes default name_show and mode 0444
__ATTR_WO(name): assumes a name_store only and is restricted to mode
0200 that is root write access only.
__ATTR_RO_MODE(name, mode): fore more restrictive RO access currently
only use case is the EFI System Resource Table
(see drivers/firmware/efi/esrt.c)
__ATTR_RW(name): assumes default name_show, name_store and setting
mode to 0644.
__ATTR_NULL: which sets the name to NULL and is used as end of list
indicator (see: kernel/workqueue.c)
Subsystem-Specific Callbacks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
......
Documentation/hwmon/f71882fg
View file @ 1a29e857
......@@ -94,7 +94,7 @@ Note that the lowest numbered temperature zone trip point corresponds to
to the border between the highest and one but highest temperature zones, and
vica versa. So the temperature zone trip points 1-4 (or 1-2) go from high temp
to low temp! This is how things are implemented in the IC, and the driver
mimicks this.
mimics this.
There are 2 modes to specify the speed of the fan, PWM duty cycle (or DC
voltage) mode, where 0-100% duty cycle (0-100% of 12V) is specified. And RPM
......
Documentation/index.rst
View file @ 1a29e857
......@@ -90,6 +90,7 @@ needed).
filesystems/index
vm/index
bpf/index
misc-devices/index
Architecture-specific documentation
-----------------------------------
......
Documentation/input/devices/xpad.rst
View file @ 1a29e857
......@@ -218,7 +218,7 @@ References
.. [1] http://euc.jp/periphs/xbox-controller.ja.html (ITO Takayuki)
.. [2] http://xpad.xbox-scene.com/
.. [3] http://www.markosweb.com/www/xboxhackz.com/
.. [4] http://lxr.free-electrons.com/ident?i=xpad_device
.. [4] https://elixir.bootlin.com/linux/latest/ident/xpad_device
Historic Edits
......
Documentation/laptops/lg-laptop.rst
View file @ 1a29e857
.. SPDX-License-Identifier: GPL-2.0+
LG Gram laptop extra features
=============================
......@@ -9,6 +10,7 @@ Hotkeys
-------
The following FN keys are ignored by the kernel without this driver:
- FN-F1 (LG control panel) - Generates F15
- FN-F5 (Touchpad toggle) - Generates F13
- FN-F6 (Airplane mode) - Generates RFKILL
......@@ -16,7 +18,7 @@ The following FN keys are ignored by the kernel without this driver:
This key also changes keyboard backlight mode.
- FN-F9 (Reader mode) - Generates F14
The rest of the FN key work without a need for a special driver.
The rest of the FN keys work without a need for a special driver.
Reader mode
......
Documentation/locking/lockdep-design.txt
View file @ 1a29e857
......@@ -45,10 +45,10 @@ When locking rules are violated, these state bits are presented in the
locking error messages, inside curlies. A contrived example:
modprobe/2287 is trying to acquire lock:
(&sio_locks[i].lock){-.-...}, at: [<c02867fd>] mutex_lock+0x21/0x24
(&sio_locks[i].lock){-.-.}, at: [<c02867fd>] mutex_lock+0x21/0x24
but task is already holding lock:
(&sio_locks[i].lock){-.-...}, at: [<c02867fd>] mutex_lock+0x21/0x24
(&sio_locks[i].lock){-.-.}, at: [<c02867fd>] mutex_lock+0x21/0x24
The bit position indicates STATE, STATE-read, for each of the states listed
......
Documentation/misc-devices/ibmvmc.rst
View file @ 1a29e857
.. SPDX-License-Identifier: GPL-2.0+
======================================================
IBM Virtual Management Channel Kernel Driver (IBMVMC)
======================================================
......
Documentation/misc-devices/index.rst 0 → 100644
View file @ 1a29e857
.. SPDX-License-Identifier: GPL-2.0
============================================
Assorted Miscellaneous Devices Documentation
============================================
This documentation contains information for assorted devices that do not
fit into other categories.
.. class:: toc-title
Table of contents
.. toctree::
:maxdepth: 2
ibmvmc
Documentation/networking/checksum-offloads.rst 0 → 100644
View file @ 1a29e857
.. SPDX-License-Identifier: GPL-2.0
=================
Checksum Offloads
=================
Introduction
============
This document describes a set of techniques in the Linux networking stack to
take advantage of checksum offload capabilities of various NICs.
The following technologies are described:
* TX Checksum Offload
* LCO: Local Checksum Offload
* RCO: Remote Checksum Offload
Things that should be documented here but aren't yet:
* RX Checksum Offload
* CHECKSUM_UNNECESSARY conversion
TX Checksum Offload
===================
The interface for offloading a transmit checksum to a device is explained in
detail in comments near the top of include/linux/skbuff.h.
In brief, it allows to request the device fill in a single ones-complement
checksum defined by the sk_buff fields skb->csum_start and skb->csum_offset.
The device should compute the 16-bit ones-complement checksum (i.e. the
'IP-style' checksum) from csum_start to the end of the packet, and fill in the
result at (csum_start + csum_offset).
Because csum_offset cannot be negative, this ensures that the previous value of
the checksum field is included in the checksum computation, thus it can be used
to supply any needed corrections to the checksum (such as the sum of the
pseudo-header for UDP or TCP).
This interface only allows a single checksum to be offloaded. Where
encapsulation is used, the packet may have multiple checksum fields in
different header layers, and the rest will have to be handled by another
mechanism such as LCO or RCO.
CRC32c can also be offloaded using this interface, by means of filling
skb->csum_start and skb->csum_offset as described above, and setting
skb->csum_not_inet: see skbuff.h comment (section 'D') for more details.
No offloading of the IP header checksum is performed; it is always done in
software. This is OK because when we build the IP header, we obviously have it
in cache, so summing it isn't expensive. It's also rather short.
The requirements for GSO are more complicated, because when segmenting an
encapsulated packet both the inner and outer checksums may need to be edited or
recomputed for each resulting segment. See the skbuff.h comment (section 'E')
for more details.
A driver declares its offload capabilities in netdev->hw_features; see
Documentation/networking/netdev-features.txt for more. Note that a device
which only advertises NETIF_F_IP[V6]_CSUM must still obey the csum_start and
csum_offset given in the SKB; if it tries to deduce these itself in hardware
(as some NICs do) the driver should check that the values in the SKB match
those which the hardware will deduce, and if not, fall back to checksumming in
software instead (with skb_csum_hwoffload_help() or one of the
skb_checksum_help() / skb_crc32c_csum_help functions, as mentioned in
include/linux/skbuff.h).
The stack should, for the most part, assume that checksum offload is supported
by the underlying device. The only place that should check is
validate_xmit_skb(), and the functions it calls directly or indirectly. That
function compares the offload features requested by the SKB (which may include
other offloads besides TX Checksum Offload) and, if they are not supported or
enabled on the device (determined by netdev->features), performs the
corresponding offload in software. In the case of TX Checksum Offload, that
means calling skb_csum_hwoffload_help(skb, features).
LCO: Local Checksum Offload
===========================
LCO is a technique for efficiently computing the outer checksum of an
encapsulated datagram when the inner checksum is due to be offloaded.
The ones-complement sum of a correctly checksummed TCP or UDP packet is equal
to the complement of the sum of the pseudo header, because everything else gets
'cancelled out' by the checksum field. This is because the sum was
complemented before being written to the checksum field.
More generally, this holds in any case where the 'IP-style' ones complement
checksum is used, and thus any checksum that TX Checksum Offload supports.
That is, if we have set up TX Checksum Offload with a start/offset pair, we
know that after the device has filled in that checksum, the ones complement sum
from csum_start to the end of the packet will be equal to the complement of
whatever value we put in the checksum field beforehand. This allows us to
compute the outer checksum without looking at the payload: we simply stop
summing when we get to csum_start, then add the complement of the 16-bit word
at (csum_start + csum_offset).
Then, when the true inner checksum is filled in (either by hardware or by
skb_checksum_help()), the outer checksum will become correct by virtue of the
arithmetic.
LCO is performed by the stack when constructing an outer UDP header for an
encapsulation such as VXLAN or GENEVE, in udp_set_csum(). Similarly for the
IPv6 equivalents, in udp6_set_csum().
It is also performed when constructing an IPv4 GRE header, in
net/ipv4/ip_gre.c:build_header(). It is *not* currently performed when
constructing an IPv6 GRE header; the GRE checksum is computed over the whole
packet in net/ipv6/ip6_gre.c:ip6gre_xmit2(), but it should be possible to use
LCO here as IPv6 GRE still uses an IP-style checksum.
All of the LCO implementations use a helper function lco_csum(), in
include/linux/skbuff.h.
LCO can safely be used for nested encapsulations; in this case, the outer
encapsulation layer will sum over both its own header and the 'middle' header.
This does mean that the 'middle' header will get summed multiple times, but
there doesn't seem to be a way to avoid that without incurring bigger costs
(e.g. in SKB bloat).
RCO: Remote Checksum Offload
============================
RCO is a technique for eliding the inner checksum of an encapsulated datagram,
allowing the outer checksum to be offloaded. It does, however, involve a
change to the encapsulation protocols, which the receiver must also support.
For this reason, it is disabled by default.
RCO is detailed in the following Internet-Drafts:
* https://tools.ietf.org/html/draft-herbert-remotecsumoffload-00
* https://tools.ietf.org/html/draft-herbert-vxlan-rco-00
In Linux, RCO is implemented individually in each encapsulation protocol, and
most tunnel types have flags controlling its use. For instance, VXLAN has the
flag VXLAN_F_REMCSUM_TX (per struct vxlan_rdst) to indicate that RCO should be
used when transmitting to a given remote destination.
Documentation/networking/checksum-offloads.txt deleted 100644 → 0
View file @ c4703acd
Checksum Offloads in the Linux Networking Stack
Introduction
============
This document describes a set of techniques in the Linux networking stack
to take advantage of checksum offload capabilities of various NICs.
The following technologies are described:
* TX Checksum Offload
* LCO: Local Checksum Offload
* RCO: Remote Checksum Offload
Things that should be documented here but aren't yet:
* RX Checksum Offload
* CHECKSUM_UNNECESSARY conversion
TX Checksum Offload
===================
The interface for offloading a transmit checksum to a device is explained
in detail in comments near the top of include/linux/skbuff.h.
In brief, it allows to request the device fill in a single ones-complement
checksum defined by the sk_buff fields skb->csum_start and
skb->csum_offset. The device should compute the 16-bit ones-complement
checksum (i.e. the 'IP-style' checksum) from csum_start to the end of the
packet, and fill in the result at (csum_start + csum_offset).
Because csum_offset cannot be negative, this ensures that the previous
value of the checksum field is included in the checksum computation, thus
it can be used to supply any needed corrections to the checksum (such as
the sum of the pseudo-header for UDP or TCP).
This interface only allows a single checksum to be offloaded. Where
encapsulation is used, the packet may have multiple checksum fields in
different header layers, and the rest will have to be handled by another
mechanism such as LCO or RCO.
CRC32c can also be offloaded using this interface, by means of filling
skb->csum_start and skb->csum_offset as described above, and setting
skb->csum_not_inet: see skbuff.h comment (section 'D') for more details.
No offloading of the IP header checksum is performed; it is always done in
software. This is OK because when we build the IP header, we obviously
have it in cache, so summing it isn't expensive. It's also rather short.
The requirements for GSO are more complicated, because when segmenting an
encapsulated packet both the inner and outer checksums may need to be
edited or recomputed for each resulting segment. See the skbuff.h comment
(section 'E') for more details.
A driver declares its offload capabilities in netdev->hw_features; see
Documentation/networking/netdev-features.txt for more. Note that a device
which only advertises NETIF_F_IP[V6]_CSUM must still obey the csum_start
and csum_offset given in the SKB; if it tries to deduce these itself in
hardware (as some NICs do) the driver should check that the values in the
SKB match those which the hardware will deduce, and if not, fall back to
checksumming in software instead (with skb_csum_hwoffload_help() or one of
the skb_checksum_help() / skb_crc32c_csum_help functions, as mentioned in
include/linux/skbuff.h).
The stack should, for the most part, assume that checksum offload is
supported by the underlying device. The only place that should check is
validate_xmit_skb(), and the functions it calls directly or indirectly.
That function compares the offload features requested by the SKB (which
may include other offloads besides TX Checksum Offload) and, if they are
not supported or enabled on the device (determined by netdev->features),
performs the corresponding offload in software. In the case of TX
Checksum Offload, that means calling skb_csum_hwoffload_help(skb, features).
LCO: Local Checksum Offload
===========================
LCO is a technique for efficiently computing the outer checksum of an
encapsulated datagram when the inner checksum is due to be offloaded.
The ones-complement sum of a correctly checksummed TCP or UDP packet is
equal to the complement of the sum of the pseudo header, because everything
else gets 'cancelled out' by the checksum field. This is because the sum was
complemented before being written to the checksum field.
More generally, this holds in any case where the 'IP-style' ones complement
checksum is used, and thus any checksum that TX Checksum Offload supports.
That is, if we have set up TX Checksum Offload with a start/offset pair, we
know that after the device has filled in that checksum, the ones
complement sum from csum_start to the end of the packet will be equal to
the complement of whatever value we put in the checksum field beforehand.
This allows us to compute the outer checksum without looking at the payload:
we simply stop summing when we get to csum_start, then add the complement of
the 16-bit word at (csum_start + csum_offset).
Then, when the true inner checksum is filled in (either by hardware or by
skb_checksum_help()), the outer checksum will become correct by virtue of
the arithmetic.
LCO is performed by the stack when constructing an outer UDP header for an
encapsulation such as VXLAN or GENEVE, in udp_set_csum(). Similarly for
the IPv6 equivalents, in udp6_set_csum().
It is also performed when constructing an IPv4 GRE header, in
net/ipv4/ip_gre.c:build_header(). It is *not* currently performed when
constructing an IPv6 GRE header; the GRE checksum is computed over the
whole packet in net/ipv6/ip6_gre.c:ip6gre_xmit2(), but it should be
possible to use LCO here as IPv6 GRE still uses an IP-style checksum.
All of the LCO implementations use a helper function lco_csum(), in
include/linux/skbuff.h.
LCO can safely be used for nested encapsulations; in this case, the outer
encapsulation layer will sum over both its own header and the 'middle'
header. This does mean that the 'middle' header will get summed multiple
times, but there doesn't seem to be a way to avoid that without incurring
bigger costs (e.g. in SKB bloat).
RCO: Remote Checksum Offload
============================
RCO is a technique for eliding the inner checksum of an encapsulated
datagram, allowing the outer checksum to be offloaded. It does, however,
involve a change to the encapsulation protocols, which the receiver must
also support. For this reason, it is disabled by default.
RCO is detailed in the following Internet-Drafts:
https://tools.ietf.org/html/draft-herbert-remotecsumoffload-00
https://tools.ietf.org/html/draft-herbert-vxlan-rco-00
In Linux, RCO is implemented individually in each encapsulation protocol,
and most tunnel types have flags controlling its use. For instance, VXLAN
has the flag VXLAN_F_REMCSUM_TX (per struct vxlan_rdst) to indicate that
RCO should be used when transmitting to a given remote destination.
Documentation/networking/index.rst
View file @ 1a29e857
......@@ -36,6 +36,9 @@ Contents:
alias
bridge
snmp_counter
checksum-offloads
segmentation-offloads
scaling
.. only:: subproject
......
Documentation/networking/segmentation-offloads.txt → Documentation/networking/segmentation-offloads.rst
View file @ 1a29e857
Segmentation Offloads in the Linux Networking Stack
.. SPDX-License-Identifier: GPL-2.0
=====================
Segmentation Offloads
=====================
Introduction
============
......@@ -15,6 +20,7 @@ The following technologies are described:
* Partial Generic Segmentation Offload - GSO_PARTIAL
* SCTP accelleration with GSO - GSO_BY_FRAGS
TCP Segmentation Offload
========================
......@@ -42,6 +48,7 @@ NETIF_F_TSO_MANGLEID set then the IP ID can be ignored when performing TSO
and we will either increment the IP ID for all frames, or leave it at a
static value based on driver preference.
UDP Fragmentation Offload
=========================
......@@ -54,6 +61,7 @@ UFO is deprecated: modern kernels will no longer generate UFO skbs, but can
still receive them from tuntap and similar devices. Offload of UDP-based
tunnel protocols is still supported.
IPIP, SIT, GRE, UDP Tunnel, and Remote Checksum Offloads
========================================================
......@@ -71,17 +79,19 @@ refer to the tunnel headers as the outer headers, while the encapsulated
data is normally referred to as the inner headers. Below is the list of
calls to access the given headers:
IPIP/SIT Tunnel:
IPIP/SIT Tunnel::
Outer Inner
MAC skb_mac_header
Network skb_network_header skb_inner_network_header
Transport skb_transport_header
MAC skb_mac_header
Network skb_network_header skb_inner_network_header
Transport skb_transport_header
UDP/GRE Tunnel::
UDP/GRE Tunnel:
Outer Inner
MAC skb_mac_header skb_inner_mac_header
Network skb_network_header skb_inner_network_header
Transport skb_transport_header skb_inner_transport_header
MAC skb_mac_header skb_inner_mac_header
Network skb_network_header skb_inner_network_header
Transport skb_transport_header skb_inner_transport_header
In addition to the above tunnel types there are also SKB_GSO_GRE_CSUM and
SKB_GSO_UDP_TUNNEL_CSUM. These two additional tunnel types reflect the
......@@ -93,6 +103,7 @@ header has requested a remote checksum offload. In this case the inner
headers will be left with a partial checksum and only the outer header
checksum will be computed.
Generic Segmentation Offload
============================
......@@ -106,6 +117,7 @@ Before enabling any hardware segmentation offload a corresponding software
offload is required in GSO. Otherwise it becomes possible for a frame to
be re-routed between devices and end up being unable to be transmitted.
Generic Receive Offload
=======================
......@@ -117,6 +129,7 @@ this is IPv4 ID in the case that the DF bit is set for a given IP header.
If the value of the IPv4 ID is not sequentially incrementing it will be
altered so that it is when a frame assembled via GRO is segmented via GSO.
Partial Generic Segmentation Offload
====================================
......@@ -134,6 +147,7 @@ is the outer IPv4 ID field. It is up to the device drivers to guarantee
that the IPv4 ID field is incremented in the case that a given header does
not have the DF bit set.
SCTP accelleration with GSO
===========================
......@@ -157,13 +171,13 @@ appropriately.
There are some helpers to make this easier:
- skb_is_gso(skb) && skb_is_gso_sctp(skb) is the best way to see if
- skb_is_gso(skb) && skb_is_gso_sctp(skb) is the best way to see if
an skb is an SCTP GSO skb.
- For size checks, the skb_gso_validate_*_len family of helpers correctly
- For size checks, the skb_gso_validate_*_len family of helpers correctly
considers GSO_BY_FRAGS.
- For manipulating packets, skb_increase_gso_size and skb_decrease_gso_size
- For manipulating packets, skb_increase_gso_size and skb_decrease_gso_size
will check for GSO_BY_FRAGS and WARN if asked to manipulate these skbs.
This also affects drivers with the NETIF_F_FRAGLIST & NETIF_F_GSO_SCTP bits
......
Documentation/process/coding-style.rst
View file @ 1a29e857
......@@ -443,7 +443,7 @@ In function prototypes, include parameter names with their data types.
Although this is not required by the C language, it is preferred in Linux
because it is a simple way to add valuable information for the reader.
Do not use the `extern' keyword with function prototypes as this makes
Do not use the ``extern`` keyword with function prototypes as this makes
lines longer and isn't strictly necessary.
......@@ -595,26 +595,43 @@ values. To do the latter, you can stick the following in your .emacs file:
(* (max steps 1)
c-basic-offset)))
(add-hook 'c-mode-common-hook
(lambda ()
;; Add kernel style
(c-add-style
"linux-tabs-only"
'("linux" (c-offsets-alist
(arglist-cont-nonempty
c-lineup-gcc-asm-reg
c-lineup-arglist-tabs-only))))))
(add-hook 'c-mode-hook
(lambda ()
(let ((filename (buffer-file-name)))
;; Enable kernel mode for the appropriate files
(when (and filename
(string-match (expand-file-name "~/src/linux-trees")
filename))
(setq indent-tabs-mode t)
(setq show-trailing-whitespace t)
(c-set-style "linux-tabs-only")))))
(dir-locals-set-class-variables
'linux-kernel
'((c-mode . (
(c-basic-offset . 8)
(c-label-minimum-indentation . 0)
(c-offsets-alist . (
(arglist-close . c-lineup-arglist-tabs-only)
(arglist-cont-nonempty .
(c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only))
(arglist-intro . +)
(brace-list-intro . +)
(c . c-lineup-C-comments)
(case-label . 0)
(comment-intro . c-lineup-comment)
(cpp-define-intro . +)
(cpp-macro . -1000)
(cpp-macro-cont . +)
(defun-block-intro . +)
(else-clause . 0)
(func-decl-cont . +)
(inclass . +)
(inher-cont . c-lineup-multi-inher)
(knr-argdecl-intro . 0)
(label . -1000)
(statement . 0)
(statement-block-intro . +)
(statement-case-intro . +)
(statement-cont . +)
(substatement . +)
))
(indent-tabs-mode . t)
(show-trailing-whitespace . t)
))))
(dir-locals-set-directory-class
(expand-file-name "~/src/linux-trees")
'linux-kernel)
This will make emacs go better with the kernel coding style for C
files below ``~/src/linux-trees``.
......@@ -921,7 +938,37 @@ result. Typical examples would be functions that return pointers; they use
NULL or the ERR_PTR mechanism to report failure.
17) Don't re-invent the kernel macros
17) Using bool
--------------
The Linux kernel bool type is an alias for the C99 _Bool type. bool values can
only evaluate to 0 or 1, and implicit or explicit conversion to bool
automatically converts the value to true or false. When using bool types the
!! construction is not needed, which eliminates a class of bugs.
When working with bool values the true and false definitions should be used
instead of 1 and 0.
bool function return types and stack variables are always fine to use whenever
appropriate. Use of bool is encouraged to improve readability and is often a
better option than 'int' for storing boolean values.
Do not use bool if cache line layout or size of the value matters, as its size
and alignment varies based on the compiled architecture. Structures that are
optimized for alignment and size should not use bool.
If a structure has many true/false values, consider consolidating them into a
bitfield with 1 bit members, or using an appropriate fixed width type, such as
u8.
Similarly for function arguments, many true/false values can be consolidated
into a single bitwise 'flags' argument and 'flags' can often be a more
readable alternative if the call-sites have naked true/false constants.
Otherwise limited use of bool in structures and arguments can improve
readability.
18) Don't re-invent the kernel macros
-------------------------------------
The header file include/linux/kernel.h contains a number of macros that
......@@ -944,7 +991,7 @@ need them. Feel free to peruse that header file to see what else is already
defined that you shouldn't reproduce in your code.
18) Editor modelines and other cruft
19) Editor modelines and other cruft
------------------------------------
Some editors can interpret configuration information embedded in source files,
......@@ -978,7 +1025,7 @@ own custom mode, or may have some other magic method for making indentation
work correctly.
19) Inline assembly
20) Inline assembly
-------------------
In architecture-specific code, you may need to use inline assembly to interface
......@@ -1010,7 +1057,7 @@ the next instruction in the assembly output:
: /* outputs */ : /* inputs */ : /* clobbers */);
20) Conditional Compilation
21) Conditional Compilation
---------------------------
Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c
......
Documentation/process/howto.rst
View file @ 1a29e857
......@@ -225,7 +225,7 @@ Cross-Reference project, which is able to present source code in a
self-referential, indexed webpage format. An excellent up-to-date
repository of the kernel code may be found at:
http://lxr.free-electrons.com/
https://elixir.bootlin.com/
The development process
......@@ -235,23 +235,21 @@ Linux kernel development process currently consists of a few different
main kernel "branches" and lots of different subsystem-specific kernel
branches. These different branches are:
- main 4.x kernel tree
- 4.x.y -stable kernel tree
- 4.x -git kernel patches
- subsystem specific kernel trees and patches
- the 4.x -next kernel tree for integration tests
- Linus's mainline tree
- Various stable trees with multiple major numbers
- Subsystem-specific trees
- linux-next integration testing tree
4.x kernel tree
~~~~~~~~~~~~~~~
Mainline tree
~~~~~~~~~~~~~
4.x kernels are maintained by Linus Torvalds, and can be found on
https://kernel.org in the pub/linux/kernel/v4.x/ directory. Its development
process is as follows:
Mainline tree are maintained by Linus Torvalds, and can be found at
https://kernel.org or in the repo. Its development process is as follows:
- As soon as a new kernel is released a two weeks window is open,
during this period of time maintainers can submit big diffs to
Linus, usually the patches that have already been included in the
-next kernel for a few weeks. The preferred way to submit big changes
linux-next for a few weeks. The preferred way to submit big changes
is using git (the kernel's source management tool, more information
can be found at https://git-scm.com/) but plain patches are also just
fine.
......@@ -278,21 +276,19 @@ mailing list about kernel releases:
released according to perceived bug status, not according to a
preconceived timeline."*
4.x.y -stable kernel tree
~~~~~~~~~~~~~~~~~~~~~~~~~
Various stable trees with multiple major numbers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Kernels with 3-part versions are -stable kernels. They contain
relatively small and critical fixes for security problems or significant
regressions discovered in a given 4.x kernel.
regressions discovered in a given major mainline release, with the first
2-part of version number are the same correspondingly.
This is the recommended branch for users who want the most recent stable
kernel and are not interested in helping test development/experimental
versions.
If no 4.x.y kernel is available, then the highest numbered 4.x
kernel is the current stable kernel.
4.x.y are maintained by the "stable" team <stable@vger.kernel.org>, and
Stable trees are maintained by the "stable" team <stable@vger.kernel.org>, and
are released as needs dictate. The normal release period is approximately
two weeks, but it can be longer if there are no pressing problems. A
security-related problem, instead, can cause a release to happen almost
......@@ -302,17 +298,8 @@ The file :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rule
in the kernel tree documents what kinds of changes are acceptable for
the -stable tree, and how the release process works.
4.x -git patches
~~~~~~~~~~~~~~~~
These are daily snapshots of Linus' kernel tree which are managed in a
git repository (hence the name.) These patches are usually released
daily and represent the current state of Linus' tree. They are more
experimental than -rc kernels since they are generated automatically
without even a cursory glance to see if they are sane.
Subsystem Specific kernel trees and patches
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Subsystem-specific trees
~~~~~~~~~~~~~~~~~~~~~~~~
The maintainers of the various kernel subsystems --- and also many
kernel subsystem developers --- expose their current state of
......@@ -336,19 +323,19 @@ revisions to it, and maintainers can mark patches as under review,
accepted, or rejected. Most of these patchwork sites are listed at
https://patchwork.kernel.org/.
4.x -next kernel tree for integration tests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
linux-next integration testing tree
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Before updates from subsystem trees are merged into the mainline 4.x
tree, they need to be integration-tested. For this purpose, a special
Before updates from subsystem trees are merged into the mainline tree,
they need to be integration-tested. For this purpose, a special
testing repository exists into which virtually all subsystem trees are
pulled on an almost daily basis:
https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git
This way, the -next kernel gives a summary outlook onto what will be
This way, the linux-next gives a summary outlook onto what will be
expected to go into the mainline kernel at the next merge period.
Adventurous testers are very welcome to runtime-test the -next kernel.
Adventurous testers are very welcome to runtime-test the linux-next.
Bug Reporting
......
Documentation/process/kernel-docs.rst
View file @ 1a29e857
......@@ -565,7 +565,7 @@ Miscellaneous
* Name: **Cross-Referencing Linux**
:URL: http://lxr.free-electrons.com/
:URL: https://elixir.bootlin.com/
:Keywords: Browsing source code.
:Description: Another web-based Linux kernel source code browser.
Lots of cross references to variables and functions. You can see
......
Documentation/process/license-rules.rst
View file @ 1a29e857
......@@ -62,7 +62,7 @@ License identifier syntax
The SPDX license identifier in kernel files shall be added at the first
possible line in a file which can contain a comment. For the majority
or files this is the first line, except for scripts which require the
of files this is the first line, except for scripts which require the
'#!PATH_TO_INTERPRETER' in the first line. For those scripts the SPDX
identifier goes into the second line.
......@@ -368,7 +368,69 @@ kernel, can be broken down into:
All SPDX license identifiers and exceptions must have a corresponding file
in the LICENSE subdirectories. This is required to allow tool
in the LICENSES subdirectories. This is required to allow tool
verification (e.g. checkpatch.pl) and to have the licenses ready to read
and extract right from the source, which is recommended by various FOSS
organizations, e.g. the `FSFE REUSE initiative <https://reuse.software/>`_.
_`MODULE_LICENSE`
-----------------
Loadable kernel modules also require a MODULE_LICENSE() tag. This tag is
neither a replacement for proper source code license information
(SPDX-License-Identifier) nor in any way relevant for expressing or
determining the exact license under which the source code of the module
is provided.
The sole purpose of this tag is to provide sufficient information
whether the module is free software or proprietary for the kernel
module loader and for user space tools.
The valid license strings for MODULE_LICENSE() are:
============================= =============================================
"GPL" Module is licensed under GPL version 2. This
does not express any distinction between
GPL-2.0-only or GPL-2.0-or-later. The exact
license information can only be determined
via the license information in the
corresponding source files.
"GPL v2" Same as "GPL". It exists for historic
reasons.
"GPL and additional rights" Historical variant of expressing that the
module source is dual licensed under a
GPL v2 variant and MIT license. Please do
not use in new code.
"Dual MIT/GPL" The correct way of expressing that the
module is dual licensed under a GPL v2
variant or MIT license choice.
"Dual BSD/GPL" The module is dual licensed under a GPL v2
variant or BSD license choice. The exact
variant of the BSD license can only be
determined via the license information
in the corresponding source files.
"Dual MPL/GPL" The module is dual licensed under a GPL v2
variant or Mozilla Public License (MPL)
choice. The exact variant of the MPL
license can only be determined via the
license information in the corresponding
source files.
"Proprietary" The module is under a proprietary license.
This string is solely for proprietary third
party modules and cannot be used for modules
which have their source code in the kernel
tree. Modules tagged that way are tainting
the kernel with the 'P' flag when loaded and
the kernel module loader refuses to link such
modules against symbols which are exported
with EXPORT_SYMBOL_GPL().
============================= =============================================
Documentation/process/stable-api-nonsense.rst
View file @ 1a29e857
......@@ -169,14 +169,13 @@ driver for every different kernel version for every distribution is a
nightmare, and trying to keep up with an ever changing kernel interface
is also a rough job.
Simple, get your kernel driver into the main kernel tree (remember we
are talking about GPL released drivers here, if your code doesn't fall
under this category, good luck, you are on your own here, you leech
<insert link to leech comment from Andrew and Linus here>.) If your
driver is in the tree, and a kernel interface changes, it will be fixed
up by the person who did the kernel change in the first place. This
ensures that your driver is always buildable, and works over time, with
very little effort on your part.
Simple, get your kernel driver into the main kernel tree (remember we are
talking about drivers released under a GPL-compatible license here, if your
code doesn't fall under this category, good luck, you are on your own here,
you leech). If your driver is in the tree, and a kernel interface changes,
it will be fixed up by the person who did the kernel change in the first
place. This ensures that your driver is always buildable, and works over
time, with very little effort on your part.
The very good side effects of having your driver in the main kernel tree
are:
......
Documentation/process/stable-kernel-rules.rst
View file @ 1a29e857
......@@ -38,6 +38,9 @@ Procedure for submitting patches to the -stable tree
- If the patch covers files in net/ or drivers/net please follow netdev stable
submission guidelines as described in
:ref:`Documentation/networking/netdev-FAQ.rst <netdev-FAQ>`
after first checking the stable networking queue at
https://patchwork.ozlabs.org/bundle/davem/stable/?series=&submitter=&state=*&q=&archive=
to ensure the requested patch is not already queued up.
- Security patches should not be handled (solely) by the -stable review
process but should follow the procedures in
:ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>`.
......@@ -98,9 +101,9 @@ text, like this:
commit <sha1> upstream.
Additionally, some patches submitted via Option 1 may have additional patch
prerequisites which can be cherry-picked. This can be specified in the following
format in the sign-off area:
Additionally, some patches submitted via :ref:`option_1` may have additional
patch prerequisites which can be cherry-picked. This can be specified in the
following format in the sign-off area:
.. code-block:: none
......
Documentation/process/submitting-patches.rst
View file @ 1a29e857
......@@ -182,9 +182,11 @@ change five years from now.
If your patch fixes a bug in a specific commit, e.g. you found an issue using
``git bisect``, please use the 'Fixes:' tag with the first 12 characters of
the SHA-1 ID, and the one line summary. For example::
the SHA-1 ID, and the one line summary. Do not split the tag across multiple
lines, tags are exempt from the "wrap at 75 columns" rule in order to simplify
parsing scripts. For example::
Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()")
Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed")
The following ``git config`` settings can be used to add a pretty format for
outputting the above style in the ``git log`` or ``git show`` commands::
......
Documentation/security/LSM.rst
View file @ 1a29e857
......@@ -11,4 +11,7 @@ that end users and distros can make a more informed decision about which
LSMs suit their requirements.
For extensive documentation on the available LSM hook interfaces, please
see ``include/linux/lsm_hooks.h``.
see ``include/linux/lsm_hooks.h`` and associated structures:
.. kernel-doc:: include/linux/lsm_hooks.h
:internal:
Documentation/security/LSM-sctp.rst → Documentation/security/SCTP.rst
View file @ 1a29e857
.. SPDX-License-Identifier: GPL-2.0
====
SCTP
====
SCTP LSM Support
================
Security Hooks
--------------
For security module support, three SCTP specific hooks have been implemented::
security_sctp_assoc_request()
......@@ -12,11 +21,11 @@ Also the following security hook has been utilised::
security_inet_conn_established()
The usage of these hooks are described below with the SELinux implementation
described in ``Documentation/security/SELinux-sctp.rst``
described in the `SCTP SELinux Support`_ chapter.
security_sctp_assoc_request()
-----------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Passes the ``@ep`` and ``@chunk->skb`` of the association INIT packet to the
security module. Returns 0 on success, error on failure.
::
......@@ -26,7 +35,7 @@ security module. Returns 0 on success, error on failure.
security_sctp_bind_connect()
-----------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Passes one or more ipv4/ipv6 addresses to the security module for validation
based on the ``@optname`` that will result in either a bind or connect
service as shown in the permission check tables below.
......@@ -102,7 +111,7 @@ ASCONF chunk when the corresponding ``@optname``'s are present::
security_sctp_sk_clone()
-------------------------
~~~~~~~~~~~~~~~~~~~~~~~~
Called whenever a new socket is created by **accept**\(2)
(i.e. a TCP style socket) or when a socket is 'peeled off' e.g userspace
calls **sctp_peeloff**\(3).
......@@ -114,7 +123,7 @@ calls **sctp_peeloff**\(3).
security_inet_conn_established()
---------------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Called when a COOKIE ACK is received::
@sk - pointer to sock structure.
......@@ -122,7 +131,8 @@ Called when a COOKIE ACK is received::
Security Hooks used for Association Establishment
=================================================
-------------------------------------------------
The following diagram shows the use of ``security_sctp_bind_connect()``,
``security_sctp_assoc_request()``, ``security_inet_conn_established()`` when
establishing an association.
......@@ -173,3 +183,161 @@ establishing an association.
------------------------------------------------------------------
SCTP SELinux Support
====================
Security Hooks
--------------
The `SCTP LSM Support`_ chapter above describes the following SCTP security
hooks with the SELinux specifics expanded below::
security_sctp_assoc_request()
security_sctp_bind_connect()
security_sctp_sk_clone()
security_inet_conn_established()
security_sctp_assoc_request()
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Passes the ``@ep`` and ``@chunk->skb`` of the association INIT packet to the
security module. Returns 0 on success, error on failure.
::
@ep - pointer to sctp endpoint structure.
@skb - pointer to skbuff of association packet.
The security module performs the following operations:
IF this is the first association on ``@ep->base.sk``, then set the peer
sid to that in ``@skb``. This will ensure there is only one peer sid
assigned to ``@ep->base.sk`` that may support multiple associations.
ELSE validate the ``@ep->base.sk peer_sid`` against the ``@skb peer sid``
to determine whether the association should be allowed or denied.
Set the sctp ``@ep sid`` to socket's sid (from ``ep->base.sk``) with
MLS portion taken from ``@skb peer sid``. This will be used by SCTP
TCP style sockets and peeled off connections as they cause a new socket
to be generated.
If IP security options are configured (CIPSO/CALIPSO), then the ip
options are set on the socket.
security_sctp_bind_connect()
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Checks permissions required for ipv4/ipv6 addresses based on the ``@optname``
as follows::
------------------------------------------------------------------
| BIND Permission Checks |
| @optname | @address contains |
|----------------------------|-----------------------------------|
| SCTP_SOCKOPT_BINDX_ADD | One or more ipv4 / ipv6 addresses |
| SCTP_PRIMARY_ADDR | Single ipv4 or ipv6 address |
| SCTP_SET_PEER_PRIMARY_ADDR | Single ipv4 or ipv6 address |
------------------------------------------------------------------
------------------------------------------------------------------
| CONNECT Permission Checks |
| @optname | @address contains |
|----------------------------|-----------------------------------|
| SCTP_SOCKOPT_CONNECTX | One or more ipv4 / ipv6 addresses |
| SCTP_PARAM_ADD_IP | One or more ipv4 / ipv6 addresses |
| SCTP_SENDMSG_CONNECT | Single ipv4 or ipv6 address |
| SCTP_PARAM_SET_PRIMARY | Single ipv4 or ipv6 address |
------------------------------------------------------------------
`SCTP LSM Support`_ gives a summary of the ``@optname``
entries and also describes ASCONF chunk processing when Dynamic Address
Reconfiguration is enabled.
security_sctp_sk_clone()
~~~~~~~~~~~~~~~~~~~~~~~~
Called whenever a new socket is created by **accept**\(2) (i.e. a TCP style
socket) or when a socket is 'peeled off' e.g userspace calls
**sctp_peeloff**\(3). ``security_sctp_sk_clone()`` will set the new
sockets sid and peer sid to that contained in the ``@ep sid`` and
``@ep peer sid`` respectively.
::
@ep - pointer to current sctp endpoint structure.
@sk - pointer to current sock structure.
@sk - pointer to new sock structure.
security_inet_conn_established()
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Called when a COOKIE ACK is received where it sets the connection's peer sid
to that in ``@skb``::
@sk - pointer to sock structure.
@skb - pointer to skbuff of the COOKIE ACK packet.
Policy Statements
-----------------
The following class and permissions to support SCTP are available within the
kernel::
class sctp_socket inherits socket { node_bind }
whenever the following policy capability is enabled::
policycap extended_socket_class;
SELinux SCTP support adds the ``name_connect`` permission for connecting
to a specific port type and the ``association`` permission that is explained
in the section below.
If userspace tools have been updated, SCTP will support the ``portcon``
statement as shown in the following example::
portcon sctp 1024-1036 system_u:object_r:sctp_ports_t:s0
SCTP Peer Labeling
------------------
An SCTP socket will only have one peer label assigned to it. This will be
assigned during the establishment of the first association. Any further
associations on this socket will have their packet peer label compared to
the sockets peer label, and only if they are different will the
``association`` permission be validated. This is validated by checking the
socket peer sid against the received packets peer sid to determine whether
the association should be allowed or denied.
NOTES:
1) If peer labeling is not enabled, then the peer context will always be
``SECINITSID_UNLABELED`` (``unlabeled_t`` in Reference Policy).
2) As SCTP can support more than one transport address per endpoint
(multi-homing) on a single socket, it is possible to configure policy
and NetLabel to provide different peer labels for each of these. As the
socket peer label is determined by the first associations transport
address, it is recommended that all peer labels are consistent.
3) **getpeercon**\(3) may be used by userspace to retrieve the sockets peer
context.
4) While not SCTP specific, be aware when using NetLabel that if a label
is assigned to a specific interface, and that interface 'goes down',
then the NetLabel service will remove the entry. Therefore ensure that
the network startup scripts call **netlabelctl**\(8) to set the required
label (see **netlabel-config**\(8) helper script for details).
5) The NetLabel SCTP peer labeling rules apply as discussed in the following
set of posts tagged "netlabel" at: http://www.paul-moore.com/blog/t.
6) CIPSO is only supported for IPv4 addressing: ``socket(AF_INET, ...)``
CALIPSO is only supported for IPv6 addressing: ``socket(AF_INET6, ...)``
Note the following when testing CIPSO/CALIPSO:
a) CIPSO will send an ICMP packet if an SCTP packet cannot be
delivered because of an invalid label.
b) CALIPSO does not send an ICMP packet, just silently discards it.
7) IPSEC is not supported as RFC 3554 - sctp/ipsec support has not been
implemented in userspace (**racoon**\(8) or **ipsec_pluto**\(8)),
although the kernel supports SCTP/IPSEC.
Documentation/security/SELinux-sctp.rst deleted 100644 → 0
View file @ c4703acd
SCTP SELinux Support
=====================
Security Hooks
===============
``Documentation/security/LSM-sctp.rst`` describes the following SCTP security
hooks with the SELinux specifics expanded below::
security_sctp_assoc_request()
security_sctp_bind_connect()
security_sctp_sk_clone()
security_inet_conn_established()
security_sctp_assoc_request()
-----------------------------
Passes the ``@ep`` and ``@chunk->skb`` of the association INIT packet to the
security module. Returns 0 on success, error on failure.
::
@ep - pointer to sctp endpoint structure.
@skb - pointer to skbuff of association packet.
The security module performs the following operations:
IF this is the first association on ``@ep->base.sk``, then set the peer
sid to that in ``@skb``. This will ensure there is only one peer sid
assigned to ``@ep->base.sk`` that may support multiple associations.
ELSE validate the ``@ep->base.sk peer_sid`` against the ``@skb peer sid``
to determine whether the association should be allowed or denied.
Set the sctp ``@ep sid`` to socket's sid (from ``ep->base.sk``) with
MLS portion taken from ``@skb peer sid``. This will be used by SCTP
TCP style sockets and peeled off connections as they cause a new socket
to be generated.
If IP security options are configured (CIPSO/CALIPSO), then the ip
options are set on the socket.
security_sctp_bind_connect()
-----------------------------
Checks permissions required for ipv4/ipv6 addresses based on the ``@optname``
as follows::
------------------------------------------------------------------
| BIND Permission Checks |
| @optname | @address contains |
|----------------------------|-----------------------------------|
| SCTP_SOCKOPT_BINDX_ADD | One or more ipv4 / ipv6 addresses |
| SCTP_PRIMARY_ADDR | Single ipv4 or ipv6 address |
| SCTP_SET_PEER_PRIMARY_ADDR | Single ipv4 or ipv6 address |
------------------------------------------------------------------
------------------------------------------------------------------
| CONNECT Permission Checks |
| @optname | @address contains |
|----------------------------|-----------------------------------|
| SCTP_SOCKOPT_CONNECTX | One or more ipv4 / ipv6 addresses |
| SCTP_PARAM_ADD_IP | One or more ipv4 / ipv6 addresses |
| SCTP_SENDMSG_CONNECT | Single ipv4 or ipv6 address |
| SCTP_PARAM_SET_PRIMARY | Single ipv4 or ipv6 address |
------------------------------------------------------------------
``Documentation/security/LSM-sctp.rst`` gives a summary of the ``@optname``
entries and also describes ASCONF chunk processing when Dynamic Address
Reconfiguration is enabled.
security_sctp_sk_clone()
-------------------------
Called whenever a new socket is created by **accept**\(2) (i.e. a TCP style
socket) or when a socket is 'peeled off' e.g userspace calls
**sctp_peeloff**\(3). ``security_sctp_sk_clone()`` will set the new
sockets sid and peer sid to that contained in the ``@ep sid`` and
``@ep peer sid`` respectively.
::
@ep - pointer to current sctp endpoint structure.
@sk - pointer to current sock structure.
@sk - pointer to new sock structure.
security_inet_conn_established()
---------------------------------
Called when a COOKIE ACK is received where it sets the connection's peer sid
to that in ``@skb``::
@sk - pointer to sock structure.
@skb - pointer to skbuff of the COOKIE ACK packet.
Policy Statements
==================
The following class and permissions to support SCTP are available within the
kernel::
class sctp_socket inherits socket { node_bind }
whenever the following policy capability is enabled::
policycap extended_socket_class;
SELinux SCTP support adds the ``name_connect`` permission for connecting
to a specific port type and the ``association`` permission that is explained
in the section below.
If userspace tools have been updated, SCTP will support the ``portcon``
statement as shown in the following example::
portcon sctp 1024-1036 system_u:object_r:sctp_ports_t:s0
SCTP Peer Labeling
===================
An SCTP socket will only have one peer label assigned to it. This will be
assigned during the establishment of the first association. Any further
associations on this socket will have their packet peer label compared to
the sockets peer label, and only if they are different will the
``association`` permission be validated. This is validated by checking the
socket peer sid against the received packets peer sid to determine whether
the association should be allowed or denied.
NOTES:
1) If peer labeling is not enabled, then the peer context will always be
``SECINITSID_UNLABELED`` (``unlabeled_t`` in Reference Policy).
2) As SCTP can support more than one transport address per endpoint
(multi-homing) on a single socket, it is possible to configure policy
and NetLabel to provide different peer labels for each of these. As the
socket peer label is determined by the first associations transport
address, it is recommended that all peer labels are consistent.
3) **getpeercon**\(3) may be used by userspace to retrieve the sockets peer
context.
4) While not SCTP specific, be aware when using NetLabel that if a label
is assigned to a specific interface, and that interface 'goes down',
then the NetLabel service will remove the entry. Therefore ensure that
the network startup scripts call **netlabelctl**\(8) to set the required
label (see **netlabel-config**\(8) helper script for details).
5) The NetLabel SCTP peer labeling rules apply as discussed in the following
set of posts tagged "netlabel" at: http://www.paul-moore.com/blog/t.
6) CIPSO is only supported for IPv4 addressing: ``socket(AF_INET, ...)``
CALIPSO is only supported for IPv6 addressing: ``socket(AF_INET6, ...)``
Note the following when testing CIPSO/CALIPSO:
a) CIPSO will send an ICMP packet if an SCTP packet cannot be
delivered because of an invalid label.
b) CALIPSO does not send an ICMP packet, just silently discards it.
7) IPSEC is not supported as RFC 3554 - sctp/ipsec support has not been
implemented in userspace (**racoon**\(8) or **ipsec_pluto**\(8)),
although the kernel supports SCTP/IPSEC.
Documentation/security/index.rst
View file @ 1a29e857
......@@ -9,7 +9,6 @@ Security Documentation
IMA-templates
keys/index
LSM
LSM-sctp
SELinux-sctp
SCTP
self-protection
tpm/index
Documentation/static-keys.txt
View file @ 1a29e857
......@@ -159,7 +159,7 @@ particularly the CPU hotplug lock (in order to avoid races against
CPUs being brought in the kernel while the kernel is getting
patched). Calling the static key API from within a hotplug notifier is
thus a sure deadlock recipe. In order to still allow use of the
functionnality, the following functions are provided:
functionality, the following functions are provided:
static_key_enable_cpuslocked()
static_key_disable_cpuslocked()
......
Documentation/sysctl/kernel.txt
View file @ 1a29e857
......@@ -95,7 +95,7 @@ show up in /proc/sys/kernel:
- stop-a [ SPARC only ]
- sysrq ==> Documentation/admin-guide/sysrq.rst
- sysctl_writes_strict
- tainted
- tainted ==> Documentation/admin-guide/tainted-kernels.rst
- threads-max
- unknown_nmi_panic
- watchdog
......@@ -1031,39 +1031,33 @@ compilation sees a 1% slowdown, other systems and workloads may vary.
1: kernel stack erasing is enabled (default), it is performed before
returning to the userspace at the end of syscalls.
==============================================================
tainted:
tainted
Non-zero if the kernel has been tainted. Numeric values, which can be
ORed together. The letters are seen in "Tainted" line of Oops reports.
1 (P): A module with a non-GPL license has been loaded, this
includes modules with no license.
Set by modutils >= 2.4.9 and module-init-tools.
2 (F): A module was force loaded by insmod -f.
Set by modutils >= 2.4.9 and module-init-tools.
4 (S): Unsafe SMP processors: SMP with CPUs not designed for SMP.
8 (R): A module was forcibly unloaded from the system by rmmod -f.
16 (M): A hardware machine check error occurred on the system.
32 (B): A bad page was discovered on the system.
64 (U): The user has asked that the system be marked "tainted". This
could be because they are running software that directly modifies
the hardware, or for other reasons.
128 (D): The system has died.
256 (A): The ACPI DSDT has been overridden with one supplied by the user
instead of using the one provided by the hardware.
512 (W): A kernel warning has occurred.
1024 (C): A module from drivers/staging was loaded.
2048 (I): The system is working around a severe firmware bug.
4096 (O): An out-of-tree module has been loaded.
8192 (E): An unsigned module has been loaded in a kernel supporting module
signature.
16384 (L): A soft lockup has previously occurred on the system.
32768 (K): The kernel has been live patched.
65536 (X): Auxiliary taint, defined and used by for distros.
131072 (T): The kernel was built with the struct randomization plugin.
1 (P): proprietary module was loaded
2 (F): module was force loaded
4 (S): SMP kernel oops on an officially SMP incapable processor
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
64 (U): taint requested by userspace application
128 (D): kernel died recently, i.e. there was an OOPS or BUG
256 (A): an ACPI table was overridden by user
512 (W): kernel issued warning
1024 (C): staging driver was loaded
2048 (I): workaround for bug in platform firmware applied
4096 (O): externally-built ("out-of-tree") module was loaded
8192 (E): unsigned module was loaded
16384 (L): soft lockup occurred
32768 (K): kernel has been live patched
65536 (X): Auxiliary taint, defined and used by for distros
131072 (T): The kernel was built with the struct randomization plugin
See Documentation/admin-guide/tainted-kernels.rst for more information.
==============================================================
......
Documentation/sysctl/vm.txt
View file @ 1a29e857
......@@ -237,7 +237,7 @@ used:
cat (1234): drop_caches: 3
These are informational only. They do not mean that anything is wrong
with your system. To disable them, echo 4 (bit 3) into drop_caches.
with your system. To disable them, echo 4 (bit 2) into drop_caches.
==============================================================
......
Documentation/timers/highres.txt
View file @ 1a29e857
......@@ -231,7 +231,7 @@ in the idle period to make sure that jiffies are up to date and the interrupt
handler has not to deal with an eventually stale jiffy value.
The dynamic tick feature provides statistical values which are exported to
userspace via /proc/stats and can be made available for enhanced power
userspace via /proc/stat and can be made available for enhanced power
management control.
The implementation leaves room for further development like full tickless
......
Documentation/translations/it_IT/doc-guide/sphinx.rst
View file @ 1a29e857
......@@ -3,6 +3,8 @@
.. note:: Per leggere la documentazione originale in inglese:
:ref:`Documentation/doc-guide/index.rst <doc_guide>`
.. _it_sphinxdoc:
Introduzione
============
......
Documentation/translations/it_IT/process/applying-patches.rst
View file @ 1a29e857
.. include:: ../disclaimer-ita.rst
:Original: :ref:`Documentation/process/applying-patches.rst <applying_patches>`
:Translator: Federico Vaga <federico.vaga@vaga.pv.it>
.. _it_applying_patches:
Applicare modifiche al kernel Linux
===================================
Applicare patch al kernel Linux
+++++++++++++++++++++++++++++++
.. warning::
.. note::
TODO ancora da tradurre
Questo documento è obsoleto. Nella maggior parte dei casi, piuttosto
che usare ``patch`` manualmente, vorrete usare Git. Per questo motivo
il documento non verrà tradotto.
Documentation/translations/it_IT/process/coding-style.rst
View file @ 1a29e857
......@@ -449,6 +449,9 @@ Nonostante questo non sia richiesto dal linguaggio C, in Linux viene preferito
perché è un modo semplice per aggiungere informazioni importanti per il
lettore.
Non usate la parola chiave ``extern`` coi prototipi di funzione perché
rende le righe più lunghe e non è strettamente necessario.
7) Centralizzare il ritorno delle funzioni
------------------------------------------
......@@ -600,26 +603,43 @@ segue nel vostro file .emacs:
(* (max steps 1)
c-basic-offset)))
(add-hook 'c-mode-common-hook
(lambda ()
;; Add kernel style
(c-add-style
"linux-tabs-only"
'("linux" (c-offsets-alist
(arglist-cont-nonempty
c-lineup-gcc-asm-reg
c-lineup-arglist-tabs-only))))))
(add-hook 'c-mode-hook
(lambda ()
(let ((filename (buffer-file-name)))
;; Enable kernel mode for the appropriate files
(when (and filename
(string-match (expand-file-name "~/src/linux-trees")
filename))
(setq indent-tabs-mode t)
(setq show-trailing-whitespace t)
(c-set-style "linux-tabs-only")))))
(dir-locals-set-class-variables
'linux-kernel
'((c-mode . (
(c-basic-offset . 8)
(c-label-minimum-indentation . 0)
(c-offsets-alist . (
(arglist-close . c-lineup-arglist-tabs-only)
(arglist-cont-nonempty .
(c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only))
(arglist-intro . +)
(brace-list-intro . +)
(c . c-lineup-C-comments)
(case-label . 0)
(comment-intro . c-lineup-comment)
(cpp-define-intro . +)
(cpp-macro . -1000)
(cpp-macro-cont . +)
(defun-block-intro . +)
(else-clause . 0)
(func-decl-cont . +)
(inclass . +)
(inher-cont . c-lineup-multi-inher)
(knr-argdecl-intro . 0)
(label . -1000)
(statement . 0)
(statement-block-intro . +)
(statement-case-intro . +)
(statement-cont . +)
(substatement . +)
))
(indent-tabs-mode . t)
(show-trailing-whitespace . t)
))))
(dir-locals-set-directory-class
(expand-file-name "~/src/linux-trees")
'linux-kernel)
Questo farà funzionare meglio emacs con lo stile del kernel per i file che
si trovano nella cartella ``~/src/linux-trees``.
......@@ -929,7 +949,40 @@ qualche valore fuori dai limiti. Un tipico esempio è quello delle funzioni
che ritornano un puntatore; queste utilizzano NULL o ERR_PTR come meccanismo
di notifica degli errori.
17) Non reinventate le macro del kernel
17) L'uso di bool
-----------------
Nel kernel Linux il tipo bool deriva dal tipo _Bool dello standard C99.
Un valore bool può assumere solo i valori 0 o 1, e implicitamente o
esplicitamente la conversione a bool converte i valori in vero (*true*) o
falso (*false*). Quando si usa un tipo bool il costrutto !! non sarà più
necessario, e questo va ad eliminare una certa serie di bachi.
Quando si usano i valori booleani, dovreste utilizzare le definizioni di true
e false al posto dei valori 1 e 0.
Per il valore di ritorno delle funzioni e per le variabili sullo stack, l'uso
del tipo bool è sempre appropriato. L'uso di bool viene incoraggiato per
migliorare la leggibilità e spesso è molto meglio di 'int' nella gestione di
valori booleani.
Non usate bool se per voi sono importanti l'ordine delle righe di cache o
la loro dimensione; la dimensione e l'allineamento cambia a seconda
dell'architettura per la quale è stato compilato. Le strutture che sono state
ottimizzate per l'allineamento o la dimensione non dovrebbero usare bool.
Se una struttura ha molti valori true/false, considerate l'idea di raggrupparli
in un intero usando campi da 1 bit, oppure usate un tipo dalla larghezza fissa,
come u8.
Come per gli argomenti delle funzioni, molti valori true/false possono essere
raggruppati in un singolo argomento a bit denominato 'flags'; spesso 'flags' è
un'alternativa molto più leggibile se si hanno valori costanti per true/false.
Detto ciò, un uso parsimonioso di bool nelle strutture dati e negli argomenti
può migliorare la leggibilità.
18) Non reinventate le macro del kernel
---------------------------------------
Il file di intestazione include/linux/kernel.h contiene un certo numero
......@@ -953,7 +1006,7 @@ rigido sui tipi. Sentitevi liberi di leggere attentamente questo file
d'intestazione per scoprire cos'altro è stato definito che non dovreste
reinventare nel vostro codice.
18) Linee di configurazione degli editor e altre schifezze
19) Linee di configurazione degli editor e altre schifezze
-----------------------------------------------------------
Alcuni editor possono interpretare dei parametri di configurazione integrati
......@@ -987,8 +1040,8 @@ d'indentazione e di modalità d'uso. Le persone potrebbero aver configurato una
modalità su misura, oppure potrebbero avere qualche altra magia per far
funzionare bene l'indentazione.
19) Inline assembly
---------------------
20) Inline assembly
-------------------
Nel codice specifico per un'architettura, potreste aver bisogno di codice
*inline assembly* per interfacciarvi col processore o con una funzionalità
......@@ -1020,7 +1073,7 @@ al fine di allineare correttamente l'assembler che verrà generato:
"more_magic %reg2, %reg3"
: /* outputs */ : /* inputs */ : /* clobbers */);
20) Compilazione sotto condizione
21) Compilazione sotto condizione
---------------------------------
Ovunque sia possibile, non usate le direttive condizionali del preprocessore
......
Documentation/translations/it_IT/process/howto.rst
View file @ 1a29e857
......@@ -234,7 +234,7 @@ il progetto Linux Cross-Reference, che è in grado di presentare codice
sorgente in un formato autoreferenziale ed indicizzato. Un eccellente ed
aggiornata fonte di consultazione del codice del kernel la potete trovare qui:
http://lxr.free-electrons.com/
https://elixir.bootlin.com/
Il processo di sviluppo
......@@ -244,7 +244,6 @@ e di molti altri rami per specifici sottosistemi. Questi rami sono:
- I sorgenti kernel 4.x
- I sorgenti stabili del kernel 4.x.y -stable
- Le modifiche in 4.x -git
- Sorgenti dei sottosistemi del kernel e le loro modifiche
- Il kernel 4.x -next per test d'integrazione
......@@ -313,16 +312,6 @@ Il file Documentation/process/stable-kernel-rules.rst (nei sorgenti) documenta
quali tipologie di modifiche sono accettate per i sorgenti -stable, e come
avviene il processo di rilascio.
Le modifiche in 4.x -git
~~~~~~~~~~~~~~~~~~~~~~~~
Queste sono istantanee quotidiane del kernel di Linus e sono gestite in
una repositorio git (da qui il nome). Queste modifiche sono solitamente
rilasciate giornalmente e rappresentano l'attuale stato dei sorgenti di
Linus. Queste sono da considerarsi più sperimentali di un -rc in quanto
generate automaticamente senza nemmeno aver dato una rapida occhiata
per verificarne lo stato.
Sorgenti dei sottosistemi del kernel e le loro patch
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
......
Documentation/translations/it_IT/process/submit-checklist.rst
View file @ 1a29e857
.. include:: ../disclaimer-ita.rst
:Original: :ref:`Documentation/process/submit-checklist.rst <submitchecklist>`
:Translator: Federico Vaga <federico.vaga@vaga.pv.it>
.. _it_submitchecklist:
Lista delle cose da fare per inviare una modifica al kernel Linux
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Lista delle verifiche da fare prima di inviare una patch per il kernel Linux
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. warning::
Qui troverete una lista di cose che uno sviluppatore dovrebbe fare per
vedere le proprie patch accettate più rapidamente.
TODO ancora da tradurre
Tutti questi punti integrano la documentazione fornita riguardo alla
sottomissione delle patch, in particolare
:ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.
1) Se state usando delle funzionalità del kernel allora includete (#include)
i file che le dichiarano/definiscono. Non dipendente dal fatto che un file
d'intestazione include anche quelli usati da voi.
2) Compilazione pulita:
a) con le opzioni ``CONFIG`` negli stati ``=y``, ``=m`` e ``=n``. Nessun
avviso/errore di ``gcc`` e nessun avviso/errore dal linker.
b) con ``allnoconfig``, ``allmodconfig``
c) quando si usa ``O=builddir``
3) Compilare per diverse architetture di processore usando strumenti per
la cross-compilazione o altri.
4) Una buona architettura per la verifica della cross-compilazione è la ppc64
perché tende ad usare ``unsigned long`` per le quantità a 64-bit.
5) Controllate lo stile del codice della vostra patch secondo le direttive
scritte in :ref:`Documentation/translations/it_IT/process/coding-style.rst <it_codingstyle>`.
Prima dell'invio della patch, usate il verificatore di stile
(``script/checkpatch.pl``) per scovare le violazioni più semplici.
Dovreste essere in grado di giustificare tutte le violazioni rimanenti nella
vostra patch.
6) Le opzioni ``CONFIG``, nuove o modificate, non scombussolano il menu
di configurazione e sono preimpostate come disabilitate a meno che non
soddisfino i criteri descritti in ``Documentation/kbuild/kconfig-language.txt``
alla punto "Voci di menu: valori predefiniti".
7) Tutte le nuove opzioni ``Kconfig`` hanno un messaggio di aiuto.
8) La patch è stata accuratamente revisionata rispetto alle più importanti
configurazioni ``Kconfig``. Questo è molto difficile da fare
correttamente - un buono lavoro di testa sarà utile.
9) Verificare con sparse.
10) Usare ``make checkstack`` e ``make namespacecheck`` e correggere tutti i
problemi rilevati.
.. note::
``checkstack`` non evidenzia esplicitamente i problemi, ma una funzione
che usa più di 512 byte sullo stack è una buona candidata per una
correzione.
11) Includete commenti :ref:`kernel-doc <kernel_doc>` per documentare API
globali del kernel. Usate ``make htmldocs`` o ``make pdfdocs`` per
verificare i commenti :ref:`kernel-doc <kernel_doc>` ed eventualmente
correggerli.
12) La patch è stata verificata con le seguenti opzioni abilitate
contemporaneamente: ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``,
``CONFIG_DEBUG_SLAB``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``,
``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``,
``CONFIG_PROVE_RCU`` e ``CONFIG_DEBUG_OBJECTS_RCU_HEAD``.
13) La patch è stata compilata e verificata in esecuzione con, e senza,
le opzioni ``CONFIG_SMP`` e ``CONFIG_PREEMPT``.
14) Se la patch ha effetti sull'IO dei dischi, eccetera: allora dev'essere
verificata con, e senza, l'opzione ``CONFIG_LBDAF``.
15) Tutti i percorsi del codice sono stati verificati con tutte le funzionalità
di lockdep abilitate.
16) Tutti i nuovi elementi in ``/proc`` sono documentati in ``Documentation/``.
17) Tutti i nuovi parametri d'avvio del kernel sono documentati in
``Documentation/admin-guide/kernel-parameters.rst``.
18) Tutti i nuovi parametri dei moduli sono documentati con ``MODULE_PARM_DESC()``.
19) Tutte le nuove interfacce verso lo spazio utente sono documentate in
``Documentation/ABI/``. Leggete ``Documentation/ABI/README`` per maggiori
informazioni. Le patch che modificano le interfacce utente dovrebbero
essere inviate in copia anche a linux-api@vger.kernel.org.
20) Verifica che il kernel passi con successo ``make headers_check``
21) La patch è stata verificata con l'iniezione di fallimenti in slab e
nell'allocazione di pagine. Vedere ``Documentation/fault-injection/``.
Se il nuovo codice è corposo, potrebbe essere opportuno aggiungere
l'iniezione di fallimenti specifici per il sottosistema.
22) Il nuovo codice è stato compilato con ``gcc -W`` (usate
``make EXTRA_CFLAGS=-W``). Questo genererà molti avvisi, ma è ottimo
per scovare bachi come "warning: comparison between signed and unsigned".
23) La patch è stata verificata dopo essere stata inclusa nella serie di patch
-mm; questo al fine di assicurarsi che continui a funzionare assieme a
tutte le altre patch in coda e i vari cambiamenti nei sottosistemi VM, VFS
e altri.
24) Tutte le barriere di sincronizzazione {per esempio, ``barrier()``,
``rmb()``, ``wmb()``} devono essere accompagnate da un commento nei
sorgenti che ne spieghi la logica: cosa fanno e perché.
25) Se la patch aggiunge nuove chiamate ioctl, allora aggiornate
``Documentation/ioctl/ioctl-number.txt``.
26) Se il codice che avete modificato dipende o usa una qualsiasi interfaccia o
funzionalità del kernel che è associata a uno dei seguenti simboli
``Kconfig``, allora verificate che il kernel compili con diverse
configurazioni dove i simboli sono disabilitati e/o ``=m`` (se c'è la
possibilità) [non tutti contemporaneamente, solo diverse combinazioni
casuali]:
``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``,
``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``,
``CONFIG_NET``, ``CONFIG_INET=n`` (ma l'ultimo con ``CONFIG_NET=y``).
Documentation/translations/it_IT/process/submitting-drivers.rst
View file @ 1a29e857
.. include:: ../disclaimer-ita.rst
:Original: :ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>`
:Translator: Federico Vaga <federico.vaga@vaga.pv.it>
.. _it_submittingdrivers:
Sottomettere driver per il kernel Linux
=======================================
.. warning::
.. note::
TODO ancora da tradurre
Questo documento è vecchio e negli ultimi anni non è stato più aggiornato;
dovrebbe essere aggiornato, o forse meglio, rimosso. La maggior parte di
quello che viene detto qui può essere trovato anche negli altri documenti
dedicati allo sviluppo. Per questo motivo il documento non verrà tradotto.
Documentation/translations/ja_JP/howto.rst
View file @ 1a29e857
......@@ -245,7 +245,7 @@ Linux カーネルソースツリーの中に含まれる、きれいにし、
できます。この最新の素晴しいカーネルコードのリポジトリは以下で見つかり
ます -
http://lxr.free-electrons.com/
https://elixir.bootlin.com/
開発プロセス
------------
......@@ -256,7 +256,6 @@ Linux カーネルの開発プロセスは現在幾つかの異なるメイン
- メインの 4.x カーネルツリー
- 4.x.y -stable カーネルツリー
- 4.x -git カーネルパッチ
- サブシステム毎のカーネルツリーとパッチ
- 統合テストのための 4.x -next カーネルツリー
......@@ -319,15 +318,6 @@ Documentation/process/stable-kernel-rules.rst ファイルにはどのような
類の変更が -stable ツリーに受け入れ可能か、またリリースプロセスがどう
動くかが記述されています。
4.x -git パッチ
~~~~~~~~~~~~~~~
git リポジトリで管理されているLinus のカーネルツリーの毎日のスナップ
ショットがあります。(だから -git という名前がついています)。これらのパッ
チはおおむね毎日リリースされており、Linus のツリーの現状を表します。こ
れは -rc カーネルと比べて、パッチが大丈夫かどうかも確認しないで自動的
に生成されるので、より実験的です。
サブシステム毎のカーネルツリーとパッチ
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
......
Documentation/translations/ko_KR/howto.rst
View file @ 1a29e857
......@@ -77,10 +77,12 @@ Documentation/process/howto.rst
리눅스 커널 소스 코드는 GPL로 배포(release)되었다. 소스트리의 메인
디렉토리에 있는 라이센스에 관하여 상세하게 쓰여 있는 COPYING이라는
파일을 봐라. 여러분이 라이센스에 관한 더 깊은 문제를 가지고 있다면
리눅스 커널 메일링 리스트에 묻지말고 변호사와 연락하라. 메일링
리스트들에 있는 사람들은 변호사가 아니기 때문에 법적 문제에 관하여
그들의 말에 의지해서는 안된다.
파일을 봐라. 리눅스 커널 라이센싱 규칙과 소스 코드 안의 `SPDX
<https://spdx.org/>`_ 식별자 사용법은
:ref:`Documentation/process/license-rules.rst <kernel_licensing>` 에 설명되어
있다. 여러분이 라이센스에 관한 더 깊은 문제를 가지고 있다면 리눅스 커널 메일링
리스트에 묻지말고 변호사와 연락하라. 메일링 리스트들에 있는 사람들은 변호사가
아니기 때문에 법적 문제에 관하여 그들의 말에 의지해서는 안된다.
GPL에 관한 잦은 질문들과 답변들은 다음을 참조하라.
......@@ -99,7 +101,7 @@ mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다.
다음은 커널 소스 트리에 있는 읽어야 할 파일들의 리스트이다.
README
:ref:`Documentation/admin-guide/README.rst <readme>`
이 파일은 리눅스 커널에 관하여 간단한 배경 설명과 커널을 설정하고
빌드하기 위해 필요한 것을 설명한다. 커널에 입문하는 사람들은 여기서
시작해야 한다.
......@@ -220,13 +222,6 @@ ReST 마크업을 사용하는 문서들은 Documentation/output 에 생성된
가지고 있지 않다면 다음에 무엇을 해야할지에 관한 방향을 배울 수 있을
것이다.
여러분들이 이미 커널 트리에 반영하길 원하는 코드 묶음을 가지고 있지만
올바른 포맷으로 포장하는데 도움이 필요하다면 그러한 문제를 돕기 위해
만들어진 kernel-mentors 프로젝트가 있다. 그곳은 메일링 리스트이며
다음에서 참조할 수 있다.
https://selenic.com/mailman/listinfo/kernel-mentors
리눅스 커널 코드에 실제 변경을 하기 전에 반드시 그 코드가 어떻게
동작하는지 이해하고 있어야 한다. 코드를 분석하기 위하여 특정한 툴의
도움을 빌려서라도 코드를 직접 읽는 것보다 좋은 것은 없다(대부분의
......@@ -235,7 +230,7 @@ ReST 마크업을 사용하는 문서들은 Documentation/output 에 생성된
소스코드를 인덱스된 웹 페이지들의 형태로 보여준다. 최신의 멋진 커널
코드 저장소는 다음을 통하여 참조할 수 있다.
http://lxr.free-electrons.com/
https://elixir.bootlin.com/
개발 프로세스
......@@ -247,7 +242,6 @@ ReST 마크업을 사용하는 문서들은 Documentation/output 에 생성된
- main 4.x 커널 트리
- 4.x.y - 안정된 커널 트리
- 4.x -git 커널 패치들
- 서브시스템을 위한 커널 트리들과 패치들
- 4.x - 통합 테스트를 위한 next 커널 트리
......@@ -303,17 +297,9 @@ Andrew Morton의 글이 있다.
4.x.y는 "stable" 팀<stable@vger.kernel.org>에 의해 관리되며 거의 매번 격주로
배포된다.
커널 트리 문서들 내에 Documentation/process/stable-kernel-rules.rst 파일은 어떤
종류의 변경들이 -stable 트리로 들어왔는지와 배포 프로세스가 어떻게
진행되는지를 설명한다.
4.x -git 패치들
~~~~~~~~~~~~~~~
git 저장소(그러므로 -git이라는 이름이 붙음)에는 날마다 관리되는 Linus의
커널 트리의 snapshot 들이 있다. 이 패치들은 일반적으로 날마다 배포되며
Linus의 트리의 현재 상태를 나타낸다. 이 패치들은 정상적인지 조금도
살펴보지 않고 자동적으로 생성된 것이므로 -rc 커널들 보다도 더 실험적이다.
커널 트리 문서들 내의 :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`
파일은 어떤 종류의 변경들이 -stable 트리로 들어왔는지와
배포 프로세스가 어떻게 진행되는지를 설명한다.
서브시스템 커널 트리들과 패치들
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
......@@ -360,9 +346,10 @@ https://bugzilla.kernel.org 는 리눅스 커널 개발자들이 커널의 버
https://bugzilla.kernel.org/page.cgi?id=faq.html
메인 커널 소스 디렉토리에 있는 admin-guide/reporting-bugs.rst 파일은 커널 버그라고 생각되는
것을 보고하는 방법에 관한 좋은 템플릿이며 문제를 추적하기 위해서 커널
개발자들이 필요로 하는 정보가 무엇들인지를 상세히 설명하고 있다.
메인 커널 소스 디렉토리에 있는 :ref:`admin-guide/reporting-bugs.rst <reportingbugs>`
파일은 커널 버그라고 생각되는 것을 보고하는 방법에 관한 좋은 템플릿이며 문제를
추적하기 위해서 커널 개발자들이 필요로 하는 정보가 무엇들인지를 상세히 설명하고
있다.
버그 리포트들의 관리
......@@ -377,15 +364,7 @@ https://bugzilla.kernel.org 는 리눅스 커널 개발자들이 커널의 버
다른 사람들의 버그들을 수정하기 위하여 시간을 낭비하지 않기 때문이다.
이미 보고된 버그 리포트들을 가지고 작업하기 위해서 https://bugzilla.kernel.org
를 참조하라. 여러분이 앞으로 생겨날 버그 리포트들의 조언자가 되길 원한다면
bugme-new 메일링 리스트나(새로운 버그 리포트들만이 이곳에서 메일로 전해진다)
bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메일로 전해진다)
에 등록하면 된다.
https://lists.linux-foundation.org/mailman/listinfo/bugme-new
https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors
를 참조하라.
메일링 리스트들
......@@ -430,7 +409,8 @@ bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메
"John 커널해커는 작성했다...."를 유지하며 여러분들의 의견을 그 메일의 윗부분에
작성하지 말고 각 인용한 단락들 사이에 넣어라.
여러분들이 패치들을 메일에 넣는다면 그것들은 Documentation/process/submitting-patches.rst에
여러분들이 패치들을 메일에 넣는다면 그것들은
:ref:`Documentation/process/submitting-patches.rst <submittingpatches>` 에
나와있는데로 명백히(plain) 읽을 수 있는 텍스트여야 한다. 커널 개발자들은
첨부파일이나 압축된 패치들을 원하지 않는다. 그들은 여러분들의 패치의
각 라인 단위로 코멘트를 하길 원하며 압축하거나 첨부하지 않고 보내는 것이
......
Documentation/translations/zh_CN/HOWTO
View file @ 1a29e857
......@@ -192,7 +192,6 @@ Linux内核代码中包含有大量的文档。这些文档对于学习如何与
些分支包括：
- 2.6.x主内核源码树
- 2.6.x.y -stable内核源码树
- 2.6.x -git内核补丁集
- 2.6.x -mm内核补丁集
- 子系统相关的内核源码树和补丁集
......@@ -240,14 +239,6 @@ kernel.org网站的pub/linux/kernel/v2.6/目录下找到它。它的开发遵循
版内核接受的修改类型以及发布的流程。
2.6.x -git补丁集
----------------
Linus的内核源码树的每日快照，这个源码树是由git工具管理的（由此得名）。这
些补丁通常每天更新以反映Linus的源码树的最新状态。它们比-rc版本的内核源码
树更具试验性质，因为这个补丁集是全自动生成的，没有任何人来确认其是否真正
健全。
2.6.x -mm补丁集
---------------
这是由Andrew Morton维护的试验性内核补丁集。Andrew将所有子系统的内核源码
......
Documentation/translations/zh_CN/coding-style.rst
View file @ 1a29e857
......@@ -535,26 +535,43 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以获得详细信息。
(* (max steps 1)
c-basic-offset)))
(add-hook 'c-mode-common-hook
(lambda ()
;; Add kernel style
(c-add-style
"linux-tabs-only"
'("linux" (c-offsets-alist
(arglist-cont-nonempty
c-lineup-gcc-asm-reg
c-lineup-arglist-tabs-only))))))
(add-hook 'c-mode-hook
(lambda ()
(let ((filename (buffer-file-name)))
;; Enable kernel mode for the appropriate files
(when (and filename
(string-match (expand-file-name "~/src/linux-trees")
filename))
(setq indent-tabs-mode t)
(setq show-trailing-whitespace t)
(c-set-style "linux-tabs-only")))))
(dir-locals-set-class-variables
'linux-kernel
'((c-mode . (
(c-basic-offset . 8)
(c-label-minimum-indentation . 0)
(c-offsets-alist . (
(arglist-close . c-lineup-arglist-tabs-only)
(arglist-cont-nonempty .
(c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only))
(arglist-intro . +)
(brace-list-intro . +)
(c . c-lineup-C-comments)
(case-label . 0)
(comment-intro . c-lineup-comment)
(cpp-define-intro . +)
(cpp-macro . -1000)
(cpp-macro-cont . +)
(defun-block-intro . +)
(else-clause . 0)
(func-decl-cont . +)
(inclass . +)
(inher-cont . c-lineup-multi-inher)
(knr-argdecl-intro . 0)
(label . -1000)
(statement . 0)
(statement-block-intro . +)
(statement-case-intro . +)
(statement-cont . +)
(substatement . +)
))
(indent-tabs-mode . t)
(show-trailing-whitespace . t)
))))
(dir-locals-set-directory-class
(expand-file-name "~/src/linux-trees")
'linux-kernel)
这会让 emacs 在 ``~/src/linux-trees`` 下的 C 源文件获得更好的内核代码风格。
......
Documentation/vm/index.rst
View file @ 1a29e857
......@@ -4,7 +4,7 @@ Linux Memory Management Documentation
This is a collection of documents about the Linux memory management (mm)
subsystem. If you are looking for advice on simply allocating memory,
see the :ref:`memory-allocation`.
see the :ref:`memory_allocation`.
User guides for MM features
===========================
......
Documentation/vm/slub.rst
View file @ 1a29e857
......@@ -66,7 +66,7 @@ Trying to find an issue in the dentry cache? Try::
to only enable debugging on the dentry cache. You may use an asterisk at the
end of the slab name, in order to cover all slabs with the same prefix. For
example, here's how you can poison the dentry cache as well as all kmalloc
slabs:
slabs::
slub_debug=P,kmalloc-*,dentry
......@@ -141,7 +141,7 @@ can be influenced by kernel parameters:
(list_lock) where contention may occur.
``slub_min_order``
specifies a minim order of slabs. A similar effect like
specifies a minimum order of slabs. A similar effect like
``slub_min_objects``.
``slub_max_order``
......
LICENSES/exceptions/GCC-exception-2.0 0 → 100644
View file @ 1a29e857
SPDX-Exception-Identifier: GCC-exception-2.0
SPDX-URL: https://spdx.org/licenses/GCC-exception-2.0.html
SPDX-Licenses: GPL-2.0, GPL-2.0+, GPL-2.0-only, GPL-2.0-or-later
Usage-Guide:
This exception is used together with one of the above SPDX-Licenses to
allow linking the compiled version of code to non GPL compliant code.
To use this exception add it with the keyword WITH to one of the
identifiers in the SPDX-Licenses tag:
SPDX-License-Identifier: <SPDX-License> WITH GCC-exception-2.0
License-Text:
In addition to the permissions in the GNU Library General Public License,
the Free Software Foundation gives you unlimited permission to link the
compiled version of this file into combinations with other programs, and to
distribute those programs without any restriction coming from the use of
this file. (The General Public License restrictions do apply in other
respects; for example, they cover modification of the file, and
distribution when not linked into another program.)
include/linux/module.h
View file @ 1a29e857
......@@ -172,7 +172,7 @@ extern void cleanup_module(void);
* The following license idents are currently accepted as indicating free
* software modules
*
* "GPL" [GNU Public License v2 or later]
* "GPL" [GNU Public License v2]
* "GPL v2" [GNU Public License v2]
* "GPL and additional rights" [GNU Public License v2 rights and more]
* "Dual BSD/GPL" [GNU Public License v2
......@@ -186,6 +186,22 @@ extern void cleanup_module(void);
*
* "Proprietary" [Non free products]
*
* Both "GPL v2" and "GPL" (the latter also in dual licensed strings) are
* merely stating that the module is licensed under the GPL v2, but are not
* telling whether "GPL v2 only" or "GPL v2 or later". The reason why there
* are two variants is a historic and failed attempt to convey more
* information in the MODULE_LICENSE string. For module loading the
* "only/or later" distinction is completely irrelevant and does neither
* replace the proper license identifiers in the corresponding source file
* nor amends them in any way. The sole purpose is to make the
* 'Proprietary' flagging work and to refuse to bind symbols which are
* exported with EXPORT_SYMBOL_GPL when a non free module is loaded.
*
* In the same way "BSD" is not a clear license information. It merely
* states, that the module is licensed under one of the compatible BSD
* license variants. The detailed and correct license information is again
* to be found in the corresponding source files.
*
* There are dual licensed components, but when running with Linux it is the
* GPL that is relevant so this is a non issue. Similarly LGPL linked with GPL
* is a GPL combined work.
......
include/linux/skbuff.h
View file @ 1a29e857
......@@ -4323,7 +4323,7 @@ static inline bool skb_head_is_locked(const struct sk_buff *skb)
/* Local Checksum Offload.
* Compute outer checksum based on the assumption that the
* inner checksum will be offloaded later.
* See Documentation/networking/checksum-offloads.txt for
* See Documentation/networking/checksum-offloads.rst for
* explanation of how this works.
* Fill in outer checksum adjustment (e.g. with sum of outer
* pseudo-header) before calling.
......
samples/Kconfig
View file @ 1a29e857
......@@ -147,6 +147,13 @@ config SAMPLE_VFIO_MDEV_MBOCHS
Specifically it does *not* include any legacy vga stuff.
Device looks a lot like "qemu -device secondary-vga".
config SAMPLE_ANDROID_BINDERFS
bool "Build Android binderfs example"
depends on CONFIG_ANDROID_BINDERFS
help
Builds a sample program to illustrate the use of the Android binderfs
filesystem.
config SAMPLE_STATX
bool "Build example extended-stat using code"
depends on BROKEN
......
samples/Makefile
View file @ 1a29e857
......@@ -3,4 +3,4 @@
obj-$(CONFIG_SAMPLES) += kobject/ kprobes/ trace_events/ livepatch/ \
hw_breakpoint/ kfifo/ kdb/ hidraw/ rpmsg/ seccomp/ \
configfs/ connector/ v4l/ trace_printk/ \
vfio-mdev/ statx/ qmi/
vfio-mdev/ statx/ qmi/ binderfs/
samples/binderfs/Makefile 0 → 100644
View file @ 1a29e857
obj-$(CONFIG_SAMPLE_ANDROID_BINDERFS) += binderfs_example.o
samples/binderfs/binderfs_example.c 0 → 100644
View file @ 1a29e857
// SPDX-License-Identifier: GPL-2.0
#define _GNU_SOURCE
#include <errno.h>
#include <fcntl.h>
#include <sched.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/ioctl.h>
#include <sys/mount.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <unistd.h>
#include <linux/android/binder.h>
#include <linux/android/binderfs.h>
int main(int argc, char *argv[])
{
int fd, ret, saved_errno;
size_t len;
struct binderfs_device device = { 0 };
ret = unshare(CLONE_NEWNS);
if (ret < 0) {
fprintf(stderr, "%s - Failed to unshare mount namespace\n",
strerror(errno));
exit(EXIT_FAILURE);
}
ret = mount(NULL, "/", NULL, MS_REC | MS_PRIVATE, 0);
if (ret < 0) {
fprintf(stderr, "%s - Failed to mount / as private\n",
strerror(errno));
exit(EXIT_FAILURE);
}
ret = mkdir("/dev/binderfs", 0755);
if (ret < 0 && errno != EEXIST) {
fprintf(stderr, "%s - Failed to create binderfs mountpoint\n",
strerror(errno));
exit(EXIT_FAILURE);
}
ret = mount(NULL, "/dev/binderfs", "binder", 0, 0);
if (ret < 0) {
fprintf(stderr, "%s - Failed to mount binderfs\n",
strerror(errno));
exit(EXIT_FAILURE);
}
memcpy(device.name, "my-binder", strlen("my-binder"));
fd = open("/dev/binderfs/binder-control", O_RDONLY | O_CLOEXEC);
if (fd < 0) {
fprintf(stderr, "%s - Failed to open binder-control device\n",
strerror(errno));
exit(EXIT_FAILURE);
}
ret = ioctl(fd, BINDER_CTL_ADD, &device);
saved_errno = errno;
close(fd);
errno = saved_errno;
if (ret < 0) {
fprintf(stderr, "%s - Failed to allocate new binder device\n",
strerror(errno));
exit(EXIT_FAILURE);
}
printf("Allocated new binder device with major %d, minor %d, and name %s\n",
device.major, device.minor, device.name);
ret = unlink("/dev/binderfs/my-binder");
if (ret < 0) {
fprintf(stderr, "%s - Failed to delete binder device\n",
strerror(errno));
exit(EXIT_FAILURE);
}
/* Cleanup happens when the mount namespace dies. */
exit(EXIT_SUCCESS);
}
scripts/checkpatch.pl
View file @ 1a29e857
......@@ -6396,19 +6396,6 @@ sub process {
}
}
# check for bool bitfields
if ($sline =~ /^.\s+bool\s*$Ident\s*:\s*\d+\s*;/) {
WARN("BOOL_BITFIELD",
"Avoid using bool as bitfield. Prefer bool bitfields as unsigned int or u<8|16|32>\n" . $herecurr);
}
# check for bool use in .h files
if ($realfile =~ /\.h$/ &&
$sline =~ /^.\s+bool\s*$Ident\s*(?::\s*d+\s*)?;/) {
CHK("BOOL_MEMBER",
"Avoid using bool structure members because of possible alignment issues - see: https://lkml.org/lkml/2017/11/21/384\n" . $herecurr);
}
# check for semaphores initialized locked
if ($line =~ /^.\s*sema_init.+,\W?0\W?\)/) {
WARN("CONSIDER_COMPLETION",
......
scripts/kernel-doc
View file @ 1a29e857
......@@ -1474,7 +1474,7 @@ sub push_parameter($$$$) {
if (!defined $parameterdescs{$param} && $param !~ /^#/) {
$parameterdescs{$param} = $undescribed;
if (show_warnings($type, $declaration_name)) {
if (show_warnings($type, $declaration_name) && $param !~ /\./) {
print STDERR
"${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n";
++$warnings;
......
scripts/spdxcheck.py
View file @ 1a29e857
......@@ -175,7 +175,13 @@ class id_parser(object):
self.lines_checked += 1
if line.find("SPDX-License-Identifier:") < 0:
continue
expr = line.split(':')[1].replace('*/', '').strip()
expr = line.split(':')[1].strip()
# Remove trailing comment closure
if line.strip().endswith('*/'):
expr = expr.rstrip('*/').strip()
# Special case for SH magic boot code files
if line.startswith('LIST \"'):
expr = expr.rstrip('\"').strip()
self.parse(expr)
self.spdx_valid += 1
#
......
security/selinux/hooks.c
View file @ 1a29e857
......@@ -4472,7 +4472,7 @@ static int selinux_socket_bind(struct socket *sock, struct sockaddr *address, in
}
/* This supports connect(2) and SCTP connect services such as sctp_connectx(3)
* and sctp_sendmsg(3) as described in Documentation/security/LSM-sctp.rst
* and sctp_sendmsg(3) as described in Documentation/security/SCTP.rst
*/
static int selinux_socket_connect_helper(struct socket *sock,
struct sockaddr *address, int addrlen)
......
tools/Makefile
View file @ 1a29e857
......@@ -12,6 +12,7 @@ help:
@echo ' acpi - ACPI tools'
@echo ' cgroup - cgroup tools'
@echo ' cpupower - a tool for all things x86 CPU power'
@echo ' debugging - tools for debugging'
@echo ' firewire - the userspace part of nosy, an IEEE-1394 traffic sniffer'
@echo ' firmware - Firmware tools'
@echo ' freefall - laptop accelerometer program for disk protection'
......@@ -61,7 +62,7 @@ acpi: FORCE
cpupower: FORCE
$(call descend,power/$@)
cgroup firewire hv guest spi usb virtio vm bpf iio gpio objtool leds wmi pci firmware: FORCE
cgroup firewire hv guest spi usb virtio vm bpf iio gpio objtool leds wmi pci firmware debugging: FORCE
$(call descend,$@)
liblockdep: FORCE
......@@ -96,7 +97,8 @@ kvm_stat: FORCE
all: acpi cgroup cpupower gpio hv firewire liblockdep \
perf selftests spi turbostat usb \
virtio vm bpf x86_energy_perf_policy \
tmon freefall iio objtool kvm_stat wmi pci
tmon freefall iio objtool kvm_stat wmi \
pci debugging
acpi_install:
$(call descend,power/$(@:_install=),install)
......@@ -104,7 +106,7 @@ acpi_install:
cpupower_install:
$(call descend,power/$(@:_install=),install)
cgroup_install firewire_install gpio_install hv_install iio_install perf_install spi_install usb_install virtio_install vm_install bpf_install objtool_install wmi_install pci_install:
cgroup_install firewire_install gpio_install hv_install iio_install perf_install spi_install usb_install virtio_install vm_install bpf_install objtool_install wmi_install pci_install debugging_install:
$(call descend,$(@:_install=),install)
liblockdep_install:
......@@ -130,7 +132,7 @@ install: acpi_install cgroup_install cpupower_install gpio_install \
perf_install selftests_install turbostat_install usb_install \
virtio_install vm_install bpf_install x86_energy_perf_policy_install \
tmon_install freefall_install objtool_install kvm_stat_install \
wmi_install pci_install
wmi_install pci_install debugging_install
acpi_clean:
$(call descend,power/acpi,clean)
......@@ -138,7 +140,7 @@ acpi_clean:
cpupower_clean:
$(call descend,power/cpupower,clean)
cgroup_clean hv_clean firewire_clean spi_clean usb_clean virtio_clean vm_clean wmi_clean bpf_clean iio_clean gpio_clean objtool_clean leds_clean pci_clean firmware_clean:
cgroup_clean hv_clean firewire_clean spi_clean usb_clean virtio_clean vm_clean wmi_clean bpf_clean iio_clean gpio_clean objtool_clean leds_clean pci_clean firmware_clean debugging_clean:
$(call descend,$(@:_clean=),clean)
liblockdep_clean:
......@@ -176,6 +178,6 @@ clean: acpi_clean cgroup_clean cpupower_clean hv_clean firewire_clean \
perf_clean selftests_clean turbostat_clean spi_clean usb_clean virtio_clean \
vm_clean bpf_clean iio_clean x86_energy_perf_policy_clean tmon_clean \
freefall_clean build_clean libbpf_clean libsubcmd_clean liblockdep_clean \
gpio_clean objtool_clean leds_clean wmi_clean pci_clean firmware_clean
gpio_clean objtool_clean leds_clean wmi_clean pci_clean firmware_clean debugging_clean
.PHONY: FORCE
tools/debugging/Makefile 0 → 100644
View file @ 1a29e857
# SPDX-License-Identifier: GPL-2.0
# Makefile for debugging tools
PREFIX ?= /usr
BINDIR ?= bin
INSTALL ?= install
TARGET = kernel-chktaint
all: $(TARGET)
clean:
install: kernel-chktaint
$(INSTALL) -D -m 755 $(TARGET) $(DESTDIR)$(PREFIX)/$(BINDIR)/$(TARGET)
tools/debugging/kernel-chktaint 0 → 100755
View file @ 1a29e857
This diff is collapsed.
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