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:
commit
233a806b00
@ -6,4 +6,4 @@ Description:
|
|||||||
with the update that cpuidle governor can be changed at runtime in default,
|
with the update that cpuidle governor can be changed at runtime in default,
|
||||||
both current_governor and current_governor_ro co-exist under
|
both current_governor and current_governor_ro co-exist under
|
||||||
/sys/devices/system/cpu/cpuidle/ file, it's duplicate so make
|
/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:
|
Description:
|
||||||
The /sys/kernel/uids/<uid>/cpu_shares tunable is used
|
The /sys/kernel/uids/<uid>/cpu_shares tunable is used
|
||||||
to set the cpu bandwidth a user is allowed. This is a
|
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
|
are two users logged in, each with an equal number of
|
||||||
shares, then they will get equal CPU bandwidth. Another
|
shares, then they will get equal CPU bandwidth. Another
|
||||||
example would be, if User A has shares = 1024 and user
|
example would be, if User A has shares = 1024 and user
|
||||||
|
@ -61,7 +61,7 @@ Date: September. 2017
|
|||||||
KernelVersion: 4.14
|
KernelVersion: 4.14
|
||||||
Contact: Stephen Hemminger <sthemmin@microsoft.com>
|
Contact: Stephen Hemminger <sthemmin@microsoft.com>
|
||||||
Description: Directory for per-channel information
|
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
|
What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/cpu
|
||||||
Date: September. 2017
|
Date: September. 2017
|
||||||
|
@ -19,7 +19,7 @@ Date: April 2011
|
|||||||
KernelVersion: 3.0
|
KernelVersion: 3.0
|
||||||
Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
|
Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
|
||||||
Description:
|
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
|
physical device providing the storage for this backend
|
||||||
block device.
|
block device.
|
||||||
|
|
||||||
|
@ -23,3 +23,86 @@ Description: Default value for the Data Stream Control Register (DSCR) on
|
|||||||
here).
|
here).
|
||||||
If set by a process it will be inherited by child processes.
|
If set by a process it will be inherited by child processes.
|
||||||
Values: 64 bit unsigned integer (bit field)
|
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
|
Date: Oct 25, 2019
|
||||||
KernelVersion: 5.6.0
|
KernelVersion: 5.6.0
|
||||||
Contact: dmaengine@vger.kernel.org
|
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
|
other work queue in the same group to control quality of service
|
||||||
for dispatching work from multiple workqueues in the same group.
|
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:
|
Description: These files show the system reset cause, as following:
|
||||||
COMEX thermal shutdown; wathchdog power off or reset was derived
|
COMEX thermal shutdown; wathchdog power off or reset was derived
|
||||||
by one of the next components: COMEX, switch board or by Small Form
|
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.
|
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 one of the above causes could be 1 at the same time, representing
|
||||||
only last reset cause.
|
only last reset cause.
|
||||||
@ -183,7 +183,7 @@ What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/vpd_wp
|
|||||||
Date: January 2020
|
Date: January 2020
|
||||||
KernelVersion: 5.6
|
KernelVersion: 5.6
|
||||||
Contact: Vadim Pasternak <vadimpmellanox.com>
|
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.
|
protection when attribute is set 1.
|
||||||
|
|
||||||
The file is read/write.
|
The file is read/write.
|
||||||
|
@ -31,4 +31,4 @@ Date: April 2016
|
|||||||
KernelVersion: 4.7
|
KernelVersion: 4.7
|
||||||
Description:
|
Description:
|
||||||
Dummy IIO devices directory. Creating a directory here will result
|
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
|
subbuffer_size
|
||||||
configure the sub-buffer size for this channel
|
configure the sub-buffer size for this channel
|
||||||
(needed for synchronous and isochrnous data)
|
(needed for synchronous and isochronous data)
|
||||||
|
|
||||||
|
|
||||||
num_buffers
|
num_buffers
|
||||||
@ -75,7 +75,7 @@ Description:
|
|||||||
|
|
||||||
subbuffer_size
|
subbuffer_size
|
||||||
configure the sub-buffer size for this channel
|
configure the sub-buffer size for this channel
|
||||||
(needed for synchronous and isochrnous data)
|
(needed for synchronous and isochronous data)
|
||||||
|
|
||||||
|
|
||||||
num_buffers
|
num_buffers
|
||||||
@ -130,7 +130,7 @@ Description:
|
|||||||
|
|
||||||
subbuffer_size
|
subbuffer_size
|
||||||
configure the sub-buffer size for this channel
|
configure the sub-buffer size for this channel
|
||||||
(needed for synchronous and isochrnous data)
|
(needed for synchronous and isochronous data)
|
||||||
|
|
||||||
|
|
||||||
num_buffers
|
num_buffers
|
||||||
@ -196,7 +196,7 @@ Description:
|
|||||||
|
|
||||||
subbuffer_size
|
subbuffer_size
|
||||||
configure the sub-buffer size for this channel
|
configure the sub-buffer size for this channel
|
||||||
(needed for synchronous and isochrnous data)
|
(needed for synchronous and isochronous data)
|
||||||
|
|
||||||
|
|
||||||
num_buffers
|
num_buffers
|
||||||
|
@ -137,7 +137,7 @@ Description:
|
|||||||
This group contains "OS String" extension handling attributes.
|
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
|
b_vendor_code one-byte value used for custom per-device and
|
||||||
per-interface requests
|
per-interface requests
|
||||||
qw_sign an identifier to be reported as "OS String"
|
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
|
bMatrixCoefficients matrix used to compute luma and
|
||||||
chroma values from the color primaries
|
chroma values from the color primaries
|
||||||
bTransferCharacteristics optoelectronic transfer
|
bTransferCharacteristics optoelectronic transfer
|
||||||
characteristic of the source picutre,
|
characteristic of the source picture,
|
||||||
also called the gamma function
|
also called the gamma function
|
||||||
bColorPrimaries color primaries and the reference
|
bColorPrimaries color primaries and the reference
|
||||||
white
|
white
|
||||||
@ -311,7 +311,7 @@ Description: Specific streaming header descriptors
|
|||||||
a hardware trigger interrupt event
|
a hardware trigger interrupt event
|
||||||
bTriggerSupport flag specifying if hardware
|
bTriggerSupport flag specifying if hardware
|
||||||
triggering is supported
|
triggering is supported
|
||||||
bStillCaptureMethod method of still image caputre
|
bStillCaptureMethod method of still image capture
|
||||||
supported
|
supported
|
||||||
bTerminalLink id of the output terminal to which
|
bTerminalLink id of the output terminal to which
|
||||||
the video endpoint of this interface
|
the video endpoint of this interface
|
||||||
|
@ -31,7 +31,7 @@ What: /sys/kernel/debug/genwqe/genwqe<n>_card/prev_regs
|
|||||||
Date: Oct 2013
|
Date: Oct 2013
|
||||||
Contact: haver@linux.vnet.ibm.com
|
Contact: haver@linux.vnet.ibm.com
|
||||||
Description: Dump of the error registers before the last reset of
|
Description: Dump of the error registers before the last reset of
|
||||||
the card occured.
|
the card occurred.
|
||||||
Only available for PF.
|
Only available for PF.
|
||||||
|
|
||||||
What: /sys/kernel/debug/genwqe/genwqe<n>_card/prev_dbg_uid0
|
What: /sys/kernel/debug/genwqe/genwqe<n>_card/prev_dbg_uid0
|
||||||
|
@ -153,7 +153,7 @@ KernelVersion: 5.1
|
|||||||
Contact: ogabbay@kernel.org
|
Contact: ogabbay@kernel.org
|
||||||
Description: Triggers an I2C transaction that is generated by the device's
|
Description: Triggers an I2C transaction that is generated by the device's
|
||||||
CPU. Writing to this file generates a write transaction while
|
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
|
What: /sys/kernel/debug/habanalabs/hl<n>/i2c_reg
|
||||||
Date: Jan 2019
|
Date: Jan 2019
|
||||||
|
@ -12,7 +12,7 @@ KernelVersion: 4.12
|
|||||||
Contact: linux-fsi@lists.ozlabs.org
|
Contact: linux-fsi@lists.ozlabs.org
|
||||||
Description:
|
Description:
|
||||||
Sends an FSI BREAK command on a master's communication
|
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
|
device's logic and preps it to receive further commands
|
||||||
from the master.
|
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
|
What: /sys/.../events/in_capacitanceY_adaptive_thresh_falling_en
|
||||||
KernelVersion: 5.13
|
KernelVersion: 5.13
|
||||||
Contact: linux-iio@vger.kernel.org
|
Contact: linux-iio@vger.kernel.org
|
||||||
Descrption:
|
Description:
|
||||||
Adaptive thresholds are similar to normal fixed thresholds
|
Adaptive thresholds are similar to normal fixed thresholds
|
||||||
but the value is expressed as an offset from a value which
|
but the value is expressed as an offset from a value which
|
||||||
provides a low frequency approximation of the channel itself.
|
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
|
What: /sys/.../in_capacitanceY_adaptive_thresh_falling_timeout
|
||||||
KernelVersion: 5.11
|
KernelVersion: 5.11
|
||||||
Contact: linux-iio@vger.kernel.org
|
Contact: linux-iio@vger.kernel.org
|
||||||
Descrption:
|
Description:
|
||||||
When adaptive thresholds are used, the tracking signal
|
When adaptive thresholds are used, the tracking signal
|
||||||
may adjust too slowly to step changes in the raw 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
|
difference between the slow tracking signal and the raw
|
||||||
signal is allowed to remain out-of-range before a reset
|
signal is allowed to remain out-of-range before a reset
|
||||||
event occurs in which the tracking signal is made equal
|
event occurs in which the tracking signal is made equal
|
||||||
|
@ -139,8 +139,8 @@ Description:
|
|||||||
binary file containing the Vital Product Data for the
|
binary file containing the Vital Product Data for the
|
||||||
device. It should follow the VPD format defined in
|
device. It should follow the VPD format defined in
|
||||||
PCI Specification 2.1 or 2.2, but users should consider
|
PCI Specification 2.1 or 2.2, but users should consider
|
||||||
that some devices may have malformatted data. If the
|
that some devices may have incorrectly formatted data.
|
||||||
underlying VPD has a writable section then the
|
If the underlying VPD has a writable section then the
|
||||||
corresponding section of this file will be writable.
|
corresponding section of this file will be writable.
|
||||||
|
|
||||||
What: /sys/bus/pci/devices/.../virtfnN
|
What: /sys/bus/pci/devices/.../virtfnN
|
||||||
|
@ -84,3 +84,103 @@ Description:
|
|||||||
It can be enabled by writing the value stored in
|
It can be enabled by writing the value stored in
|
||||||
/sys/class/backlight/<backlight>/max_brightness to
|
/sys/class/backlight/<backlight>/max_brightness to
|
||||||
/sys/class/backlight/<backlight>/brightness.
|
/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
|
This file will always return the originally written repeat
|
||||||
number.
|
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.
|
architecture specific.
|
||||||
|
|
||||||
release: writes to this file dynamically remove a CPU from
|
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.
|
is architecture specific.
|
||||||
|
|
||||||
What: /sys/devices/system/cpu/cpu#/node
|
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
|
corresponds to a physical socket number, but the actual value
|
||||||
is architecture and platform dependent.
|
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#
|
threads within the same core as cpu#
|
||||||
|
|
||||||
thread_siblings_list: human-readable list of cpu#'s hardware
|
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
|
on a processor with this functionality will return the currently
|
||||||
disabled index for that node. There is one L3 structure per
|
disabled index for that node. There is one L3 structure per
|
||||||
node, or per internal node on MCM machines. Writing a valid
|
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.
|
index to be disabled.
|
||||||
|
|
||||||
All AMD processors with L3 caches provide this functionality.
|
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.
|
This switch controls the boost setting for the whole system.
|
||||||
Boosting allows the CPU and the firmware to run at a frequency
|
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
|
More details can be found in
|
||||||
Documentation/admin-guide/pm/cpufreq.rst
|
Documentation/admin-guide/pm/cpufreq.rst
|
||||||
@ -532,7 +532,7 @@ What: /sys/devices/system/cpu/smt
|
|||||||
/sys/devices/system/cpu/smt/control
|
/sys/devices/system/cpu/smt/control
|
||||||
Date: June 2018
|
Date: June 2018
|
||||||
Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
|
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)
|
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
|
What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/manufacturer_id
|
||||||
Date: February 2018
|
Date: February 2018
|
||||||
Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
|
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
|
UFS device descriptor parameters. The full information about
|
||||||
the descriptor could be found at UFS specifications 2.1.
|
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
|
What: /sys/bus/platform/drivers/ufshcd/*/string_descriptors/manufacturer_name
|
||||||
Date: February 2018
|
Date: February 2018
|
||||||
Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
|
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
|
The full information about the descriptor could be found at
|
||||||
UFS specifications 2.1.
|
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
|
What: /sys/fs/f2fs/<disk>/gc_urgent
|
||||||
Date: August 2017
|
Date: August 2017
|
||||||
Contact: "Jaegeuk Kim" <jaegeuk@kernel.org>
|
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
|
background thread starts to do GC by given gc_urgent_sleep_time
|
||||||
interval. When gc_urgent = 2, F2FS will lower the bar of
|
interval. When gc_urgent = 2, F2FS will lower the bar of
|
||||||
checking idle in order to process outstanding discard commands
|
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
|
the base IOVA, the second is the end IOVA and the third
|
||||||
field describes the type of the region.
|
field describes the type of the region.
|
||||||
|
|
||||||
What: /sys/kernel/iommu_groups/reserved_regions
|
Since kernel 5.3, in case an RMRR is used only by graphics or
|
||||||
Date: June 2019
|
USB devices it is now exposed as "direct-relaxable" instead
|
||||||
KernelVersion: v5.3
|
of "direct". In device assignment use case, for instance,
|
||||||
Contact: Eric Auger <eric.auger@redhat.com>
|
those RMRR are considered to be relaxable and safe.
|
||||||
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.
|
|
||||||
|
|
||||||
What: /sys/kernel/iommu_groups/<grp_id>/type
|
What: /sys/kernel/iommu_groups/<grp_id>/type
|
||||||
Date: November 2020
|
Date: November 2020
|
||||||
|
@ -76,7 +76,7 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
|
|||||||
PYTHONDONTWRITEBYTECODE=1 \
|
PYTHONDONTWRITEBYTECODE=1 \
|
||||||
BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \
|
BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \
|
||||||
$(PYTHON3) $(srctree)/scripts/jobserver-exec \
|
$(PYTHON3) $(srctree)/scripts/jobserver-exec \
|
||||||
$(SHELL) $(srctree)/Documentation/sphinx/parallel-wrapper.sh \
|
$(CONFIG_SHELL) $(srctree)/Documentation/sphinx/parallel-wrapper.sh \
|
||||||
$(SPHINXBUILD) \
|
$(SPHINXBUILD) \
|
||||||
-b $2 \
|
-b $2 \
|
||||||
-c $(abspath $(srctree)/$(src)) \
|
-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.
|
controllers and a _PRT is needed to describe those connections.
|
||||||
|
|
||||||
ACPI resource description is done via _CRS objects of devices in the ACPI
|
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
|
_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.
|
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
|
The new devices might not do anything, but the OS can at least make sure no
|
||||||
resources conflict with them.
|
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
|
driver to bind to it, and the _CRS tells the OS and the driver where the
|
||||||
device's registers are.
|
device's registers are.
|
||||||
|
|
||||||
PCI host bridges are PNP0A03 or PNP0A08 devices. Their _CRS should
|
PCI host bridges are PNP0A03 or PNP0A08 devices. Their _CRS should
|
||||||
describe all the address space they consume. This includes all the windows
|
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
|
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
|
things like secondary/subordinate bus registers that determine the bus
|
||||||
range below the bridge, window registers that describe the apertures, etc.
|
range below the bridge, window registers that describe the apertures, etc.
|
||||||
These are all device-specific, non-architected things, so the only way a
|
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
|
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.
|
space, since it is consumed by the host bridge.
|
||||||
|
|
||||||
ACPI defines a Consumer/Producer bit to distinguish the bridge registers
|
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].
|
bridge registers (including ECAM space) in PNP0C02 catch-all devices [6].
|
||||||
With the exception of ECAM, the bridge register space is device-specific
|
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
|
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
|
New architectures should be able to use "Consumer" Extended Address Space
|
||||||
descriptors in the PNP0A03 device for bridge registers, including ECAM,
|
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
|
Extended Address Space ones, are windows, so it would not be safe to
|
||||||
describe bridge registers this way on those architectures.
|
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
|
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
|
(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.
|
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
|
| interrupt_pin
|
||||||
| function
|
| function
|
||||||
|
|
||||||
[1] :doc:`pci-endpoint`
|
[1] Documentation/PCI/endpoint/pci-endpoint.rst
|
||||||
|
@ -265,7 +265,7 @@ Set the DMA mask size
|
|||||||
---------------------
|
---------------------
|
||||||
.. note::
|
.. note::
|
||||||
If anything below doesn't make sense, please refer to
|
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
|
drivers need to indicate DMA capabilities of the device and is not
|
||||||
an authoritative source for DMA interfaces.
|
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
|
Setup shared control data
|
||||||
-------------------------
|
-------------------------
|
||||||
Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared)
|
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
|
the DMA APIs. This section is just a reminder that it needs to be done
|
||||||
before enabling DMA on the device.
|
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.
|
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
|
Unregister from other subsystems
|
||||||
|
@ -2,87 +2,10 @@
|
|||||||
How CPU topology info is exported via sysfs
|
How CPU topology info is exported via sysfs
|
||||||
===========================================
|
===========================================
|
||||||
|
|
||||||
Export CPU topology info via sysfs. Items (attributes) are similar
|
CPU topology info is exported via sysfs. Items (attributes) are similar
|
||||||
to /proc/cpuinfo output of some architectures. They reside in
|
to /proc/cpuinfo output of some architectures. They reside in
|
||||||
/sys/devices/system/cpu/cpuX/topology/:
|
/sys/devices/system/cpu/cpuX/topology/. Please refer to the ABI file:
|
||||||
|
Documentation/ABI/stable/sysfs-devices-system-cpu.
|
||||||
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.
|
|
||||||
|
|
||||||
Architecture-neutral, drivers/base/topology.c, exports these attributes.
|
Architecture-neutral, drivers/base/topology.c, exports these attributes.
|
||||||
However, the book and drawer related sysfs files will only be created if
|
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
|
dax
|
||||||
Use direct access (no page cache). See
|
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.
|
incompatible with data=journal.
|
||||||
|
|
||||||
inlinecrypt
|
inlinecrypt
|
||||||
|
@ -3,7 +3,8 @@
|
|||||||
SRBDS - Special Register Buffer Data Sampling
|
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
|
infer values returned from special register accesses. Special register
|
||||||
accesses are accesses to off core registers. According to Intel's evaluation,
|
accesses are accesses to off core registers. According to Intel's evaluation,
|
||||||
the special register reads that have a security expectation of privacy are
|
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
|
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.
|
information.
|
||||||
|
|
||||||
Overview
|
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 system panics). The system kernel's memory image is preserved across
|
||||||
the reboot and is accessible to the dump-capture kernel.
|
the reboot and is accessible to the dump-capture kernel.
|
||||||
|
|
||||||
You can use common commands, such as cp and scp, to copy the
|
You can use common commands, such as cp, scp or makedumpfile to copy
|
||||||
memory image to a dump file on the local disk, or across the network to
|
the memory image to a dump file on the local disk, or across the network
|
||||||
a remote system.
|
to a remote system.
|
||||||
|
|
||||||
Kdump and kexec are currently supported on the x86, x86_64, ppc64, ia64,
|
Kdump and kexec are currently supported on the x86, x86_64, ppc64, ia64,
|
||||||
s390x, arm and arm64 architectures.
|
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
|
The kexec -p command loads the dump-capture kernel into this reserved
|
||||||
memory.
|
memory.
|
||||||
|
|
||||||
On x86 machines, the first 640 KB of physical memory is needed to boot,
|
On x86 machines, the first 640 KB of physical memory is needed for boot,
|
||||||
regardless of where the kernel loads. Therefore, kexec backs up this
|
regardless of where the kernel loads. For simpler handling, the whole
|
||||||
region just before rebooting into the dump-capture kernel.
|
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
|
On PPC64 machines first 32KB of physical memory is needed for booting
|
||||||
booting regardless of where the kernel is loaded and to support 64K page
|
regardless of where the kernel is loaded and to support 64K page size
|
||||||
size kexec backs up the first 64KB memory.
|
kexec backs up the first 64KB memory.
|
||||||
|
|
||||||
For s390x, when kdump is triggered, the crashkernel region is exchanged
|
For s390x, when kdump is triggered, the crashkernel region is exchanged
|
||||||
with the region [0, crashkernel region size] and then the kdump kernel
|
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
|
parameter. Optionally the size of the ELF header can also be passed
|
||||||
when using the elfcorehdr=[size[KMG]@]offset[KMG] syntax.
|
when using the elfcorehdr=[size[KMG]@]offset[KMG] syntax.
|
||||||
|
|
||||||
|
|
||||||
With the dump-capture kernel, you can access the memory image through
|
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
|
/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
|
write out using file copy commands such as cp or scp. You can also use
|
||||||
use analysis tools such as the GNU Debugger (GDB) and the Crash tool to
|
makedumpfile utility to analyze and write out filtered contents with
|
||||||
debug the dump file. This method ensures that the dump pages are correctly
|
options, e.g with '-d 31' it will only write out kernel data. Further,
|
||||||
ordered.
|
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
|
Setup and Installation
|
||||||
======================
|
======================
|
||||||
@ -125,9 +127,18 @@ dump-capture kernels for enabling kdump support.
|
|||||||
System kernel config options
|
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
|
2) Enable "sysfs file system support" in "Filesystem" -> "Pseudo
|
||||||
filesystems." This is usually enabled by default::
|
filesystems." This is usually enabled by default::
|
||||||
@ -175,17 +186,19 @@ Dump-capture kernel config options (Arch Dependent, i386 and x86_64)
|
|||||||
|
|
||||||
CONFIG_HIGHMEM4G
|
CONFIG_HIGHMEM4G
|
||||||
|
|
||||||
2) On i386 and x86_64, disable symmetric multi-processing support
|
2) With CONFIG_SMP=y, usually nr_cpus=1 need specified on the kernel
|
||||||
under "Processor type and features"::
|
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
|
With CONFIG_SMP=n, the above things are not related.
|
||||||
when loading the dump-capture kernel, see section "Load the Dump-capture
|
|
||||||
Kernel".)
|
|
||||||
|
|
||||||
3) If one wants to build and use a relocatable kernel,
|
3) A relocatable kernel is suggested to be built by default. If not yet,
|
||||||
Enable "Build a relocatable kernel" support under "Processor type and
|
enable "Build a relocatable kernel" support under "Processor type and
|
||||||
features"::
|
features"::
|
||||||
|
|
||||||
CONFIG_RELOCATABLE=y
|
CONFIG_RELOCATABLE=y
|
||||||
@ -232,7 +245,7 @@ Dump-capture kernel config options (Arch Dependent, ia64)
|
|||||||
as a dump-capture kernel if desired.
|
as a dump-capture kernel if desired.
|
||||||
|
|
||||||
The crashkernel region can be automatically placed by the system
|
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::
|
or omitting it all together::
|
||||||
|
|
||||||
crashkernel=256M@0
|
crashkernel=256M@0
|
||||||
@ -241,10 +254,6 @@ Dump-capture kernel config options (Arch Dependent, ia64)
|
|||||||
|
|
||||||
crashkernel=256M
|
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)
|
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
|
on non-VHE systems even if it is configured. This is because the CPU
|
||||||
will not be reset to EL2 on panic.
|
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
|
Here 'size' specifies how much memory to reserve for the dump-capture kernel
|
||||||
configurations, sometimes it's handy to have the reserved memory dependent
|
and 'offset' specifies the beginning of this reserved memory. For example,
|
||||||
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,
|
|
||||||
"crashkernel=64M@16M" tells the system kernel to reserve 64 MB of memory
|
"crashkernel=64M@16M" tells the system kernel to reserve 64 MB of memory
|
||||||
starting at physical address 0x01000000 (16MB) for the dump-capture kernel.
|
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".
|
On ppc64, use "crashkernel=128M@32M".
|
||||||
|
|
||||||
@ -331,8 +376,8 @@ of dump-capture kernel. Following is the summary.
|
|||||||
|
|
||||||
For i386 and x86_64:
|
For i386 and x86_64:
|
||||||
|
|
||||||
- Use vmlinux if kernel is not relocatable.
|
|
||||||
- Use bzImage/vmlinuz if kernel is relocatable.
|
- Use bzImage/vmlinuz if kernel is relocatable.
|
||||||
|
- Use vmlinux if kernel is not relocatable.
|
||||||
|
|
||||||
For ppc64:
|
For ppc64:
|
||||||
|
|
||||||
@ -392,7 +437,7 @@ loading dump-capture kernel.
|
|||||||
|
|
||||||
For i386, x86_64 and ia64:
|
For i386, x86_64 and ia64:
|
||||||
|
|
||||||
"1 irqpoll maxcpus=1 reset_devices"
|
"1 irqpoll nr_cpus=1 reset_devices"
|
||||||
|
|
||||||
For ppc64:
|
For ppc64:
|
||||||
|
|
||||||
@ -400,7 +445,7 @@ For ppc64:
|
|||||||
|
|
||||||
For s390x:
|
For s390x:
|
||||||
|
|
||||||
"1 maxcpus=1 cgroup_disable=memory"
|
"1 nr_cpus=1 cgroup_disable=memory"
|
||||||
|
|
||||||
For arm:
|
For arm:
|
||||||
|
|
||||||
@ -408,7 +453,7 @@ For arm:
|
|||||||
|
|
||||||
For arm64:
|
For arm64:
|
||||||
|
|
||||||
"1 maxcpus=1 reset_devices"
|
"1 nr_cpus=1 reset_devices"
|
||||||
|
|
||||||
Notes on loading the dump-capture kernel:
|
Notes on loading the dump-capture kernel:
|
||||||
|
|
||||||
@ -488,6 +533,10 @@ the following command::
|
|||||||
|
|
||||||
cp /proc/vmcore <dump-file>
|
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
|
Analysis
|
||||||
========
|
========
|
||||||
@ -535,8 +584,7 @@ This will cause a kdump to occur at the add_taint()->panic() call.
|
|||||||
Contact
|
Contact
|
||||||
=======
|
=======
|
||||||
|
|
||||||
- Vivek Goyal (vgoyal@redhat.com)
|
- kexec@lists.infradead.org
|
||||||
- Maneesh Soni (maneesh@in.ibm.com)
|
|
||||||
|
|
||||||
GDB macros
|
GDB macros
|
||||||
==========
|
==========
|
||||||
|
@ -3513,6 +3513,9 @@
|
|||||||
|
|
||||||
nr_uarts= [SERIAL] maximum number of UARTs to be registered.
|
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= [KNL,ARM64,PPC,RISCV,S390,X86] Enable or disable automatic
|
||||||
NUMA balancing.
|
NUMA balancing.
|
||||||
Allowed values are enable and disable
|
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
|
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
|
processor model and may also depend on information coming from the platform
|
||||||
firmware. [To understand ``intel_idle`` it is necessary to know how ``CPUIdle``
|
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
|
works in general, so this is the time to get familiar with
|
||||||
have not done that yet.]
|
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
|
``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
|
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.
|
depend on the configuration of the platform.
|
||||||
|
|
||||||
In order to create a list of available idle states required by the ``CPUIdle``
|
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
|
``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
|
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
|
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
|
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
|
space still can enable them later (on a per-CPU basis) with the help of
|
||||||
the ``disable`` idle state attribute in ``sysfs`` (see
|
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
|
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).
|
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
|
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
|
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
|
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.
|
Setting ``max_cstate`` to 0 causes the ``intel_idle`` initialization to fail.
|
||||||
|
|
||||||
The ``no_acpi`` and ``use_acpi`` module parameters (recognized by ``intel_idle``
|
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
|
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`,
|
of the corresponding idle state directories in ``sysfs``, :file:`state0`,
|
||||||
:file:`state1` ... :file:`state<i>` ..., where ``<i>`` is the index of the given
|
: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
|
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
|
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
|
(``CPUFreq``). It is a scaling driver for the Sandy Bridge and later
|
||||||
generations of Intel processors. Note, however, that some of those processors
|
generations of Intel processors. Note, however, that some of those processors
|
||||||
may not be supported. [To understand ``intel_pstate`` it is necessary to know
|
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
|
how ``CPUFreq`` works in general, so this is the time to read
|
||||||
you have not done that yet.]
|
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
|
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
|
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
|
The interpretation of some ``CPUFreq`` policy attributes described in
|
||||||
:doc:`cpufreq` is special with ``intel_pstate`` as the current scaling driver
|
Documentation/admin-guide/pm/cpufreq.rst is special with ``intel_pstate``
|
||||||
and it generally depends on the driver's `operation mode <Operation Modes_>`_.
|
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
|
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
|
``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
|
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
|
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)
|
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).
|
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
|
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>
|
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
|
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
|
in a similar fashion to the ``acpi_sleep`` kernel parameter, by
|
||||||
combining the following values:
|
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.
|
the value 340 = 0x154.
|
||||||
|
|
||||||
See the ``type_of_loader`` and ``ext_loader_type`` fields in
|
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)
|
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.
|
file will contain the value 564 = 0x234.
|
||||||
|
|
||||||
See the ``type_of_loader`` and ``ext_loader_ver`` fields in
|
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
|
bpf_stats_enabled
|
||||||
@ -269,7 +270,7 @@ see the ``hostname(1)`` man page.
|
|||||||
firmware_config
|
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
|
The entries in this directory allow the firmware loader helper
|
||||||
fallback to be controlled:
|
fallback to be controlled:
|
||||||
@ -297,7 +298,7 @@ crashes and outputting them to a serial console.
|
|||||||
ftrace_enabled, stack_tracer_enabled
|
ftrace_enabled, stack_tracer_enabled
|
||||||
====================================
|
====================================
|
||||||
|
|
||||||
See :doc:`/trace/ftrace`.
|
See Documentation/trace/ftrace.rst.
|
||||||
|
|
||||||
|
|
||||||
hardlockup_all_cpu_backtrace
|
hardlockup_all_cpu_backtrace
|
||||||
@ -325,7 +326,7 @@ when a hard lockup is detected.
|
|||||||
1 Panic on hard lockup.
|
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.
|
This can also be set using the nmi_watchdog kernel parameter.
|
||||||
|
|
||||||
|
|
||||||
@ -333,7 +334,12 @@ hotplug
|
|||||||
=======
|
=======
|
||||||
|
|
||||||
Path for the hotplug policy agent.
|
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
|
hung_task_all_cpu_backtrace
|
||||||
@ -582,7 +588,8 @@ in a KVM virtual machine. This default can be overridden by adding::
|
|||||||
|
|
||||||
nmi_watchdog=1
|
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
|
numa_balancing
|
||||||
@ -1067,7 +1074,7 @@ that support this feature.
|
|||||||
real-root-dev
|
real-root-dev
|
||||||
=============
|
=============
|
||||||
|
|
||||||
See :doc:`/admin-guide/initrd`.
|
See Documentation/admin-guide/initrd.rst.
|
||||||
|
|
||||||
|
|
||||||
reboot-cmd (SPARC only)
|
reboot-cmd (SPARC only)
|
||||||
@ -1161,7 +1168,7 @@ will take effect.
|
|||||||
seccomp
|
seccomp
|
||||||
=======
|
=======
|
||||||
|
|
||||||
See :doc:`/userspace-api/seccomp_filter`.
|
See Documentation/userspace-api/seccomp_filter.rst.
|
||||||
|
|
||||||
|
|
||||||
sg-big-buff
|
sg-big-buff
|
||||||
@ -1332,7 +1339,7 @@ the boot PROM.
|
|||||||
sysrq
|
sysrq
|
||||||
=====
|
=====
|
||||||
|
|
||||||
See :doc:`/admin-guide/sysrq`.
|
See Documentation/admin-guide/sysrq.rst.
|
||||||
|
|
||||||
|
|
||||||
tainted
|
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
|
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:
|
Note:
|
||||||
writes to this sysctl interface will fail with ``EINVAL`` if the kernel is
|
writes to this sysctl interface will fail with ``EINVAL`` if the kernel is
|
||||||
booted with the command line option ``panic_on_taint=<bitmask>,nousertaint``
|
booted with the command line option ``panic_on_taint=<bitmask>,nousertaint``
|
||||||
and any of the ORed together values being written to ``tainted`` match with
|
and any of the ORed together values being written to ``tainted`` match with
|
||||||
the bitmask declared on panic_on_taint.
|
the bitmask declared on panic_on_taint.
|
||||||
See :doc:`/admin-guide/kernel-parameters` for more details on that particular
|
See Documentation/admin-guide/kernel-parameters.rst for more details on
|
||||||
kernel command line option and its optional ``nousertaint`` switch.
|
that particular kernel command line option and its optional
|
||||||
|
``nousertaint`` switch.
|
||||||
|
|
||||||
threads-max
|
threads-max
|
||||||
===========
|
===========
|
||||||
@ -1394,7 +1402,7 @@ If a value outside of this range is written to ``threads-max`` an
|
|||||||
traceoff_on_warning
|
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.
|
``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.
|
This only works if the kernel was booted with ``tp_printk`` enabled.
|
||||||
|
|
||||||
See :doc:`/admin-guide/kernel-parameters` and
|
See Documentation/admin-guide/kernel-parameters.rst and
|
||||||
:doc:`/trace/boottime-trace`.
|
Documentation/trace/boottime-trace.rst.
|
||||||
|
|
||||||
|
|
||||||
.. _unaligned-dump-stack:
|
.. _unaligned-dump-stack:
|
||||||
|
@ -259,7 +259,7 @@ Storage family
|
|||||||
https://web.archive.org/web/20191129073953/http://www.marvell.com/storage/armada-sp/
|
https://web.archive.org/web/20191129073953/http://www.marvell.com/storage/armada-sp/
|
||||||
|
|
||||||
Core:
|
Core:
|
||||||
Sheeva ARMv7 comatible Quad-core PJ4C
|
Sheeva ARMv7 compatible Quad-core PJ4C
|
||||||
|
|
||||||
(not supported in upstream Linux kernel)
|
(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
|
do not have a corresponding kernel virtual address space mapping) and
|
||||||
low-memory pages.
|
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
|
on PCI high mem DMA aspects and mapping of scatter gather lists, and support
|
||||||
for 64 bit PCI.
|
for 64 bit PCI.
|
||||||
|
|
||||||
|
@ -62,7 +62,7 @@ queue, to be sent in the future, when the hardware is able.
|
|||||||
Software staging queues
|
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
|
(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
|
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
|
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
|
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
|
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
|
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
|
This removes the need to do a linear search to find out which IO has been
|
||||||
completed.
|
completed.
|
||||||
|
|
||||||
|
@ -18,7 +18,7 @@ A.
|
|||||||
each, it would be impossible to guarantee that a set of readings
|
each, it would be impossible to guarantee that a set of readings
|
||||||
represent a single point in time.
|
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
|
values separated by whitespace. The fields are summarized in the
|
||||||
following table, and described in more detail below.
|
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
|
Other LSM hooks which can be instrumented can be found in
|
||||||
``include/linux/lsm_hooks.h``.
|
``include/linux/lsm_hooks.h``.
|
||||||
|
|
||||||
eBPF programs that use :doc:`/bpf/btf` do not need to include kernel headers
|
eBPF programs that use Documentation/bpf/btf.rst do not need to include kernel
|
||||||
for accessing information from the attached eBPF program's context. They can
|
headers for accessing information from the attached eBPF program's context.
|
||||||
simply declare the structures in the eBPF program and only specify the fields
|
They can simply declare the structures in the eBPF program and only specify
|
||||||
that need to be accessed.
|
the fields that need to be accessed.
|
||||||
|
|
||||||
.. code-block:: c
|
.. code-block:: c
|
||||||
|
|
||||||
@ -88,8 +88,9 @@ example:
|
|||||||
|
|
||||||
The ``__attribute__((preserve_access_index))`` is a clang feature that allows
|
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
|
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
|
Documentation/bpf/btf.rst information. Since the BPF verifier is aware of the
|
||||||
also validates all the accesses made to the various types in the eBPF program.
|
types, it also validates all the accesses made to the various types in the
|
||||||
|
eBPF program.
|
||||||
|
|
||||||
Loading
|
Loading
|
||||||
-------
|
-------
|
||||||
|
@ -41,15 +41,7 @@ extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
|
|||||||
'maintainers_include', 'sphinx.ext.autosectionlabel',
|
'maintainers_include', 'sphinx.ext.autosectionlabel',
|
||||||
'kernel_abi', 'kernel_feat']
|
'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:
|
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):
|
if (major > 3) or (minor > 0 or patch >= 2):
|
||||||
# Sphinx c function parser is more pedantic with regards to type
|
# Sphinx c function parser is more pedantic with regards to type
|
||||||
# checking. Due to that, having macros at c:function cause problems.
|
# checking. Due to that, having macros at c:function cause problems.
|
||||||
@ -353,6 +345,8 @@ latex_elements = {
|
|||||||
|
|
||||||
# Additional stuff for the LaTeX preamble.
|
# Additional stuff for the LaTeX preamble.
|
||||||
'preamble': '''
|
'preamble': '''
|
||||||
|
% Prevent column squeezing of tabulary.
|
||||||
|
\\setlength{\\tymin}{20em}
|
||||||
% Use some font with UTF-8 support with XeLaTeX
|
% Use some font with UTF-8 support with XeLaTeX
|
||||||
\\usepackage{fontspec}
|
\\usepackage{fontspec}
|
||||||
\\setsansfont{DejaVu Sans}
|
\\setsansfont{DejaVu Sans}
|
||||||
@ -366,11 +360,23 @@ latex_elements = {
|
|||||||
|
|
||||||
cjk_cmd = check_output(['fc-list', '--format="%{family[0]}\n"']).decode('utf-8', 'ignore')
|
cjk_cmd = check_output(['fc-list', '--format="%{family[0]}\n"']).decode('utf-8', 'ignore')
|
||||||
if cjk_cmd.find("Noto Sans CJK SC") >= 0:
|
if cjk_cmd.find("Noto Sans CJK SC") >= 0:
|
||||||
print ("enabling CJK for LaTeX builder")
|
|
||||||
latex_elements['preamble'] += '''
|
latex_elements['preamble'] += '''
|
||||||
% This is needed for translations
|
% This is needed for translations
|
||||||
\\usepackage{xeCJK}
|
\\usepackage{xeCJK}
|
||||||
\\setCJKmainfont{Noto Sans CJK SC}
|
\\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
|
# 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
|
The virt_to_bus() and bus_to_virt() functions have been
|
||||||
superseded by the functionality provided by the PCI DMA interface
|
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
|
to be documented below for historical purposes, but new code
|
||||||
must not use them. --davidm 00/12/12
|
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>
|
:Author: James E.J. Bottomley <James.Bottomley@HansenPartnership.com>
|
||||||
|
|
||||||
This document describes the DMA API. For a more gentle introduction
|
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.
|
This API is split into two pieces. Part I describes the basic API.
|
||||||
Part II describes extensions for supporting non-consistent memory
|
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.
|
dma_attrs.
|
||||||
|
|
||||||
The interpretation of DMA attributes is architecture-specific, and
|
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
|
If dma_attrs are 0, the semantics of each of these functions
|
||||||
is identical to those of the corresponding function
|
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>
|
#include <asm/dma.h>
|
||||||
|
|
||||||
The first is the generic DMA API used to convert virtual addresses to
|
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
|
The second contains the routines specific to ISA DMA transfers. Since
|
||||||
this is not present on all platforms make sure you construct your
|
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
|
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::
|
.. toctree::
|
||||||
:maxdepth: 1
|
:maxdepth: 1
|
||||||
@ -77,7 +77,7 @@ Memory management
|
|||||||
=================
|
=================
|
||||||
|
|
||||||
How to allocate and use memory in the kernel. Note that there is a lot
|
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::
|
.. toctree::
|
||||||
:maxdepth: 1
|
:maxdepth: 1
|
||||||
|
@ -37,14 +37,13 @@ Integer types
|
|||||||
u64 %llu or %llx
|
u64 %llu or %llx
|
||||||
|
|
||||||
|
|
||||||
If <type> is dependent on a config option for its size (e.g., sector_t,
|
If <type> is architecture-dependent for its size (e.g., cycles_t, tcflag_t) or
|
||||||
blkcnt_t) or is architecture-dependent for its size (e.g., tcflag_t), use a
|
is dependent on a config option for its size (e.g., blk_status_t), use a format
|
||||||
format specifier of its largest possible type and explicitly cast to it.
|
specifier of its largest possible type and explicitly cast to it.
|
||||||
|
|
||||||
Example::
|
Example::
|
||||||
|
|
||||||
printk("test: sector number/total blocks: %llu/%llu\n",
|
printk("test: latency: %llu cycles\n", (unsigned long long)time);
|
||||||
(unsigned long long)sector, (unsigned long long)blockcount);
|
|
||||||
|
|
||||||
Reminder: sizeof() returns type size_t.
|
Reminder: sizeof() returns type size_t.
|
||||||
|
|
||||||
|
@ -246,6 +246,7 @@ Allocation style
|
|||||||
The first argument for kcalloc or kmalloc_array should be the
|
The first argument for kcalloc or kmalloc_array should be the
|
||||||
number of elements. sizeof() as the first argument is generally
|
number of elements. sizeof() as the first argument is generally
|
||||||
wrong.
|
wrong.
|
||||||
|
|
||||||
See: https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html
|
See: https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html
|
||||||
|
|
||||||
**ALLOC_SIZEOF_STRUCT**
|
**ALLOC_SIZEOF_STRUCT**
|
||||||
@ -264,6 +265,7 @@ Allocation style
|
|||||||
**ALLOC_WITH_MULTIPLY**
|
**ALLOC_WITH_MULTIPLY**
|
||||||
Prefer kmalloc_array/kcalloc over kmalloc/kzalloc with a
|
Prefer kmalloc_array/kcalloc over kmalloc/kzalloc with a
|
||||||
sizeof multiply.
|
sizeof multiply.
|
||||||
|
|
||||||
See: https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html
|
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.
|
BUG() or BUG_ON() should be avoided totally.
|
||||||
Use WARN() and WARN_ON() instead, and handle the "impossible"
|
Use WARN() and WARN_ON() instead, and handle the "impossible"
|
||||||
error condition as gracefully as possible.
|
error condition as gracefully as possible.
|
||||||
|
|
||||||
See: https://www.kernel.org/doc/html/latest/process/deprecated.html#bug-and-bug-on
|
See: https://www.kernel.org/doc/html/latest/process/deprecated.html#bug-and-bug-on
|
||||||
|
|
||||||
**CONSIDER_KSTRTO**
|
**CONSIDER_KSTRTO**
|
||||||
@ -292,12 +295,161 @@ API usage
|
|||||||
may lead to unexpected results in callers. The respective kstrtol(),
|
may lead to unexpected results in callers. The respective kstrtol(),
|
||||||
kstrtoll(), kstrtoul(), and kstrtoull() functions tend to be the
|
kstrtoll(), kstrtoul(), and kstrtoull() functions tend to be the
|
||||||
correct replacements.
|
correct replacements.
|
||||||
|
|
||||||
See: https://www.kernel.org/doc/html/latest/process/deprecated.html#simple-strtol-simple-strtoll-simple-strtoul-simple-strtoull
|
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**
|
**LOCKDEP**
|
||||||
The lockdep_no_validate class was added as a temporary measure to
|
The lockdep_no_validate class was added as a temporary measure to
|
||||||
prevent warnings on conversion of device->sem to device->mutex.
|
prevent warnings on conversion of device->sem to device->mutex.
|
||||||
It should not be used for any other purpose.
|
It should not be used for any other purpose.
|
||||||
|
|
||||||
See: https://lore.kernel.org/lkml/1268959062.9440.467.camel@laptop/
|
See: https://lore.kernel.org/lkml/1268959062.9440.467.camel@laptop/
|
||||||
|
|
||||||
**MALFORMED_INCLUDE**
|
**MALFORMED_INCLUDE**
|
||||||
@ -308,14 +460,21 @@ API usage
|
|||||||
**USE_LOCKDEP**
|
**USE_LOCKDEP**
|
||||||
lockdep_assert_held() annotations should be preferred over
|
lockdep_assert_held() annotations should be preferred over
|
||||||
assertions based on spin_is_locked()
|
assertions based on spin_is_locked()
|
||||||
|
|
||||||
See: https://www.kernel.org/doc/html/latest/locking/lockdep-design.html#annotations
|
See: https://www.kernel.org/doc/html/latest/locking/lockdep-design.html#annotations
|
||||||
|
|
||||||
**UAPI_INCLUDE**
|
**UAPI_INCLUDE**
|
||||||
No #include statements in include/uapi should use a uapi/ path.
|
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**
|
**BLOCK_COMMENT_STYLE**
|
||||||
The comment style is incorrect. The preferred style for multi-
|
The comment style is incorrect. The preferred style for multi-
|
||||||
@ -338,8 +497,24 @@ Comment style
|
|||||||
**C99_COMMENTS**
|
**C99_COMMENTS**
|
||||||
C99 style single line comments (//) should not be used.
|
C99 style single line comments (//) should not be used.
|
||||||
Prefer the block comment style instead.
|
Prefer the block comment style instead.
|
||||||
|
|
||||||
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting
|
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
|
Commit message
|
||||||
--------------
|
--------------
|
||||||
@ -347,6 +522,7 @@ Commit message
|
|||||||
**BAD_SIGN_OFF**
|
**BAD_SIGN_OFF**
|
||||||
The signed-off-by line does not fall in line with the standards
|
The signed-off-by line does not fall in line with the standards
|
||||||
specified by the community.
|
specified by the community.
|
||||||
|
|
||||||
See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#developer-s-certificate-of-origin-1-1
|
See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#developer-s-certificate-of-origin-1-1
|
||||||
|
|
||||||
**BAD_STABLE_ADDRESS_STYLE**
|
**BAD_STABLE_ADDRESS_STYLE**
|
||||||
@ -368,12 +544,33 @@ Commit message
|
|||||||
**COMMIT_MESSAGE**
|
**COMMIT_MESSAGE**
|
||||||
The patch is missing a commit description. A brief
|
The patch is missing a commit description. A brief
|
||||||
description of the changes made by the patch should be added.
|
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
|
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**
|
**MISSING_SIGN_OFF**
|
||||||
The patch is missing a Signed-off-by line. A signed-off-by
|
The patch is missing a Signed-off-by line. A signed-off-by
|
||||||
line should be added according to Developer's certificate of
|
line should be added according to Developer's certificate of
|
||||||
Origin.
|
Origin.
|
||||||
|
|
||||||
See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-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**
|
**NO_AUTHOR_SIGN_OFF**
|
||||||
@ -382,6 +579,7 @@ Commit message
|
|||||||
end of explanation of the patch to denote that the author has
|
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
|
written it or otherwise has the rights to pass it on as an open
|
||||||
source patch.
|
source patch.
|
||||||
|
|
||||||
See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-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
|
||||||
|
|
||||||
**DIFF_IN_COMMIT_MSG**
|
**DIFF_IN_COMMIT_MSG**
|
||||||
@ -389,6 +587,7 @@ Commit message
|
|||||||
This causes problems when one tries to apply a file containing both
|
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
|
the changelog and the diff because patch(1) tries to apply the diff
|
||||||
which it found in the changelog.
|
which it found in the changelog.
|
||||||
|
|
||||||
See: https://lore.kernel.org/lkml/20150611134006.9df79a893e3636019ad2759e@linux-foundation.org/
|
See: https://lore.kernel.org/lkml/20150611134006.9df79a893e3636019ad2759e@linux-foundation.org/
|
||||||
|
|
||||||
**GERRIT_CHANGE_ID**
|
**GERRIT_CHANGE_ID**
|
||||||
@ -431,6 +630,7 @@ Comparison style
|
|||||||
**BOOL_COMPARISON**
|
**BOOL_COMPARISON**
|
||||||
Comparisons of A to true and false are better written
|
Comparisons of A to true and false are better written
|
||||||
as A and !A.
|
as A and !A.
|
||||||
|
|
||||||
See: https://lore.kernel.org/lkml/1365563834.27174.12.camel@joe-AO722/
|
See: https://lore.kernel.org/lkml/1365563834.27174.12.camel@joe-AO722/
|
||||||
|
|
||||||
**COMPARISON_TO_NULL**
|
**COMPARISON_TO_NULL**
|
||||||
@ -442,6 +642,87 @@ Comparison style
|
|||||||
side of the test should be avoided.
|
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
|
Macros, Attributes and Symbols
|
||||||
------------------------------
|
------------------------------
|
||||||
|
|
||||||
@ -472,7 +753,7 @@ Macros, Attributes and Symbols
|
|||||||
|
|
||||||
**BIT_MACRO**
|
**BIT_MACRO**
|
||||||
Defines like: 1 << <digit> could be BIT(digit).
|
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))
|
#define BIT(nr) (1UL << (nr))
|
||||||
|
|
||||||
@ -492,6 +773,7 @@ Macros, Attributes and Symbols
|
|||||||
The kernel does *not* use the ``__DATE__`` and ``__TIME__`` macros,
|
The kernel does *not* use the ``__DATE__`` and ``__TIME__`` macros,
|
||||||
and enables warnings if they are used as they can lead to
|
and enables warnings if they are used as they can lead to
|
||||||
non-deterministic builds.
|
non-deterministic builds.
|
||||||
|
|
||||||
See: https://www.kernel.org/doc/html/latest/kbuild/reproducible-builds.html#timestamps
|
See: https://www.kernel.org/doc/html/latest/kbuild/reproducible-builds.html#timestamps
|
||||||
|
|
||||||
**DEFINE_ARCH_HAS**
|
**DEFINE_ARCH_HAS**
|
||||||
@ -502,8 +784,12 @@ Macros, Attributes and Symbols
|
|||||||
want architectures able to override them with optimized ones, we
|
want architectures able to override them with optimized ones, we
|
||||||
should either use weak functions (appropriate for some cases), or
|
should either use weak functions (appropriate for some cases), or
|
||||||
the symbol that protects them should be the same symbol we use.
|
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/
|
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**
|
**INIT_ATTRIBUTE**
|
||||||
Const init definitions should use __initconst instead of
|
Const init definitions should use __initconst instead of
|
||||||
__initdata.
|
__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**
|
**MULTISTATEMENT_MACRO_USE_DO_WHILE**
|
||||||
Macros with multiple statements should be enclosed in a
|
Macros with multiple statements should be enclosed in a
|
||||||
do - while block. Same should also be the case for macros
|
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
|
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**
|
**WEAK_DECLARATION**
|
||||||
Using weak declarations like __attribute__((weak)) or __weak
|
Using weak declarations like __attribute__((weak)) or __weak
|
||||||
can have unintended link defects. Avoid using them.
|
can have unintended link defects. Avoid using them.
|
||||||
@ -551,8 +855,51 @@ Functions and Variables
|
|||||||
|
|
||||||
**CAMELCASE**
|
**CAMELCASE**
|
||||||
Avoid CamelCase Identifiers.
|
Avoid CamelCase Identifiers.
|
||||||
|
|
||||||
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#naming
|
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_WITHOUT_ARGS**
|
||||||
Function declarations without arguments like::
|
Function declarations without arguments like::
|
||||||
|
|
||||||
@ -583,6 +930,34 @@ Functions and Variables
|
|||||||
return bar;
|
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
|
Spacing and Brackets
|
||||||
--------------------
|
--------------------
|
||||||
|
|
||||||
@ -616,7 +991,7 @@ Spacing and Brackets
|
|||||||
|
|
||||||
1. With a type on the left::
|
1. With a type on the left::
|
||||||
|
|
||||||
;int [] a;
|
int [] a;
|
||||||
|
|
||||||
2. At the beginning of a line for slice initialisers::
|
2. At the beginning of a line for slice initialisers::
|
||||||
|
|
||||||
@ -626,12 +1001,6 @@ Spacing and Brackets
|
|||||||
|
|
||||||
= { [0...10] = 5 }
|
= { [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_STRING**
|
||||||
Concatenated elements should have a space in between.
|
Concatenated elements should have a space in between.
|
||||||
Example::
|
Example::
|
||||||
@ -644,17 +1013,20 @@ Spacing and Brackets
|
|||||||
|
|
||||||
**ELSE_AFTER_BRACE**
|
**ELSE_AFTER_BRACE**
|
||||||
`else {` should follow the closing block `}` on the same line.
|
`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
|
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces
|
||||||
|
|
||||||
**LINE_SPACING**
|
**LINE_SPACING**
|
||||||
Vertical space is wasted given the limited number of lines an
|
Vertical space is wasted given the limited number of lines an
|
||||||
editor window can display when multiple blank lines are used.
|
editor window can display when multiple blank lines are used.
|
||||||
|
|
||||||
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
|
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
|
||||||
|
|
||||||
**OPEN_BRACE**
|
**OPEN_BRACE**
|
||||||
The opening brace should be following the function definitions on the
|
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
|
next line. For any non-functional block it should be on the same line
|
||||||
as the last construct.
|
as the last construct.
|
||||||
|
|
||||||
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces
|
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces
|
||||||
|
|
||||||
**POINTER_LOCATION**
|
**POINTER_LOCATION**
|
||||||
@ -671,37 +1043,47 @@ Spacing and Brackets
|
|||||||
|
|
||||||
**SPACING**
|
**SPACING**
|
||||||
Whitespace style used in the kernel sources is described in kernel docs.
|
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
|
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**
|
||||||
Trailing whitespace should always be removed.
|
Trailing whitespace should always be removed.
|
||||||
Some editors highlight the trailing whitespace and cause visual
|
Some editors highlight the trailing whitespace and cause visual
|
||||||
distractions when editing files.
|
distractions when editing files.
|
||||||
|
|
||||||
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
|
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_AFTER_BRACE**
|
||||||
while should follow the closing bracket on the same line::
|
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.
|
The patch seems to be corrupted or lines are wrapped.
|
||||||
Please regenerate the patch file before sending it to the maintainer.
|
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**
|
**DOS_LINE_ENDINGS**
|
||||||
For DOS-formatted patches, there are extra ^M symbols at the end of
|
For DOS-formatted patches, there are extra ^M symbols at the end of
|
||||||
the line. These should be removed.
|
the line. These should be removed.
|
||||||
|
|
||||||
**EXECUTE_PERMISSIONS**
|
**DT_SCHEMA_BINDING_PATCH**
|
||||||
There is no reason for source files to be executable. The executable
|
DT bindings moved to a json-schema based format instead of
|
||||||
bit can be removed safely.
|
freeform text.
|
||||||
|
|
||||||
**NON_OCTAL_PERMISSIONS**
|
See: https://www.kernel.org/doc/html/latest/devicetree/bindings/writing-schema.html
|
||||||
Permission bits should use 4 digit octal permissions (like 0700 or 0444).
|
|
||||||
Avoid using any other base like decimal.
|
**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**
|
**NOT_UNIFIED_DIFF**
|
||||||
The patch file does not appear to be in unified-diff format. Please
|
The patch file does not appear to be in unified-diff format. Please
|
||||||
@ -742,14 +1157,12 @@ Others
|
|||||||
**PRINTF_0XDECIMAL**
|
**PRINTF_0XDECIMAL**
|
||||||
Prefixing 0x with decimal output is defective and should be corrected.
|
Prefixing 0x with decimal output is defective and should be corrected.
|
||||||
|
|
||||||
**TRAILING_STATEMENTS**
|
**SPDX_LICENSE_TAG**
|
||||||
Trailing statements (for example after any conditional) should be
|
The source file is missing or has an improper SPDX identifier tag.
|
||||||
on the next line.
|
The Linux kernel requires the precise SPDX identifier in all source files,
|
||||||
Like::
|
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::
|
**TYPO_SPELLING**
|
||||||
|
Some words may have been misspelled. Consider reviewing them.
|
||||||
if (x == y)
|
|
||||||
break;
|
|
||||||
|
@ -10,7 +10,7 @@ API Reference
|
|||||||
This section documents the KUnit kernel testing API. It is divided into the
|
This section documents the KUnit kernel testing API. It is divided into the
|
||||||
following sections:
|
following sections:
|
||||||
|
|
||||||
================================= ==============================================
|
Documentation/dev-tools/kunit/api/test.rst
|
||||||
:doc:`test` documents all of the standard testing API
|
|
||||||
excluding mocking or mocking related features.
|
- 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
|
modules will automatically execute associated tests when loaded. Test results
|
||||||
can be collected from ``/sys/kernel/debug/kunit/<test suite>/results``, and
|
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
|
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
|
If none of the above tricks help, you are always welcome to email any issues to
|
||||||
kunit-dev@googlegroups.com.
|
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,
|
results. This provides a quick way of running KUnit tests during development,
|
||||||
without requiring a virtual machine or separate hardware.
|
without requiring a virtual machine or separate hardware.
|
||||||
|
|
||||||
Get started now: :doc:`start`
|
Get started now: Documentation/dev-tools/kunit/start.rst
|
||||||
|
|
||||||
Why KUnit?
|
Why KUnit?
|
||||||
==========
|
==========
|
||||||
@ -88,9 +88,9 @@ it takes to read their test log?
|
|||||||
How do I use it?
|
How do I use it?
|
||||||
================
|
================
|
||||||
|
|
||||||
* :doc:`start` - for new users of KUnit
|
* Documentation/dev-tools/kunit/start.rst - for new users of KUnit
|
||||||
* :doc:`tips` - for short examples of best practices
|
* Documentation/dev-tools/kunit/tips.rst - for short examples of best practices
|
||||||
* :doc:`usage` - for a more detailed explanation of KUnit features
|
* Documentation/dev-tools/kunit/usage.rst - for a more detailed explanation of KUnit features
|
||||||
* :doc:`api/index` - for the list of KUnit APIs used for testing
|
* Documentation/dev-tools/kunit/api/index.rst - for the list of KUnit APIs used for testing
|
||||||
* :doc:`kunit-tool` - for more information on the kunit_tool helper script
|
* Documentation/dev-tools/kunit/kunit-tool.rst - for more information on the kunit_tool helper script
|
||||||
* :doc:`faq` - for answers to some common questions about KUnit
|
* 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
|
./tools/testing/kunit/kunit.py run
|
||||||
|
|
||||||
For more information on this wrapper (also called kunit_tool) check out the
|
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
|
Creating a .kunitconfig
|
||||||
-----------------------
|
-----------------------
|
||||||
@ -234,7 +234,7 @@ Congrats! You just wrote your first KUnit test!
|
|||||||
|
|
||||||
Next Steps
|
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.
|
writing idiomatic KUnit tests.
|
||||||
* Optional: see the :doc:`usage` page for a more
|
* Optional: see the :doc:`usage` page for a more
|
||||||
in-depth explanation of KUnit.
|
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
|
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
|
Failing the current test
|
||||||
------------------------
|
------------------------
|
||||||
@ -185,5 +186,5 @@ Alternatively, one can take full control over the error message by using ``KUNIT
|
|||||||
|
|
||||||
Next Steps
|
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.
|
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.
|
some basic knowledge of testing.
|
||||||
|
|
||||||
For a high level introduction to KUnit, including setting up KUnit for your
|
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
|
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
|
expectations until the test case ends or is otherwise terminated. This is as
|
||||||
opposed to *assertions* which are discussed later.
|
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::
|
.. note::
|
||||||
A single test case should be pretty short, pretty easy to understand,
|
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
|
after late_init, or when the test module is loaded (depending on whether the
|
||||||
test was built in or not).
|
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
|
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,
|
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.
|
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
|
Documentation/dev-tools/gcov.rst is GCC's coverage testing tool, which can be
|
||||||
to get global or per-module coverage. Unlike KCOV, it does not record per-task
|
used with the kernel to get global or per-module coverage. Unlike KCOV, it
|
||||||
coverage. Coverage data can be read from debugfs, and interpreted using the
|
does not record per-task coverage. Coverage data can be read from debugfs,
|
||||||
usual gcov tooling.
|
and interpreted using the usual gcov tooling.
|
||||||
|
|
||||||
:doc:`kcov` is a feature which can be built in to the kernel to allow
|
Documentation/dev-tools/kcov.rst is a feature which can be built in to the
|
||||||
capturing coverage on a per-task level. It's therefore useful for fuzzing and
|
kernel to allow capturing coverage on a per-task level. It's therefore useful
|
||||||
other situations where information about code executed during, for example, a
|
for fuzzing and other situations where information about code executed during,
|
||||||
single syscall is useful.
|
for example, a single syscall is useful.
|
||||||
|
|
||||||
|
|
||||||
Dynamic Analysis Tools
|
Dynamic Analysis Tools
|
||||||
|
@ -7,8 +7,8 @@ Submitting Devicetree (DT) binding patches
|
|||||||
I. For patch submitters
|
I. For patch submitters
|
||||||
=======================
|
=======================
|
||||||
|
|
||||||
0) Normal patch submission rules from Documentation/process/submitting-patches.rst
|
0) Normal patch submission rules from
|
||||||
applies.
|
Documentation/process/submitting-patches.rst applies.
|
||||||
|
|
||||||
1) The Documentation/ and include/dt-bindings/ portion of the patch should
|
1) The Documentation/ and include/dt-bindings/ portion of the patch should
|
||||||
be a separate patch. The preferred subject prefix for binding patches is::
|
be a separate patch. The preferred subject prefix for binding patches is::
|
||||||
@ -25,8 +25,8 @@ I. For patch submitters
|
|||||||
|
|
||||||
make dt_binding_check
|
make dt_binding_check
|
||||||
|
|
||||||
See Documentation/devicetree/bindings/writing-schema.rst for more details about
|
See Documentation/devicetree/bindings/writing-schema.rst for more details
|
||||||
schema and tools setup.
|
about schema and tools setup.
|
||||||
|
|
||||||
3) DT binding files should be dual licensed. The preferred license tag is
|
3) DT binding files should be dual licensed. The preferred license tag is
|
||||||
(GPL-2.0-only OR BSD-2-Clause).
|
(GPL-2.0-only OR BSD-2-Clause).
|
||||||
@ -84,7 +84,8 @@ II. For kernel maintainers
|
|||||||
III. Notes
|
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
|
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
|
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
|
a set of "books" that group documentation for specific readers. These
|
||||||
include:
|
include:
|
||||||
|
|
||||||
- :doc:`../admin-guide/index`
|
- Documentation/admin-guide/index.rst
|
||||||
- :doc:`../core-api/index`
|
- Documentation/core-api/index.rst
|
||||||
- :doc:`../driver-api/index`
|
- Documentation/driver-api/index.rst
|
||||||
- :doc:`../userspace-api/index`
|
- Documentation/userspace-api/index.rst
|
||||||
|
|
||||||
As well as this book on documentation itself.
|
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://github.com/acpica/acpica
|
||||||
# git clone https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
|
# git clone https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
|
||||||
# cd acpica
|
# 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
|
For examples of already existing generic drivers that will also be good
|
||||||
examples for any other kernel drivers you want to author, refer to
|
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,
|
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
|
laptops, phones, tablets, routers, and any consumer or office or business goods
|
||||||
using appropriate kernel drivers is paramount. Submit your code for inclusion
|
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
|
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.
|
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:
|
with the correct parameters:
|
||||||
|
|
||||||
_IO/_IOR/_IOW/_IOWR
|
_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
|
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.
|
argument or those passing an integer value instead of a pointer.
|
||||||
It is recommended to only use _IO for commands without arguments,
|
It is recommended to only use _IO for commands without arguments,
|
||||||
and use pointers for passing data.
|
and use pointers for passing data.
|
||||||
|
|
||||||
type
|
type
|
||||||
An 8-bit number, often a character literal, specific to a subsystem
|
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
|
nr
|
||||||
An 8-bit number identifying the specific command, unique for a give
|
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.
|
space layout randomization (KASLR), helping in an attack.
|
||||||
|
|
||||||
For this reason (and for compat support) it is best to avoid any
|
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
|
in an existing structure, kernel drivers must be careful to fully
|
||||||
initialize an instance of the structure before copying it to user
|
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.
|
individual members.
|
||||||
|
|
||||||
Subsystem abstractions
|
Subsystem abstractions
|
||||||
|
@ -217,7 +217,7 @@ system-wide transition to a sleep state even though its :c:member:`runtime_auto`
|
|||||||
flag is clear.
|
flag is clear.
|
||||||
|
|
||||||
For more information about the runtime power management framework, refer to
|
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
|
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
|
actions that either require user space to be available, or at least won't
|
||||||
interfere with user space.
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
[Refer to that document for more information regarding this particular issue as
|
||||||
well as for information on the device runtime power management framework in
|
well as for information on the device runtime power management framework in
|
||||||
general.] However, it often is desirable to leave devices in suspend after
|
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
|
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::
|
.. toctree::
|
||||||
:maxdepth: 1
|
: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|
|
implemented as platform devices, via |ssam_device| and |ssam_device_driver|
|
||||||
simplify management of client devices and client drivers.
|
simplify management of client devices and client drivers.
|
||||||
|
|
||||||
Refer to :doc:`client` for documentation regarding the client device/driver
|
Refer to Documentation/driver-api/surface_aggregator/client.rst for
|
||||||
API and interface options for other kernel drivers. It is recommended to
|
documentation regarding the client device/driver API and interface options
|
||||||
familiarize oneself with that chapter and the :doc:`ssh` before continuing
|
for other kernel drivers. It is recommended to familiarize oneself with
|
||||||
with the architectural overview below.
|
that chapter and the Documentation/driver-api/surface_aggregator/ssh.rst
|
||||||
|
before continuing with the architectural overview below.
|
||||||
|
|
||||||
|
|
||||||
Packet Transport Layer
|
Packet Transport Layer
|
||||||
@ -190,9 +191,9 @@ with success on the transmitter thread.
|
|||||||
|
|
||||||
Transmission of sequenced packets is limited by the number of concurrently
|
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
|
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`
|
from the EC in parallel. This limit is currently set to one (see
|
||||||
for the reasoning behind this). Control packets (i.e. ACK and NAK) can
|
Documentation/driver-api/surface_aggregator/ssh.rst for the reasoning behind
|
||||||
always be transmitted.
|
this). Control packets (i.e. ACK and NAK) can always be transmitted.
|
||||||
|
|
||||||
Receiver Thread
|
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
|
without response as commands. In general, events need to be enabled via one
|
||||||
of multiple dedicated requests before they are sent by the EC.
|
of multiple dedicated requests before they are sent by the EC.
|
||||||
|
|
||||||
See :doc:`ssh` for a more technical protocol documentation and
|
See Documentation/driver-api/surface_aggregator/ssh.rst for a
|
||||||
:doc:`internal` for an overview of the internal driver architecture.
|
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,
|
The big picture is that USB drivers can continue to ignore most DMA issues,
|
||||||
though they still must provide DMA-ready buffers (see
|
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.
|
the 2.4 (and earlier) kernels, or they can now be DMA-aware.
|
||||||
|
|
||||||
DMA-aware usb drivers:
|
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
|
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
|
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
|
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.)
|
"streaming" DMA mappings.)
|
||||||
|
|
||||||
Asking for 1/Nth of a page (as well as asking for N pages) is reasonably
|
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
|
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
|
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
|
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
|
- 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
|
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:
|
- /sys/kernel/debug/fail*/times:
|
||||||
|
|
||||||
specifies how many times failures may happen at most.
|
specifies how many times failures may happen at most. A value of -1
|
||||||
A value of -1 means "no limit".
|
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:
|
- /sys/kernel/debug/fail*/space:
|
||||||
|
|
||||||
@ -167,11 +169,13 @@ configuration of fault-injection capabilities.
|
|||||||
- ERRNO: retval must be -1 to -MAX_ERRNO (-4096).
|
- ERRNO: retval must be -1 to -MAX_ERRNO (-4096).
|
||||||
- ERR_NULL: retval must be 0 or -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
|
specifies the "error" return value to inject to the given function.
|
||||||
function for given function. This will be created when
|
This will be created when the user specifies a new injection entry.
|
||||||
user specifies 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
|
Boot option
|
||||||
^^^^^^^^^^^
|
^^^^^^^^^^^
|
||||||
@ -255,7 +259,7 @@ Application Examples
|
|||||||
echo Y > /sys/kernel/debug/$FAILTYPE/task-filter
|
echo Y > /sys/kernel/debug/$FAILTYPE/task-filter
|
||||||
echo 10 > /sys/kernel/debug/$FAILTYPE/probability
|
echo 10 > /sys/kernel/debug/$FAILTYPE/probability
|
||||||
echo 100 > /sys/kernel/debug/$FAILTYPE/interval
|
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 0 > /sys/kernel/debug/$FAILTYPE/space
|
||||||
echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
|
echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
|
||||||
echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
|
echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
|
||||||
@ -309,7 +313,7 @@ Application Examples
|
|||||||
echo N > /sys/kernel/debug/$FAILTYPE/task-filter
|
echo N > /sys/kernel/debug/$FAILTYPE/task-filter
|
||||||
echo 10 > /sys/kernel/debug/$FAILTYPE/probability
|
echo 10 > /sys/kernel/debug/$FAILTYPE/probability
|
||||||
echo 100 > /sys/kernel/debug/$FAILTYPE/interval
|
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 0 > /sys/kernel/debug/$FAILTYPE/space
|
||||||
echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
|
echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
|
||||||
echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
|
echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
|
||||||
@ -336,11 +340,11 @@ Application Examples
|
|||||||
FAILTYPE=fail_function
|
FAILTYPE=fail_function
|
||||||
FAILFUNC=open_ctree
|
FAILFUNC=open_ctree
|
||||||
echo $FAILFUNC > /sys/kernel/debug/$FAILTYPE/inject
|
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 N > /sys/kernel/debug/$FAILTYPE/task-filter
|
||||||
echo 100 > /sys/kernel/debug/$FAILTYPE/probability
|
echo 100 > /sys/kernel/debug/$FAILTYPE/probability
|
||||||
echo 0 > /sys/kernel/debug/$FAILTYPE/interval
|
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 0 > /sys/kernel/debug/$FAILTYPE/space
|
||||||
echo 1 > /sys/kernel/debug/$FAILTYPE/verbose
|
echo 1 > /sys/kernel/debug/$FAILTYPE/verbose
|
||||||
|
|
||||||
|
291
Documentation/filesystems/dax.rst
Normal file
291
Documentation/filesystems/dax.rst
Normal file
@ -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)
|
(check=normal and check=strict options removed)
|
||||||
|
|
||||||
dax Use direct access (no page cache). See
|
dax Use direct access (no page cache). See
|
||||||
Documentation/filesystems/dax.txt.
|
Documentation/filesystems/dax.rst.
|
||||||
|
|
||||||
debug Extra debugging information is sent to the
|
debug Extra debugging information is sent to the
|
||||||
kernel syslog. Useful for developers.
|
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
|
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
|
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
|
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
|
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
|
(META\_BG), which is already in ext3 for all 2.6 releases. With the
|
||||||
|
@ -77,6 +77,7 @@ Documentation for filesystem implementations.
|
|||||||
coda
|
coda
|
||||||
configfs
|
configfs
|
||||||
cramfs
|
cramfs
|
||||||
|
dax
|
||||||
debugfs
|
debugfs
|
||||||
dlmfs
|
dlmfs
|
||||||
ecryptfs
|
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.
|
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
|
If that doesn't get a good result, it calls "``lookup_slow()``" which
|
||||||
takes ``i_rwsem``, rechecks the cache, and then asks the filesystem
|
takes ``i_rwsem``, rechecks the cache, and then asks the filesystem
|
||||||
to find a definitive answer. Each of these will call
|
to find a definitive answer.
|
||||||
``follow_managed()`` (as described below) to handle any mount points.
|
|
||||||
|
|
||||||
In the absence of symbolic links, ``walk_component()`` creates a new
|
As the last step of walk_component(), step_into() will be called either
|
||||||
``struct path`` containing a counted reference to the new dentry and a
|
directly from walk_component() or from handle_dots(). It calls
|
||||||
reference to the new ``vfsmount`` which is only counted if it is
|
handle_mounts(), to check and handle mount points, in which a new
|
||||||
different from the previous ``vfsmount``. It then calls
|
``struct path`` is created containing a counted reference to the new dentry and
|
||||||
``path_to_nameidata()`` to install the new ``struct path`` in the
|
a reference to the new ``vfsmount`` which is only counted if it is
|
||||||
``struct nameidata`` and drop the unneeded references.
|
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
|
This "hand-over-hand" sequencing of getting a reference to the new
|
||||||
dentry before dropping the reference to the previous dentry may
|
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
|
``nd->last_type`` to refer to the final component of the path. It does
|
||||||
not call ``walk_component()`` that last time. Handling that final
|
not call ``walk_component()`` that last time. Handling that final
|
||||||
component remains for the caller to sort out. Those callers are
|
component remains for the caller to sort out. Those callers are
|
||||||
``path_lookupat()``, ``path_parentat()``, ``path_mountpoint()`` and
|
path_lookupat(), path_parentat() and
|
||||||
``path_openat()`` each of which handles the differing requirements of
|
path_openat() each of which handles the differing requirements of
|
||||||
different system calls.
|
different system calls.
|
||||||
|
|
||||||
``path_parentat()`` is clearly the simplest - it just wraps a little bit
|
``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
|
object is wanted such as by ``stat()`` or ``chmod()``. It essentially just
|
||||||
calls ``walk_component()`` on the final component through a call to
|
calls ``walk_component()`` on the final component through a call to
|
||||||
``lookup_last()``. ``path_lookupat()`` returns just the final dentry.
|
``lookup_last()``. ``path_lookupat()`` returns just the final dentry.
|
||||||
|
It is worth noting that when flag ``LOOKUP_MOUNTPOINT`` is set,
|
||||||
``path_mountpoint()`` handles the special case of unmounting which must
|
path_lookupat() will unset LOOKUP_JUMPED in nameidata so that in the
|
||||||
not try to revalidate the mounted filesystem. It effectively
|
subsequent path traversal d_weak_revalidate() won't be called.
|
||||||
contains, through a call to ``mountpoint_last()``, an alternate
|
This is important when unmounting a filesystem that is inaccessible, such as
|
||||||
implementation of ``lookup_slow()`` which skips that step. This is
|
|
||||||
important when unmounting a filesystem that is inaccessible, such as
|
|
||||||
one provided by a dead NFS server.
|
one provided by a dead NFS server.
|
||||||
|
|
||||||
Finally ``path_openat()`` is used for the ``open()`` system call; it
|
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
|
complexity needed to handle the different subtleties of O_CREAT (with
|
||||||
or without O_EXCL), final "``/``" characters, and trailing symbolic
|
or without O_EXCL), final "``/``" characters, and trailing symbolic
|
||||||
links. We will revisit this in the final part of this series, which
|
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.
|
not always, take ``i_rwsem``, depending on what it finds.
|
||||||
|
|
||||||
Each of these, or the functions which call them, need to be alert to
|
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
|
tree, but a few notes specifically related to path lookup are in order
|
||||||
here.
|
here.
|
||||||
|
|
||||||
The Linux VFS has a concept of "managed" dentries which is reflected
|
The Linux VFS has a concept of "managed" dentries. There are three
|
||||||
in function names such as "``follow_managed()``". There are three
|
|
||||||
potentially interesting things about these dentries corresponding
|
potentially interesting things about these dentries corresponding
|
||||||
to three different flags that might be set in ``dentry->d_flags``:
|
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.
|
restarts from the top with REF-walk.
|
||||||
|
|
||||||
This pattern of "try RCU-walk, if that fails try REF-walk" can be
|
This pattern of "try RCU-walk, if that fails try REF-walk" can be
|
||||||
clearly seen in functions like ``filename_lookup()``,
|
clearly seen in functions like filename_lookup(),
|
||||||
``filename_parentat()``, ``filename_mountpoint()``,
|
filename_parentat(),
|
||||||
``do_filp_open()``, and ``do_file_open_root()``. These five
|
do_filp_open(), and do_file_open_root(). These four
|
||||||
correspond roughly to the four ``path_*()`` functions we met earlier,
|
correspond roughly to the three ``path_*()`` functions we met earlier,
|
||||||
each of which calls ``link_path_walk()``. The ``path_*()`` functions are
|
each of which calls ``link_path_walk()``. The ``path_*()`` functions are
|
||||||
called using different mode flags until a mode is found which works.
|
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
|
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
|
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
|
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
|
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
|
at most 40 (MAXSYMLINKS) symlinks in any one path lookup. It previously imposed
|
||||||
further limit of eight on the maximum depth of recursion, but that was
|
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
|
raised to 40 when a separate stack was implemented, so there is now
|
||||||
just the one limit.
|
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
|
must return ``-ECHILD`` and ``unlazy_walk()`` will be called to return to
|
||||||
REF-walk mode in which the filesystem is allowed to sleep.
|
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
|
The place for all this to happen is the ``i_op->get_link()`` inode
|
||||||
method. In the present mainline code this is never actually called in
|
method. This is called both in RCU-walk and REF-walk. In RCU-walk the
|
||||||
RCU-walk mode as the rewrite is not quite complete. It is likely that
|
``dentry*`` argument is NULL, ``->get_link()`` can return -ECHILD to drop out of
|
||||||
in a future release this method will be passed an ``inode`` pointer when
|
RCU-walk. Much like the ``i_op->permission()`` method we
|
||||||
called in RCU-walk mode so it both (1) knows to be careful, and (2) has the
|
looked at previously, ``->get_link()`` would need to be careful that
|
||||||
validated pointer. Much like the ``i_op->permission()`` method we
|
|
||||||
looked at previously, ``->follow_link()`` would need to be careful that
|
|
||||||
all the data structures it references are safe to be accessed while
|
all the data structures it references are safe to be accessed while
|
||||||
holding no counted reference, only the RCU lock. Though getting a
|
holding no counted reference, only the RCU lock. A callback
|
||||||
reference with ``->follow_link()`` is not yet done in RCU-walk mode, the
|
``struct delayed_called`` will be passed to ``->get_link()``:
|
||||||
code is ready to release the reference when that does happen.
|
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
|
||||||
This need to drop the reference to a symlink adds significant
|
do_delayed_call() to invoke that callback function with the argument.
|
||||||
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.
|
|
||||||
|
|
||||||
In order for the reference to each symlink to be dropped when the walk completes,
|
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,
|
whether in RCU-walk or REF-walk, the symlink stack needs to contain,
|
||||||
along with the path remnants:
|
along with the path remnants:
|
||||||
|
|
||||||
- the ``struct path`` to provide a reference to the inode in REF-walk
|
- the ``struct path`` to provide a reference to the previous path
|
||||||
- the ``struct inode *`` to provide a reference to the inode in RCU-walk
|
- 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 ``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
|
This means that each entry in the symlink stack needs to hold five
|
||||||
pointers and an integer instead of just one pointer (the path
|
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
|
stack is very straightforward; pushing and popping the references is
|
||||||
a little more complex.
|
a little more complex.
|
||||||
|
|
||||||
When a symlink is found, ``walk_component()`` returns the value ``1``
|
When a symlink is found, walk_component() calls pick_link() via step_into()
|
||||||
(``0`` is returned for any other sort of success, and a negative number
|
which returns the link from the filesystem.
|
||||||
is, as usual, an error indicator). This causes ``get_link()`` to be
|
Providing that operation is successful, the old path ``name`` is placed on the
|
||||||
called; it then gets the link from the filesystem. Providing that
|
stack, and the new value is used as the ``name`` for a while. When the end of
|
||||||
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
|
the path is found (i.e. ``*name`` is ``'\0'``) the old ``name`` is restored
|
||||||
off the stack and path walking continues.
|
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
|
old symlink as it walks that last component. So it is quite
|
||||||
convenient for ``walk_component()`` to release the old symlink and pop
|
convenient for ``walk_component()`` to release the old symlink and pop
|
||||||
the references just before pushing the reference information for the
|
the references just before pushing the reference information for the
|
||||||
new symlink. It is guided in this by two flags; ``WALK_GET``, which
|
new symlink. It is guided in this by three flags: ``WALK_NOFOLLOW`` which
|
||||||
gives it permission to follow a symlink if it finds one, and
|
forbids it from following a symlink if it finds one, ``WALK_MORE``
|
||||||
``WALK_PUT``, which tells it to release the current symlink after it has been
|
which indicates that it is yet too early to release the
|
||||||
followed. ``WALK_PUT`` is tested first, leading to a call to
|
current symlink, and ``WALK_TRAILING`` which indicates that it is on the final
|
||||||
``put_link()``. ``WALK_GET`` is tested subsequently (by
|
component of the lookup, so we will check userspace flag ``LOOKUP_FOLLOW`` to
|
||||||
``should_follow_link()``) leading to a call to ``pick_link()`` which sets
|
decide whether follow it when it is a symlink and call ``may_follow_link()`` to
|
||||||
up the stack frame.
|
check if we have privilege to follow it.
|
||||||
|
|
||||||
Symlinks with no final component
|
Symlinks with no final component
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
A pair of special-case symlinks deserve a little further explanation.
|
A pair of special-case symlinks deserve a little further explanation.
|
||||||
Both result in a new ``struct path`` (with mount and dentry) being set
|
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
|
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
|
to point to the effective filesystem root. If the symlink only
|
||||||
contains "``/``" then there is nothing more to do, no components at all,
|
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
|
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
|
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
|
objects you get a name that might refer to the same file - unless it
|
||||||
has been unlinked or mounted over. When ``walk_component()`` follows
|
has been unlinked or mounted over. When ``walk_component()`` follows
|
||||||
one of these, the ``->follow_link()`` method in "procfs" doesn't return
|
one of these, the ``->get_link()`` method in "procfs" doesn't return
|
||||||
a string name, but instead calls ``nd_jump_link()`` which updates the
|
a string name, but instead calls nd_jump_link() which updates the
|
||||||
``nameidata`` in place to point to that target. ``->follow_link()`` then
|
``nameidata`` in place to point to that target. ``->get_link()`` then
|
||||||
returns ``NULL``. Again there is no final component and ``get_link()``
|
returns ``NULL``. Again there is no final component and pick_link()
|
||||||
reports this by leaving the ``last_type`` field of ``nameidata`` as
|
returns ``NULL``.
|
||||||
``LAST_BIND``.
|
|
||||||
|
|
||||||
Following the symlink in the final component
|
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
|
successive symlinks until one is found that doesn't point to another
|
||||||
symlink.
|
symlink.
|
||||||
|
|
||||||
This case is handled by the relevant caller of ``link_path_walk()``, such as
|
This case is handled by relevant callers of link_path_walk(), such as
|
||||||
``path_lookupat()`` using a loop that calls ``link_path_walk()``, and then
|
path_lookupat(), path_openat() using a loop that calls link_path_walk(),
|
||||||
handles the final component. If the final component is a symlink
|
and then handles the final component by calling open_last_lookups() or
|
||||||
that needs to be followed, then ``trailing_symlink()`` is called to set
|
lookup_last(). If it is a symlink that needs to be followed,
|
||||||
things up properly and the loop repeats, calling ``link_path_walk()``
|
open_last_lookups() or lookup_last() will set things up properly and
|
||||||
again. This could loop as many as 40 times if the last component of
|
return the path so that the loop repeats, calling
|
||||||
each symlink is another symlink.
|
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
|
Of the various functions that examine the final component,
|
||||||
report that it is a symlink are ``lookup_last()``, ``mountpoint_last()``
|
open_last_lookups() is the most interesting as it works in tandem
|
||||||
and ``do_last()``, each of which use the same convention as
|
with do_open() for opening a file. Part of open_last_lookups() runs
|
||||||
``walk_component()`` of returning ``1`` if a symlink was found that needs
|
with ``i_rwsem`` held and this part is in a separate function: lookup_open().
|
||||||
to be followed.
|
|
||||||
|
|
||||||
Of these, ``do_last()`` is the most interesting as it is used for
|
Explaining open_last_lookups() and do_open() completely is beyond the scope
|
||||||
opening a file. Part of ``do_last()`` runs with ``i_rwsem`` held and this
|
of this article, but a few highlights should help those interested in exploring
|
||||||
part is in a separate function: ``lookup_open()``.
|
the code.
|
||||||
|
|
||||||
Explaining ``do_last()`` completely is beyond the scope of this article,
|
1. Rather than just finding the target file, do_open() is used after
|
||||||
but a few highlights should help those interested in exploring the
|
open_last_lookup() to open
|
||||||
code.
|
|
||||||
|
|
||||||
1. Rather than just finding the target file, ``do_last()`` needs to open
|
|
||||||
it. If the file was found in the dcache, then ``vfs_open()`` is used for
|
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
|
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
|
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
|
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.
|
were found in the dcache.
|
||||||
|
|
||||||
2. ``vfs_open()`` can fail with ``-EOPENSTALE`` if the cached information
|
2. vfs_open() can fail with ``-EOPENSTALE`` if the cached information
|
||||||
wasn't quite current enough. Rather than restarting the lookup from
|
wasn't quite current enough. If it's in RCU-walk ``-ECHILD`` will be returned
|
||||||
the top with ``LOOKUP_REVAL`` set, ``lookup_open()`` is called instead,
|
otherwise ``-ESTALE`` is returned. When ``-ESTALE`` is returned, the caller may
|
||||||
giving the filesystem a chance to resolve small inconsistencies.
|
retry with ``LOOKUP_REVAL`` flag set.
|
||||||
If that doesn't work, only then is the lookup restarted from the top.
|
|
||||||
|
|
||||||
3. An open with O_CREAT **does** follow a symlink in the final component,
|
3. An open with O_CREAT **does** follow a symlink in the final component,
|
||||||
unlike other creation system calls (like ``mkdir``). So the sequence::
|
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
|
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
|
``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
|
like for a non-creating open: lookup_last() or open_last_lookup()
|
||||||
so does ``do_last()`` so that ``trailing_symlink()`` gets called and the
|
returns a non ``NULL`` value, and link_path_walk() gets called and the
|
||||||
open process continues on the symlink that was found.
|
open process continues on the symlink that was found.
|
||||||
|
|
||||||
Updating the access time
|
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
|
References
|
||||||
==========
|
==========
|
||||||
|
@ -174,4 +174,4 @@ References
|
|||||||
referenced 2016-10-04.
|
referenced 2016-10-04.
|
||||||
|
|
||||||
[7] _DSD Device Properties Usage Rules.
|
[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
|
There are also devm_* versions of these functions which release the
|
||||||
descriptors once the device is released.
|
descriptors once the device is released.
|
||||||
|
|
||||||
See Documentation/firmware-guide/acpi/gpio-properties.rst for more information about the
|
See Documentation/firmware-guide/acpi/gpio-properties.rst for more information
|
||||||
_DSD binding related to GPIOs.
|
about the _DSD binding related to GPIOs.
|
||||||
|
|
||||||
MFD devices
|
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"
|
Otherwise, the _DSD itself is regarded as invalid and therefore the "compatible"
|
||||||
property returned by it is meaningless.
|
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
|
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
|
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
|
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
|
With the conversion of the I2C subsystem to the standard device driver
|
||||||
binding model, it became clear that these per-module parameters were no
|
binding model, it became clear that these per-module parameters were no
|
||||||
longer needed, and that a centralized implementation was possible. The new,
|
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".
|
"Method 4: Instantiate from user-space".
|
||||||
|
|
||||||
Below is a mapping from the old module parameters to the new interface.
|
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
|
Each transaction type corresponds to a functionality flag. Before calling a
|
||||||
transaction function, a device driver should always check (just once) for
|
transaction function, a device driver should always check (just once) for
|
||||||
the corresponding functionality flag to ensure that the underlying I2C
|
the corresponding functionality flag to ensure that the underlying I2C
|
||||||
adapter supports the transaction in question. See :doc:`functionality` for
|
adapter supports the transaction in question. See
|
||||||
the details.
|
Documentation/i2c/functionality.rst for the details.
|
||||||
|
|
||||||
|
|
||||||
Key to symbols
|
Key to symbols
|
||||||
|
@ -263,7 +263,7 @@ possible overrun should the name be too long::
|
|||||||
|
|
||||||
char name[128];
|
char name[128];
|
||||||
if (ioctl(fd, JSIOCGNAME(sizeof(name)), name) < 0)
|
if (ioctl(fd, JSIOCGNAME(sizeof(name)), name) < 0)
|
||||||
strncpy(name, "Unknown", sizeof(name));
|
strscpy(name, "Unknown", sizeof(name));
|
||||||
printf("Name: %s\n", 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
|
This is the variant of `EXPORT_SYMBOL()` that allows specifying a symbol
|
||||||
namespace. Symbol Namespaces are documented in
|
namespace. Symbol Namespaces are documented in
|
||||||
:doc:`../core-api/symbol-namespaces`
|
Documentation/core-api/symbol-namespaces.rst
|
||||||
|
|
||||||
:c:func:`EXPORT_SYMBOL_NS_GPL()`
|
: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
|
This is the variant of `EXPORT_SYMBOL_GPL()` that allows specifying a symbol
|
||||||
namespace. Symbol Namespaces are documented in
|
namespace. Symbol Namespaces are documented in
|
||||||
:doc:`../core-api/symbol-namespaces`
|
Documentation/core-api/symbol-namespaces.rst
|
||||||
|
|
||||||
Routines and Conventions
|
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
|
"ethtool -T <netdev name>" to get a definitive list of PTP capabilities
|
||||||
supported by the device.
|
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
|
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
|
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
|
Maximum Bandwidth is not restricted, because no more than 100% of a port's
|
||||||
bandwidth can ever be used.
|
bandwidth can ever be used.
|
||||||
|
|
||||||
NOTE: X710/XXV710 devices fail to enable Max VFs (64) when Multiple Functions
|
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
|
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
|
"add vsi failed for VF N, aq_err 16". To workaround the issue, enable less than
|
||||||
64 virtual functions (VFs).
|
64 virtual functions (VFs).
|
||||||
|
|
||||||
|
@ -113,7 +113,7 @@ which the AVF is associated. The following are base mode features:
|
|||||||
- AVF device ID
|
- AVF device ID
|
||||||
- HW mailbox is used for VF to PF communications (including on Windows)
|
- 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
|
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
|
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.
|
address regions that are otherwise inaccessible to the user.
|
||||||
|
|
||||||
Regions may also be used to provide an additional way to debug complex error
|
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
|
Regions may optionally support capturing a snapshot on demand via the
|
||||||
``DEVLINK_CMD_REGION_NEW`` netlink message. A driver wishing to allow
|
``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
|
links to the description of driver-specific traps registered by various device
|
||||||
drivers:
|
drivers:
|
||||||
|
|
||||||
* :doc:`netdevsim`
|
* Documentation/networking/devlink/netdevsim.rst
|
||||||
* :doc:`mlxsw`
|
* Documentation/networking/devlink/mlxsw.rst
|
||||||
|
|
||||||
.. _Generic-Packet-Trap-Groups:
|
.. _Generic-Packet-Trap-Groups:
|
||||||
|
|
||||||
|
@ -153,7 +153,7 @@ As capture, each frame contains two parts::
|
|||||||
struct ifreq s_ifr;
|
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 */
|
/* get interface index of eth0 */
|
||||||
ioctl(this->socket, SIOCGIFINDEX, &s_ifr);
|
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;
|
ifr.ifr_flags = IFF_TUN;
|
||||||
if( *dev )
|
if( *dev )
|
||||||
strncpy(ifr.ifr_name, dev, IFNAMSIZ);
|
strscpy_pad(ifr.ifr_name, dev, IFNAMSIZ);
|
||||||
|
|
||||||
if( (err = ioctl(fd, TUNSETIFF, (void *) &ifr)) < 0 ){
|
if( (err = ioctl(fd, TUNSETIFF, (void *) &ifr)) < 0 ){
|
||||||
close(fd);
|
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
|
This document contains a large number of suggestions in a relatively terse
|
||||||
format. For detailed information on how the kernel development process
|
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
|
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,
|
a driver, also read Documentation/process/submitting-drivers.rst; for device
|
||||||
read :doc:`submitting-patches`.
|
tree binding patches, read Documentation/process/submitting-patches.rst.
|
||||||
|
|
||||||
This documentation assumes that you're using ``git`` to prepare your patches.
|
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
|
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
|
Check your patch for basic style violations, details of which can be
|
||||||
found in
|
found in Documentation/process/coding-style.rst.
|
||||||
:ref:`Documentation/process/coding-style.rst <codingstyle>`.
|
|
||||||
Failure to do so simply wastes
|
Failure to do so simply wastes
|
||||||
the reviewers time and will get your patch rejected, probably
|
the reviewers time and will get your patch rejected, probably
|
||||||
without even being read.
|
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 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,
|
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
|
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
|
Patches that fix a severe bug in a released kernel should be directed
|
||||||
toward the stable maintainers by putting a line like this::
|
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
|
Cc: stable@vger.kernel.org
|
||||||
|
|
||||||
into the sign-off area of your patch (note, NOT an email recipient). You
|
into the sign-off area of your patch (note, NOT an email recipient). You
|
||||||
should also read
|
should also read Documentation/process/stable-kernel-rules.rst
|
||||||
:ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`
|
in addition to this document.
|
||||||
in addition to this file.
|
|
||||||
|
|
||||||
If changes affect userland-kernel interfaces, please send the MAN-PAGES
|
If changes affect userland-kernel interfaces, please send the MAN-PAGES
|
||||||
maintainer (as listed in the MAINTAINERS file) a man-pages patch, or at
|
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
|
Exception: If your mailer is mangling patches then someone may ask
|
||||||
you to re-send them using MIME.
|
you to re-send them using MIME.
|
||||||
|
|
||||||
See :doc:`/process/email-clients` for hints about configuring your e-mail
|
See Documentation/process/email-clients.rst for hints about configuring
|
||||||
client so that it sends your patches untouched.
|
your e-mail client so that it sends your patches untouched.
|
||||||
|
|
||||||
Respond to review comments
|
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
|
reviewers sometimes get grumpy. Even in that case, though, respond
|
||||||
politely and address the problems they have pointed out.
|
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.
|
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.
|
for more details.
|
||||||
|
|
||||||
Note: Attaching a Fixes: tag does not subvert the stable kernel rules
|
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
|
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:
|
||||||
|
|
||||||
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!
|
NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
|
||||||
<https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net>
|
<https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net>
|
||||||
|
|
||||||
Kernel Documentation/process/coding-style.rst:
|
Kernel Documentation/process/coding-style.rst
|
||||||
:ref:`Documentation/process/coding-style.rst <codingstyle>`
|
|
||||||
|
|
||||||
Linus Torvalds's mail on the canonical patch format:
|
Linus Torvalds's mail on the canonical patch format:
|
||||||
<https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org>
|
<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::
|
.. note::
|
||||||
The cgroupfs files described in this section are only applicable
|
The cgroupfs files described in this section are only applicable
|
||||||
to cgroup v1. For cgroup v2, see
|
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
|
- cpu.cfs_quota_us: the total available run-time within a period (in
|
||||||
microseconds)
|
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.
|
coupling to timeslices and granularity it was not really viable.
|
||||||
|
|
||||||
The second (less frequent but still periodically occurring) complaint
|
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
|
(which you can see demonstrated in the picture above), or more
|
||||||
accurately: the fact that nice level behavior depended on the _absolute_
|
accurately: the fact that nice level behavior depended on the _absolute_
|
||||||
nice level as well, while the nice API itself is fundamentally
|
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
|
evaluated according to the inherited ones in a way that ensures that only more
|
||||||
constraints can be added.
|
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
|
Guiding principles for safe access controls
|
||||||
===========================================
|
===========================================
|
||||||
|
@ -427,7 +427,7 @@ the ‘TRC’ prefix.
|
|||||||
:Syntax:
|
:Syntax:
|
||||||
``echo idx > vmid_idx``
|
``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.
|
Note: ``cti_sys0`` appears in two of the connections lists above.
|
||||||
CTIs can connect to multiple devices and are arranged in a star topology
|
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::
|
Looking at this device we see 4 connections::
|
||||||
|
|
||||||
linaro-developer:~# ls -l /sys/bus/coresight/devices/cti_sys0/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
|
crw------- 1 root root 10, 61 Jan 3 18:11 /dev/stm0
|
||||||
root@genericarmv8:~#
|
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
|
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).
|
channels on the CTM (Cross Trigger Matrix).
|
||||||
|
|
||||||
A separate documentation file is provided to explain the use of these devices.
|
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
|
.. [#first] Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
|
||||||
|
@ -40,7 +40,7 @@ See events.rst for more information.
|
|||||||
Implementation Details
|
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
|
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
|
is being directly called by the function. If the count is greater
|
||||||
than 1 it most likely will be ftrace_ops_list_func().
|
than 1 it most likely will be ftrace_ops_list_func().
|
||||||
|
|
||||||
If the callback of the function jumps to a trampoline that is
|
If the callback of a function jumps to a trampoline that is
|
||||||
specific to a the callback and not the standard trampoline,
|
specific to the callback and which is not the standard trampoline,
|
||||||
its address will be printed as well as the function that the
|
its address will be printed as well as the function that the
|
||||||
trampoline calls.
|
trampoline calls.
|
||||||
|
|
||||||
|
@ -18,6 +18,10 @@ Translations
|
|||||||
Disclaimer
|
Disclaimer
|
||||||
----------
|
----------
|
||||||
|
|
||||||
|
.. raw:: latex
|
||||||
|
|
||||||
|
\kerneldocCJKoff
|
||||||
|
|
||||||
Translation's purpose is to ease reading and understanding in languages other
|
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
|
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
|
doubts about its interpretation. Additionally, some people prefer to read
|
||||||
|
@ -4,6 +4,10 @@
|
|||||||
Traduzione italiana
|
Traduzione italiana
|
||||||
===================
|
===================
|
||||||
|
|
||||||
|
.. raw:: latex
|
||||||
|
|
||||||
|
\kerneldocCJKoff
|
||||||
|
|
||||||
:manutentore: Federico Vaga <federico.vaga@vaga.pv.it>
|
:manutentore: Federico Vaga <federico.vaga@vaga.pv.it>
|
||||||
|
|
||||||
.. _it_disclaimer:
|
.. _it_disclaimer:
|
||||||
|
@ -62,7 +62,7 @@ i ``case``. Un esempio.:
|
|||||||
case 'K':
|
case 'K':
|
||||||
case 'k':
|
case 'k':
|
||||||
mem <<= 10;
|
mem <<= 10;
|
||||||
/* fall through */
|
fallthrough;
|
||||||
default:
|
default:
|
||||||
break;
|
break;
|
||||||
}
|
}
|
||||||
|
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue
Block a user