This was a reasonably active cycle for documentation; this pull includes:
- Some kernel-doc cleanups. That script is still regex onslaught from
hell, but it has gotten a little better.
- Improvements to the checkpatch docs, which are also used by the tool
itself.
- A major update to the pathname lookup documentation.
- Elimination of :doc: markup, since our automarkup magic can create
references from filenames without all the extra noise.
- The flurry of Chinese translation activity continues.
Plus, of course, the usual collection of updates, typo fixes, and warning
fixes.
-----BEGIN PGP SIGNATURE-----
iQFDBAABCAAtFiEEIw+MvkEiF49krdp9F0NaE2wMflgFAmDZ6pQPHGNvcmJldEBs
d24ubmV0AAoJEBdDWhNsDH5Y9W0IAIpzBZDVsDQ7s5cIjbxEh9Oeh1uRmwuObnQh
xsM5oLuAUSMczf5JX8cdyutWJfdoEF5WHjfbt1otfys+kW9m7z0b1K4xw684Y390
sPk3eYVYLiUAZ4/LVdC47BpAzzgJ5U9iC6+FjOATAYsY40EwruxyZWjmY+SaDOU5
dQPjbpRuNQTFjYE6nZIW0o6jyunrfFaJTS6g2bdDoBDOGKyNOSKEw4XZ442cJ3km
uXoMfSJGslQj6qbGY0YhNeaNQm0ErcQw2K4lS3K4gc7Lht32Fbi1lhaqnTIkgI5f
Rh3X37pb90Ya88uWxldVB2bXUrA+PZA/cJqwNTrgw+niBQl6sKU=
=KDcM
-----END PGP SIGNATURE-----
Merge tag 'docs-5.14' of git://git.lwn.net/linux
Pull documentation updates from Jonathan Corbet:
"This was a reasonably active cycle for documentation; this includes:
- Some kernel-doc cleanups. That script is still regex onslaught from
hell, but it has gotten a little better.
- Improvements to the checkpatch docs, which are also used by the
tool itself.
- A major update to the pathname lookup documentation.
- Elimination of :doc: markup, since our automarkup magic can create
references from filenames without all the extra noise.
- The flurry of Chinese translation activity continues.
Plus, of course, the usual collection of updates, typo fixes, and
warning fixes"
* tag 'docs-5.14' of git://git.lwn.net/linux: (115 commits)
docs: path-lookup: use bare function() rather than literals
docs: path-lookup: update symlink description
docs: path-lookup: update get_link() ->follow_link description
docs: path-lookup: update WALK_GET, WALK_PUT desc
docs: path-lookup: no get_link()
docs: path-lookup: update i_op->put_link and cookie description
docs: path-lookup: i_op->follow_link replaced with i_op->get_link
docs: path-lookup: Add macro name to symlink limit description
docs: path-lookup: remove filename_mountpoint
docs: path-lookup: update do_last() part
docs: path-lookup: update path_mountpoint() part
docs: path-lookup: update path_to_nameidata() part
docs: path-lookup: update follow_managed() part
docs: Makefile: Use CONFIG_SHELL not SHELL
docs: Take a little noise out of the build process
docs: x86: avoid using ReST :doc:`foo` markup
docs: virt: kvm: s390-pv-boot.rst: avoid using ReST :doc:`foo` markup
docs: userspace-api: landlock.rst: avoid using ReST :doc:`foo` markup
docs: trace: ftrace.rst: avoid using ReST :doc:`foo` markup
docs: trace: coresight: coresight.rst: avoid using ReST :doc:`foo` markup
...
This commit is contained in:
Linus Torvalds
Коммит
233a806b00
|
|
@ -6,4 +6,4 @@ Description:
|
|||
with the update that cpuidle governor can be changed at runtime in default,
|
||||
both current_governor and current_governor_ro co-exist under
|
||||
/sys/devices/system/cpu/cpuidle/ file, it's duplicate so make
|
||||
current_governor_ro obselete.
|
||||
current_governor_ro obsolete.
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ Contact: Dhaval Giani <dhaval@linux.vnet.ibm.com>
|
|||
Description:
|
||||
The /sys/kernel/uids/<uid>/cpu_shares tunable is used
|
||||
to set the cpu bandwidth a user is allowed. This is a
|
||||
propotional value. What that means is that if there
|
||||
proportional value. What that means is that if there
|
||||
are two users logged in, each with an equal number of
|
||||
shares, then they will get equal CPU bandwidth. Another
|
||||
example would be, if User A has shares = 1024 and user
|
||||
|
|
|
|||
|
|
@ -61,7 +61,7 @@ Date: September. 2017
|
|||
KernelVersion: 4.14
|
||||
Contact: Stephen Hemminger <sthemmin@microsoft.com>
|
||||
Description: Directory for per-channel information
|
||||
NN is the VMBUS relid associtated with the channel.
|
||||
NN is the VMBUS relid associated with the channel.
|
||||
|
||||
What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/cpu
|
||||
Date: September. 2017
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ Date: April 2011
|
|||
KernelVersion: 3.0
|
||||
Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
|
||||
Description:
|
||||
The major:minor number (in hexidecimal) of the
|
||||
The major:minor number (in hexadecimal) of the
|
||||
physical device providing the storage for this backend
|
||||
block device.
|
||||
|
||||
|
|
|
|||
|
|
@ -23,3 +23,86 @@ Description: Default value for the Data Stream Control Register (DSCR) on
|
|||
here).
|
||||
If set by a process it will be inherited by child processes.
|
||||
Values: 64 bit unsigned integer (bit field)
|
||||
|
||||
What: /sys/devices/system/cpu/cpuX/topology/physical_package_id
|
||||
Description: physical package id of cpuX. Typically corresponds to a physical
|
||||
socket number, but the actual value is architecture and platform
|
||||
dependent.
|
||||
Values: integer
|
||||
|
||||
What: /sys/devices/system/cpu/cpuX/topology/die_id
|
||||
Description: the CPU die ID of cpuX. Typically it is the hardware platform's
|
||||
identifier (rather than the kernel's). The actual value is
|
||||
architecture and platform dependent.
|
||||
Values: integer
|
||||
|
||||
What: /sys/devices/system/cpu/cpuX/topology/core_id
|
||||
Description: the CPU core ID of cpuX. Typically it is the hardware platform's
|
||||
identifier (rather than the kernel's). The actual value is
|
||||
architecture and platform dependent.
|
||||
Values: integer
|
||||
|
||||
What: /sys/devices/system/cpu/cpuX/topology/book_id
|
||||
Description: the book ID of cpuX. Typically it is the hardware platform's
|
||||
identifier (rather than the kernel's). The actual value is
|
||||
architecture and platform dependent. it's only used on s390.
|
||||
Values: integer
|
||||
|
||||
What: /sys/devices/system/cpu/cpuX/topology/drawer_id
|
||||
Description: the drawer ID of cpuX. Typically it is the hardware platform's
|
||||
identifier (rather than the kernel's). The actual value is
|
||||
architecture and platform dependent. it's only used on s390.
|
||||
Values: integer
|
||||
|
||||
What: /sys/devices/system/cpu/cpuX/topology/core_cpus
|
||||
Description: internal kernel map of CPUs within the same core.
|
||||
(deprecated name: "thread_siblings")
|
||||
Values: hexadecimal bitmask.
|
||||
|
||||
What: /sys/devices/system/cpu/cpuX/topology/core_cpus_list
|
||||
Description: human-readable list of CPUs within the same core.
|
||||
The format is like 0-3, 8-11, 14,17.
|
||||
(deprecated name: "thread_siblings_list").
|
||||
Values: decimal list.
|
||||
|
||||
What: /sys/devices/system/cpu/cpuX/topology/package_cpus
|
||||
Description: internal kernel map of the CPUs sharing the same physical_package_id.
|
||||
(deprecated name: "core_siblings").
|
||||
Values: hexadecimal bitmask.
|
||||
|
||||
What: /sys/devices/system/cpu/cpuX/topology/package_cpus_list
|
||||
Description: human-readable list of CPUs sharing the same physical_package_id.
|
||||
The format is like 0-3, 8-11, 14,17.
|
||||
(deprecated name: "core_siblings_list")
|
||||
Values: decimal list.
|
||||
|
||||
What: /sys/devices/system/cpu/cpuX/topology/die_cpus
|
||||
Description: internal kernel map of CPUs within the same die.
|
||||
Values: hexadecimal bitmask.
|
||||
|
||||
What: /sys/devices/system/cpu/cpuX/topology/die_cpus_list
|
||||
Description: human-readable list of CPUs within the same die.
|
||||
The format is like 0-3, 8-11, 14,17.
|
||||
Values: decimal list.
|
||||
|
||||
What: /sys/devices/system/cpu/cpuX/topology/book_siblings
|
||||
Description: internal kernel map of cpuX's hardware threads within the same
|
||||
book_id. it's only used on s390.
|
||||
Values: hexadecimal bitmask.
|
||||
|
||||
What: /sys/devices/system/cpu/cpuX/topology/book_siblings_list
|
||||
Description: human-readable list of cpuX's hardware threads within the same
|
||||
book_id.
|
||||
The format is like 0-3, 8-11, 14,17. it's only used on s390.
|
||||
Values: decimal list.
|
||||
|
||||
What: /sys/devices/system/cpu/cpuX/topology/drawer_siblings
|
||||
Description: internal kernel map of cpuX's hardware threads within the same
|
||||
drawer_id. it's only used on s390.
|
||||
Values: hexadecimal bitmask.
|
||||
|
||||
What: /sys/devices/system/cpu/cpuX/topology/drawer_siblings_list
|
||||
Description: human-readable list of cpuX's hardware threads within the same
|
||||
drawer_id.
|
||||
The format is like 0-3, 8-11, 14,17. it's only used on s390.
|
||||
Values: decimal list.
|
||||
|
|
|
|||
|
|
@ -173,7 +173,7 @@ What: /sys/bus/dsa/devices/wq<m>.<n>/priority
|
|||
Date: Oct 25, 2019
|
||||
KernelVersion: 5.6.0
|
||||
Contact: dmaengine@vger.kernel.org
|
||||
Description: The priority value of this work queue, it is a vlue relative to
|
||||
Description: The priority value of this work queue, it is a value relative to
|
||||
other work queue in the same group to control quality of service
|
||||
for dispatching work from multiple workqueues in the same group.
|
||||
|
||||
|
|
|
|||
|
|
@ -137,7 +137,7 @@ Contact: Vadim Pasternak <vadimpmellanox.com>
|
|||
Description: These files show the system reset cause, as following:
|
||||
COMEX thermal shutdown; wathchdog power off or reset was derived
|
||||
by one of the next components: COMEX, switch board or by Small Form
|
||||
Factor mezzanine, reset requested from ASIC, reset cuased by BIOS
|
||||
Factor mezzanine, reset requested from ASIC, reset caused by BIOS
|
||||
reload. Value 1 in file means this is reset cause, 0 - otherwise.
|
||||
Only one of the above causes could be 1 at the same time, representing
|
||||
only last reset cause.
|
||||
|
|
@ -183,7 +183,7 @@ What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/vpd_wp
|
|||
Date: January 2020
|
||||
KernelVersion: 5.6
|
||||
Contact: Vadim Pasternak <vadimpmellanox.com>
|
||||
Description: This file allows to overwrite system VPD hardware wrtie
|
||||
Description: This file allows to overwrite system VPD hardware write
|
||||
protection when attribute is set 1.
|
||||
|
||||
The file is read/write.
|
||||
|
|
|
|||
|
|
@ -31,4 +31,4 @@ Date: April 2016
|
|||
KernelVersion: 4.7
|
||||
Description:
|
||||
Dummy IIO devices directory. Creating a directory here will result
|
||||
in creating a dummy IIO device in the IIO subystem.
|
||||
in creating a dummy IIO device in the IIO subsystem.
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ Description:
|
|||
|
||||
subbuffer_size
|
||||
configure the sub-buffer size for this channel
|
||||
(needed for synchronous and isochrnous data)
|
||||
(needed for synchronous and isochronous data)
|
||||
|
||||
|
||||
num_buffers
|
||||
|
|
@ -75,7 +75,7 @@ Description:
|
|||
|
||||
subbuffer_size
|
||||
configure the sub-buffer size for this channel
|
||||
(needed for synchronous and isochrnous data)
|
||||
(needed for synchronous and isochronous data)
|
||||
|
||||
|
||||
num_buffers
|
||||
|
|
@ -130,7 +130,7 @@ Description:
|
|||
|
||||
subbuffer_size
|
||||
configure the sub-buffer size for this channel
|
||||
(needed for synchronous and isochrnous data)
|
||||
(needed for synchronous and isochronous data)
|
||||
|
||||
|
||||
num_buffers
|
||||
|
|
@ -196,7 +196,7 @@ Description:
|
|||
|
||||
subbuffer_size
|
||||
configure the sub-buffer size for this channel
|
||||
(needed for synchronous and isochrnous data)
|
||||
(needed for synchronous and isochronous data)
|
||||
|
||||
|
||||
num_buffers
|
||||
|
|
|
|||
|
|
@ -137,7 +137,7 @@ Description:
|
|||
This group contains "OS String" extension handling attributes.
|
||||
|
||||
============= ===============================================
|
||||
use flag turning "OS Desctiptors" support on/off
|
||||
use flag turning "OS Descriptors" support on/off
|
||||
b_vendor_code one-byte value used for custom per-device and
|
||||
per-interface requests
|
||||
qw_sign an identifier to be reported as "OS String"
|
||||
|
|
|
|||
|
|
@ -170,7 +170,7 @@ Description: Default color matching descriptors
|
|||
bMatrixCoefficients matrix used to compute luma and
|
||||
chroma values from the color primaries
|
||||
bTransferCharacteristics optoelectronic transfer
|
||||
characteristic of the source picutre,
|
||||
characteristic of the source picture,
|
||||
also called the gamma function
|
||||
bColorPrimaries color primaries and the reference
|
||||
white
|
||||
|
|
@ -311,7 +311,7 @@ Description: Specific streaming header descriptors
|
|||
a hardware trigger interrupt event
|
||||
bTriggerSupport flag specifying if hardware
|
||||
triggering is supported
|
||||
bStillCaptureMethod method of still image caputre
|
||||
bStillCaptureMethod method of still image capture
|
||||
supported
|
||||
bTerminalLink id of the output terminal to which
|
||||
the video endpoint of this interface
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@ What: /sys/kernel/debug/genwqe/genwqe<n>_card/prev_regs
|
|||
Date: Oct 2013
|
||||
Contact: haver@linux.vnet.ibm.com
|
||||
Description: Dump of the error registers before the last reset of
|
||||
the card occured.
|
||||
the card occurred.
|
||||
Only available for PF.
|
||||
|
||||
What: /sys/kernel/debug/genwqe/genwqe<n>_card/prev_dbg_uid0
|
||||
|
|
|
|||
|
|
@ -153,7 +153,7 @@ KernelVersion: 5.1
|
|||
Contact: ogabbay@kernel.org
|
||||
Description: Triggers an I2C transaction that is generated by the device's
|
||||
CPU. Writing to this file generates a write transaction while
|
||||
reading from the file generates a read transcation
|
||||
reading from the file generates a read transaction
|
||||
|
||||
What: /sys/kernel/debug/habanalabs/hl<n>/i2c_reg
|
||||
Date: Jan 2019
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ KernelVersion: 4.12
|
|||
Contact: linux-fsi@lists.ozlabs.org
|
||||
Description:
|
||||
Sends an FSI BREAK command on a master's communication
|
||||
link to any connnected slaves. A BREAK resets connected
|
||||
link to any connected slaves. A BREAK resets connected
|
||||
device's logic and preps it to receive further commands
|
||||
from the master.
|
||||
|
||||
|
|
|
|||
|
|
@ -786,7 +786,7 @@ What: /sys/.../events/in_capacitanceY_adaptive_thresh_rising_en
|
|||
What: /sys/.../events/in_capacitanceY_adaptive_thresh_falling_en
|
||||
KernelVersion: 5.13
|
||||
Contact: linux-iio@vger.kernel.org
|
||||
Descrption:
|
||||
Description:
|
||||
Adaptive thresholds are similar to normal fixed thresholds
|
||||
but the value is expressed as an offset from a value which
|
||||
provides a low frequency approximation of the channel itself.
|
||||
|
|
@ -798,10 +798,10 @@ What: /sys/.../in_capacitanceY_adaptive_thresh_rising_timeout
|
|||
What: /sys/.../in_capacitanceY_adaptive_thresh_falling_timeout
|
||||
KernelVersion: 5.11
|
||||
Contact: linux-iio@vger.kernel.org
|
||||
Descrption:
|
||||
Description:
|
||||
When adaptive thresholds are used, the tracking signal
|
||||
may adjust too slowly to step changes in the raw signal.
|
||||
*_timeout (in seconds) specifies a time for which the
|
||||
Thus these specify the time in seconds for which the
|
||||
difference between the slow tracking signal and the raw
|
||||
signal is allowed to remain out-of-range before a reset
|
||||
event occurs in which the tracking signal is made equal
|
||||
|
|
|
|||
|
|
@ -139,8 +139,8 @@ Description:
|
|||
binary file containing the Vital Product Data for the
|
||||
device. It should follow the VPD format defined in
|
||||
PCI Specification 2.1 or 2.2, but users should consider
|
||||
that some devices may have malformatted data. If the
|
||||
underlying VPD has a writable section then the
|
||||
that some devices may have incorrectly formatted data.
|
||||
If the underlying VPD has a writable section then the
|
||||
corresponding section of this file will be writable.
|
||||
|
||||
What: /sys/bus/pci/devices/.../virtfnN
|
||||
|
|
|
|||
|
|
@ -84,3 +84,103 @@ Description:
|
|||
It can be enabled by writing the value stored in
|
||||
/sys/class/backlight/<backlight>/max_brightness to
|
||||
/sys/class/backlight/<backlight>/brightness.
|
||||
|
||||
What: /sys/class/backlight/<backlight>/<ambient light zone>_max
|
||||
Date: Sep, 2009
|
||||
KernelVersion: v2.6.32
|
||||
Contact: device-drivers-devel@blackfin.uclinux.org
|
||||
Description:
|
||||
Control the maximum brightness for <ambient light zone>
|
||||
on this <backlight>. Values are between 0 and 127. This file
|
||||
will also show the brightness level stored for this
|
||||
<ambient light zone>.
|
||||
|
||||
The <ambient light zone> is device-driver specific:
|
||||
|
||||
For ADP5520 and ADP5501, <ambient light zone> can be:
|
||||
|
||||
=========== ================================================
|
||||
Ambient sysfs entry
|
||||
light zone
|
||||
=========== ================================================
|
||||
daylight /sys/class/backlight/<backlight>/daylight_max
|
||||
office /sys/class/backlight/<backlight>/office_max
|
||||
dark /sys/class/backlight/<backlight>/dark_max
|
||||
=========== ================================================
|
||||
|
||||
For ADP8860, <ambient light zone> can be:
|
||||
|
||||
=========== ================================================
|
||||
Ambient sysfs entry
|
||||
light zone
|
||||
=========== ================================================
|
||||
l1_daylight /sys/class/backlight/<backlight>/l1_daylight_max
|
||||
l2_office /sys/class/backlight/<backlight>/l2_office_max
|
||||
l3_dark /sys/class/backlight/<backlight>/l3_dark_max
|
||||
=========== ================================================
|
||||
|
||||
For ADP8870, <ambient light zone> can be:
|
||||
|
||||
=========== ================================================
|
||||
Ambient sysfs entry
|
||||
light zone
|
||||
=========== ================================================
|
||||
l1_daylight /sys/class/backlight/<backlight>/l1_daylight_max
|
||||
l2_bright /sys/class/backlight/<backlight>/l2_bright_max
|
||||
l3_office /sys/class/backlight/<backlight>/l3_office_max
|
||||
l4_indoor /sys/class/backlight/<backlight>/l4_indoor_max
|
||||
l5_dark /sys/class/backlight/<backlight>/l5_dark_max
|
||||
=========== ================================================
|
||||
|
||||
See also: /sys/class/backlight/<backlight>/ambient_light_zone.
|
||||
|
||||
What: /sys/class/backlight/<backlight>/<ambient light zone>_dim
|
||||
Date: Sep, 2009
|
||||
KernelVersion: v2.6.32
|
||||
Contact: device-drivers-devel@blackfin.uclinux.org
|
||||
Description:
|
||||
Control the dim brightness for <ambient light zone>
|
||||
on this <backlight>. Values are between 0 and 127, typically
|
||||
set to 0. Full off when the backlight is disabled.
|
||||
This file will also show the dim brightness level stored for
|
||||
this <ambient light zone>.
|
||||
|
||||
The <ambient light zone> is device-driver specific:
|
||||
|
||||
For ADP5520 and ADP5501, <ambient light zone> can be:
|
||||
|
||||
=========== ================================================
|
||||
Ambient sysfs entry
|
||||
light zone
|
||||
=========== ================================================
|
||||
daylight /sys/class/backlight/<backlight>/daylight_dim
|
||||
office /sys/class/backlight/<backlight>/office_dim
|
||||
dark /sys/class/backlight/<backlight>/dark_dim
|
||||
=========== ================================================
|
||||
|
||||
For ADP8860, <ambient light zone> can be:
|
||||
|
||||
=========== ================================================
|
||||
Ambient sysfs entry
|
||||
light zone
|
||||
=========== ================================================
|
||||
l1_daylight /sys/class/backlight/<backlight>/l1_daylight_dim
|
||||
l2_office /sys/class/backlight/<backlight>/l2_office_dim
|
||||
l3_dark /sys/class/backlight/<backlight>/l3_dark_dim
|
||||
=========== ================================================
|
||||
|
||||
For ADP8870, <ambient light zone> can be:
|
||||
|
||||
=========== ================================================
|
||||
Ambient sysfs entry
|
||||
light zone
|
||||
=========== ================================================
|
||||
l1_daylight /sys/class/backlight/<backlight>/l1_daylight_dim
|
||||
l2_bright /sys/class/backlight/<backlight>/l2_bright_dim
|
||||
l3_office /sys/class/backlight/<backlight>/l3_office_dim
|
||||
l4_indoor /sys/class/backlight/<backlight>/l4_indoor_dim
|
||||
l5_dark /sys/class/backlight/<backlight>/l5_dark_dim
|
||||
=========== ================================================
|
||||
|
||||
See also: /sys/class/backlight/<backlight>/ambient_light_zone.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,31 +0,0 @@
|
|||
sysfs interface for analog devices adp5520(01) backlight driver
|
||||
---------------------------------------------------------------
|
||||
|
||||
The backlight brightness control operates at three different levels for the
|
||||
adp5520 and adp5501 devices: daylight (level 1), office (level 2) and dark
|
||||
(level 3). By default the brightness operates at the daylight brightness level.
|
||||
|
||||
What: /sys/class/backlight/<backlight>/daylight_max
|
||||
What: /sys/class/backlight/<backlight>/office_max
|
||||
What: /sys/class/backlight/<backlight>/dark_max
|
||||
Date: Sep, 2009
|
||||
KernelVersion: v2.6.32
|
||||
Contact: Michael Hennerich <michael.hennerich@analog.com>
|
||||
Description:
|
||||
(RW) Maximum current setting for the backlight when brightness
|
||||
is at one of the three levels (daylight, office or dark). This
|
||||
is an input code between 0 and 127, which is transformed to a
|
||||
value between 0 mA and 30 mA using linear or non-linear
|
||||
algorithms.
|
||||
|
||||
What: /sys/class/backlight/<backlight>/daylight_dim
|
||||
What: /sys/class/backlight/<backlight>/office_dim
|
||||
What: /sys/class/backlight/<backlight>/dark_dim
|
||||
Date: Sep, 2009
|
||||
KernelVersion: v2.6.32
|
||||
Contact: Michael Hennerich <michael.hennerich@analog.com>
|
||||
Description:
|
||||
(RW) Dim current setting for the backlight when brightness is at
|
||||
one of the three levels (daylight, office or dark). This is an
|
||||
input code between 0 and 127, which is transformed to a value
|
||||
between 0 mA and 30 mA using linear or non-linear algorithms.
|
||||
|
|
@ -1,37 +0,0 @@
|
|||
sysfs interface for analog devices adp8860 backlight driver
|
||||
-----------------------------------------------------------
|
||||
|
||||
The backlight brightness control operates at three different levels for the
|
||||
adp8860, adp8861 and adp8863 devices: daylight (level 1), office (level 2) and
|
||||
dark (level 3). By default the brightness operates at the daylight brightness
|
||||
level.
|
||||
|
||||
See also /sys/class/backlight/<backlight>/ambient_light_level and
|
||||
/sys/class/backlight/<backlight>/ambient_light_zone.
|
||||
|
||||
|
||||
What: /sys/class/backlight/<backlight>/l1_daylight_max
|
||||
What: /sys/class/backlight/<backlight>/l2_office_max
|
||||
What: /sys/class/backlight/<backlight>/l3_dark_max
|
||||
Date: Apr, 2010
|
||||
KernelVersion: v2.6.35
|
||||
Contact: Michael Hennerich <michael.hennerich@analog.com>
|
||||
Description:
|
||||
(RW) Maximum current setting for the backlight when brightness
|
||||
is at one of the three levels (daylight, office or dark). This
|
||||
is an input code between 0 and 127, which is transformed to a
|
||||
value between 0 mA and 30 mA using linear or non-linear
|
||||
algorithms.
|
||||
|
||||
|
||||
What: /sys/class/backlight/<backlight>/l1_daylight_dim
|
||||
What: /sys/class/backlight/<backlight>/l2_office_dim
|
||||
What: /sys/class/backlight/<backlight>/l3_dark_dim
|
||||
Date: Apr, 2010
|
||||
KernelVersion: v2.6.35
|
||||
Contact: Michael Hennerich <michael.hennerich@analog.com>
|
||||
Description:
|
||||
(RW) Dim current setting for the backlight when brightness is at
|
||||
one of the three levels (daylight, office or dark). This is an
|
||||
input code between 0 and 127, which is transformed to a value
|
||||
between 0 mA and 30 mA using linear or non-linear algorithms.
|
||||
|
|
@ -1,32 +0,0 @@
|
|||
See also /sys/class/backlight/<backlight>/ambient_light_level and
|
||||
/sys/class/backlight/<backlight>/ambient_light_zone.
|
||||
|
||||
What: /sys/class/backlight/<backlight>/<ambient light zone>_max
|
||||
What: /sys/class/backlight/<backlight>/l1_daylight_max
|
||||
What: /sys/class/backlight/<backlight>/l2_bright_max
|
||||
What: /sys/class/backlight/<backlight>/l3_office_max
|
||||
What: /sys/class/backlight/<backlight>/l4_indoor_max
|
||||
What: /sys/class/backlight/<backlight>/l5_dark_max
|
||||
Date: May 2011
|
||||
KernelVersion: 3.0
|
||||
Contact: device-drivers-devel@blackfin.uclinux.org
|
||||
Description:
|
||||
Control the maximum brightness for <ambient light zone>
|
||||
on this <backlight>. Values are between 0 and 127. This file
|
||||
will also show the brightness level stored for this
|
||||
<ambient light zone>.
|
||||
|
||||
What: /sys/class/backlight/<backlight>/<ambient light zone>_dim
|
||||
What: /sys/class/backlight/<backlight>/l2_bright_dim
|
||||
What: /sys/class/backlight/<backlight>/l3_office_dim
|
||||
What: /sys/class/backlight/<backlight>/l4_indoor_dim
|
||||
What: /sys/class/backlight/<backlight>/l5_dark_dim
|
||||
Date: May 2011
|
||||
KernelVersion: 3.0
|
||||
Contact: device-drivers-devel@blackfin.uclinux.org
|
||||
Description:
|
||||
Control the dim brightness for <ambient light zone>
|
||||
on this <backlight>. Values are between 0 and 127, typically
|
||||
set to 0. Full off when the backlight is disabled.
|
||||
This file will also show the dim brightness level stored for
|
||||
this <ambient light zone>.
|
||||
|
|
@ -1,9 +0,0 @@
|
|||
What: /sys/class/leds/<led>/repeat
|
||||
Date: September 2019
|
||||
KernelVersion: 5.5
|
||||
Description:
|
||||
EL15203000 supports only indefinitely patterns,
|
||||
so this file should always store -1.
|
||||
|
||||
For more info, please see:
|
||||
Documentation/ABI/testing/sysfs-class-led-trigger-pattern
|
||||
|
|
@ -35,3 +35,6 @@ Description:
|
|||
|
||||
This file will always return the originally written repeat
|
||||
number.
|
||||
|
||||
It should be noticed that some leds, like EL15203000 may
|
||||
only support indefinitely patterns, so they always store -1.
|
||||
|
|
|
|||
|
|
@ -50,7 +50,7 @@ Description: Dynamic addition and removal of CPU's. This is not hotplug
|
|||
architecture specific.
|
||||
|
||||
release: writes to this file dynamically remove a CPU from
|
||||
the system. Information writtento the file to remove CPU's
|
||||
the system. Information written to the file to remove CPU's
|
||||
is architecture specific.
|
||||
|
||||
What: /sys/devices/system/cpu/cpu#/node
|
||||
|
|
@ -97,7 +97,7 @@ Description: CPU topology files that describe a logical CPU's relationship
|
|||
corresponds to a physical socket number, but the actual value
|
||||
is architecture and platform dependent.
|
||||
|
||||
thread_siblings: internel kernel map of cpu#'s hardware
|
||||
thread_siblings: internal kernel map of cpu#'s hardware
|
||||
threads within the same core as cpu#
|
||||
|
||||
thread_siblings_list: human-readable list of cpu#'s hardware
|
||||
|
|
@ -280,7 +280,7 @@ Description: Disable L3 cache indices
|
|||
on a processor with this functionality will return the currently
|
||||
disabled index for that node. There is one L3 structure per
|
||||
node, or per internal node on MCM machines. Writing a valid
|
||||
index to one of these files will cause the specificed cache
|
||||
index to one of these files will cause the specified cache
|
||||
index to be disabled.
|
||||
|
||||
All AMD processors with L3 caches provide this functionality.
|
||||
|
|
@ -295,7 +295,7 @@ Description: Processor frequency boosting control
|
|||
|
||||
This switch controls the boost setting for the whole system.
|
||||
Boosting allows the CPU and the firmware to run at a frequency
|
||||
beyound it's nominal limit.
|
||||
beyond it's nominal limit.
|
||||
|
||||
More details can be found in
|
||||
Documentation/admin-guide/pm/cpufreq.rst
|
||||
|
|
@ -532,7 +532,7 @@ What: /sys/devices/system/cpu/smt
|
|||
/sys/devices/system/cpu/smt/control
|
||||
Date: June 2018
|
||||
Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
|
||||
Description: Control Symetric Multi Threading (SMT)
|
||||
Description: Control Symmetric Multi Threading (SMT)
|
||||
|
||||
active: Tells whether SMT is active (enabled and siblings online)
|
||||
|
||||
|
|
|
|||
|
|
@ -168,7 +168,7 @@ Description: This file shows the manufacturing date in BCD format.
|
|||
What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/manufacturer_id
|
||||
Date: February 2018
|
||||
Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
|
||||
Description: This file shows the manufacturee ID. This is one of the
|
||||
Description: This file shows the manufacturer ID. This is one of the
|
||||
UFS device descriptor parameters. The full information about
|
||||
the descriptor could be found at UFS specifications 2.1.
|
||||
|
||||
|
|
@ -521,7 +521,7 @@ Description: This file shows maximum VCC, VCCQ and VCCQ2 value for
|
|||
What: /sys/bus/platform/drivers/ufshcd/*/string_descriptors/manufacturer_name
|
||||
Date: February 2018
|
||||
Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
|
||||
Description: This file contains a device manufactureer name string.
|
||||
Description: This file contains a device manufacturer name string.
|
||||
The full information about the descriptor could be found at
|
||||
UFS specifications 2.1.
|
||||
|
||||
|
|
|
|||
|
|
@ -238,7 +238,7 @@ Description: Shows current reserved blocks in system, it may be temporarily
|
|||
What: /sys/fs/f2fs/<disk>/gc_urgent
|
||||
Date: August 2017
|
||||
Contact: "Jaegeuk Kim" <jaegeuk@kernel.org>
|
||||
Description: Do background GC agressively when set. When gc_urgent = 1,
|
||||
Description: Do background GC aggressively when set. When gc_urgent = 1,
|
||||
background thread starts to do GC by given gc_urgent_sleep_time
|
||||
interval. When gc_urgent = 2, F2FS will lower the bar of
|
||||
checking idle in order to process outstanding discard commands
|
||||
|
|
|
|||
|
|
@ -25,14 +25,10 @@ Description: /sys/kernel/iommu_groups/reserved_regions list IOVA
|
|||
the base IOVA, the second is the end IOVA and the third
|
||||
field describes the type of the region.
|
||||
|
||||
What: /sys/kernel/iommu_groups/reserved_regions
|
||||
Date: June 2019
|
||||
KernelVersion: v5.3
|
||||
Contact: Eric Auger <eric.auger@redhat.com>
|
||||
Description: In case an RMRR is used only by graphics or USB devices
|
||||
it is now exposed as "direct-relaxable" instead of "direct".
|
||||
In device assignment use case, for instance, those RMRR
|
||||
are considered to be relaxable and safe.
|
||||
Since kernel 5.3, in case an RMRR is used only by graphics or
|
||||
USB devices it is now exposed as "direct-relaxable" instead
|
||||
of "direct". In device assignment use case, for instance,
|
||||
those RMRR are considered to be relaxable and safe.
|
||||
|
||||
What: /sys/kernel/iommu_groups/<grp_id>/type
|
||||
Date: November 2020
|
||||
|
|
|
|||
|
|
@ -76,7 +76,7 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
|
|||
PYTHONDONTWRITEBYTECODE=1 \
|
||||
BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \
|
||||
$(PYTHON3) $(srctree)/scripts/jobserver-exec \
|
||||
$(SHELL) $(srctree)/Documentation/sphinx/parallel-wrapper.sh \
|
||||
$(CONFIG_SHELL) $(srctree)/Documentation/sphinx/parallel-wrapper.sh \
|
||||
$(SPHINXBUILD) \
|
||||
-b $2 \
|
||||
-c $(abspath $(srctree)/$(src)) \
|
||||
|
|
|
|||
|
|
@ -22,9 +22,9 @@ or if the device has INTx interrupts connected by platform interrupt
|
|||
controllers and a _PRT is needed to describe those connections.
|
||||
|
||||
ACPI resource description is done via _CRS objects of devices in the ACPI
|
||||
namespace [2]. The _CRS is like a generalized PCI BAR: the OS can read
|
||||
namespace [2]. The _CRS is like a generalized PCI BAR: the OS can read
|
||||
_CRS and figure out what resource is being consumed even if it doesn't have
|
||||
a driver for the device [3]. That's important because it means an old OS
|
||||
a driver for the device [3]. That's important because it means an old OS
|
||||
can work correctly even on a system with new devices unknown to the OS.
|
||||
The new devices might not do anything, but the OS can at least make sure no
|
||||
resources conflict with them.
|
||||
|
|
@ -41,15 +41,15 @@ ACPI, that device will have a specific _HID/_CID that tells the OS what
|
|||
driver to bind to it, and the _CRS tells the OS and the driver where the
|
||||
device's registers are.
|
||||
|
||||
PCI host bridges are PNP0A03 or PNP0A08 devices. Their _CRS should
|
||||
describe all the address space they consume. This includes all the windows
|
||||
PCI host bridges are PNP0A03 or PNP0A08 devices. Their _CRS should
|
||||
describe all the address space they consume. This includes all the windows
|
||||
they forward down to the PCI bus, as well as registers of the host bridge
|
||||
itself that are not forwarded to PCI. The host bridge registers include
|
||||
itself that are not forwarded to PCI. The host bridge registers include
|
||||
things like secondary/subordinate bus registers that determine the bus
|
||||
range below the bridge, window registers that describe the apertures, etc.
|
||||
These are all device-specific, non-architected things, so the only way a
|
||||
PNP0A03/PNP0A08 driver can manage them is via _PRS/_CRS/_SRS, which contain
|
||||
the device-specific details. The host bridge registers also include ECAM
|
||||
the device-specific details. The host bridge registers also include ECAM
|
||||
space, since it is consumed by the host bridge.
|
||||
|
||||
ACPI defines a Consumer/Producer bit to distinguish the bridge registers
|
||||
|
|
@ -66,7 +66,7 @@ the PNP0A03/PNP0A08 device itself. The workaround was to describe the
|
|||
bridge registers (including ECAM space) in PNP0C02 catch-all devices [6].
|
||||
With the exception of ECAM, the bridge register space is device-specific
|
||||
anyway, so the generic PNP0A03/PNP0A08 driver (pci_root.c) has no need to
|
||||
know about it.
|
||||
know about it.
|
||||
|
||||
New architectures should be able to use "Consumer" Extended Address Space
|
||||
descriptors in the PNP0A03 device for bridge registers, including ECAM,
|
||||
|
|
@ -75,9 +75,9 @@ ia64 kernels assume all address space descriptors, including "Consumer"
|
|||
Extended Address Space ones, are windows, so it would not be safe to
|
||||
describe bridge registers this way on those architectures.
|
||||
|
||||
PNP0C02 "motherboard" devices are basically a catch-all. There's no
|
||||
PNP0C02 "motherboard" devices are basically a catch-all. There's no
|
||||
programming model for them other than "don't use these resources for
|
||||
anything else." So a PNP0C02 _CRS should claim any address space that is
|
||||
anything else." So a PNP0C02 _CRS should claim any address space that is
|
||||
(1) not claimed by _CRS under any other device object in the ACPI namespace
|
||||
and (2) should not be assigned by the OS to something else.
|
||||
|
||||
|
|
|
|||
|
|
@ -125,4 +125,4 @@ all the EPF devices are created and linked with the EPC device.
|
|||
| interrupt_pin
|
||||
| function
|
||||
|
||||
[1] :doc:`pci-endpoint`
|
||||
[1] Documentation/PCI/endpoint/pci-endpoint.rst
|
||||
|
|
|
|||
|
|
@ -265,7 +265,7 @@ Set the DMA mask size
|
|||
---------------------
|
||||
.. note::
|
||||
If anything below doesn't make sense, please refer to
|
||||
:doc:`/core-api/dma-api`. This section is just a reminder that
|
||||
Documentation/core-api/dma-api.rst. This section is just a reminder that
|
||||
drivers need to indicate DMA capabilities of the device and is not
|
||||
an authoritative source for DMA interfaces.
|
||||
|
||||
|
|
@ -291,7 +291,7 @@ Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are
|
|||
Setup shared control data
|
||||
-------------------------
|
||||
Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared)
|
||||
memory. See :doc:`/core-api/dma-api` for a full description of
|
||||
memory. See Documentation/core-api/dma-api.rst for a full description of
|
||||
the DMA APIs. This section is just a reminder that it needs to be done
|
||||
before enabling DMA on the device.
|
||||
|
||||
|
|
@ -421,7 +421,7 @@ owners if there is one.
|
|||
|
||||
Then clean up "consistent" buffers which contain the control data.
|
||||
|
||||
See :doc:`/core-api/dma-api` for details on unmapping interfaces.
|
||||
See Documentation/core-api/dma-api.rst for details on unmapping interfaces.
|
||||
|
||||
|
||||
Unregister from other subsystems
|
||||
|
|
|
|||
|
|
@ -2,87 +2,10 @@
|
|||
How CPU topology info is exported via sysfs
|
||||
===========================================
|
||||
|
||||
Export CPU topology info via sysfs. Items (attributes) are similar
|
||||
to /proc/cpuinfo output of some architectures. They reside in
|
||||
/sys/devices/system/cpu/cpuX/topology/:
|
||||
|
||||
physical_package_id:
|
||||
|
||||
physical package id of cpuX. Typically corresponds to a physical
|
||||
socket number, but the actual value is architecture and platform
|
||||
dependent.
|
||||
|
||||
die_id:
|
||||
|
||||
the CPU die ID of cpuX. Typically it is the hardware platform's
|
||||
identifier (rather than the kernel's). The actual value is
|
||||
architecture and platform dependent.
|
||||
|
||||
core_id:
|
||||
|
||||
the CPU core ID of cpuX. Typically it is the hardware platform's
|
||||
identifier (rather than the kernel's). The actual value is
|
||||
architecture and platform dependent.
|
||||
|
||||
book_id:
|
||||
|
||||
the book ID of cpuX. Typically it is the hardware platform's
|
||||
identifier (rather than the kernel's). The actual value is
|
||||
architecture and platform dependent.
|
||||
|
||||
drawer_id:
|
||||
|
||||
the drawer ID of cpuX. Typically it is the hardware platform's
|
||||
identifier (rather than the kernel's). The actual value is
|
||||
architecture and platform dependent.
|
||||
|
||||
core_cpus:
|
||||
|
||||
internal kernel map of CPUs within the same core.
|
||||
(deprecated name: "thread_siblings")
|
||||
|
||||
core_cpus_list:
|
||||
|
||||
human-readable list of CPUs within the same core.
|
||||
(deprecated name: "thread_siblings_list");
|
||||
|
||||
package_cpus:
|
||||
|
||||
internal kernel map of the CPUs sharing the same physical_package_id.
|
||||
(deprecated name: "core_siblings")
|
||||
|
||||
package_cpus_list:
|
||||
|
||||
human-readable list of CPUs sharing the same physical_package_id.
|
||||
(deprecated name: "core_siblings_list")
|
||||
|
||||
die_cpus:
|
||||
|
||||
internal kernel map of CPUs within the same die.
|
||||
|
||||
die_cpus_list:
|
||||
|
||||
human-readable list of CPUs within the same die.
|
||||
|
||||
book_siblings:
|
||||
|
||||
internal kernel map of cpuX's hardware threads within the same
|
||||
book_id.
|
||||
|
||||
book_siblings_list:
|
||||
|
||||
human-readable list of cpuX's hardware threads within the same
|
||||
book_id.
|
||||
|
||||
drawer_siblings:
|
||||
|
||||
internal kernel map of cpuX's hardware threads within the same
|
||||
drawer_id.
|
||||
|
||||
drawer_siblings_list:
|
||||
|
||||
human-readable list of cpuX's hardware threads within the same
|
||||
drawer_id.
|
||||
CPU topology info is exported via sysfs. Items (attributes) are similar
|
||||
to /proc/cpuinfo output of some architectures. They reside in
|
||||
/sys/devices/system/cpu/cpuX/topology/. Please refer to the ABI file:
|
||||
Documentation/ABI/stable/sysfs-devices-system-cpu.
|
||||
|
||||
Architecture-neutral, drivers/base/topology.c, exports these attributes.
|
||||
However, the book and drawer related sysfs files will only be created if
|
||||
|
|
|
|||
|
|
@ -392,7 +392,7 @@ When mounting an ext4 filesystem, the following option are accepted:
|
|||
|
||||
dax
|
||||
Use direct access (no page cache). See
|
||||
Documentation/filesystems/dax.txt. Note that this option is
|
||||
Documentation/filesystems/dax.rst. Note that this option is
|
||||
incompatible with data=journal.
|
||||
|
||||
inlinecrypt
|
||||
|
|
|
|||
|
|
@ -3,7 +3,8 @@
|
|||
SRBDS - Special Register Buffer Data Sampling
|
||||
=============================================
|
||||
|
||||
SRBDS is a hardware vulnerability that allows MDS :doc:`mds` techniques to
|
||||
SRBDS is a hardware vulnerability that allows MDS
|
||||
Documentation/admin-guide/hw-vuln/mds.rst techniques to
|
||||
infer values returned from special register accesses. Special register
|
||||
accesses are accesses to off core registers. According to Intel's evaluation,
|
||||
the special register reads that have a security expectation of privacy are
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
Documentation for Kdump - The kexec-based Crash Dumping Solution
|
||||
================================================================
|
||||
|
||||
This document includes overview, setup and installation, and analysis
|
||||
This document includes overview, setup, installation, and analysis
|
||||
information.
|
||||
|
||||
Overview
|
||||
|
|
@ -13,9 +13,9 @@ dump of the system kernel's memory needs to be taken (for example, when
|
|||
the system panics). The system kernel's memory image is preserved across
|
||||
the reboot and is accessible to the dump-capture kernel.
|
||||
|
||||
You can use common commands, such as cp and scp, to copy the
|
||||
memory image to a dump file on the local disk, or across the network to
|
||||
a remote system.
|
||||
You can use common commands, such as cp, scp or makedumpfile to copy
|
||||
the memory image to a dump file on the local disk, or across the network
|
||||
to a remote system.
|
||||
|
||||
Kdump and kexec are currently supported on the x86, x86_64, ppc64, ia64,
|
||||
s390x, arm and arm64 architectures.
|
||||
|
|
@ -26,13 +26,15 @@ the dump-capture kernel. This ensures that ongoing Direct Memory Access
|
|||
The kexec -p command loads the dump-capture kernel into this reserved
|
||||
memory.
|
||||
|
||||
On x86 machines, the first 640 KB of physical memory is needed to boot,
|
||||
regardless of where the kernel loads. Therefore, kexec backs up this
|
||||
region just before rebooting into the dump-capture kernel.
|
||||
On x86 machines, the first 640 KB of physical memory is needed for boot,
|
||||
regardless of where the kernel loads. For simpler handling, the whole
|
||||
low 1M is reserved to avoid any later kernel or device driver writing
|
||||
data into this area. Like this, the low 1M can be reused as system RAM
|
||||
by kdump kernel without extra handling.
|
||||
|
||||
Similarly on PPC64 machines first 32KB of physical memory is needed for
|
||||
booting regardless of where the kernel is loaded and to support 64K page
|
||||
size kexec backs up the first 64KB memory.
|
||||
On PPC64 machines first 32KB of physical memory is needed for booting
|
||||
regardless of where the kernel is loaded and to support 64K page size
|
||||
kexec backs up the first 64KB memory.
|
||||
|
||||
For s390x, when kdump is triggered, the crashkernel region is exchanged
|
||||
with the region [0, crashkernel region size] and then the kdump kernel
|
||||
|
|
@ -46,14 +48,14 @@ passed to the dump-capture kernel through the elfcorehdr= boot
|
|||
parameter. Optionally the size of the ELF header can also be passed
|
||||
when using the elfcorehdr=[size[KMG]@]offset[KMG] syntax.
|
||||
|
||||
|
||||
With the dump-capture kernel, you can access the memory image through
|
||||
/proc/vmcore. This exports the dump as an ELF-format file that you can
|
||||
write out using file copy commands such as cp or scp. Further, you can
|
||||
use analysis tools such as the GNU Debugger (GDB) and the Crash tool to
|
||||
debug the dump file. This method ensures that the dump pages are correctly
|
||||
ordered.
|
||||
|
||||
write out using file copy commands such as cp or scp. You can also use
|
||||
makedumpfile utility to analyze and write out filtered contents with
|
||||
options, e.g with '-d 31' it will only write out kernel data. Further,
|
||||
you can use analysis tools such as the GNU Debugger (GDB) and the Crash
|
||||
tool to debug the dump file. This method ensures that the dump pages are
|
||||
correctly ordered.
|
||||
|
||||
Setup and Installation
|
||||
======================
|
||||
|
|
@ -125,9 +127,18 @@ dump-capture kernels for enabling kdump support.
|
|||
System kernel config options
|
||||
----------------------------
|
||||
|
||||
1) Enable "kexec system call" in "Processor type and features."::
|
||||
1) Enable "kexec system call" or "kexec file based system call" in
|
||||
"Processor type and features."::
|
||||
|
||||
CONFIG_KEXEC=y
|
||||
CONFIG_KEXEC=y or CONFIG_KEXEC_FILE=y
|
||||
|
||||
And both of them will select KEXEC_CORE::
|
||||
|
||||
CONFIG_KEXEC_CORE=y
|
||||
|
||||
Subsequently, CRASH_CORE is selected by KEXEC_CORE::
|
||||
|
||||
CONFIG_CRASH_CORE=y
|
||||
|
||||
2) Enable "sysfs file system support" in "Filesystem" -> "Pseudo
|
||||
filesystems." This is usually enabled by default::
|
||||
|
|
@ -175,17 +186,19 @@ Dump-capture kernel config options (Arch Dependent, i386 and x86_64)
|
|||
|
||||
CONFIG_HIGHMEM4G
|
||||
|
||||
2) On i386 and x86_64, disable symmetric multi-processing support
|
||||
under "Processor type and features"::
|
||||
2) With CONFIG_SMP=y, usually nr_cpus=1 need specified on the kernel
|
||||
command line when loading the dump-capture kernel because one
|
||||
CPU is enough for kdump kernel to dump vmcore on most of systems.
|
||||
|
||||
CONFIG_SMP=n
|
||||
However, you can also specify nr_cpus=X to enable multiple processors
|
||||
in kdump kernel. In this case, "disable_cpu_apicid=" is needed to
|
||||
tell kdump kernel which cpu is 1st kernel's BSP. Please refer to
|
||||
admin-guide/kernel-parameters.txt for more details.
|
||||
|
||||
(If CONFIG_SMP=y, then specify maxcpus=1 on the kernel command line
|
||||
when loading the dump-capture kernel, see section "Load the Dump-capture
|
||||
Kernel".)
|
||||
With CONFIG_SMP=n, the above things are not related.
|
||||
|
||||
3) If one wants to build and use a relocatable kernel,
|
||||
Enable "Build a relocatable kernel" support under "Processor type and
|
||||
3) A relocatable kernel is suggested to be built by default. If not yet,
|
||||
enable "Build a relocatable kernel" support under "Processor type and
|
||||
features"::
|
||||
|
||||
CONFIG_RELOCATABLE=y
|
||||
|
|
@ -232,7 +245,7 @@ Dump-capture kernel config options (Arch Dependent, ia64)
|
|||
as a dump-capture kernel if desired.
|
||||
|
||||
The crashkernel region can be automatically placed by the system
|
||||
kernel at run time. This is done by specifying the base address as 0,
|
||||
kernel at runtime. This is done by specifying the base address as 0,
|
||||
or omitting it all together::
|
||||
|
||||
crashkernel=256M@0
|
||||
|
|
@ -241,10 +254,6 @@ Dump-capture kernel config options (Arch Dependent, ia64)
|
|||
|
||||
crashkernel=256M
|
||||
|
||||
If the start address is specified, note that the start address of the
|
||||
kernel will be aligned to 64Mb, so if the start address is not then
|
||||
any space below the alignment point will be wasted.
|
||||
|
||||
Dump-capture kernel config options (Arch Dependent, arm)
|
||||
----------------------------------------------------------
|
||||
|
||||
|
|
@ -260,46 +269,82 @@ Dump-capture kernel config options (Arch Dependent, arm64)
|
|||
on non-VHE systems even if it is configured. This is because the CPU
|
||||
will not be reset to EL2 on panic.
|
||||
|
||||
Extended crashkernel syntax
|
||||
crashkernel syntax
|
||||
===========================
|
||||
1) crashkernel=size@offset
|
||||
|
||||
While the "crashkernel=size[@offset]" syntax is sufficient for most
|
||||
configurations, sometimes it's handy to have the reserved memory dependent
|
||||
on the value of System RAM -- that's mostly for distributors that pre-setup
|
||||
the kernel command line to avoid a unbootable system after some memory has
|
||||
been removed from the machine.
|
||||
|
||||
The syntax is::
|
||||
|
||||
crashkernel=<range1>:<size1>[,<range2>:<size2>,...][@offset]
|
||||
range=start-[end]
|
||||
|
||||
For example::
|
||||
|
||||
crashkernel=512M-2G:64M,2G-:128M
|
||||
|
||||
This would mean:
|
||||
|
||||
1) if the RAM is smaller than 512M, then don't reserve anything
|
||||
(this is the "rescue" case)
|
||||
2) if the RAM size is between 512M and 2G (exclusive), then reserve 64M
|
||||
3) if the RAM size is larger than 2G, then reserve 128M
|
||||
|
||||
|
||||
|
||||
Boot into System Kernel
|
||||
=======================
|
||||
|
||||
1) Update the boot loader (such as grub, yaboot, or lilo) configuration
|
||||
files as necessary.
|
||||
|
||||
2) Boot the system kernel with the boot parameter "crashkernel=Y@X",
|
||||
where Y specifies how much memory to reserve for the dump-capture kernel
|
||||
and X specifies the beginning of this reserved memory. For example,
|
||||
Here 'size' specifies how much memory to reserve for the dump-capture kernel
|
||||
and 'offset' specifies the beginning of this reserved memory. For example,
|
||||
"crashkernel=64M@16M" tells the system kernel to reserve 64 MB of memory
|
||||
starting at physical address 0x01000000 (16MB) for the dump-capture kernel.
|
||||
|
||||
On x86 and x86_64, use "crashkernel=64M@16M".
|
||||
The crashkernel region can be automatically placed by the system
|
||||
kernel at run time. This is done by specifying the base address as 0,
|
||||
or omitting it all together::
|
||||
|
||||
crashkernel=256M@0
|
||||
|
||||
or::
|
||||
|
||||
crashkernel=256M
|
||||
|
||||
If the start address is specified, note that the start address of the
|
||||
kernel will be aligned to a value (which is Arch dependent), so if the
|
||||
start address is not then any space below the alignment point will be
|
||||
wasted.
|
||||
|
||||
2) range1:size1[,range2:size2,...][@offset]
|
||||
|
||||
While the "crashkernel=size[@offset]" syntax is sufficient for most
|
||||
configurations, sometimes it's handy to have the reserved memory dependent
|
||||
on the value of System RAM -- that's mostly for distributors that pre-setup
|
||||
the kernel command line to avoid a unbootable system after some memory has
|
||||
been removed from the machine.
|
||||
|
||||
The syntax is::
|
||||
|
||||
crashkernel=<range1>:<size1>[,<range2>:<size2>,...][@offset]
|
||||
range=start-[end]
|
||||
|
||||
For example::
|
||||
|
||||
crashkernel=512M-2G:64M,2G-:128M
|
||||
|
||||
This would mean:
|
||||
|
||||
1) if the RAM is smaller than 512M, then don't reserve anything
|
||||
(this is the "rescue" case)
|
||||
2) if the RAM size is between 512M and 2G (exclusive), then reserve 64M
|
||||
3) if the RAM size is larger than 2G, then reserve 128M
|
||||
|
||||
3) crashkernel=size,high and crashkernel=size,low
|
||||
|
||||
If memory above 4G is preferred, crashkernel=size,high can be used to
|
||||
fulfill that. With it, physical memory is allowed to be allocated from top,
|
||||
so could be above 4G if system has more than 4G RAM installed. Otherwise,
|
||||
memory region will be allocated below 4G if available.
|
||||
|
||||
When crashkernel=X,high is passed, kernel could allocate physical memory
|
||||
region above 4G, low memory under 4G is needed in this case. There are
|
||||
three ways to get low memory:
|
||||
|
||||
1) Kernel will allocate at least 256M memory below 4G automatically
|
||||
if crashkernel=Y,low is not specified.
|
||||
2) Let user specify low memory size instead.
|
||||
3) Specified value 0 will disable low memory allocation::
|
||||
|
||||
crashkernel=0,low
|
||||
|
||||
Boot into System Kernel
|
||||
-----------------------
|
||||
1) Update the boot loader (such as grub, yaboot, or lilo) configuration
|
||||
files as necessary.
|
||||
|
||||
2) Boot the system kernel with the boot parameter "crashkernel=Y@X".
|
||||
|
||||
On x86 and x86_64, use "crashkernel=Y[@X]". Most of the time, the
|
||||
start address 'X' is not necessary, kernel will search a suitable
|
||||
area. Unless an explicit start address is expected.
|
||||
|
||||
On ppc64, use "crashkernel=128M@32M".
|
||||
|
||||
|
|
@ -331,8 +376,8 @@ of dump-capture kernel. Following is the summary.
|
|||
|
||||
For i386 and x86_64:
|
||||
|
||||
- Use vmlinux if kernel is not relocatable.
|
||||
- Use bzImage/vmlinuz if kernel is relocatable.
|
||||
- Use vmlinux if kernel is not relocatable.
|
||||
|
||||
For ppc64:
|
||||
|
||||
|
|
@ -392,7 +437,7 @@ loading dump-capture kernel.
|
|||
|
||||
For i386, x86_64 and ia64:
|
||||
|
||||
"1 irqpoll maxcpus=1 reset_devices"
|
||||
"1 irqpoll nr_cpus=1 reset_devices"
|
||||
|
||||
For ppc64:
|
||||
|
||||
|
|
@ -400,7 +445,7 @@ For ppc64:
|
|||
|
||||
For s390x:
|
||||
|
||||
"1 maxcpus=1 cgroup_disable=memory"
|
||||
"1 nr_cpus=1 cgroup_disable=memory"
|
||||
|
||||
For arm:
|
||||
|
||||
|
|
@ -408,7 +453,7 @@ For arm:
|
|||
|
||||
For arm64:
|
||||
|
||||
"1 maxcpus=1 reset_devices"
|
||||
"1 nr_cpus=1 reset_devices"
|
||||
|
||||
Notes on loading the dump-capture kernel:
|
||||
|
||||
|
|
@ -488,6 +533,10 @@ the following command::
|
|||
|
||||
cp /proc/vmcore <dump-file>
|
||||
|
||||
You can also use makedumpfile utility to write out the dump file
|
||||
with specified options to filter out unwanted contents, e.g::
|
||||
|
||||
makedumpfile -l --message-level 1 -d 31 /proc/vmcore <dump-file>
|
||||
|
||||
Analysis
|
||||
========
|
||||
|
|
@ -535,8 +584,7 @@ This will cause a kdump to occur at the add_taint()->panic() call.
|
|||
Contact
|
||||
=======
|
||||
|
||||
- Vivek Goyal (vgoyal@redhat.com)
|
||||
- Maneesh Soni (maneesh@in.ibm.com)
|
||||
- kexec@lists.infradead.org
|
||||
|
||||
GDB macros
|
||||
==========
|
||||
|
|
|
|||
|
|
@ -3513,6 +3513,9 @@
|
|||
|
||||
nr_uarts= [SERIAL] maximum number of UARTs to be registered.
|
||||
|
||||
numa=off [KNL, ARM64, PPC, RISCV, SPARC, X86] Disable NUMA, Only
|
||||
set up a single NUMA node spanning all memory.
|
||||
|
||||
numa_balancing= [KNL,ARM64,PPC,RISCV,S390,X86] Enable or disable automatic
|
||||
NUMA balancing.
|
||||
Allowed values are enable and disable
|
||||
|
|
|
|||
|
|
@ -20,8 +20,8 @@ Nehalem and later generations of Intel processors, but the level of support for
|
|||
a particular processor model in it depends on whether or not it recognizes that
|
||||
processor model and may also depend on information coming from the platform
|
||||
firmware. [To understand ``intel_idle`` it is necessary to know how ``CPUIdle``
|
||||
works in general, so this is the time to get familiar with :doc:`cpuidle` if you
|
||||
have not done that yet.]
|
||||
works in general, so this is the time to get familiar with
|
||||
Documentation/admin-guide/pm/cpuidle.rst if you have not done that yet.]
|
||||
|
||||
``intel_idle`` uses the ``MWAIT`` instruction to inform the processor that the
|
||||
logical CPU executing it is idle and so it may be possible to put some of the
|
||||
|
|
@ -53,7 +53,8 @@ processor) corresponding to them depends on the processor model and it may also
|
|||
depend on the configuration of the platform.
|
||||
|
||||
In order to create a list of available idle states required by the ``CPUIdle``
|
||||
subsystem (see :ref:`idle-states-representation` in :doc:`cpuidle`),
|
||||
subsystem (see :ref:`idle-states-representation` in
|
||||
Documentation/admin-guide/pm/cpuidle.rst),
|
||||
``intel_idle`` can use two sources of information: static tables of idle states
|
||||
for different processor models included in the driver itself and the ACPI tables
|
||||
of the system. The former are always used if the processor model at hand is
|
||||
|
|
@ -98,7 +99,8 @@ states may not be enabled by default if there are no matching entries in the
|
|||
preliminary list of idle states coming from the ACPI tables. In that case user
|
||||
space still can enable them later (on a per-CPU basis) with the help of
|
||||
the ``disable`` idle state attribute in ``sysfs`` (see
|
||||
:ref:`idle-states-representation` in :doc:`cpuidle`). This basically means that
|
||||
:ref:`idle-states-representation` in
|
||||
Documentation/admin-guide/pm/cpuidle.rst). This basically means that
|
||||
the idle states "known" to the driver may not be enabled by default if they have
|
||||
not been exposed by the platform firmware (through the ACPI tables).
|
||||
|
||||
|
|
@ -186,7 +188,8 @@ be desirable. In practice, it is only really necessary to do that if the idle
|
|||
states in question cannot be enabled during system startup, because in the
|
||||
working state of the system the CPU power management quality of service (PM
|
||||
QoS) feature can be used to prevent ``CPUIdle`` from touching those idle states
|
||||
even if they have been enumerated (see :ref:`cpu-pm-qos` in :doc:`cpuidle`).
|
||||
even if they have been enumerated (see :ref:`cpu-pm-qos` in
|
||||
Documentation/admin-guide/pm/cpuidle.rst).
|
||||
Setting ``max_cstate`` to 0 causes the ``intel_idle`` initialization to fail.
|
||||
|
||||
The ``no_acpi`` and ``use_acpi`` module parameters (recognized by ``intel_idle``
|
||||
|
|
@ -202,7 +205,8 @@ Namely, the positions of the bits that are set in the ``states_off`` value are
|
|||
the indices of idle states to be disabled by default (as reflected by the names
|
||||
of the corresponding idle state directories in ``sysfs``, :file:`state0`,
|
||||
:file:`state1` ... :file:`state<i>` ..., where ``<i>`` is the index of the given
|
||||
idle state; see :ref:`idle-states-representation` in :doc:`cpuidle`).
|
||||
idle state; see :ref:`idle-states-representation` in
|
||||
Documentation/admin-guide/pm/cpuidle.rst).
|
||||
|
||||
For example, if ``states_off`` is equal to 3, the driver will disable idle
|
||||
states 0 and 1 by default, and if it is equal to 8, idle state 3 will be
|
||||
|
|
|
|||
|
|
@ -18,8 +18,8 @@ General Information
|
|||
(``CPUFreq``). It is a scaling driver for the Sandy Bridge and later
|
||||
generations of Intel processors. Note, however, that some of those processors
|
||||
may not be supported. [To understand ``intel_pstate`` it is necessary to know
|
||||
how ``CPUFreq`` works in general, so this is the time to read :doc:`cpufreq` if
|
||||
you have not done that yet.]
|
||||
how ``CPUFreq`` works in general, so this is the time to read
|
||||
Documentation/admin-guide/pm/cpufreq.rst if you have not done that yet.]
|
||||
|
||||
For the processors supported by ``intel_pstate``, the P-state concept is broader
|
||||
than just an operating frequency or an operating performance point (see the
|
||||
|
|
@ -445,8 +445,9 @@ Interpretation of Policy Attributes
|
|||
-----------------------------------
|
||||
|
||||
The interpretation of some ``CPUFreq`` policy attributes described in
|
||||
:doc:`cpufreq` is special with ``intel_pstate`` as the current scaling driver
|
||||
and it generally depends on the driver's `operation mode <Operation Modes_>`_.
|
||||
Documentation/admin-guide/pm/cpufreq.rst is special with ``intel_pstate``
|
||||
as the current scaling driver and it generally depends on the driver's
|
||||
`operation mode <Operation Modes_>`_.
|
||||
|
||||
First of all, the values of the ``cpuinfo_max_freq``, ``cpuinfo_min_freq`` and
|
||||
``scaling_cur_freq`` attributes are produced by applying a processor-specific
|
||||
|
|
|
|||
|
|
@ -1248,7 +1248,7 @@ paragraph makes the severeness obvious.
|
|||
|
||||
In case you performed a successful bisection, use the title of the change that
|
||||
introduced the regression as the second part of your subject. Make the report
|
||||
also mention the commit id of the culprit. In case of an unsuccessful bisection,
|
||||
also mention the commit id of the culprit. In case of an unsuccessful bisection,
|
||||
make your report mention the latest tested version that's working fine (say 5.7)
|
||||
and the oldest where the issue occurs (say 5.8-rc1).
|
||||
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ Documentation for /proc/sys/abi/
|
|||
|
||||
Copyright (c) 2020, Stephen Kitt
|
||||
|
||||
For general info, see :doc:`index`.
|
||||
For general info, see Documentation/admin-guide/sysctl/index.rst.
|
||||
|
||||
------------------------------------------------------------------------------
|
||||
|
||||
|
|
|
|||
|
|
@ -9,7 +9,8 @@ Copyright (c) 1998, 1999, Rik van Riel <riel@nl.linux.org>
|
|||
|
||||
Copyright (c) 2009, Shen Feng<shen@cn.fujitsu.com>
|
||||
|
||||
For general info and legal blurb, please look in :doc:`index`.
|
||||
For general info and legal blurb, please look in
|
||||
Documentation/admin-guide/sysctl/index.rst.
|
||||
|
||||
------------------------------------------------------------------------------
|
||||
|
||||
|
|
@ -54,7 +55,7 @@ free space valid for 30 seconds.
|
|||
acpi_video_flags
|
||||
================
|
||||
|
||||
See :doc:`/power/video`. This allows the video resume mode to be set,
|
||||
See Documentation/power/video.rst. This allows the video resume mode to be set,
|
||||
in a similar fashion to the ``acpi_sleep`` kernel parameter, by
|
||||
combining the following values:
|
||||
|
||||
|
|
@ -89,7 +90,7 @@ is 0x15 and the full version number is 0x234, this file will contain
|
|||
the value 340 = 0x154.
|
||||
|
||||
See the ``type_of_loader`` and ``ext_loader_type`` fields in
|
||||
:doc:`/x86/boot` for additional information.
|
||||
Documentation/x86/boot.rst for additional information.
|
||||
|
||||
|
||||
bootloader_version (x86 only)
|
||||
|
|
@ -99,7 +100,7 @@ The complete bootloader version number. In the example above, this
|
|||
file will contain the value 564 = 0x234.
|
||||
|
||||
See the ``type_of_loader`` and ``ext_loader_ver`` fields in
|
||||
:doc:`/x86/boot` for additional information.
|
||||
Documentation/x86/boot.rst for additional information.
|
||||
|
||||
|
||||
bpf_stats_enabled
|
||||
|
|
@ -269,7 +270,7 @@ see the ``hostname(1)`` man page.
|
|||
firmware_config
|
||||
===============
|
||||
|
||||
See :doc:`/driver-api/firmware/fallback-mechanisms`.
|
||||
See Documentation/driver-api/firmware/fallback-mechanisms.rst.
|
||||
|
||||
The entries in this directory allow the firmware loader helper
|
||||
fallback to be controlled:
|
||||
|
|
@ -297,7 +298,7 @@ crashes and outputting them to a serial console.
|
|||
ftrace_enabled, stack_tracer_enabled
|
||||
====================================
|
||||
|
||||
See :doc:`/trace/ftrace`.
|
||||
See Documentation/trace/ftrace.rst.
|
||||
|
||||
|
||||
hardlockup_all_cpu_backtrace
|
||||
|
|
@ -325,7 +326,7 @@ when a hard lockup is detected.
|
|||
1 Panic on hard lockup.
|
||||
= ===========================
|
||||
|
||||
See :doc:`/admin-guide/lockup-watchdogs` for more information.
|
||||
See Documentation/admin-guide/lockup-watchdogs.rst for more information.
|
||||
This can also be set using the nmi_watchdog kernel parameter.
|
||||
|
||||
|
||||
|
|
@ -333,7 +334,12 @@ hotplug
|
|||
=======
|
||||
|
||||
Path for the hotplug policy agent.
|
||||
Default value is "``/sbin/hotplug``".
|
||||
Default value is ``CONFIG_UEVENT_HELPER_PATH``, which in turn defaults
|
||||
to the empty string.
|
||||
|
||||
This file only exists when ``CONFIG_UEVENT_HELPER`` is enabled. Most
|
||||
modern systems rely exclusively on the netlink-based uevent source and
|
||||
don't need this.
|
||||
|
||||
|
||||
hung_task_all_cpu_backtrace
|
||||
|
|
@ -582,7 +588,8 @@ in a KVM virtual machine. This default can be overridden by adding::
|
|||
|
||||
nmi_watchdog=1
|
||||
|
||||
to the guest kernel command line (see :doc:`/admin-guide/kernel-parameters`).
|
||||
to the guest kernel command line (see
|
||||
Documentation/admin-guide/kernel-parameters.rst).
|
||||
|
||||
|
||||
numa_balancing
|
||||
|
|
@ -1067,7 +1074,7 @@ that support this feature.
|
|||
real-root-dev
|
||||
=============
|
||||
|
||||
See :doc:`/admin-guide/initrd`.
|
||||
See Documentation/admin-guide/initrd.rst.
|
||||
|
||||
|
||||
reboot-cmd (SPARC only)
|
||||
|
|
@ -1161,7 +1168,7 @@ will take effect.
|
|||
seccomp
|
||||
=======
|
||||
|
||||
See :doc:`/userspace-api/seccomp_filter`.
|
||||
See Documentation/userspace-api/seccomp_filter.rst.
|
||||
|
||||
|
||||
sg-big-buff
|
||||
|
|
@ -1332,7 +1339,7 @@ the boot PROM.
|
|||
sysrq
|
||||
=====
|
||||
|
||||
See :doc:`/admin-guide/sysrq`.
|
||||
See Documentation/admin-guide/sysrq.rst.
|
||||
|
||||
|
||||
tainted
|
||||
|
|
@ -1362,15 +1369,16 @@ ORed together. The letters are seen in "Tainted" line of Oops reports.
|
|||
131072 `(T)` The kernel was built with the struct randomization plugin
|
||||
====== ===== ==============================================================
|
||||
|
||||
See :doc:`/admin-guide/tainted-kernels` for more information.
|
||||
See Documentation/admin-guide/tainted-kernels.rst for more information.
|
||||
|
||||
Note:
|
||||
writes to this sysctl interface will fail with ``EINVAL`` if the kernel is
|
||||
booted with the command line option ``panic_on_taint=<bitmask>,nousertaint``
|
||||
and any of the ORed together values being written to ``tainted`` match with
|
||||
the bitmask declared on panic_on_taint.
|
||||
See :doc:`/admin-guide/kernel-parameters` for more details on that particular
|
||||
kernel command line option and its optional ``nousertaint`` switch.
|
||||
See Documentation/admin-guide/kernel-parameters.rst for more details on
|
||||
that particular kernel command line option and its optional
|
||||
``nousertaint`` switch.
|
||||
|
||||
threads-max
|
||||
===========
|
||||
|
|
@ -1394,7 +1402,7 @@ If a value outside of this range is written to ``threads-max`` an
|
|||
traceoff_on_warning
|
||||
===================
|
||||
|
||||
When set, disables tracing (see :doc:`/trace/ftrace`) when a
|
||||
When set, disables tracing (see Documentation/trace/ftrace.rst) when a
|
||||
``WARN()`` is hit.
|
||||
|
||||
|
||||
|
|
@ -1414,8 +1422,8 @@ will send them to printk() again.
|
|||
|
||||
This only works if the kernel was booted with ``tp_printk`` enabled.
|
||||
|
||||
See :doc:`/admin-guide/kernel-parameters` and
|
||||
:doc:`/trace/boottime-trace`.
|
||||
See Documentation/admin-guide/kernel-parameters.rst and
|
||||
Documentation/trace/boottime-trace.rst.
|
||||
|
||||
|
||||
.. _unaligned-dump-stack:
|
||||
|
|
|
|||
|
|
@ -259,7 +259,7 @@ Storage family
|
|||
https://web.archive.org/web/20191129073953/http://www.marvell.com/storage/armada-sp/
|
||||
|
||||
Core:
|
||||
Sheeva ARMv7 comatible Quad-core PJ4C
|
||||
Sheeva ARMv7 compatible Quad-core PJ4C
|
||||
|
||||
(not supported in upstream Linux kernel)
|
||||
|
||||
|
|
|
|||
|
|
@ -196,7 +196,7 @@ a virtual address mapping (unlike the earlier scheme of virtual address
|
|||
do not have a corresponding kernel virtual address space mapping) and
|
||||
low-memory pages.
|
||||
|
||||
Note: Please refer to :doc:`/core-api/dma-api-howto` for a discussion
|
||||
Note: Please refer to Documentation/core-api/dma-api-howto.rst for a discussion
|
||||
on PCI high mem DMA aspects and mapping of scatter gather lists, and support
|
||||
for 64 bit PCI.
|
||||
|
||||
|
|
|
|||
|
|
@ -62,7 +62,7 @@ queue, to be sent in the future, when the hardware is able.
|
|||
Software staging queues
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The block IO subsystem adds requests in the software staging queues
|
||||
The block IO subsystem adds requests in the software staging queues
|
||||
(represented by struct blk_mq_ctx) in case that they weren't sent
|
||||
directly to the driver. A request is one or more BIOs. They arrived at the
|
||||
block layer through the data structure struct bio. The block layer
|
||||
|
|
@ -132,7 +132,7 @@ In order to indicate which request has been completed, every request is
|
|||
identified by an integer, ranging from 0 to the dispatch queue size. This tag
|
||||
is generated by the block layer and later reused by the device driver, removing
|
||||
the need to create a redundant identifier. When a request is completed in the
|
||||
drive, the tag is sent back to the block layer to notify it of the finalization.
|
||||
driver, the tag is sent back to the block layer to notify it of the finalization.
|
||||
This removes the need to do a linear search to find out which IO has been
|
||||
completed.
|
||||
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ A.
|
|||
each, it would be impossible to guarantee that a set of readings
|
||||
represent a single point in time.
|
||||
|
||||
The stat file consists of a single line of text containing 11 decimal
|
||||
The stat file consists of a single line of text containing 17 decimal
|
||||
values separated by whitespace. The fields are summarized in the
|
||||
following table, and described in more detail below.
|
||||
|
||||
|
|
|
|||
|
|
@ -20,10 +20,10 @@ LSM hook:
|
|||
Other LSM hooks which can be instrumented can be found in
|
||||
``include/linux/lsm_hooks.h``.
|
||||
|
||||
eBPF programs that use :doc:`/bpf/btf` do not need to include kernel headers
|
||||
for accessing information from the attached eBPF program's context. They can
|
||||
simply declare the structures in the eBPF program and only specify the fields
|
||||
that need to be accessed.
|
||||
eBPF programs that use Documentation/bpf/btf.rst do not need to include kernel
|
||||
headers for accessing information from the attached eBPF program's context.
|
||||
They can simply declare the structures in the eBPF program and only specify
|
||||
the fields that need to be accessed.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
|
|
@ -88,8 +88,9 @@ example:
|
|||
|
||||
The ``__attribute__((preserve_access_index))`` is a clang feature that allows
|
||||
the BPF verifier to update the offsets for the access at runtime using the
|
||||
:doc:`/bpf/btf` information. Since the BPF verifier is aware of the types, it
|
||||
also validates all the accesses made to the various types in the eBPF program.
|
||||
Documentation/bpf/btf.rst information. Since the BPF verifier is aware of the
|
||||
types, it also validates all the accesses made to the various types in the
|
||||
eBPF program.
|
||||
|
||||
Loading
|
||||
-------
|
||||
|
|
|
|||
|
|
@ -41,15 +41,7 @@ extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
|
|||
'maintainers_include', 'sphinx.ext.autosectionlabel',
|
||||
'kernel_abi', 'kernel_feat']
|
||||
|
||||
#
|
||||
# cdomain is badly broken in Sphinx 3+. Leaving it out generates *most*
|
||||
# of the docs correctly, but not all. Scream bloody murder but allow
|
||||
# the process to proceed; hopefully somebody will fix this properly soon.
|
||||
#
|
||||
if major >= 3:
|
||||
sys.stderr.write('''WARNING: The kernel documentation build process
|
||||
support for Sphinx v3.0 and above is brand new. Be prepared for
|
||||
possible issues in the generated output.\n''')
|
||||
if (major > 3) or (minor > 0 or patch >= 2):
|
||||
# Sphinx c function parser is more pedantic with regards to type
|
||||
# checking. Due to that, having macros at c:function cause problems.
|
||||
|
|
@ -353,6 +345,8 @@ latex_elements = {
|
|||
|
||||
# Additional stuff for the LaTeX preamble.
|
||||
'preamble': '''
|
||||
% Prevent column squeezing of tabulary.
|
||||
\\setlength{\\tymin}{20em}
|
||||
% Use some font with UTF-8 support with XeLaTeX
|
||||
\\usepackage{fontspec}
|
||||
\\setsansfont{DejaVu Sans}
|
||||
|
|
@ -366,11 +360,23 @@ latex_elements = {
|
|||
|
||||
cjk_cmd = check_output(['fc-list', '--format="%{family[0]}\n"']).decode('utf-8', 'ignore')
|
||||
if cjk_cmd.find("Noto Sans CJK SC") >= 0:
|
||||
print ("enabling CJK for LaTeX builder")
|
||||
latex_elements['preamble'] += '''
|
||||
% This is needed for translations
|
||||
\\usepackage{xeCJK}
|
||||
\\setCJKmainfont{Noto Sans CJK SC}
|
||||
% Define custom macros to on/off CJK
|
||||
\\newcommand{\\kerneldocCJKon}{\\makexeCJKactive}
|
||||
\\newcommand{\\kerneldocCJKoff}{\\makexeCJKinactive}
|
||||
% To customize \sphinxtableofcontents
|
||||
\\usepackage{etoolbox}
|
||||
% Inactivate CJK after tableofcontents
|
||||
\\apptocmd{\\sphinxtableofcontents}{\\kerneldocCJKoff}{}{}
|
||||
'''
|
||||
else:
|
||||
latex_elements['preamble'] += '''
|
||||
% Custom macros to on/off CJK (Dummy)
|
||||
\\newcommand{\\kerneldocCJKon}{}
|
||||
\\newcommand{\\kerneldocCJKoff}{}
|
||||
'''
|
||||
|
||||
# Fix reference escape troubles with Sphinx 1.4.x
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ How to access I/O mapped memory from within device drivers
|
|||
|
||||
The virt_to_bus() and bus_to_virt() functions have been
|
||||
superseded by the functionality provided by the PCI DMA interface
|
||||
(see :doc:`/core-api/dma-api-howto`). They continue
|
||||
(see Documentation/core-api/dma-api-howto.rst). They continue
|
||||
to be documented below for historical purposes, but new code
|
||||
must not use them. --davidm 00/12/12
|
||||
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ Dynamic DMA mapping using the generic device
|
|||
:Author: James E.J. Bottomley <James.Bottomley@HansenPartnership.com>
|
||||
|
||||
This document describes the DMA API. For a more gentle introduction
|
||||
of the API (and actual examples), see :doc:`/core-api/dma-api-howto`.
|
||||
of the API (and actual examples), see Documentation/core-api/dma-api-howto.rst.
|
||||
|
||||
This API is split into two pieces. Part I describes the basic API.
|
||||
Part II describes extensions for supporting non-consistent memory
|
||||
|
|
@ -479,7 +479,8 @@ without the _attrs suffixes, except that they pass an optional
|
|||
dma_attrs.
|
||||
|
||||
The interpretation of DMA attributes is architecture-specific, and
|
||||
each attribute should be documented in :doc:`/core-api/dma-attributes`.
|
||||
each attribute should be documented in
|
||||
Documentation/core-api/dma-attributes.rst.
|
||||
|
||||
If dma_attrs are 0, the semantics of each of these functions
|
||||
is identical to those of the corresponding function
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ To do ISA style DMA you need to include two headers::
|
|||
#include <asm/dma.h>
|
||||
|
||||
The first is the generic DMA API used to convert virtual addresses to
|
||||
bus addresses (see :doc:`/core-api/dma-api` for details).
|
||||
bus addresses (see Documentation/core-api/dma-api.rst for details).
|
||||
|
||||
The second contains the routines specific to ISA DMA transfers. Since
|
||||
this is not present on all platforms make sure you construct your
|
||||
|
|
|
|||
|
|
@ -48,7 +48,7 @@ Concurrency primitives
|
|||
======================
|
||||
|
||||
How Linux keeps everything from happening at the same time. See
|
||||
:doc:`/locking/index` for more related documentation.
|
||||
Documentation/locking/index.rst for more related documentation.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
|
@ -77,7 +77,7 @@ Memory management
|
|||
=================
|
||||
|
||||
How to allocate and use memory in the kernel. Note that there is a lot
|
||||
more memory-management documentation in :doc:`/vm/index`.
|
||||
more memory-management documentation in Documentation/vm/index.rst.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
|
|
|||
|
|
@ -37,14 +37,13 @@ Integer types
|
|||
u64 %llu or %llx
|
||||
|
||||
|
||||
If <type> is dependent on a config option for its size (e.g., sector_t,
|
||||
blkcnt_t) or is architecture-dependent for its size (e.g., tcflag_t), use a
|
||||
format specifier of its largest possible type and explicitly cast to it.
|
||||
If <type> is architecture-dependent for its size (e.g., cycles_t, tcflag_t) or
|
||||
is dependent on a config option for its size (e.g., blk_status_t), use a format
|
||||
specifier of its largest possible type and explicitly cast to it.
|
||||
|
||||
Example::
|
||||
|
||||
printk("test: sector number/total blocks: %llu/%llu\n",
|
||||
(unsigned long long)sector, (unsigned long long)blockcount);
|
||||
printk("test: latency: %llu cycles\n", (unsigned long long)time);
|
||||
|
||||
Reminder: sizeof() returns type size_t.
|
||||
|
||||
|
|
|
|||
|
|
@ -246,6 +246,7 @@ Allocation style
|
|||
The first argument for kcalloc or kmalloc_array should be the
|
||||
number of elements. sizeof() as the first argument is generally
|
||||
wrong.
|
||||
|
||||
See: https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html
|
||||
|
||||
**ALLOC_SIZEOF_STRUCT**
|
||||
|
|
@ -264,6 +265,7 @@ Allocation style
|
|||
**ALLOC_WITH_MULTIPLY**
|
||||
Prefer kmalloc_array/kcalloc over kmalloc/kzalloc with a
|
||||
sizeof multiply.
|
||||
|
||||
See: https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html
|
||||
|
||||
|
||||
|
|
@ -284,6 +286,7 @@ API usage
|
|||
BUG() or BUG_ON() should be avoided totally.
|
||||
Use WARN() and WARN_ON() instead, and handle the "impossible"
|
||||
error condition as gracefully as possible.
|
||||
|
||||
See: https://www.kernel.org/doc/html/latest/process/deprecated.html#bug-and-bug-on
|
||||
|
||||
**CONSIDER_KSTRTO**
|
||||
|
|
@ -292,12 +295,161 @@ API usage
|
|||
may lead to unexpected results in callers. The respective kstrtol(),
|
||||
kstrtoll(), kstrtoul(), and kstrtoull() functions tend to be the
|
||||
correct replacements.
|
||||
|
||||
See: https://www.kernel.org/doc/html/latest/process/deprecated.html#simple-strtol-simple-strtoll-simple-strtoul-simple-strtoull
|
||||
|
||||
**CONSTANT_CONVERSION**
|
||||
Use of __constant_<foo> form is discouraged for the following functions::
|
||||
|
||||
__constant_cpu_to_be[x]
|
||||
__constant_cpu_to_le[x]
|
||||
__constant_be[x]_to_cpu
|
||||
__constant_le[x]_to_cpu
|
||||
__constant_htons
|
||||
__constant_ntohs
|
||||
|
||||
Using any of these outside of include/uapi/ is not preferred as using the
|
||||
function without __constant_ is identical when the argument is a
|
||||
constant.
|
||||
|
||||
In big endian systems, the macros like __constant_cpu_to_be32(x) and
|
||||
cpu_to_be32(x) expand to the same expression::
|
||||
|
||||
#define __constant_cpu_to_be32(x) ((__force __be32)(__u32)(x))
|
||||
#define __cpu_to_be32(x) ((__force __be32)(__u32)(x))
|
||||
|
||||
In little endian systems, the macros __constant_cpu_to_be32(x) and
|
||||
cpu_to_be32(x) expand to __constant_swab32 and __swab32. __swab32
|
||||
has a __builtin_constant_p check::
|
||||
|
||||
#define __swab32(x) \
|
||||
(__builtin_constant_p((__u32)(x)) ? \
|
||||
___constant_swab32(x) : \
|
||||
__fswab32(x))
|
||||
|
||||
So ultimately they have a special case for constants.
|
||||
Similar is the case with all of the macros in the list. Thus
|
||||
using the __constant_... forms are unnecessarily verbose and
|
||||
not preferred outside of include/uapi.
|
||||
|
||||
See: https://lore.kernel.org/lkml/1400106425.12666.6.camel@joe-AO725/
|
||||
|
||||
**DEPRECATED_API**
|
||||
Usage of a deprecated RCU API is detected. It is recommended to replace
|
||||
old flavourful RCU APIs by their new vanilla-RCU counterparts.
|
||||
|
||||
The full list of available RCU APIs can be viewed from the kernel docs.
|
||||
|
||||
See: https://www.kernel.org/doc/html/latest/RCU/whatisRCU.html#full-list-of-rcu-apis
|
||||
|
||||
**DEPRECATED_VARIABLE**
|
||||
EXTRA_{A,C,CPP,LD}FLAGS are deprecated and should be replaced by the new
|
||||
flags added via commit f77bf01425b1 ("kbuild: introduce ccflags-y,
|
||||
asflags-y and ldflags-y").
|
||||
|
||||
The following conversion scheme maybe used::
|
||||
|
||||
EXTRA_AFLAGS -> asflags-y
|
||||
EXTRA_CFLAGS -> ccflags-y
|
||||
EXTRA_CPPFLAGS -> cppflags-y
|
||||
EXTRA_LDFLAGS -> ldflags-y
|
||||
|
||||
See:
|
||||
|
||||
1. https://lore.kernel.org/lkml/20070930191054.GA15876@uranus.ravnborg.org/
|
||||
2. https://lore.kernel.org/lkml/1313384834-24433-12-git-send-email-lacombar@gmail.com/
|
||||
3. https://www.kernel.org/doc/html/latest/kbuild/makefiles.html#compilation-flags
|
||||
|
||||
**DEVICE_ATTR_FUNCTIONS**
|
||||
The function names used in DEVICE_ATTR is unusual.
|
||||
Typically, the store and show functions are used with <attr>_store and
|
||||
<attr>_show, where <attr> is a named attribute variable of the device.
|
||||
|
||||
Consider the following examples::
|
||||
|
||||
static DEVICE_ATTR(type, 0444, type_show, NULL);
|
||||
static DEVICE_ATTR(power, 0644, power_show, power_store);
|
||||
|
||||
The function names should preferably follow the above pattern.
|
||||
|
||||
See: https://www.kernel.org/doc/html/latest/driver-api/driver-model/device.html#attributes
|
||||
|
||||
**DEVICE_ATTR_RO**
|
||||
The DEVICE_ATTR_RO(name) helper macro can be used instead of
|
||||
DEVICE_ATTR(name, 0444, name_show, NULL);
|
||||
|
||||
Note that the macro automatically appends _show to the named
|
||||
attribute variable of the device for the show method.
|
||||
|
||||
See: https://www.kernel.org/doc/html/latest/driver-api/driver-model/device.html#attributes
|
||||
|
||||
**DEVICE_ATTR_RW**
|
||||
The DEVICE_ATTR_RW(name) helper macro can be used instead of
|
||||
DEVICE_ATTR(name, 0644, name_show, name_store);
|
||||
|
||||
Note that the macro automatically appends _show and _store to the
|
||||
named attribute variable of the device for the show and store methods.
|
||||
|
||||
See: https://www.kernel.org/doc/html/latest/driver-api/driver-model/device.html#attributes
|
||||
|
||||
**DEVICE_ATTR_WO**
|
||||
The DEVICE_AATR_WO(name) helper macro can be used instead of
|
||||
DEVICE_ATTR(name, 0200, NULL, name_store);
|
||||
|
||||
Note that the macro automatically appends _store to the
|
||||
named attribute variable of the device for the store method.
|
||||
|
||||
See: https://www.kernel.org/doc/html/latest/driver-api/driver-model/device.html#attributes
|
||||
|
||||
**DUPLICATED_SYSCTL_CONST**
|
||||
Commit d91bff3011cf ("proc/sysctl: add shared variables for range
|
||||
check") added some shared const variables to be used instead of a local
|
||||
copy in each source file.
|
||||
|
||||
Consider replacing the sysctl range checking value with the shared
|
||||
one in include/linux/sysctl.h. The following conversion scheme may
|
||||
be used::
|
||||
|
||||
&zero -> SYSCTL_ZERO
|
||||
&one -> SYSCTL_ONE
|
||||
&int_max -> SYSCTL_INT_MAX
|
||||
|
||||
See:
|
||||
|
||||
1. https://lore.kernel.org/lkml/20190430180111.10688-1-mcroce@redhat.com/
|
||||
2. https://lore.kernel.org/lkml/20190531131422.14970-1-mcroce@redhat.com/
|
||||
|
||||
**ENOSYS**
|
||||
ENOSYS means that a nonexistent system call was called.
|
||||
Earlier, it was wrongly used for things like invalid operations on
|
||||
otherwise valid syscalls. This should be avoided in new code.
|
||||
|
||||
See: https://lore.kernel.org/lkml/5eb299021dec23c1a48fa7d9f2c8b794e967766d.1408730669.git.luto@amacapital.net/
|
||||
|
||||
**ENOTSUPP**
|
||||
ENOTSUPP is not a standard error code and should be avoided in new patches.
|
||||
EOPNOTSUPP should be used instead.
|
||||
|
||||
See: https://lore.kernel.org/netdev/20200510182252.GA411829@lunn.ch/
|
||||
|
||||
**EXPORT_SYMBOL**
|
||||
EXPORT_SYMBOL should immediately follow the symbol to be exported.
|
||||
|
||||
**IN_ATOMIC**
|
||||
in_atomic() is not for driver use so any such use is reported as an ERROR.
|
||||
Also in_atomic() is often used to determine if sleeping is permitted,
|
||||
but it is not reliable in this use model. Therefore its use is
|
||||
strongly discouraged.
|
||||
|
||||
However, in_atomic() is ok for core kernel use.
|
||||
|
||||
See: https://lore.kernel.org/lkml/20080320201723.b87b3732.akpm@linux-foundation.org/
|
||||
|
||||
**LOCKDEP**
|
||||
The lockdep_no_validate class was added as a temporary measure to
|
||||
prevent warnings on conversion of device->sem to device->mutex.
|
||||
It should not be used for any other purpose.
|
||||
|
||||
See: https://lore.kernel.org/lkml/1268959062.9440.467.camel@laptop/
|
||||
|
||||
**MALFORMED_INCLUDE**
|
||||
|
|
@ -308,14 +460,21 @@ API usage
|
|||
**USE_LOCKDEP**
|
||||
lockdep_assert_held() annotations should be preferred over
|
||||
assertions based on spin_is_locked()
|
||||
|
||||
See: https://www.kernel.org/doc/html/latest/locking/lockdep-design.html#annotations
|
||||
|
||||
**UAPI_INCLUDE**
|
||||
No #include statements in include/uapi should use a uapi/ path.
|
||||
|
||||
**USLEEP_RANGE**
|
||||
usleep_range() should be preferred over udelay(). The proper way of
|
||||
using usleep_range() is mentioned in the kernel docs.
|
||||
|
||||
Comment style
|
||||
-------------
|
||||
See: https://www.kernel.org/doc/html/latest/timers/timers-howto.html#delays-information-on-the-various-kernel-delay-sleep-mechanisms
|
||||
|
||||
|
||||
Comments
|
||||
--------
|
||||
|
||||
**BLOCK_COMMENT_STYLE**
|
||||
The comment style is incorrect. The preferred style for multi-
|
||||
|
|
@ -338,8 +497,24 @@ Comment style
|
|||
**C99_COMMENTS**
|
||||
C99 style single line comments (//) should not be used.
|
||||
Prefer the block comment style instead.
|
||||
|
||||
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting
|
||||
|
||||
**DATA_RACE**
|
||||
Applications of data_race() should have a comment so as to document the
|
||||
reasoning behind why it was deemed safe.
|
||||
|
||||
See: https://lore.kernel.org/lkml/20200401101714.44781-1-elver@google.com/
|
||||
|
||||
**FSF_MAILING_ADDRESS**
|
||||
Kernel maintainers reject new instances of the GPL boilerplate paragraph
|
||||
directing people to write to the FSF for a copy of the GPL, since the
|
||||
FSF has moved in the past and may do so again.
|
||||
So do not write paragraphs about writing to the Free Software Foundation's
|
||||
mailing address.
|
||||
|
||||
See: https://lore.kernel.org/lkml/20131006222342.GT19510@leaf/
|
||||
|
||||
|
||||
Commit message
|
||||
--------------
|
||||
|
|
@ -347,6 +522,7 @@ Commit message
|
|||
**BAD_SIGN_OFF**
|
||||
The signed-off-by line does not fall in line with the standards
|
||||
specified by the community.
|
||||
|
||||
See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#developer-s-certificate-of-origin-1-1
|
||||
|
||||
**BAD_STABLE_ADDRESS_STYLE**
|
||||
|
|
@ -368,12 +544,33 @@ Commit message
|
|||
**COMMIT_MESSAGE**
|
||||
The patch is missing a commit description. A brief
|
||||
description of the changes made by the patch should be added.
|
||||
|
||||
See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes
|
||||
|
||||
**EMAIL_SUBJECT**
|
||||
Naming the tool that found the issue is not very useful in the
|
||||
subject line. A good subject line summarizes the change that
|
||||
the patch brings.
|
||||
|
||||
See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes
|
||||
|
||||
**FROM_SIGN_OFF_MISMATCH**
|
||||
The author's email does not match with that in the Signed-off-by:
|
||||
line(s). This can be sometimes caused due to an improperly configured
|
||||
email client.
|
||||
|
||||
This message is emitted due to any of the following reasons::
|
||||
|
||||
- The email names do not match.
|
||||
- The email addresses do not match.
|
||||
- The email subaddresses do not match.
|
||||
- The email comments do not match.
|
||||
|
||||
**MISSING_SIGN_OFF**
|
||||
The patch is missing a Signed-off-by line. A signed-off-by
|
||||
line should be added according to Developer's certificate of
|
||||
Origin.
|
||||
|
||||
See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin
|
||||
|
||||
**NO_AUTHOR_SIGN_OFF**
|
||||
|
|
@ -382,6 +579,7 @@ Commit message
|
|||
end of explanation of the patch to denote that the author has
|
||||
written it or otherwise has the rights to pass it on as an open
|
||||
source patch.
|
||||
|
||||
See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin
|
||||
|
||||
**DIFF_IN_COMMIT_MSG**
|
||||
|
|
@ -389,6 +587,7 @@ Commit message
|
|||
This causes problems when one tries to apply a file containing both
|
||||
the changelog and the diff because patch(1) tries to apply the diff
|
||||
which it found in the changelog.
|
||||
|
||||
See: https://lore.kernel.org/lkml/20150611134006.9df79a893e3636019ad2759e@linux-foundation.org/
|
||||
|
||||
**GERRIT_CHANGE_ID**
|
||||
|
|
@ -431,6 +630,7 @@ Comparison style
|
|||
**BOOL_COMPARISON**
|
||||
Comparisons of A to true and false are better written
|
||||
as A and !A.
|
||||
|
||||
See: https://lore.kernel.org/lkml/1365563834.27174.12.camel@joe-AO722/
|
||||
|
||||
**COMPARISON_TO_NULL**
|
||||
|
|
@ -442,6 +642,87 @@ Comparison style
|
|||
side of the test should be avoided.
|
||||
|
||||
|
||||
Indentation and Line Breaks
|
||||
---------------------------
|
||||
|
||||
**CODE_INDENT**
|
||||
Code indent should use tabs instead of spaces.
|
||||
Outside of comments, documentation and Kconfig,
|
||||
spaces are never used for indentation.
|
||||
|
||||
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation
|
||||
|
||||
**DEEP_INDENTATION**
|
||||
Indentation with 6 or more tabs usually indicate overly indented
|
||||
code.
|
||||
|
||||
It is suggested to refactor excessive indentation of
|
||||
if/else/for/do/while/switch statements.
|
||||
|
||||
See: https://lore.kernel.org/lkml/1328311239.21255.24.camel@joe2Laptop/
|
||||
|
||||
**SWITCH_CASE_INDENT_LEVEL**
|
||||
switch should be at the same indent as case.
|
||||
Example::
|
||||
|
||||
switch (suffix) {
|
||||
case 'G':
|
||||
case 'g':
|
||||
mem <<= 30;
|
||||
break;
|
||||
case 'M':
|
||||
case 'm':
|
||||
mem <<= 20;
|
||||
break;
|
||||
case 'K':
|
||||
case 'k':
|
||||
mem <<= 10;
|
||||
fallthrough;
|
||||
default:
|
||||
break;
|
||||
}
|
||||
|
||||
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation
|
||||
|
||||
**LONG_LINE**
|
||||
The line has exceeded the specified maximum length.
|
||||
To use a different maximum line length, the --max-line-length=n option
|
||||
may be added while invoking checkpatch.
|
||||
|
||||
Earlier, the default line length was 80 columns. Commit bdc48fa11e46
|
||||
("checkpatch/coding-style: deprecate 80-column warning") increased the
|
||||
limit to 100 columns. This is not a hard limit either and it's
|
||||
preferable to stay within 80 columns whenever possible.
|
||||
|
||||
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#breaking-long-lines-and-strings
|
||||
|
||||
**LONG_LINE_STRING**
|
||||
A string starts before but extends beyond the maximum line length.
|
||||
To use a different maximum line length, the --max-line-length=n option
|
||||
may be added while invoking checkpatch.
|
||||
|
||||
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#breaking-long-lines-and-strings
|
||||
|
||||
**LONG_LINE_COMMENT**
|
||||
A comment starts before but extends beyond the maximum line length.
|
||||
To use a different maximum line length, the --max-line-length=n option
|
||||
may be added while invoking checkpatch.
|
||||
|
||||
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#breaking-long-lines-and-strings
|
||||
|
||||
**TRAILING_STATEMENTS**
|
||||
Trailing statements (for example after any conditional) should be
|
||||
on the next line.
|
||||
Statements, such as::
|
||||
|
||||
if (x == y) break;
|
||||
|
||||
should be::
|
||||
|
||||
if (x == y)
|
||||
break;
|
||||
|
||||
|
||||
Macros, Attributes and Symbols
|
||||
------------------------------
|
||||
|
||||
|
|
@ -472,7 +753,7 @@ Macros, Attributes and Symbols
|
|||
|
||||
**BIT_MACRO**
|
||||
Defines like: 1 << <digit> could be BIT(digit).
|
||||
The BIT() macro is defined in include/linux/bitops.h::
|
||||
The BIT() macro is defined via include/linux/bits.h::
|
||||
|
||||
#define BIT(nr) (1UL << (nr))
|
||||
|
||||
|
|
@ -492,6 +773,7 @@ Macros, Attributes and Symbols
|
|||
The kernel does *not* use the ``__DATE__`` and ``__TIME__`` macros,
|
||||
and enables warnings if they are used as they can lead to
|
||||
non-deterministic builds.
|
||||
|
||||
See: https://www.kernel.org/doc/html/latest/kbuild/reproducible-builds.html#timestamps
|
||||
|
||||
**DEFINE_ARCH_HAS**
|
||||
|
|
@ -502,8 +784,12 @@ Macros, Attributes and Symbols
|
|||
want architectures able to override them with optimized ones, we
|
||||
should either use weak functions (appropriate for some cases), or
|
||||
the symbol that protects them should be the same symbol we use.
|
||||
|
||||
See: https://lore.kernel.org/lkml/CA+55aFycQ9XJvEOsiM3txHL5bjUc8CeKWJNR_H+MiicaddB42Q@mail.gmail.com/
|
||||
|
||||
**DO_WHILE_MACRO_WITH_TRAILING_SEMICOLON**
|
||||
do {} while(0) macros should not have a trailing semicolon.
|
||||
|
||||
**INIT_ATTRIBUTE**
|
||||
Const init definitions should use __initconst instead of
|
||||
__initdata.
|
||||
|
|
@ -528,6 +814,20 @@ Macros, Attributes and Symbols
|
|||
...
|
||||
}
|
||||
|
||||
**MISPLACED_INIT**
|
||||
It is possible to use section markers on variables in a way
|
||||
which gcc doesn't understand (or at least not the way the
|
||||
developer intended)::
|
||||
|
||||
static struct __initdata samsung_pll_clock exynos4_plls[nr_plls] = {
|
||||
|
||||
does not put exynos4_plls in the .initdata section. The __initdata
|
||||
marker can be virtually anywhere on the line, except right after
|
||||
"struct". The preferred location is before the "=" sign if there is
|
||||
one, or before the trailing ";" otherwise.
|
||||
|
||||
See: https://lore.kernel.org/lkml/1377655732.3619.19.camel@joe-AO722/
|
||||
|
||||
**MULTISTATEMENT_MACRO_USE_DO_WHILE**
|
||||
Macros with multiple statements should be enclosed in a
|
||||
do - while block. Same should also be the case for macros
|
||||
|
|
@ -541,6 +841,10 @@ Macros, Attributes and Symbols
|
|||
|
||||
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#macros-enums-and-rtl
|
||||
|
||||
**PREFER_FALLTHROUGH**
|
||||
Use the `fallthrough;` pseudo keyword instead of
|
||||
`/* fallthrough */` like comments.
|
||||
|
||||
**WEAK_DECLARATION**
|
||||
Using weak declarations like __attribute__((weak)) or __weak
|
||||
can have unintended link defects. Avoid using them.
|
||||
|
|
@ -551,8 +855,51 @@ Functions and Variables
|
|||
|
||||
**CAMELCASE**
|
||||
Avoid CamelCase Identifiers.
|
||||
|
||||
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#naming
|
||||
|
||||
**CONST_CONST**
|
||||
Using `const <type> const *` is generally meant to be
|
||||
written `const <type> * const`.
|
||||
|
||||
**CONST_STRUCT**
|
||||
Using const is generally a good idea. Checkpatch reads
|
||||
a list of frequently used structs that are always or
|
||||
almost always constant.
|
||||
|
||||
The existing structs list can be viewed from
|
||||
`scripts/const_structs.checkpatch`.
|
||||
|
||||
See: https://lore.kernel.org/lkml/alpine.DEB.2.10.1608281509480.3321@hadrien/
|
||||
|
||||
**EMBEDDED_FUNCTION_NAME**
|
||||
Embedded function names are less appropriate to use as
|
||||
refactoring can cause function renaming. Prefer the use of
|
||||
"%s", __func__ to embedded function names.
|
||||
|
||||
Note that this does not work with -f (--file) checkpatch option
|
||||
as it depends on patch context providing the function name.
|
||||
|
||||
**FUNCTION_ARGUMENTS**
|
||||
This warning is emitted due to any of the following reasons:
|
||||
|
||||
1. Arguments for the function declaration do not follow
|
||||
the identifier name. Example::
|
||||
|
||||
void foo
|
||||
(int bar, int baz)
|
||||
|
||||
This should be corrected to::
|
||||
|
||||
void foo(int bar, int baz)
|
||||
|
||||
2. Some arguments for the function definition do not
|
||||
have an identifier name. Example::
|
||||
|
||||
void foo(int)
|
||||
|
||||
All arguments should have identifier names.
|
||||
|
||||
**FUNCTION_WITHOUT_ARGS**
|
||||
Function declarations without arguments like::
|
||||
|
||||
|
|
@ -583,6 +930,34 @@ Functions and Variables
|
|||
return bar;
|
||||
|
||||
|
||||
Permissions
|
||||
-----------
|
||||
|
||||
**DEVICE_ATTR_PERMS**
|
||||
The permissions used in DEVICE_ATTR are unusual.
|
||||
Typically only three permissions are used - 0644 (RW), 0444 (RO)
|
||||
and 0200 (WO).
|
||||
|
||||
See: https://www.kernel.org/doc/html/latest/filesystems/sysfs.html#attributes
|
||||
|
||||
**EXECUTE_PERMISSIONS**
|
||||
There is no reason for source files to be executable. The executable
|
||||
bit can be removed safely.
|
||||
|
||||
**EXPORTED_WORLD_WRITABLE**
|
||||
Exporting world writable sysfs/debugfs files is usually a bad thing.
|
||||
When done arbitrarily they can introduce serious security bugs.
|
||||
In the past, some of the debugfs vulnerabilities would seemingly allow
|
||||
any local user to write arbitrary values into device registers - a
|
||||
situation from which little good can be expected to emerge.
|
||||
|
||||
See: https://lore.kernel.org/linux-arm-kernel/cover.1296818921.git.segoon@openwall.com/
|
||||
|
||||
**NON_OCTAL_PERMISSIONS**
|
||||
Permission bits should use 4 digit octal permissions (like 0700 or 0444).
|
||||
Avoid using any other base like decimal.
|
||||
|
||||
|
||||
Spacing and Brackets
|
||||
--------------------
|
||||
|
||||
|
|
@ -616,7 +991,7 @@ Spacing and Brackets
|
|||
|
||||
1. With a type on the left::
|
||||
|
||||
;int [] a;
|
||||
int [] a;
|
||||
|
||||
2. At the beginning of a line for slice initialisers::
|
||||
|
||||
|
|
@ -626,12 +1001,6 @@ Spacing and Brackets
|
|||
|
||||
= { [0...10] = 5 }
|
||||
|
||||
**CODE_INDENT**
|
||||
Code indent should use tabs instead of spaces.
|
||||
Outside of comments, documentation and Kconfig,
|
||||
spaces are never used for indentation.
|
||||
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation
|
||||
|
||||
**CONCATENATED_STRING**
|
||||
Concatenated elements should have a space in between.
|
||||
Example::
|
||||
|
|
@ -644,17 +1013,20 @@ Spacing and Brackets
|
|||
|
||||
**ELSE_AFTER_BRACE**
|
||||
`else {` should follow the closing block `}` on the same line.
|
||||
|
||||
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces
|
||||
|
||||
**LINE_SPACING**
|
||||
Vertical space is wasted given the limited number of lines an
|
||||
editor window can display when multiple blank lines are used.
|
||||
|
||||
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
|
||||
|
||||
**OPEN_BRACE**
|
||||
The opening brace should be following the function definitions on the
|
||||
next line. For any non-functional block it should be on the same line
|
||||
as the last construct.
|
||||
|
||||
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces
|
||||
|
||||
**POINTER_LOCATION**
|
||||
|
|
@ -671,37 +1043,47 @@ Spacing and Brackets
|
|||
|
||||
**SPACING**
|
||||
Whitespace style used in the kernel sources is described in kernel docs.
|
||||
|
||||
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
|
||||
|
||||
**SWITCH_CASE_INDENT_LEVEL**
|
||||
switch should be at the same indent as case.
|
||||
Example::
|
||||
|
||||
switch (suffix) {
|
||||
case 'G':
|
||||
case 'g':
|
||||
mem <<= 30;
|
||||
break;
|
||||
case 'M':
|
||||
case 'm':
|
||||
mem <<= 20;
|
||||
break;
|
||||
case 'K':
|
||||
case 'k':
|
||||
mem <<= 10;
|
||||
/* fall through */
|
||||
default:
|
||||
break;
|
||||
}
|
||||
|
||||
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation
|
||||
|
||||
**TRAILING_WHITESPACE**
|
||||
Trailing whitespace should always be removed.
|
||||
Some editors highlight the trailing whitespace and cause visual
|
||||
distractions when editing files.
|
||||
|
||||
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
|
||||
|
||||
**UNNECESSARY_PARENTHESES**
|
||||
Parentheses are not required in the following cases:
|
||||
|
||||
1. Function pointer uses::
|
||||
|
||||
(foo->bar)();
|
||||
|
||||
could be::
|
||||
|
||||
foo->bar();
|
||||
|
||||
2. Comparisons in if::
|
||||
|
||||
if ((foo->bar) && (foo->baz))
|
||||
if ((foo == bar))
|
||||
|
||||
could be::
|
||||
|
||||
if (foo->bar && foo->baz)
|
||||
if (foo == bar)
|
||||
|
||||
3. addressof/dereference single Lvalues::
|
||||
|
||||
&(foo->bar)
|
||||
*(foo->bar)
|
||||
|
||||
could be::
|
||||
|
||||
&foo->bar
|
||||
*foo->bar
|
||||
|
||||
**WHILE_AFTER_BRACE**
|
||||
while should follow the closing bracket on the same line::
|
||||
|
||||
|
|
@ -723,17 +1105,50 @@ Others
|
|||
The patch seems to be corrupted or lines are wrapped.
|
||||
Please regenerate the patch file before sending it to the maintainer.
|
||||
|
||||
**CVS_KEYWORD**
|
||||
Since linux moved to git, the CVS markers are no longer used.
|
||||
So, CVS style keywords ($Id$, $Revision$, $Log$) should not be
|
||||
added.
|
||||
|
||||
**DEFAULT_NO_BREAK**
|
||||
switch default case is sometimes written as "default:;". This can
|
||||
cause new cases added below default to be defective.
|
||||
|
||||
A "break;" should be added after empty default statement to avoid
|
||||
unwanted fallthrough.
|
||||
|
||||
**DOS_LINE_ENDINGS**
|
||||
For DOS-formatted patches, there are extra ^M symbols at the end of
|
||||
the line. These should be removed.
|
||||
|
||||
**EXECUTE_PERMISSIONS**
|
||||
There is no reason for source files to be executable. The executable
|
||||
bit can be removed safely.
|
||||
**DT_SCHEMA_BINDING_PATCH**
|
||||
DT bindings moved to a json-schema based format instead of
|
||||
freeform text.
|
||||
|
||||
**NON_OCTAL_PERMISSIONS**
|
||||
Permission bits should use 4 digit octal permissions (like 0700 or 0444).
|
||||
Avoid using any other base like decimal.
|
||||
See: https://www.kernel.org/doc/html/latest/devicetree/bindings/writing-schema.html
|
||||
|
||||
**DT_SPLIT_BINDING_PATCH**
|
||||
Devicetree bindings should be their own patch. This is because
|
||||
bindings are logically independent from a driver implementation,
|
||||
they have a different maintainer (even though they often
|
||||
are applied via the same tree), and it makes for a cleaner history in the
|
||||
DT only tree created with git-filter-branch.
|
||||
|
||||
See: https://www.kernel.org/doc/html/latest/devicetree/bindings/submitting-patches.html#i-for-patch-submitters
|
||||
|
||||
**EMBEDDED_FILENAME**
|
||||
Embedding the complete filename path inside the file isn't particularly
|
||||
useful as often the path is moved around and becomes incorrect.
|
||||
|
||||
**FILE_PATH_CHANGES**
|
||||
Whenever files are added, moved, or deleted, the MAINTAINERS file
|
||||
patterns can be out of sync or outdated.
|
||||
|
||||
So MAINTAINERS might need updating in these cases.
|
||||
|
||||
**MEMSET**
|
||||
The memset use appears to be incorrect. This may be caused due to
|
||||
badly ordered parameters. Please recheck the usage.
|
||||
|
||||
**NOT_UNIFIED_DIFF**
|
||||
The patch file does not appear to be in unified-diff format. Please
|
||||
|
|
@ -742,14 +1157,12 @@ Others
|
|||
**PRINTF_0XDECIMAL**
|
||||
Prefixing 0x with decimal output is defective and should be corrected.
|
||||
|
||||
**TRAILING_STATEMENTS**
|
||||
Trailing statements (for example after any conditional) should be
|
||||
on the next line.
|
||||
Like::
|
||||
**SPDX_LICENSE_TAG**
|
||||
The source file is missing or has an improper SPDX identifier tag.
|
||||
The Linux kernel requires the precise SPDX identifier in all source files,
|
||||
and it is thoroughly documented in the kernel docs.
|
||||
|
||||
if (x == y) break;
|
||||
See: https://www.kernel.org/doc/html/latest/process/license-rules.html
|
||||
|
||||
should be::
|
||||
|
||||
if (x == y)
|
||||
break;
|
||||
**TYPO_SPELLING**
|
||||
Some words may have been misspelled. Consider reviewing them.
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ API Reference
|
|||
This section documents the KUnit kernel testing API. It is divided into the
|
||||
following sections:
|
||||
|
||||
================================= ==============================================
|
||||
:doc:`test` documents all of the standard testing API
|
||||
excluding mocking or mocking related features.
|
||||
================================= ==============================================
|
||||
Documentation/dev-tools/kunit/api/test.rst
|
||||
|
||||
- documents all of the standard testing API excluding mocking
|
||||
or mocking related features.
|
||||
|
|
|
|||
|
|
@ -97,7 +97,7 @@ things to try.
|
|||
modules will automatically execute associated tests when loaded. Test results
|
||||
can be collected from ``/sys/kernel/debug/kunit/<test suite>/results``, and
|
||||
can be parsed with ``kunit.py parse``. For more details, see "KUnit on
|
||||
non-UML architectures" in :doc:`usage`.
|
||||
non-UML architectures" in Documentation/dev-tools/kunit/usage.rst.
|
||||
|
||||
If none of the above tricks help, you are always welcome to email any issues to
|
||||
kunit-dev@googlegroups.com.
|
||||
|
|
|
|||
|
|
@ -36,7 +36,7 @@ To make running these tests (and reading the results) easier, KUnit offers
|
|||
results. This provides a quick way of running KUnit tests during development,
|
||||
without requiring a virtual machine or separate hardware.
|
||||
|
||||
Get started now: :doc:`start`
|
||||
Get started now: Documentation/dev-tools/kunit/start.rst
|
||||
|
||||
Why KUnit?
|
||||
==========
|
||||
|
|
@ -88,9 +88,9 @@ it takes to read their test log?
|
|||
How do I use it?
|
||||
================
|
||||
|
||||
* :doc:`start` - for new users of KUnit
|
||||
* :doc:`tips` - for short examples of best practices
|
||||
* :doc:`usage` - for a more detailed explanation of KUnit features
|
||||
* :doc:`api/index` - for the list of KUnit APIs used for testing
|
||||
* :doc:`kunit-tool` - for more information on the kunit_tool helper script
|
||||
* :doc:`faq` - for answers to some common questions about KUnit
|
||||
* Documentation/dev-tools/kunit/start.rst - for new users of KUnit
|
||||
* Documentation/dev-tools/kunit/tips.rst - for short examples of best practices
|
||||
* Documentation/dev-tools/kunit/usage.rst - for a more detailed explanation of KUnit features
|
||||
* Documentation/dev-tools/kunit/api/index.rst - for the list of KUnit APIs used for testing
|
||||
* Documentation/dev-tools/kunit/kunit-tool.rst - for more information on the kunit_tool helper script
|
||||
* Documentation/dev-tools/kunit/faq.rst - for answers to some common questions about KUnit
|
||||
|
|
|
|||
|
|
@ -21,7 +21,7 @@ The wrapper can be run with:
|
|||
./tools/testing/kunit/kunit.py run
|
||||
|
||||
For more information on this wrapper (also called kunit_tool) check out the
|
||||
:doc:`kunit-tool` page.
|
||||
Documentation/dev-tools/kunit/kunit-tool.rst page.
|
||||
|
||||
Creating a .kunitconfig
|
||||
-----------------------
|
||||
|
|
@ -234,7 +234,7 @@ Congrats! You just wrote your first KUnit test!
|
|||
|
||||
Next Steps
|
||||
==========
|
||||
* Check out the :doc:`tips` page for tips on
|
||||
* Check out the Documentation/dev-tools/kunit/tips.rst page for tips on
|
||||
writing idiomatic KUnit tests.
|
||||
* Optional: see the :doc:`usage` page for a more
|
||||
in-depth explanation of KUnit.
|
||||
|
|
|
|||
|
|
@ -125,7 +125,8 @@ Here's a slightly in-depth example of how one could implement "mocking":
|
|||
|
||||
|
||||
Note: here we're able to get away with using ``test->priv``, but if you wanted
|
||||
something more flexible you could use a named ``kunit_resource``, see :doc:`api/test`.
|
||||
something more flexible you could use a named ``kunit_resource``, see
|
||||
Documentation/dev-tools/kunit/api/test.rst.
|
||||
|
||||
Failing the current test
|
||||
------------------------
|
||||
|
|
@ -185,5 +186,5 @@ Alternatively, one can take full control over the error message by using ``KUNIT
|
|||
|
||||
Next Steps
|
||||
==========
|
||||
* Optional: see the :doc:`usage` page for a more
|
||||
* Optional: see the Documentation/dev-tools/kunit/usage.rst page for a more
|
||||
in-depth explanation of KUnit.
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ understand it. This guide assumes a working knowledge of the Linux kernel and
|
|||
some basic knowledge of testing.
|
||||
|
||||
For a high level introduction to KUnit, including setting up KUnit for your
|
||||
project, see :doc:`start`.
|
||||
project, see Documentation/dev-tools/kunit/start.rst.
|
||||
|
||||
Organization of this document
|
||||
=============================
|
||||
|
|
@ -99,7 +99,8 @@ violated; however, the test will continue running, potentially trying other
|
|||
expectations until the test case ends or is otherwise terminated. This is as
|
||||
opposed to *assertions* which are discussed later.
|
||||
|
||||
To learn about more expectations supported by KUnit, see :doc:`api/test`.
|
||||
To learn about more expectations supported by KUnit, see
|
||||
Documentation/dev-tools/kunit/api/test.rst.
|
||||
|
||||
.. note::
|
||||
A single test case should be pretty short, pretty easy to understand,
|
||||
|
|
@ -216,7 +217,8 @@ test suite in a special linker section so that it can be run by KUnit either
|
|||
after late_init, or when the test module is loaded (depending on whether the
|
||||
test was built in or not).
|
||||
|
||||
For more information on these types of things see the :doc:`api/test`.
|
||||
For more information on these types of things see the
|
||||
Documentation/dev-tools/kunit/api/test.rst.
|
||||
|
||||
Common Patterns
|
||||
===============
|
||||
|
|
|
|||
|
|
@ -71,15 +71,15 @@ can be used to verify that a test is executing particular functions or lines
|
|||
of code. This is useful for determining how much of the kernel is being tested,
|
||||
and for finding corner-cases which are not covered by the appropriate test.
|
||||
|
||||
:doc:`gcov` is GCC's coverage testing tool, which can be used with the kernel
|
||||
to get global or per-module coverage. Unlike KCOV, it does not record per-task
|
||||
coverage. Coverage data can be read from debugfs, and interpreted using the
|
||||
usual gcov tooling.
|
||||
Documentation/dev-tools/gcov.rst is GCC's coverage testing tool, which can be
|
||||
used with the kernel to get global or per-module coverage. Unlike KCOV, it
|
||||
does not record per-task coverage. Coverage data can be read from debugfs,
|
||||
and interpreted using the usual gcov tooling.
|
||||
|
||||
:doc:`kcov` is a feature which can be built in to the kernel to allow
|
||||
capturing coverage on a per-task level. It's therefore useful for fuzzing and
|
||||
other situations where information about code executed during, for example, a
|
||||
single syscall is useful.
|
||||
Documentation/dev-tools/kcov.rst is a feature which can be built in to the
|
||||
kernel to allow capturing coverage on a per-task level. It's therefore useful
|
||||
for fuzzing and other situations where information about code executed during,
|
||||
for example, a single syscall is useful.
|
||||
|
||||
|
||||
Dynamic Analysis Tools
|
||||
|
|
|
|||
|
|
@ -7,8 +7,8 @@ Submitting Devicetree (DT) binding patches
|
|||
I. For patch submitters
|
||||
=======================
|
||||
|
||||
0) Normal patch submission rules from Documentation/process/submitting-patches.rst
|
||||
applies.
|
||||
0) Normal patch submission rules from
|
||||
Documentation/process/submitting-patches.rst applies.
|
||||
|
||||
1) The Documentation/ and include/dt-bindings/ portion of the patch should
|
||||
be a separate patch. The preferred subject prefix for binding patches is::
|
||||
|
|
@ -25,8 +25,8 @@ I. For patch submitters
|
|||
|
||||
make dt_binding_check
|
||||
|
||||
See Documentation/devicetree/bindings/writing-schema.rst for more details about
|
||||
schema and tools setup.
|
||||
See Documentation/devicetree/bindings/writing-schema.rst for more details
|
||||
about schema and tools setup.
|
||||
|
||||
3) DT binding files should be dual licensed. The preferred license tag is
|
||||
(GPL-2.0-only OR BSD-2-Clause).
|
||||
|
|
@ -84,7 +84,8 @@ II. For kernel maintainers
|
|||
III. Notes
|
||||
==========
|
||||
|
||||
0) Please see :doc:`ABI` for details regarding devicetree ABI.
|
||||
0) Please see Documentation/devicetree/bindings/ABI.rst for details
|
||||
regarding devicetree ABI.
|
||||
|
||||
1) This document is intended as a general familiarization with the process as
|
||||
decided at the 2013 Kernel Summit. When in doubt, the current word of the
|
||||
|
|
|
|||
|
|
@ -237,10 +237,10 @@ We have been trying to improve the situation through the creation of
|
|||
a set of "books" that group documentation for specific readers. These
|
||||
include:
|
||||
|
||||
- :doc:`../admin-guide/index`
|
||||
- :doc:`../core-api/index`
|
||||
- :doc:`../driver-api/index`
|
||||
- :doc:`../userspace-api/index`
|
||||
- Documentation/admin-guide/index.rst
|
||||
- Documentation/core-api/index.rst
|
||||
- Documentation/driver-api/index.rst
|
||||
- Documentation/userspace-api/index.rst
|
||||
|
||||
As well as this book on documentation itself.
|
||||
|
||||
|
|
|
|||
|
|
@ -276,4 +276,4 @@ before they become available from the ACPICA release process.
|
|||
# git clone https://github.com/acpica/acpica
|
||||
# git clone https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
|
||||
# cd acpica
|
||||
# generate/linux/divergences.sh -s ../linux
|
||||
# generate/linux/divergence.sh -s ../linux
|
||||
|
|
|
|||
|
|
@ -9,13 +9,13 @@ with them.
|
|||
|
||||
For examples of already existing generic drivers that will also be good
|
||||
examples for any other kernel drivers you want to author, refer to
|
||||
:doc:`drivers-on-gpio`
|
||||
Documentation/driver-api/gpio/drivers-on-gpio.rst
|
||||
|
||||
For any kind of mass produced system you want to support, such as servers,
|
||||
laptops, phones, tablets, routers, and any consumer or office or business goods
|
||||
using appropriate kernel drivers is paramount. Submit your code for inclusion
|
||||
in the upstream Linux kernel when you feel it is mature enough and you will get
|
||||
help to refine it, see :doc:`../../process/submitting-patches`.
|
||||
help to refine it, see Documentation/process/submitting-patches.rst.
|
||||
|
||||
In Linux GPIO lines also have a userspace ABI.
|
||||
|
||||
|
|
|
|||
|
|
@ -25,16 +25,16 @@ ioctl commands that follow modern conventions: ``_IO``, ``_IOR``,
|
|||
with the correct parameters:
|
||||
|
||||
_IO/_IOR/_IOW/_IOWR
|
||||
The macro name specifies how the argument will be used. It may be a
|
||||
The macro name specifies how the argument will be used. It may be a
|
||||
pointer to data to be passed into the kernel (_IOW), out of the kernel
|
||||
(_IOR), or both (_IOWR). _IO can indicate either commands with no
|
||||
(_IOR), or both (_IOWR). _IO can indicate either commands with no
|
||||
argument or those passing an integer value instead of a pointer.
|
||||
It is recommended to only use _IO for commands without arguments,
|
||||
and use pointers for passing data.
|
||||
|
||||
type
|
||||
An 8-bit number, often a character literal, specific to a subsystem
|
||||
or driver, and listed in :doc:`../userspace-api/ioctl/ioctl-number`
|
||||
or driver, and listed in Documentation/userspace-api/ioctl/ioctl-number.rst
|
||||
|
||||
nr
|
||||
An 8-bit number identifying the specific command, unique for a give
|
||||
|
|
@ -200,10 +200,10 @@ cause an information leak, which can be used to defeat kernel address
|
|||
space layout randomization (KASLR), helping in an attack.
|
||||
|
||||
For this reason (and for compat support) it is best to avoid any
|
||||
implicit padding in data structures. Where there is implicit padding
|
||||
implicit padding in data structures. Where there is implicit padding
|
||||
in an existing structure, kernel drivers must be careful to fully
|
||||
initialize an instance of the structure before copying it to user
|
||||
space. This is usually done by calling memset() before assigning to
|
||||
space. This is usually done by calling memset() before assigning to
|
||||
individual members.
|
||||
|
||||
Subsystem abstractions
|
||||
|
|
|
|||
|
|
@ -217,7 +217,7 @@ system-wide transition to a sleep state even though its :c:member:`runtime_auto`
|
|||
flag is clear.
|
||||
|
||||
For more information about the runtime power management framework, refer to
|
||||
:file:`Documentation/power/runtime_pm.rst`.
|
||||
Documentation/power/runtime_pm.rst.
|
||||
|
||||
|
||||
Calling Drivers to Enter and Leave System Sleep States
|
||||
|
|
@ -655,7 +655,7 @@ been thawed. Generally speaking, the PM notifiers are suitable for performing
|
|||
actions that either require user space to be available, or at least won't
|
||||
interfere with user space.
|
||||
|
||||
For details refer to :doc:`notifiers`.
|
||||
For details refer to Documentation/driver-api/pm/notifiers.rst.
|
||||
|
||||
|
||||
Device Low-Power (suspend) States
|
||||
|
|
@ -726,7 +726,7 @@ it into account in any way.
|
|||
|
||||
Devices may be defined as IRQ-safe which indicates to the PM core that their
|
||||
runtime PM callbacks may be invoked with disabled interrupts (see
|
||||
:file:`Documentation/power/runtime_pm.rst` for more information). If an
|
||||
Documentation/power/runtime_pm.rst for more information). If an
|
||||
IRQ-safe device belongs to a PM domain, the runtime PM of the domain will be
|
||||
disallowed, unless the domain itself is defined as IRQ-safe. However, it
|
||||
makes sense to define a PM domain as IRQ-safe only if all the devices in it
|
||||
|
|
@ -805,7 +805,7 @@ The ``DPM_FLAG_MAY_SKIP_RESUME`` Driver Flag
|
|||
--------------------------------------------
|
||||
|
||||
During system-wide resume from a sleep state it's easiest to put devices into
|
||||
the full-power state, as explained in :file:`Documentation/power/runtime_pm.rst`.
|
||||
the full-power state, as explained in Documentation/power/runtime_pm.rst.
|
||||
[Refer to that document for more information regarding this particular issue as
|
||||
well as for information on the device runtime power management framework in
|
||||
general.] However, it often is desirable to leave devices in suspend after
|
||||
|
|
|
|||
|
|
@ -5,7 +5,8 @@ Client Driver Documentation
|
|||
===========================
|
||||
|
||||
This is the documentation for client drivers themselves. Refer to
|
||||
:doc:`../client` for documentation on how to write client drivers.
|
||||
Documentation/driver-api/surface_aggregator/client.rst for documentation
|
||||
on how to write client drivers.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
|
|
|||
|
|
@ -87,10 +87,11 @@ native SSAM devices, i.e. devices that are not defined in ACPI and not
|
|||
implemented as platform devices, via |ssam_device| and |ssam_device_driver|
|
||||
simplify management of client devices and client drivers.
|
||||
|
||||
Refer to :doc:`client` for documentation regarding the client device/driver
|
||||
API and interface options for other kernel drivers. It is recommended to
|
||||
familiarize oneself with that chapter and the :doc:`ssh` before continuing
|
||||
with the architectural overview below.
|
||||
Refer to Documentation/driver-api/surface_aggregator/client.rst for
|
||||
documentation regarding the client device/driver API and interface options
|
||||
for other kernel drivers. It is recommended to familiarize oneself with
|
||||
that chapter and the Documentation/driver-api/surface_aggregator/ssh.rst
|
||||
before continuing with the architectural overview below.
|
||||
|
||||
|
||||
Packet Transport Layer
|
||||
|
|
@ -190,9 +191,9 @@ with success on the transmitter thread.
|
|||
|
||||
Transmission of sequenced packets is limited by the number of concurrently
|
||||
pending packets, i.e. a limit on how many packets may be waiting for an ACK
|
||||
from the EC in parallel. This limit is currently set to one (see :doc:`ssh`
|
||||
for the reasoning behind this). Control packets (i.e. ACK and NAK) can
|
||||
always be transmitted.
|
||||
from the EC in parallel. This limit is currently set to one (see
|
||||
Documentation/driver-api/surface_aggregator/ssh.rst for the reasoning behind
|
||||
this). Control packets (i.e. ACK and NAK) can always be transmitted.
|
||||
|
||||
Receiver Thread
|
||||
---------------
|
||||
|
|
|
|||
|
|
@ -73,5 +73,7 @@ being a direct response to a previous request. We may also refer to requests
|
|||
without response as commands. In general, events need to be enabled via one
|
||||
of multiple dedicated requests before they are sent by the EC.
|
||||
|
||||
See :doc:`ssh` for a more technical protocol documentation and
|
||||
:doc:`internal` for an overview of the internal driver architecture.
|
||||
See Documentation/driver-api/surface_aggregator/ssh.rst for a
|
||||
more technical protocol documentation and
|
||||
Documentation/driver-api/surface_aggregator/internal.rst for an
|
||||
overview of the internal driver architecture.
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ API overview
|
|||
|
||||
The big picture is that USB drivers can continue to ignore most DMA issues,
|
||||
though they still must provide DMA-ready buffers (see
|
||||
:doc:`/core-api/dma-api-howto`). That's how they've worked through
|
||||
Documentation/core-api/dma-api-howto.rst). That's how they've worked through
|
||||
the 2.4 (and earlier) kernels, or they can now be DMA-aware.
|
||||
|
||||
DMA-aware usb drivers:
|
||||
|
|
@ -60,7 +60,7 @@ and effects like cache-trashing can impose subtle penalties.
|
|||
force a consistent memory access ordering by using memory barriers. It's
|
||||
not using a streaming DMA mapping, so it's good for small transfers on
|
||||
systems where the I/O would otherwise thrash an IOMMU mapping. (See
|
||||
:doc:`/core-api/dma-api-howto` for definitions of "coherent" and
|
||||
Documentation/core-api/dma-api-howto.rst for definitions of "coherent" and
|
||||
"streaming" DMA mappings.)
|
||||
|
||||
Asking for 1/Nth of a page (as well as asking for N pages) is reasonably
|
||||
|
|
@ -91,7 +91,7 @@ Working with existing buffers
|
|||
Existing buffers aren't usable for DMA without first being mapped into the
|
||||
DMA address space of the device. However, most buffers passed to your
|
||||
driver can safely be used with such DMA mapping. (See the first section
|
||||
of :doc:`/core-api/dma-api-howto`, titled "What memory is DMA-able?")
|
||||
of Documentation/core-api/dma-api-howto.rst, titled "What memory is DMA-able?")
|
||||
|
||||
- When you're using scatterlists, you can map everything at once. On some
|
||||
systems, this kicks in an IOMMU and turns the scatterlists into single
|
||||
|
|
|
|||
|
|
@ -78,8 +78,10 @@ configuration of fault-injection capabilities.
|
|||
|
||||
- /sys/kernel/debug/fail*/times:
|
||||
|
||||
specifies how many times failures may happen at most.
|
||||
A value of -1 means "no limit".
|
||||
specifies how many times failures may happen at most. A value of -1
|
||||
means "no limit". Note, though, that this file only accepts unsigned
|
||||
values. So, if you want to specify -1, you better use 'printf' instead
|
||||
of 'echo', e.g.: $ printf %#x -1 > times
|
||||
|
||||
- /sys/kernel/debug/fail*/space:
|
||||
|
||||
|
|
@ -167,11 +169,13 @@ configuration of fault-injection capabilities.
|
|||
- ERRNO: retval must be -1 to -MAX_ERRNO (-4096).
|
||||
- ERR_NULL: retval must be 0 or -1 to -MAX_ERRNO (-4096).
|
||||
|
||||
- /sys/kernel/debug/fail_function/<functiuon-name>/retval:
|
||||
- /sys/kernel/debug/fail_function/<function-name>/retval:
|
||||
|
||||
specifies the "error" return value to inject to the given
|
||||
function for given function. This will be created when
|
||||
user specifies new injection entry.
|
||||
specifies the "error" return value to inject to the given function.
|
||||
This will be created when the user specifies a new injection entry.
|
||||
Note that this file only accepts unsigned values. So, if you want to
|
||||
use a negative errno, you better use 'printf' instead of 'echo', e.g.:
|
||||
$ printf %#x -12 > retval
|
||||
|
||||
Boot option
|
||||
^^^^^^^^^^^
|
||||
|
|
@ -255,7 +259,7 @@ Application Examples
|
|||
echo Y > /sys/kernel/debug/$FAILTYPE/task-filter
|
||||
echo 10 > /sys/kernel/debug/$FAILTYPE/probability
|
||||
echo 100 > /sys/kernel/debug/$FAILTYPE/interval
|
||||
echo -1 > /sys/kernel/debug/$FAILTYPE/times
|
||||
printf %#x -1 > /sys/kernel/debug/$FAILTYPE/times
|
||||
echo 0 > /sys/kernel/debug/$FAILTYPE/space
|
||||
echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
|
||||
echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
|
||||
|
|
@ -309,7 +313,7 @@ Application Examples
|
|||
echo N > /sys/kernel/debug/$FAILTYPE/task-filter
|
||||
echo 10 > /sys/kernel/debug/$FAILTYPE/probability
|
||||
echo 100 > /sys/kernel/debug/$FAILTYPE/interval
|
||||
echo -1 > /sys/kernel/debug/$FAILTYPE/times
|
||||
printf %#x -1 > /sys/kernel/debug/$FAILTYPE/times
|
||||
echo 0 > /sys/kernel/debug/$FAILTYPE/space
|
||||
echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
|
||||
echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
|
||||
|
|
@ -336,11 +340,11 @@ Application Examples
|
|||
FAILTYPE=fail_function
|
||||
FAILFUNC=open_ctree
|
||||
echo $FAILFUNC > /sys/kernel/debug/$FAILTYPE/inject
|
||||
echo -12 > /sys/kernel/debug/$FAILTYPE/$FAILFUNC/retval
|
||||
printf %#x -12 > /sys/kernel/debug/$FAILTYPE/$FAILFUNC/retval
|
||||
echo N > /sys/kernel/debug/$FAILTYPE/task-filter
|
||||
echo 100 > /sys/kernel/debug/$FAILTYPE/probability
|
||||
echo 0 > /sys/kernel/debug/$FAILTYPE/interval
|
||||
echo -1 > /sys/kernel/debug/$FAILTYPE/times
|
||||
printf %#x -1 > /sys/kernel/debug/$FAILTYPE/times
|
||||
echo 0 > /sys/kernel/debug/$FAILTYPE/space
|
||||
echo 1 > /sys/kernel/debug/$FAILTYPE/verbose
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,291 @@
|
|||
=======================
|
||||
Direct Access for files
|
||||
=======================
|
||||
|
||||
Motivation
|
||||
----------
|
||||
|
||||
The page cache is usually used to buffer reads and writes to files.
|
||||
It is also used to provide the pages which are mapped into userspace
|
||||
by a call to mmap.
|
||||
|
||||
For block devices that are memory-like, the page cache pages would be
|
||||
unnecessary copies of the original storage. The `DAX` code removes the
|
||||
extra copy by performing reads and writes directly to the storage device.
|
||||
For file mappings, the storage device is mapped directly into userspace.
|
||||
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
If you have a block device which supports `DAX`, you can make a filesystem
|
||||
on it as usual. The `DAX` code currently only supports files with a block
|
||||
size equal to your kernel's `PAGE_SIZE`, so you may need to specify a block
|
||||
size when creating the filesystem.
|
||||
|
||||
Currently 3 filesystems support `DAX`: ext2, ext4 and xfs. Enabling `DAX` on them
|
||||
is different.
|
||||
|
||||
Enabling DAX on ext2
|
||||
--------------------
|
||||
|
||||
When mounting the filesystem, use the ``-o dax`` option on the command line or
|
||||
add 'dax' to the options in ``/etc/fstab``. This works to enable `DAX` on all files
|
||||
within the filesystem. It is equivalent to the ``-o dax=always`` behavior below.
|
||||
|
||||
|
||||
Enabling DAX on xfs and ext4
|
||||
----------------------------
|
||||
|
||||
Summary
|
||||
-------
|
||||
|
||||
1. There exists an in-kernel file access mode flag `S_DAX` that corresponds to
|
||||
the statx flag `STATX_ATTR_DAX`. See the manpage for statx(2) for details
|
||||
about this access mode.
|
||||
|
||||
2. There exists a persistent flag `FS_XFLAG_DAX` that can be applied to regular
|
||||
files and directories. This advisory flag can be set or cleared at any
|
||||
time, but doing so does not immediately affect the `S_DAX` state.
|
||||
|
||||
3. If the persistent `FS_XFLAG_DAX` flag is set on a directory, this flag will
|
||||
be inherited by all regular files and subdirectories that are subsequently
|
||||
created in this directory. Files and subdirectories that exist at the time
|
||||
this flag is set or cleared on the parent directory are not modified by
|
||||
this modification of the parent directory.
|
||||
|
||||
4. There exist dax mount options which can override `FS_XFLAG_DAX` in the
|
||||
setting of the `S_DAX` flag. Given underlying storage which supports `DAX` the
|
||||
following hold:
|
||||
|
||||
``-o dax=inode`` means "follow `FS_XFLAG_DAX`" and is the default.
|
||||
|
||||
``-o dax=never`` means "never set `S_DAX`, ignore `FS_XFLAG_DAX`."
|
||||
|
||||
``-o dax=always`` means "always set `S_DAX` ignore `FS_XFLAG_DAX`."
|
||||
|
||||
``-o dax`` is a legacy option which is an alias for ``dax=always``.
|
||||
|
||||
.. warning::
|
||||
|
||||
The option ``-o dax`` may be removed in the future so ``-o dax=always`` is
|
||||
the preferred method for specifying this behavior.
|
||||
|
||||
.. note::
|
||||
|
||||
Modifications to and the inheritance behavior of `FS_XFLAG_DAX` remain
|
||||
the same even when the filesystem is mounted with a dax option. However,
|
||||
in-core inode state (`S_DAX`) will be overridden until the filesystem is
|
||||
remounted with dax=inode and the inode is evicted from kernel memory.
|
||||
|
||||
5. The `S_DAX` policy can be changed via:
|
||||
|
||||
a) Setting the parent directory `FS_XFLAG_DAX` as needed before files are
|
||||
created
|
||||
|
||||
b) Setting the appropriate dax="foo" mount option
|
||||
|
||||
c) Changing the `FS_XFLAG_DAX` flag on existing regular files and
|
||||
directories. This has runtime constraints and limitations that are
|
||||
described in 6) below.
|
||||
|
||||
6. When changing the `S_DAX` policy via toggling the persistent `FS_XFLAG_DAX`
|
||||
flag, the change to existing regular files won't take effect until the
|
||||
files are closed by all processes.
|
||||
|
||||
|
||||
Details
|
||||
-------
|
||||
|
||||
There are 2 per-file dax flags. One is a persistent inode setting (`FS_XFLAG_DAX`)
|
||||
and the other is a volatile flag indicating the active state of the feature
|
||||
(`S_DAX`).
|
||||
|
||||
`FS_XFLAG_DAX` is preserved within the filesystem. This persistent config
|
||||
setting can be set, cleared and/or queried using the `FS_IOC_FS`[`GS`]`ETXATTR` ioctl
|
||||
(see ioctl_xfs_fsgetxattr(2)) or an utility such as 'xfs_io'.
|
||||
|
||||
New files and directories automatically inherit `FS_XFLAG_DAX` from
|
||||
their parent directory **when created**. Therefore, setting `FS_XFLAG_DAX` at
|
||||
directory creation time can be used to set a default behavior for an entire
|
||||
sub-tree.
|
||||
|
||||
To clarify inheritance, here are 3 examples:
|
||||
|
||||
Example A:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
mkdir -p a/b/c
|
||||
xfs_io -c 'chattr +x' a
|
||||
mkdir a/b/c/d
|
||||
mkdir a/e
|
||||
|
||||
------[outcome]------
|
||||
|
||||
dax: a,e
|
||||
no dax: b,c,d
|
||||
|
||||
Example B:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
mkdir a
|
||||
xfs_io -c 'chattr +x' a
|
||||
mkdir -p a/b/c/d
|
||||
|
||||
------[outcome]------
|
||||
|
||||
dax: a,b,c,d
|
||||
no dax:
|
||||
|
||||
Example C:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
mkdir -p a/b/c
|
||||
xfs_io -c 'chattr +x' c
|
||||
mkdir a/b/c/d
|
||||
|
||||
------[outcome]------
|
||||
|
||||
dax: c,d
|
||||
no dax: a,b
|
||||
|
||||
The current enabled state (`S_DAX`) is set when a file inode is instantiated in
|
||||
memory by the kernel. It is set based on the underlying media support, the
|
||||
value of `FS_XFLAG_DAX` and the filesystem's dax mount option.
|
||||
|
||||
statx can be used to query `S_DAX`.
|
||||
|
||||
.. note::
|
||||
|
||||
That only regular files will ever have `S_DAX` set and therefore statx
|
||||
will never indicate that `S_DAX` is set on directories.
|
||||
|
||||
Setting the `FS_XFLAG_DAX` flag (specifically or through inheritance) occurs even
|
||||
if the underlying media does not support dax and/or the filesystem is
|
||||
overridden with a mount option.
|
||||
|
||||
|
||||
Implementation Tips for Block Driver Writers
|
||||
--------------------------------------------
|
||||
|
||||
To support `DAX` in your block driver, implement the 'direct_access'
|
||||
block device operation. It is used to translate the sector number
|
||||
(expressed in units of 512-byte sectors) to a page frame number (pfn)
|
||||
that identifies the physical page for the memory. It also returns a
|
||||
kernel virtual address that can be used to access the memory.
|
||||
|
||||
The direct_access method takes a 'size' parameter that indicates the
|
||||
number of bytes being requested. The function should return the number
|
||||
of bytes that can be contiguously accessed at that offset. It may also
|
||||
return a negative errno if an error occurs.
|
||||
|
||||
In order to support this method, the storage must be byte-accessible by
|
||||
the CPU at all times. If your device uses paging techniques to expose
|
||||
a large amount of memory through a smaller window, then you cannot
|
||||
implement direct_access. Equally, if your device can occasionally
|
||||
stall the CPU for an extended period, you should also not attempt to
|
||||
implement direct_access.
|
||||
|
||||
These block devices may be used for inspiration:
|
||||
- brd: RAM backed block device driver
|
||||
- dcssblk: s390 dcss block device driver
|
||||
- pmem: NVDIMM persistent memory driver
|
||||
|
||||
|
||||
Implementation Tips for Filesystem Writers
|
||||
------------------------------------------
|
||||
|
||||
Filesystem support consists of:
|
||||
|
||||
* Adding support to mark inodes as being `DAX` by setting the `S_DAX` flag in
|
||||
i_flags
|
||||
* Implementing ->read_iter and ->write_iter operations which use
|
||||
:c:func:`dax_iomap_rw()` when inode has `S_DAX` flag set
|
||||
* Implementing an mmap file operation for `DAX` files which sets the
|
||||
`VM_MIXEDMAP` and `VM_HUGEPAGE` flags on the `VMA`, and setting the vm_ops to
|
||||
include handlers for fault, pmd_fault, page_mkwrite, pfn_mkwrite. These
|
||||
handlers should probably call :c:func:`dax_iomap_fault()` passing the
|
||||
appropriate fault size and iomap operations.
|
||||
* Calling :c:func:`iomap_zero_range()` passing appropriate iomap operations
|
||||
instead of :c:func:`block_truncate_page()` for `DAX` files
|
||||
* Ensuring that there is sufficient locking between reads, writes,
|
||||
truncates and page faults
|
||||
|
||||
The iomap handlers for allocating blocks must make sure that allocated blocks
|
||||
are zeroed out and converted to written extents before being returned to avoid
|
||||
exposure of uninitialized data through mmap.
|
||||
|
||||
These filesystems may be used for inspiration:
|
||||
|
||||
.. seealso::
|
||||
|
||||
ext2: see Documentation/filesystems/ext2.rst
|
||||
|
||||
.. seealso::
|
||||
|
||||
xfs: see Documentation/admin-guide/xfs.rst
|
||||
|
||||
.. seealso::
|
||||
|
||||
ext4: see Documentation/filesystems/ext4/
|
||||
|
||||
|
||||
Handling Media Errors
|
||||
---------------------
|
||||
|
||||
The libnvdimm subsystem stores a record of known media error locations for
|
||||
each pmem block device (in gendisk->badblocks). If we fault at such location,
|
||||
or one with a latent error not yet discovered, the application can expect
|
||||
to receive a `SIGBUS`. Libnvdimm also allows clearing of these errors by simply
|
||||
writing the affected sectors (through the pmem driver, and if the underlying
|
||||
NVDIMM supports the clear_poison DSM defined by ACPI).
|
||||
|
||||
Since `DAX` IO normally doesn't go through the ``driver/bio`` path, applications or
|
||||
sysadmins have an option to restore the lost data from a prior ``backup/inbuilt``
|
||||
redundancy in the following ways:
|
||||
|
||||
1. Delete the affected file, and restore from a backup (sysadmin route):
|
||||
This will free the filesystem blocks that were being used by the file,
|
||||
and the next time they're allocated, they will be zeroed first, which
|
||||
happens through the driver, and will clear bad sectors.
|
||||
|
||||
2. Truncate or hole-punch the part of the file that has a bad-block (at least
|
||||
an entire aligned sector has to be hole-punched, but not necessarily an
|
||||
entire filesystem block).
|
||||
|
||||
These are the two basic paths that allow `DAX` filesystems to continue operating
|
||||
in the presence of media errors. More robust error recovery mechanisms can be
|
||||
built on top of this in the future, for example, involving redundancy/mirroring
|
||||
provided at the block layer through DM, or additionally, at the filesystem
|
||||
level. These would have to rely on the above two tenets, that error clearing
|
||||
can happen either by sending an IO through the driver, or zeroing (also through
|
||||
the driver).
|
||||
|
||||
|
||||
Shortcomings
|
||||
------------
|
||||
|
||||
Even if the kernel or its modules are stored on a filesystem that supports
|
||||
`DAX` on a block device that supports `DAX`, they will still be copied into RAM.
|
||||
|
||||
The DAX code does not work correctly on architectures which have virtually
|
||||
mapped caches such as ARM, MIPS and SPARC.
|
||||
|
||||
Calling :c:func:`get_user_pages()` on a range of user memory that has been
|
||||
mmaped from a `DAX` file will fail when there are no 'struct page' to describe
|
||||
those pages. This problem has been addressed in some device drivers
|
||||
by adding optional struct page support for pages under the control of
|
||||
the driver (see `CONFIG_NVDIMM_PFN` in ``drivers/nvdimm`` for an example of
|
||||
how to do this). In the non struct page cases `O_DIRECT` reads/writes to
|
||||
those memory ranges from a non-`DAX` file will fail
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
`O_DIRECT` reads/writes _of a `DAX` file do work, it is the memory that
|
||||
is being accessed that is key here). Other things that will not work in
|
||||
the non struct page case include RDMA, :c:func:`sendfile()` and
|
||||
:c:func:`splice()`.
|
||||
|
|
@ -1,257 +0,0 @@
|
|||
Direct Access for files
|
||||
-----------------------
|
||||
|
||||
Motivation
|
||||
----------
|
||||
|
||||
The page cache is usually used to buffer reads and writes to files.
|
||||
It is also used to provide the pages which are mapped into userspace
|
||||
by a call to mmap.
|
||||
|
||||
For block devices that are memory-like, the page cache pages would be
|
||||
unnecessary copies of the original storage. The DAX code removes the
|
||||
extra copy by performing reads and writes directly to the storage device.
|
||||
For file mappings, the storage device is mapped directly into userspace.
|
||||
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
If you have a block device which supports DAX, you can make a filesystem
|
||||
on it as usual. The DAX code currently only supports files with a block
|
||||
size equal to your kernel's PAGE_SIZE, so you may need to specify a block
|
||||
size when creating the filesystem.
|
||||
|
||||
Currently 3 filesystems support DAX: ext2, ext4 and xfs. Enabling DAX on them
|
||||
is different.
|
||||
|
||||
Enabling DAX on ext2
|
||||
-----------------------------
|
||||
|
||||
When mounting the filesystem, use the "-o dax" option on the command line or
|
||||
add 'dax' to the options in /etc/fstab. This works to enable DAX on all files
|
||||
within the filesystem. It is equivalent to the '-o dax=always' behavior below.
|
||||
|
||||
|
||||
Enabling DAX on xfs and ext4
|
||||
----------------------------
|
||||
|
||||
Summary
|
||||
-------
|
||||
|
||||
1. There exists an in-kernel file access mode flag S_DAX that corresponds to
|
||||
the statx flag STATX_ATTR_DAX. See the manpage for statx(2) for details
|
||||
about this access mode.
|
||||
|
||||
2. There exists a persistent flag FS_XFLAG_DAX that can be applied to regular
|
||||
files and directories. This advisory flag can be set or cleared at any
|
||||
time, but doing so does not immediately affect the S_DAX state.
|
||||
|
||||
3. If the persistent FS_XFLAG_DAX flag is set on a directory, this flag will
|
||||
be inherited by all regular files and subdirectories that are subsequently
|
||||
created in this directory. Files and subdirectories that exist at the time
|
||||
this flag is set or cleared on the parent directory are not modified by
|
||||
this modification of the parent directory.
|
||||
|
||||
4. There exist dax mount options which can override FS_XFLAG_DAX in the
|
||||
setting of the S_DAX flag. Given underlying storage which supports DAX the
|
||||
following hold:
|
||||
|
||||
"-o dax=inode" means "follow FS_XFLAG_DAX" and is the default.
|
||||
|
||||
"-o dax=never" means "never set S_DAX, ignore FS_XFLAG_DAX."
|
||||
|
||||
"-o dax=always" means "always set S_DAX ignore FS_XFLAG_DAX."
|
||||
|
||||
"-o dax" is a legacy option which is an alias for "dax=always".
|
||||
This may be removed in the future so "-o dax=always" is
|
||||
the preferred method for specifying this behavior.
|
||||
|
||||
NOTE: Modifications to and the inheritance behavior of FS_XFLAG_DAX remain
|
||||
the same even when the filesystem is mounted with a dax option. However,
|
||||
in-core inode state (S_DAX) will be overridden until the filesystem is
|
||||
remounted with dax=inode and the inode is evicted from kernel memory.
|
||||
|
||||
5. The S_DAX policy can be changed via:
|
||||
|
||||
a) Setting the parent directory FS_XFLAG_DAX as needed before files are
|
||||
created
|
||||
|
||||
b) Setting the appropriate dax="foo" mount option
|
||||
|
||||
c) Changing the FS_XFLAG_DAX flag on existing regular files and
|
||||
directories. This has runtime constraints and limitations that are
|
||||
described in 6) below.
|
||||
|
||||
6. When changing the S_DAX policy via toggling the persistent FS_XFLAG_DAX
|
||||
flag, the change to existing regular files won't take effect until the
|
||||
files are closed by all processes.
|
||||
|
||||
|
||||
Details
|
||||
-------
|
||||
|
||||
There are 2 per-file dax flags. One is a persistent inode setting (FS_XFLAG_DAX)
|
||||
and the other is a volatile flag indicating the active state of the feature
|
||||
(S_DAX).
|
||||
|
||||
FS_XFLAG_DAX is preserved within the filesystem. This persistent config
|
||||
setting can be set, cleared and/or queried using the FS_IOC_FS[GS]ETXATTR ioctl
|
||||
(see ioctl_xfs_fsgetxattr(2)) or an utility such as 'xfs_io'.
|
||||
|
||||
New files and directories automatically inherit FS_XFLAG_DAX from
|
||||
their parent directory _when_ _created_. Therefore, setting FS_XFLAG_DAX at
|
||||
directory creation time can be used to set a default behavior for an entire
|
||||
sub-tree.
|
||||
|
||||
To clarify inheritance, here are 3 examples:
|
||||
|
||||
Example A:
|
||||
|
||||
mkdir -p a/b/c
|
||||
xfs_io -c 'chattr +x' a
|
||||
mkdir a/b/c/d
|
||||
mkdir a/e
|
||||
|
||||
dax: a,e
|
||||
no dax: b,c,d
|
||||
|
||||
Example B:
|
||||
|
||||
mkdir a
|
||||
xfs_io -c 'chattr +x' a
|
||||
mkdir -p a/b/c/d
|
||||
|
||||
dax: a,b,c,d
|
||||
no dax:
|
||||
|
||||
Example C:
|
||||
|
||||
mkdir -p a/b/c
|
||||
xfs_io -c 'chattr +x' c
|
||||
mkdir a/b/c/d
|
||||
|
||||
dax: c,d
|
||||
no dax: a,b
|
||||
|
||||
|
||||
The current enabled state (S_DAX) is set when a file inode is instantiated in
|
||||
memory by the kernel. It is set based on the underlying media support, the
|
||||
value of FS_XFLAG_DAX and the filesystem's dax mount option.
|
||||
|
||||
statx can be used to query S_DAX. NOTE that only regular files will ever have
|
||||
S_DAX set and therefore statx will never indicate that S_DAX is set on
|
||||
directories.
|
||||
|
||||
Setting the FS_XFLAG_DAX flag (specifically or through inheritance) occurs even
|
||||
if the underlying media does not support dax and/or the filesystem is
|
||||
overridden with a mount option.
|
||||
|
||||
|
||||
|
||||
Implementation Tips for Block Driver Writers
|
||||
--------------------------------------------
|
||||
|
||||
To support DAX in your block driver, implement the 'direct_access'
|
||||
block device operation. It is used to translate the sector number
|
||||
(expressed in units of 512-byte sectors) to a page frame number (pfn)
|
||||
that identifies the physical page for the memory. It also returns a
|
||||
kernel virtual address that can be used to access the memory.
|
||||
|
||||
The direct_access method takes a 'size' parameter that indicates the
|
||||
number of bytes being requested. The function should return the number
|
||||
of bytes that can be contiguously accessed at that offset. It may also
|
||||
return a negative errno if an error occurs.
|
||||
|
||||
In order to support this method, the storage must be byte-accessible by
|
||||
the CPU at all times. If your device uses paging techniques to expose
|
||||
a large amount of memory through a smaller window, then you cannot
|
||||
implement direct_access. Equally, if your device can occasionally
|
||||
stall the CPU for an extended period, you should also not attempt to
|
||||
implement direct_access.
|
||||
|
||||
These block devices may be used for inspiration:
|
||||
- brd: RAM backed block device driver
|
||||
- dcssblk: s390 dcss block device driver
|
||||
- pmem: NVDIMM persistent memory driver
|
||||
|
||||
|
||||
Implementation Tips for Filesystem Writers
|
||||
------------------------------------------
|
||||
|
||||
Filesystem support consists of
|
||||
- adding support to mark inodes as being DAX by setting the S_DAX flag in
|
||||
i_flags
|
||||
- implementing ->read_iter and ->write_iter operations which use dax_iomap_rw()
|
||||
when inode has S_DAX flag set
|
||||
- implementing an mmap file operation for DAX files which sets the
|
||||
VM_MIXEDMAP and VM_HUGEPAGE flags on the VMA, and setting the vm_ops to
|
||||
include handlers for fault, pmd_fault, page_mkwrite, pfn_mkwrite. These
|
||||
handlers should probably call dax_iomap_fault() passing the appropriate
|
||||
fault size and iomap operations.
|
||||
- calling iomap_zero_range() passing appropriate iomap operations instead of
|
||||
block_truncate_page() for DAX files
|
||||
- ensuring that there is sufficient locking between reads, writes,
|
||||
truncates and page faults
|
||||
|
||||
The iomap handlers for allocating blocks must make sure that allocated blocks
|
||||
are zeroed out and converted to written extents before being returned to avoid
|
||||
exposure of uninitialized data through mmap.
|
||||
|
||||
These filesystems may be used for inspiration:
|
||||
- ext2: see Documentation/filesystems/ext2.rst
|
||||
- ext4: see Documentation/filesystems/ext4/
|
||||
- xfs: see Documentation/admin-guide/xfs.rst
|
||||
|
||||
|
||||
Handling Media Errors
|
||||
---------------------
|
||||
|
||||
The libnvdimm subsystem stores a record of known media error locations for
|
||||
each pmem block device (in gendisk->badblocks). If we fault at such location,
|
||||
or one with a latent error not yet discovered, the application can expect
|
||||
to receive a SIGBUS. Libnvdimm also allows clearing of these errors by simply
|
||||
writing the affected sectors (through the pmem driver, and if the underlying
|
||||
NVDIMM supports the clear_poison DSM defined by ACPI).
|
||||
|
||||
Since DAX IO normally doesn't go through the driver/bio path, applications or
|
||||
sysadmins have an option to restore the lost data from a prior backup/inbuilt
|
||||
redundancy in the following ways:
|
||||
|
||||
1. Delete the affected file, and restore from a backup (sysadmin route):
|
||||
This will free the filesystem blocks that were being used by the file,
|
||||
and the next time they're allocated, they will be zeroed first, which
|
||||
happens through the driver, and will clear bad sectors.
|
||||
|
||||
2. Truncate or hole-punch the part of the file that has a bad-block (at least
|
||||
an entire aligned sector has to be hole-punched, but not necessarily an
|
||||
entire filesystem block).
|
||||
|
||||
These are the two basic paths that allow DAX filesystems to continue operating
|
||||
in the presence of media errors. More robust error recovery mechanisms can be
|
||||
built on top of this in the future, for example, involving redundancy/mirroring
|
||||
provided at the block layer through DM, or additionally, at the filesystem
|
||||
level. These would have to rely on the above two tenets, that error clearing
|
||||
can happen either by sending an IO through the driver, or zeroing (also through
|
||||
the driver).
|
||||
|
||||
|
||||
Shortcomings
|
||||
------------
|
||||
|
||||
Even if the kernel or its modules are stored on a filesystem that supports
|
||||
DAX on a block device that supports DAX, they will still be copied into RAM.
|
||||
|
||||
The DAX code does not work correctly on architectures which have virtually
|
||||
mapped caches such as ARM, MIPS and SPARC.
|
||||
|
||||
Calling get_user_pages() on a range of user memory that has been mmaped
|
||||
from a DAX file will fail when there are no 'struct page' to describe
|
||||
those pages. This problem has been addressed in some device drivers
|
||||
by adding optional struct page support for pages under the control of
|
||||
the driver (see CONFIG_NVDIMM_PFN in drivers/nvdimm for an example of
|
||||
how to do this). In the non struct page cases O_DIRECT reads/writes to
|
||||
those memory ranges from a non-DAX file will fail (note that O_DIRECT
|
||||
reads/writes _of a DAX file_ do work, it is the memory that is being
|
||||
accessed that is key here). Other things that will not work in the
|
||||
non struct page case include RDMA, sendfile() and splice().
|
||||
|
|
@ -25,7 +25,7 @@ check=none, nocheck (*) Don't do extra checking of bitmaps on mount
|
|||
(check=normal and check=strict options removed)
|
||||
|
||||
dax Use direct access (no page cache). See
|
||||
Documentation/filesystems/dax.txt.
|
||||
Documentation/filesystems/dax.rst.
|
||||
|
||||
debug Extra debugging information is sent to the
|
||||
kernel syslog. Useful for developers.
|
||||
|
|
|
|||
|
|
@ -84,7 +84,7 @@ Without the option META\_BG, for safety concerns, all block group
|
|||
descriptors copies are kept in the first block group. Given the default
|
||||
128MiB(2^27 bytes) block group size and 64-byte group descriptors, ext4
|
||||
can have at most 2^27/64 = 2^21 block groups. This limits the entire
|
||||
filesystem size to 2^21 ∗ 2^27 = 2^48bytes or 256TiB.
|
||||
filesystem size to 2^21 * 2^27 = 2^48bytes or 256TiB.
|
||||
|
||||
The solution to this problem is to use the metablock group feature
|
||||
(META\_BG), which is already in ext3 for all 2.6 releases. With the
|
||||
|
|
|
|||
|
|
@ -77,6 +77,7 @@ Documentation for filesystem implementations.
|
|||
coda
|
||||
configfs
|
||||
cramfs
|
||||
dax
|
||||
debugfs
|
||||
dlmfs
|
||||
ecryptfs
|
||||
|
|
|
|||
|
|
@ -448,15 +448,17 @@ described. If it finds a ``LAST_NORM`` component it first calls
|
|||
filesystem to revalidate the result if it is that sort of filesystem.
|
||||
If that doesn't get a good result, it calls "``lookup_slow()``" which
|
||||
takes ``i_rwsem``, rechecks the cache, and then asks the filesystem
|
||||
to find a definitive answer. Each of these will call
|
||||
``follow_managed()`` (as described below) to handle any mount points.
|
||||
to find a definitive answer.
|
||||
|
||||
In the absence of symbolic links, ``walk_component()`` creates a new
|
||||
``struct path`` containing a counted reference to the new dentry and a
|
||||
reference to the new ``vfsmount`` which is only counted if it is
|
||||
different from the previous ``vfsmount``. It then calls
|
||||
``path_to_nameidata()`` to install the new ``struct path`` in the
|
||||
``struct nameidata`` and drop the unneeded references.
|
||||
As the last step of walk_component(), step_into() will be called either
|
||||
directly from walk_component() or from handle_dots(). It calls
|
||||
handle_mounts(), to check and handle mount points, in which a new
|
||||
``struct path`` is created containing a counted reference to the new dentry and
|
||||
a reference to the new ``vfsmount`` which is only counted if it is
|
||||
different from the previous ``vfsmount``. Then if there is
|
||||
a symbolic link, step_into() calls pick_link() to deal with it,
|
||||
otherwise it installs the new ``struct path`` in the ``struct nameidata``, and
|
||||
drops the unneeded references.
|
||||
|
||||
This "hand-over-hand" sequencing of getting a reference to the new
|
||||
dentry before dropping the reference to the previous dentry may
|
||||
|
|
@ -470,8 +472,8 @@ Handling the final component
|
|||
``nd->last_type`` to refer to the final component of the path. It does
|
||||
not call ``walk_component()`` that last time. Handling that final
|
||||
component remains for the caller to sort out. Those callers are
|
||||
``path_lookupat()``, ``path_parentat()``, ``path_mountpoint()`` and
|
||||
``path_openat()`` each of which handles the differing requirements of
|
||||
path_lookupat(), path_parentat() and
|
||||
path_openat() each of which handles the differing requirements of
|
||||
different system calls.
|
||||
|
||||
``path_parentat()`` is clearly the simplest - it just wraps a little bit
|
||||
|
|
@ -486,20 +488,18 @@ perform their operation.
|
|||
object is wanted such as by ``stat()`` or ``chmod()``. It essentially just
|
||||
calls ``walk_component()`` on the final component through a call to
|
||||
``lookup_last()``. ``path_lookupat()`` returns just the final dentry.
|
||||
|
||||
``path_mountpoint()`` handles the special case of unmounting which must
|
||||
not try to revalidate the mounted filesystem. It effectively
|
||||
contains, through a call to ``mountpoint_last()``, an alternate
|
||||
implementation of ``lookup_slow()`` which skips that step. This is
|
||||
important when unmounting a filesystem that is inaccessible, such as
|
||||
It is worth noting that when flag ``LOOKUP_MOUNTPOINT`` is set,
|
||||
path_lookupat() will unset LOOKUP_JUMPED in nameidata so that in the
|
||||
subsequent path traversal d_weak_revalidate() won't be called.
|
||||
This is important when unmounting a filesystem that is inaccessible, such as
|
||||
one provided by a dead NFS server.
|
||||
|
||||
Finally ``path_openat()`` is used for the ``open()`` system call; it
|
||||
contains, in support functions starting with "``do_last()``", all the
|
||||
contains, in support functions starting with "open_last_lookups()", all the
|
||||
complexity needed to handle the different subtleties of O_CREAT (with
|
||||
or without O_EXCL), final "``/``" characters, and trailing symbolic
|
||||
links. We will revisit this in the final part of this series, which
|
||||
focuses on those symbolic links. "``do_last()``" will sometimes, but
|
||||
focuses on those symbolic links. "open_last_lookups()" will sometimes, but
|
||||
not always, take ``i_rwsem``, depending on what it finds.
|
||||
|
||||
Each of these, or the functions which call them, need to be alert to
|
||||
|
|
@ -535,8 +535,7 @@ covered in greater detail in autofs.txt in the Linux documentation
|
|||
tree, but a few notes specifically related to path lookup are in order
|
||||
here.
|
||||
|
||||
The Linux VFS has a concept of "managed" dentries which is reflected
|
||||
in function names such as "``follow_managed()``". There are three
|
||||
The Linux VFS has a concept of "managed" dentries. There are three
|
||||
potentially interesting things about these dentries corresponding
|
||||
to three different flags that might be set in ``dentry->d_flags``:
|
||||
|
||||
|
|
@ -652,10 +651,10 @@ RCU-walk finds it cannot stop gracefully, it simply gives up and
|
|||
restarts from the top with REF-walk.
|
||||
|
||||
This pattern of "try RCU-walk, if that fails try REF-walk" can be
|
||||
clearly seen in functions like ``filename_lookup()``,
|
||||
``filename_parentat()``, ``filename_mountpoint()``,
|
||||
``do_filp_open()``, and ``do_file_open_root()``. These five
|
||||
correspond roughly to the four ``path_*()`` functions we met earlier,
|
||||
clearly seen in functions like filename_lookup(),
|
||||
filename_parentat(),
|
||||
do_filp_open(), and do_file_open_root(). These four
|
||||
correspond roughly to the three ``path_*()`` functions we met earlier,
|
||||
each of which calls ``link_path_walk()``. The ``path_*()`` functions are
|
||||
called using different mode flags until a mode is found which works.
|
||||
They are first called with ``LOOKUP_RCU`` set to request "RCU-walk". If
|
||||
|
|
@ -993,8 +992,8 @@ is 4096. There are a number of reasons for this limit; not letting the
|
|||
kernel spend too much time on just one path is one of them. With
|
||||
symbolic links you can effectively generate much longer paths so some
|
||||
sort of limit is needed for the same reason. Linux imposes a limit of
|
||||
at most 40 symlinks in any one path lookup. It previously imposed a
|
||||
further limit of eight on the maximum depth of recursion, but that was
|
||||
at most 40 (MAXSYMLINKS) symlinks in any one path lookup. It previously imposed
|
||||
a further limit of eight on the maximum depth of recursion, but that was
|
||||
raised to 40 when a separate stack was implemented, so there is now
|
||||
just the one limit.
|
||||
|
||||
|
|
@ -1061,42 +1060,26 @@ filesystem cannot successfully get a reference in RCU-walk mode, it
|
|||
must return ``-ECHILD`` and ``unlazy_walk()`` will be called to return to
|
||||
REF-walk mode in which the filesystem is allowed to sleep.
|
||||
|
||||
The place for all this to happen is the ``i_op->follow_link()`` inode
|
||||
method. In the present mainline code this is never actually called in
|
||||
RCU-walk mode as the rewrite is not quite complete. It is likely that
|
||||
in a future release this method will be passed an ``inode`` pointer when
|
||||
called in RCU-walk mode so it both (1) knows to be careful, and (2) has the
|
||||
validated pointer. Much like the ``i_op->permission()`` method we
|
||||
looked at previously, ``->follow_link()`` would need to be careful that
|
||||
The place for all this to happen is the ``i_op->get_link()`` inode
|
||||
method. This is called both in RCU-walk and REF-walk. In RCU-walk the
|
||||
``dentry*`` argument is NULL, ``->get_link()`` can return -ECHILD to drop out of
|
||||
RCU-walk. Much like the ``i_op->permission()`` method we
|
||||
looked at previously, ``->get_link()`` would need to be careful that
|
||||
all the data structures it references are safe to be accessed while
|
||||
holding no counted reference, only the RCU lock. Though getting a
|
||||
reference with ``->follow_link()`` is not yet done in RCU-walk mode, the
|
||||
code is ready to release the reference when that does happen.
|
||||
|
||||
This need to drop the reference to a symlink adds significant
|
||||
complexity. It requires a reference to the inode so that the
|
||||
``i_op->put_link()`` inode operation can be called. In REF-walk, that
|
||||
reference is kept implicitly through a reference to the dentry, so
|
||||
keeping the ``struct path`` of the symlink is easiest. For RCU-walk,
|
||||
the pointer to the inode is kept separately. To allow switching from
|
||||
RCU-walk back to REF-walk in the middle of processing nested symlinks
|
||||
we also need the seq number for the dentry so we can confirm that
|
||||
switching back was safe.
|
||||
|
||||
Finally, when providing a reference to a symlink, the filesystem also
|
||||
provides an opaque "cookie" that must be passed to ``->put_link()`` so that it
|
||||
knows what to free. This might be the allocated memory area, or a
|
||||
pointer to the ``struct page`` in the page cache, or something else
|
||||
completely. Only the filesystem knows what it is.
|
||||
holding no counted reference, only the RCU lock. A callback
|
||||
``struct delayed_called`` will be passed to ``->get_link()``:
|
||||
file systems can set their own put_link function and argument through
|
||||
set_delayed_call(). Later on, when VFS wants to put link, it will call
|
||||
do_delayed_call() to invoke that callback function with the argument.
|
||||
|
||||
In order for the reference to each symlink to be dropped when the walk completes,
|
||||
whether in RCU-walk or REF-walk, the symlink stack needs to contain,
|
||||
along with the path remnants:
|
||||
|
||||
- the ``struct path`` to provide a reference to the inode in REF-walk
|
||||
- the ``struct inode *`` to provide a reference to the inode in RCU-walk
|
||||
- the ``struct path`` to provide a reference to the previous path
|
||||
- the ``const char *`` to provide a reference to the to previous name
|
||||
- the ``seq`` to allow the path to be safely switched from RCU-walk to REF-walk
|
||||
- the ``cookie`` that tells ``->put_path()`` what to put.
|
||||
- the ``struct delayed_call`` for later invocation.
|
||||
|
||||
This means that each entry in the symlink stack needs to hold five
|
||||
pointers and an integer instead of just one pointer (the path
|
||||
|
|
@ -1120,12 +1103,10 @@ doesn't need to notice. Getting this ``name`` variable on and off the
|
|||
stack is very straightforward; pushing and popping the references is
|
||||
a little more complex.
|
||||
|
||||
When a symlink is found, ``walk_component()`` returns the value ``1``
|
||||
(``0`` is returned for any other sort of success, and a negative number
|
||||
is, as usual, an error indicator). This causes ``get_link()`` to be
|
||||
called; it then gets the link from the filesystem. Providing that
|
||||
operation is successful, the old path ``name`` is placed on the stack,
|
||||
and the new value is used as the ``name`` for a while. When the end of
|
||||
When a symlink is found, walk_component() calls pick_link() via step_into()
|
||||
which returns the link from the filesystem.
|
||||
Providing that operation is successful, the old path ``name`` is placed on the
|
||||
stack, and the new value is used as the ``name`` for a while. When the end of
|
||||
the path is found (i.e. ``*name`` is ``'\0'``) the old ``name`` is restored
|
||||
off the stack and path walking continues.
|
||||
|
||||
|
|
@ -1142,23 +1123,23 @@ stack in ``walk_component()`` immediately when the symlink is found;
|
|||
old symlink as it walks that last component. So it is quite
|
||||
convenient for ``walk_component()`` to release the old symlink and pop
|
||||
the references just before pushing the reference information for the
|
||||
new symlink. It is guided in this by two flags; ``WALK_GET``, which
|
||||
gives it permission to follow a symlink if it finds one, and
|
||||
``WALK_PUT``, which tells it to release the current symlink after it has been
|
||||
followed. ``WALK_PUT`` is tested first, leading to a call to
|
||||
``put_link()``. ``WALK_GET`` is tested subsequently (by
|
||||
``should_follow_link()``) leading to a call to ``pick_link()`` which sets
|
||||
up the stack frame.
|
||||
new symlink. It is guided in this by three flags: ``WALK_NOFOLLOW`` which
|
||||
forbids it from following a symlink if it finds one, ``WALK_MORE``
|
||||
which indicates that it is yet too early to release the
|
||||
current symlink, and ``WALK_TRAILING`` which indicates that it is on the final
|
||||
component of the lookup, so we will check userspace flag ``LOOKUP_FOLLOW`` to
|
||||
decide whether follow it when it is a symlink and call ``may_follow_link()`` to
|
||||
check if we have privilege to follow it.
|
||||
|
||||
Symlinks with no final component
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
A pair of special-case symlinks deserve a little further explanation.
|
||||
Both result in a new ``struct path`` (with mount and dentry) being set
|
||||
up in the ``nameidata``, and result in ``get_link()`` returning ``NULL``.
|
||||
up in the ``nameidata``, and result in pick_link() returning ``NULL``.
|
||||
|
||||
The more obvious case is a symlink to "``/``". All symlinks starting
|
||||
with "``/``" are detected in ``get_link()`` which resets the ``nameidata``
|
||||
with "``/``" are detected in pick_link() which resets the ``nameidata``
|
||||
to point to the effective filesystem root. If the symlink only
|
||||
contains "``/``" then there is nothing more to do, no components at all,
|
||||
so ``NULL`` is returned to indicate that the symlink can be released and
|
||||
|
|
@ -1175,12 +1156,11 @@ something that looks like a symlink. It is really a reference to the
|
|||
target file, not just the name of it. When you ``readlink`` these
|
||||
objects you get a name that might refer to the same file - unless it
|
||||
has been unlinked or mounted over. When ``walk_component()`` follows
|
||||
one of these, the ``->follow_link()`` method in "procfs" doesn't return
|
||||
a string name, but instead calls ``nd_jump_link()`` which updates the
|
||||
``nameidata`` in place to point to that target. ``->follow_link()`` then
|
||||
returns ``NULL``. Again there is no final component and ``get_link()``
|
||||
reports this by leaving the ``last_type`` field of ``nameidata`` as
|
||||
``LAST_BIND``.
|
||||
one of these, the ``->get_link()`` method in "procfs" doesn't return
|
||||
a string name, but instead calls nd_jump_link() which updates the
|
||||
``nameidata`` in place to point to that target. ``->get_link()`` then
|
||||
returns ``NULL``. Again there is no final component and pick_link()
|
||||
returns ``NULL``.
|
||||
|
||||
Following the symlink in the final component
|
||||
--------------------------------------------
|
||||
|
|
@ -1197,42 +1177,38 @@ potentially need to call ``link_path_walk()`` again and again on
|
|||
successive symlinks until one is found that doesn't point to another
|
||||
symlink.
|
||||
|
||||
This case is handled by the relevant caller of ``link_path_walk()``, such as
|
||||
``path_lookupat()`` using a loop that calls ``link_path_walk()``, and then
|
||||
handles the final component. If the final component is a symlink
|
||||
that needs to be followed, then ``trailing_symlink()`` is called to set
|
||||
things up properly and the loop repeats, calling ``link_path_walk()``
|
||||
again. This could loop as many as 40 times if the last component of
|
||||
each symlink is another symlink.
|
||||
This case is handled by relevant callers of link_path_walk(), such as
|
||||
path_lookupat(), path_openat() using a loop that calls link_path_walk(),
|
||||
and then handles the final component by calling open_last_lookups() or
|
||||
lookup_last(). If it is a symlink that needs to be followed,
|
||||
open_last_lookups() or lookup_last() will set things up properly and
|
||||
return the path so that the loop repeats, calling
|
||||
link_path_walk() again. This could loop as many as 40 times if the last
|
||||
component of each symlink is another symlink.
|
||||
|
||||
The various functions that examine the final component and possibly
|
||||
report that it is a symlink are ``lookup_last()``, ``mountpoint_last()``
|
||||
and ``do_last()``, each of which use the same convention as
|
||||
``walk_component()`` of returning ``1`` if a symlink was found that needs
|
||||
to be followed.
|
||||
Of the various functions that examine the final component,
|
||||
open_last_lookups() is the most interesting as it works in tandem
|
||||
with do_open() for opening a file. Part of open_last_lookups() runs
|
||||
with ``i_rwsem`` held and this part is in a separate function: lookup_open().
|
||||
|
||||
Of these, ``do_last()`` is the most interesting as it is used for
|
||||
opening a file. Part of ``do_last()`` runs with ``i_rwsem`` held and this
|
||||
part is in a separate function: ``lookup_open()``.
|
||||
Explaining open_last_lookups() and do_open() completely is beyond the scope
|
||||
of this article, but a few highlights should help those interested in exploring
|
||||
the code.
|
||||
|
||||
Explaining ``do_last()`` completely is beyond the scope of this article,
|
||||
but a few highlights should help those interested in exploring the
|
||||
code.
|
||||
|
||||
1. Rather than just finding the target file, ``do_last()`` needs to open
|
||||
1. Rather than just finding the target file, do_open() is used after
|
||||
open_last_lookup() to open
|
||||
it. If the file was found in the dcache, then ``vfs_open()`` is used for
|
||||
this. If not, then ``lookup_open()`` will either call ``atomic_open()`` (if
|
||||
the filesystem provides it) to combine the final lookup with the open, or
|
||||
will perform the separate ``lookup_real()`` and ``vfs_create()`` steps
|
||||
will perform the separate ``i_op->lookup()`` and ``i_op->create()`` steps
|
||||
directly. In the later case the actual "open" of this newly found or
|
||||
created file will be performed by ``vfs_open()``, just as if the name
|
||||
created file will be performed by vfs_open(), just as if the name
|
||||
were found in the dcache.
|
||||
|
||||
2. ``vfs_open()`` can fail with ``-EOPENSTALE`` if the cached information
|
||||
wasn't quite current enough. Rather than restarting the lookup from
|
||||
the top with ``LOOKUP_REVAL`` set, ``lookup_open()`` is called instead,
|
||||
giving the filesystem a chance to resolve small inconsistencies.
|
||||
If that doesn't work, only then is the lookup restarted from the top.
|
||||
2. vfs_open() can fail with ``-EOPENSTALE`` if the cached information
|
||||
wasn't quite current enough. If it's in RCU-walk ``-ECHILD`` will be returned
|
||||
otherwise ``-ESTALE`` is returned. When ``-ESTALE`` is returned, the caller may
|
||||
retry with ``LOOKUP_REVAL`` flag set.
|
||||
|
||||
3. An open with O_CREAT **does** follow a symlink in the final component,
|
||||
unlike other creation system calls (like ``mkdir``). So the sequence::
|
||||
|
|
@ -1242,8 +1218,8 @@ code.
|
|||
|
||||
will create a file called ``/tmp/bar``. This is not permitted if
|
||||
``O_EXCL`` is set but otherwise is handled for an O_CREAT open much
|
||||
like for a non-creating open: ``should_follow_link()`` returns ``1``, and
|
||||
so does ``do_last()`` so that ``trailing_symlink()`` gets called and the
|
||||
like for a non-creating open: lookup_last() or open_last_lookup()
|
||||
returns a non ``NULL`` value, and link_path_walk() gets called and the
|
||||
open process continues on the symlink that was found.
|
||||
|
||||
Updating the access time
|
||||
|
|
|
|||
|
|
@ -79,7 +79,8 @@ the ANOD object which is also the final target node of the reference.
|
|||
})
|
||||
}
|
||||
|
||||
Please also see a graph example in :doc:`graph`.
|
||||
Please also see a graph example in
|
||||
Documentation/firmware-guide/acpi/dsd/graph.rst.
|
||||
|
||||
References
|
||||
==========
|
||||
|
|
|
|||
|
|
@ -174,4 +174,4 @@ References
|
|||
referenced 2016-10-04.
|
||||
|
||||
[7] _DSD Device Properties Usage Rules.
|
||||
:doc:`../DSD-properties-rules`
|
||||
Documentation/firmware-guide/acpi/DSD-properties-rules.rst
|
||||
|
|
|
|||
|
|
@ -339,8 +339,8 @@ a code like this::
|
|||
There are also devm_* versions of these functions which release the
|
||||
descriptors once the device is released.
|
||||
|
||||
See Documentation/firmware-guide/acpi/gpio-properties.rst for more information about the
|
||||
_DSD binding related to GPIOs.
|
||||
See Documentation/firmware-guide/acpi/gpio-properties.rst for more information
|
||||
about the _DSD binding related to GPIOs.
|
||||
|
||||
MFD devices
|
||||
===========
|
||||
|
|
@ -460,7 +460,8 @@ the _DSD of the device object itself or the _DSD of its ancestor in the
|
|||
Otherwise, the _DSD itself is regarded as invalid and therefore the "compatible"
|
||||
property returned by it is meaningless.
|
||||
|
||||
Refer to :doc:`DSD-properties-rules` for more information.
|
||||
Refer to Documentation/firmware-guide/acpi/DSD-properties-rules.rst for more
|
||||
information.
|
||||
|
||||
PCI hierarchy representation
|
||||
============================
|
||||
|
|
|
|||
|
|
@ -59,7 +59,7 @@ Declare the I2C devices via ACPI
|
|||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
ACPI can also describe I2C devices. There is special documentation for this
|
||||
which is currently located at :doc:`../firmware-guide/acpi/enumeration`.
|
||||
which is currently located at Documentation/firmware-guide/acpi/enumeration.rst.
|
||||
|
||||
|
||||
Declare the I2C devices in board files
|
||||
|
|
|
|||
|
|
@ -17,7 +17,8 @@ address), ``force`` (to forcibly attach the driver to a given device) and
|
|||
With the conversion of the I2C subsystem to the standard device driver
|
||||
binding model, it became clear that these per-module parameters were no
|
||||
longer needed, and that a centralized implementation was possible. The new,
|
||||
sysfs-based interface is described in :doc:`instantiating-devices`, section
|
||||
sysfs-based interface is described in
|
||||
Documentation/i2c/instantiating-devices.rst, section
|
||||
"Method 4: Instantiate from user-space".
|
||||
|
||||
Below is a mapping from the old module parameters to the new interface.
|
||||
|
|
|
|||
|
|
@ -27,8 +27,8 @@ a different protocol operation entirely.
|
|||
Each transaction type corresponds to a functionality flag. Before calling a
|
||||
transaction function, a device driver should always check (just once) for
|
||||
the corresponding functionality flag to ensure that the underlying I2C
|
||||
adapter supports the transaction in question. See :doc:`functionality` for
|
||||
the details.
|
||||
adapter supports the transaction in question. See
|
||||
Documentation/i2c/functionality.rst for the details.
|
||||
|
||||
|
||||
Key to symbols
|
||||
|
|
|
|||
|
|
@ -263,7 +263,7 @@ possible overrun should the name be too long::
|
|||
|
||||
char name[128];
|
||||
if (ioctl(fd, JSIOCGNAME(sizeof(name)), name) < 0)
|
||||
strncpy(name, "Unknown", sizeof(name));
|
||||
strscpy(name, "Unknown", sizeof(name));
|
||||
printf("Name: %s\n", name);
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -601,7 +601,7 @@ Defined in ``include/linux/export.h``
|
|||
|
||||
This is the variant of `EXPORT_SYMBOL()` that allows specifying a symbol
|
||||
namespace. Symbol Namespaces are documented in
|
||||
:doc:`../core-api/symbol-namespaces`
|
||||
Documentation/core-api/symbol-namespaces.rst
|
||||
|
||||
:c:func:`EXPORT_SYMBOL_NS_GPL()`
|
||||
--------------------------------
|
||||
|
|
@ -610,7 +610,7 @@ Defined in ``include/linux/export.h``
|
|||
|
||||
This is the variant of `EXPORT_SYMBOL_GPL()` that allows specifying a symbol
|
||||
namespace. Symbol Namespaces are documented in
|
||||
:doc:`../core-api/symbol-namespaces`
|
||||
Documentation/core-api/symbol-namespaces.rst
|
||||
|
||||
Routines and Conventions
|
||||
========================
|
||||
|
|
|
|||
|
|
@ -466,7 +466,7 @@ network. PTP support varies among Intel devices that support this driver. Use
|
|||
"ethtool -T <netdev name>" to get a definitive list of PTP capabilities
|
||||
supported by the device.
|
||||
|
||||
IEEE 802.1ad (QinQ) Support
|
||||
IEEE 802.1ad (QinQ) Support
|
||||
---------------------------
|
||||
The IEEE 802.1ad standard, informally known as QinQ, allows for multiple VLAN
|
||||
IDs within a single Ethernet frame. VLAN IDs are sometimes referred to as
|
||||
|
|
@ -523,8 +523,8 @@ of a port's bandwidth (should it be available). The sum of all the values for
|
|||
Maximum Bandwidth is not restricted, because no more than 100% of a port's
|
||||
bandwidth can ever be used.
|
||||
|
||||
NOTE: X710/XXV710 devices fail to enable Max VFs (64) when Multiple Functions
|
||||
per Port (MFP) and SR-IOV are enabled. An error from i40e is logged that says
|
||||
NOTE: X710/XXV710 devices fail to enable Max VFs (64) when Multiple Functions
|
||||
per Port (MFP) and SR-IOV are enabled. An error from i40e is logged that says
|
||||
"add vsi failed for VF N, aq_err 16". To workaround the issue, enable less than
|
||||
64 virtual functions (VFs).
|
||||
|
||||
|
|
|
|||
|
|
@ -113,7 +113,7 @@ which the AVF is associated. The following are base mode features:
|
|||
- AVF device ID
|
||||
- HW mailbox is used for VF to PF communications (including on Windows)
|
||||
|
||||
IEEE 802.1ad (QinQ) Support
|
||||
IEEE 802.1ad (QinQ) Support
|
||||
---------------------------
|
||||
The IEEE 802.1ad standard, informally known as QinQ, allows for multiple VLAN
|
||||
IDs within a single Ethernet frame. VLAN IDs are sometimes referred to as
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@ The major benefit to creating a region is to provide access to internal
|
|||
address regions that are otherwise inaccessible to the user.
|
||||
|
||||
Regions may also be used to provide an additional way to debug complex error
|
||||
states, but see also :doc:`devlink-health`
|
||||
states, but see also Documentation/networking/devlink/devlink-health.rst
|
||||
|
||||
Regions may optionally support capturing a snapshot on demand via the
|
||||
``DEVLINK_CMD_REGION_NEW`` netlink message. A driver wishing to allow
|
||||
|
|
|
|||
|
|
@ -495,8 +495,8 @@ help debug packet drops caused by these exceptions. The following list includes
|
|||
links to the description of driver-specific traps registered by various device
|
||||
drivers:
|
||||
|
||||
* :doc:`netdevsim`
|
||||
* :doc:`mlxsw`
|
||||
* Documentation/networking/devlink/netdevsim.rst
|
||||
* Documentation/networking/devlink/mlxsw.rst
|
||||
|
||||
.. _Generic-Packet-Trap-Groups:
|
||||
|
||||
|
|
|
|||
|
|
@ -153,7 +153,7 @@ As capture, each frame contains two parts::
|
|||
struct ifreq s_ifr;
|
||||
...
|
||||
|
||||
strncpy (s_ifr.ifr_name, "eth0", sizeof(s_ifr.ifr_name));
|
||||
strscpy_pad (s_ifr.ifr_name, "eth0", sizeof(s_ifr.ifr_name));
|
||||
|
||||
/* get interface index of eth0 */
|
||||
ioctl(this->socket, SIOCGIFINDEX, &s_ifr);
|
||||
|
|
|
|||
|
|
@ -107,7 +107,7 @@ Note that the character pointer becomes overwritten with the real device name
|
|||
*/
|
||||
ifr.ifr_flags = IFF_TUN;
|
||||
if( *dev )
|
||||
strncpy(ifr.ifr_name, dev, IFNAMSIZ);
|
||||
strscpy_pad(ifr.ifr_name, dev, IFNAMSIZ);
|
||||
|
||||
if( (err = ioctl(fd, TUNSETIFF, (void *) &ifr)) < 0 ){
|
||||
close(fd);
|
||||
|
|
|
|||
|
|
@ -10,10 +10,11 @@ can greatly increase the chances of your change being accepted.
|
|||
|
||||
This document contains a large number of suggestions in a relatively terse
|
||||
format. For detailed information on how the kernel development process
|
||||
works, see :doc:`development-process`. Also, read :doc:`submit-checklist`
|
||||
works, see Documentation/process/development-process.rst. Also, read
|
||||
Documentation/process/submit-checklist.rst
|
||||
for a list of items to check before submitting code. If you are submitting
|
||||
a driver, also read :doc:`submitting-drivers`; for device tree binding patches,
|
||||
read :doc:`submitting-patches`.
|
||||
a driver, also read Documentation/process/submitting-drivers.rst; for device
|
||||
tree binding patches, read Documentation/process/submitting-patches.rst.
|
||||
|
||||
This documentation assumes that you're using ``git`` to prepare your patches.
|
||||
If you're unfamiliar with ``git``, you would be well-advised to learn how to
|
||||
|
|
@ -178,8 +179,7 @@ Style-check your changes
|
|||
------------------------
|
||||
|
||||
Check your patch for basic style violations, details of which can be
|
||||
found in
|
||||
:ref:`Documentation/process/coding-style.rst <codingstyle>`.
|
||||
found in Documentation/process/coding-style.rst.
|
||||
Failure to do so simply wastes
|
||||
the reviewers time and will get your patch rejected, probably
|
||||
without even being read.
|
||||
|
|
@ -238,7 +238,7 @@ If you have a patch that fixes an exploitable security bug, send that patch
|
|||
to security@kernel.org. For severe bugs, a short embargo may be considered
|
||||
to allow distributors to get the patch out to users; in such cases,
|
||||
obviously, the patch should not be sent to any public lists. See also
|
||||
:doc:`/admin-guide/security-bugs`.
|
||||
Documentation/admin-guide/security-bugs.rst.
|
||||
|
||||
Patches that fix a severe bug in a released kernel should be directed
|
||||
toward the stable maintainers by putting a line like this::
|
||||
|
|
@ -246,9 +246,8 @@ toward the stable maintainers by putting a line like this::
|
|||
Cc: stable@vger.kernel.org
|
||||
|
||||
into the sign-off area of your patch (note, NOT an email recipient). You
|
||||
should also read
|
||||
:ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`
|
||||
in addition to this file.
|
||||
should also read Documentation/process/stable-kernel-rules.rst
|
||||
in addition to this document.
|
||||
|
||||
If changes affect userland-kernel interfaces, please send the MAN-PAGES
|
||||
maintainer (as listed in the MAINTAINERS file) a man-pages patch, or at
|
||||
|
|
@ -305,8 +304,8 @@ decreasing the likelihood of your MIME-attached change being accepted.
|
|||
Exception: If your mailer is mangling patches then someone may ask
|
||||
you to re-send them using MIME.
|
||||
|
||||
See :doc:`/process/email-clients` for hints about configuring your e-mail
|
||||
client so that it sends your patches untouched.
|
||||
See Documentation/process/email-clients.rst for hints about configuring
|
||||
your e-mail client so that it sends your patches untouched.
|
||||
|
||||
Respond to review comments
|
||||
--------------------------
|
||||
|
|
@ -324,7 +323,7 @@ for their time. Code review is a tiring and time-consuming process, and
|
|||
reviewers sometimes get grumpy. Even in that case, though, respond
|
||||
politely and address the problems they have pointed out.
|
||||
|
||||
See :doc:`email-clients` for recommendations on email
|
||||
See Documentation/process/email-clients.rst for recommendations on email
|
||||
clients and mailing list etiquette.
|
||||
|
||||
|
||||
|
|
@ -562,10 +561,10 @@ method for indicating a bug fixed by the patch. See :ref:`describe_changes`
|
|||
for more details.
|
||||
|
||||
Note: Attaching a Fixes: tag does not subvert the stable kernel rules
|
||||
process nor the requirement to Cc: stable@vger.kernel.org on all stable
|
||||
process nor the requirement to Cc: stable@vger.kernel.org on all stable
|
||||
patch candidates. For more information, please read
|
||||
:ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`
|
||||
|
||||
Documentation/process/stable-kernel-rules.rst.
|
||||
|
||||
.. _the_canonical_patch_format:
|
||||
|
||||
The canonical patch format
|
||||
|
|
@ -824,8 +823,7 @@ Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
|
|||
NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
|
||||
<https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net>
|
||||
|
||||
Kernel Documentation/process/coding-style.rst:
|
||||
:ref:`Documentation/process/coding-style.rst <codingstyle>`
|
||||
Kernel Documentation/process/coding-style.rst
|
||||
|
||||
Linus Torvalds's mail on the canonical patch format:
|
||||
<https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org>
|
||||
|
|
|
|||
|
|
@ -29,7 +29,7 @@ Quota and period are managed within the cpu subsystem via cgroupfs.
|
|||
.. note::
|
||||
The cgroupfs files described in this section are only applicable
|
||||
to cgroup v1. For cgroup v2, see
|
||||
:ref:`Documentation/admin-guide/cgroupv2.rst <cgroup-v2-cpu>`.
|
||||
:ref:`Documentation/admin-guide/cgroup-v2.rst <cgroup-v2-cpu>`.
|
||||
|
||||
- cpu.cfs_quota_us: the total available run-time within a period (in
|
||||
microseconds)
|
||||
|
|
|
|||
|
|
@ -60,7 +60,7 @@ within the constraints of HZ and jiffies and their nasty design level
|
|||
coupling to timeslices and granularity it was not really viable.
|
||||
|
||||
The second (less frequent but still periodically occurring) complaint
|
||||
about Linux's nice level support was its assymetry around the origo
|
||||
about Linux's nice level support was its asymmetry around the origin
|
||||
(which you can see demonstrated in the picture above), or more
|
||||
accurately: the fact that nice level behavior depended on the _absolute_
|
||||
nice level as well, while the nice API itself is fundamentally
|
||||
|
|
|
|||
|
|
@ -25,7 +25,8 @@ Any user can enforce Landlock rulesets on their processes. They are merged and
|
|||
evaluated according to the inherited ones in a way that ensures that only more
|
||||
constraints can be added.
|
||||
|
||||
User space documentation can be found here: :doc:`/userspace-api/landlock`.
|
||||
User space documentation can be found here:
|
||||
Documentation/userspace-api/landlock.rst.
|
||||
|
||||
Guiding principles for safe access controls
|
||||
===========================================
|
||||
|
|
|
|||
|
|
@ -427,7 +427,7 @@ the ‘TRC’ prefix.
|
|||
:Syntax:
|
||||
``echo idx > vmid_idx``
|
||||
|
||||
Where idx < numvmidc
|
||||
Where idx < numvmidc
|
||||
|
||||
----
|
||||
|
||||
|
|
|
|||
|
|
@ -315,7 +315,8 @@ intermediate links as required.
|
|||
|
||||
Note: ``cti_sys0`` appears in two of the connections lists above.
|
||||
CTIs can connect to multiple devices and are arranged in a star topology
|
||||
via the CTM. See (:doc:`coresight-ect`) [#fourth]_ for further details.
|
||||
via the CTM. See (Documentation/trace/coresight/coresight-ect.rst)
|
||||
[#fourth]_ for further details.
|
||||
Looking at this device we see 4 connections::
|
||||
|
||||
linaro-developer:~# ls -l /sys/bus/coresight/devices/cti_sys0/connections
|
||||
|
|
@ -606,7 +607,8 @@ interface provided for that purpose by the generic STM API::
|
|||
crw------- 1 root root 10, 61 Jan 3 18:11 /dev/stm0
|
||||
root@genericarmv8:~#
|
||||
|
||||
Details on how to use the generic STM API can be found here:- :doc:`../stm` [#second]_.
|
||||
Details on how to use the generic STM API can be found here:
|
||||
- Documentation/trace/stm.rst [#second]_.
|
||||
|
||||
The CTI & CTM Modules
|
||||
---------------------
|
||||
|
|
@ -616,7 +618,7 @@ individual CTIs and components, and can propagate these between all CTIs via
|
|||
channels on the CTM (Cross Trigger Matrix).
|
||||
|
||||
A separate documentation file is provided to explain the use of these devices.
|
||||
(:doc:`coresight-ect`) [#fourth]_.
|
||||
(Documentation/trace/coresight/coresight-ect.rst) [#fourth]_.
|
||||
|
||||
|
||||
.. [#first] Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
|
||||
|
|
|
|||
|
|
@ -40,7 +40,7 @@ See events.rst for more information.
|
|||
Implementation Details
|
||||
----------------------
|
||||
|
||||
See :doc:`ftrace-design` for details for arch porters and such.
|
||||
See Documentation/trace/ftrace-design.rst for details for arch porters and such.
|
||||
|
||||
|
||||
The File System
|
||||
|
|
@ -354,8 +354,8 @@ of ftrace. Here is a list of some of the key files:
|
|||
is being directly called by the function. If the count is greater
|
||||
than 1 it most likely will be ftrace_ops_list_func().
|
||||
|
||||
If the callback of the function jumps to a trampoline that is
|
||||
specific to a the callback and not the standard trampoline,
|
||||
If the callback of a function jumps to a trampoline that is
|
||||
specific to the callback and which is not the standard trampoline,
|
||||
its address will be printed as well as the function that the
|
||||
trampoline calls.
|
||||
|
||||
|
|
|
|||
|
|
@ -18,6 +18,10 @@ Translations
|
|||
Disclaimer
|
||||
----------
|
||||
|
||||
.. raw:: latex
|
||||
|
||||
\kerneldocCJKoff
|
||||
|
||||
Translation's purpose is to ease reading and understanding in languages other
|
||||
than English. Its aim is to help people who do not understand English or have
|
||||
doubts about its interpretation. Additionally, some people prefer to read
|
||||
|
|
|
|||
|
|
@ -4,6 +4,10 @@
|
|||
Traduzione italiana
|
||||
===================
|
||||
|
||||
.. raw:: latex
|
||||
|
||||
\kerneldocCJKoff
|
||||
|
||||
:manutentore: Federico Vaga <federico.vaga@vaga.pv.it>
|
||||
|
||||
.. _it_disclaimer:
|
||||
|
|
|
|||
|
|
@ -62,7 +62,7 @@ i ``case``. Un esempio.:
|
|||
case 'K':
|
||||
case 'k':
|
||||
mem <<= 10;
|
||||
/* fall through */
|
||||
fallthrough;
|
||||
default:
|
||||
break;
|
||||
}
|
||||
|
|
|
|||
Некоторые файлы не были показаны из-за слишком большого количества измененных файлов Показать больше
Загрузка…
Ссылка в новой задаче