Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Merge tag 'docs-6.12' of git://git.lwn.net/linux
Pull documentation update from Jonathan Corbet:
"Another relatively mundane cycle for docs:
- The beginning of an EEVDF scheduler document
- More Chinese translations
- A rethrashing of our bisection documentation
...plus the usual array of smaller fixes, and more than the usual
number of typo fixes"
* tag 'docs-6.12' of git://git.lwn.net/linux: (48 commits)
Remove duplicate "and" in 'Linux NVMe docs.
docs:filesystems: fix spelling and grammar mistakes
docs:filesystem: fix mispelled words on autofs page
docs:mm: fixed spelling and grammar mistakes on vmalloc kernel stack page
Documentation: PCI: fix typo in pci.rst
docs/zh_CN: add the translation of kbuild/gcc-plugins.rst
docs/process: fix typos
docs:mm: fix spelling mistakes in heterogeneous memory management page
accel/qaic: Fix a typo
docs/zh_CN: update the translation of security-bugs
docs: block: Fix grammar and spelling mistakes in bfq-iosched.rst
Documentation: Fix spelling mistakes
Documentation/gpu: Fix typo in Documentation/gpu/komeda-kms.rst
scripts: sphinx-pre-install: remove unnecessary double check for $cur_version
Loongarch: KVM: Add KVM hypercalls documentation for LoongArch
Documentation: Document the kernel flag bdev_allow_write_mounted
docs: scheduler: completion: Update member of struct completion
docs: kerneldoc-preamble.sty: Suppress extra spaces in CJK literal blocks
docs: submitting-patches: Advertise b4
docs: update dev-tools/kcsan.rst url about KTSAN
...
+1308
-250
+1
-1
Documentation/PCI/pci.rst
+1
-1
Documentation/PCI/pci.rst
···
52
52
- Enable DMA/processing engines
53
53
54
54
When done using the device, and perhaps the module needs to be unloaded,
55
-
the driver needs to take the follow steps:
55
+
the driver needs to take the following steps:
56
56
57
57
- Disable the device from generating IRQs
58
58
- Release the IRQ (free_irq())
+1
-1
Documentation/accel/qaic/qaic.rst
+1
-1
Documentation/accel/qaic/qaic.rst
···
93
93
uAPI
94
94
====
95
95
96
-
QAIC creates an accel device per phsyical PCIe device. This accel device exists
96
+
QAIC creates an accel device per physical PCIe device. This accel device exists
97
97
for as long as the PCIe device is known to Linux.
98
98
99
99
The PCIe device may not be in the state to accept requests from userspace at
+117
-49
Documentation/admin-guide/bug-bisect.rst
+117
-49
Documentation/admin-guide/bug-bisect.rst
···
1
-
Bisecting a bug
2
-
+++++++++++++++
1
+
.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0)
2
+
.. [see the bottom of this file for redistribution information]
3
3
4
-
Last updated: 28 October 2016
4
+
======================
5
+
Bisecting a regression
6
+
======================
5
7
6
-
Introduction
7
-
============
8
+
This document describes how to use a ``git bisect`` to find the source code
9
+
change that broke something -- for example when some functionality stopped
10
+
working after upgrading from Linux 6.0 to 6.1.
8
11
9
-
Always try the latest kernel from kernel.org and build from source. If you are
10
-
not confident in doing that please report the bug to your distribution vendor
11
-
instead of to a kernel developer.
12
+
The text focuses on the gist of the process. If you are new to bisecting the
13
+
kernel, better follow Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst
14
+
instead: it depicts everything from start to finish while covering multiple
15
+
aspects even kernel developers occasionally forget. This includes detecting
16
+
situations early where a bisection would be a waste of time, as nobody would
17
+
care about the result -- for example, because the problem happens after the
18
+
kernel marked itself as 'tainted', occurs in an abandoned version, was already
19
+
fixed, or is caused by a .config change you or your Linux distributor performed.
12
20
13
-
Finding bugs is not always easy. Have a go though. If you can't find it don't
14
-
give up. Report as much as you have found to the relevant maintainer. See
15
-
MAINTAINERS for who that is for the subsystem you have worked on.
21
+
Finding the change causing a kernel issue using a bisection
22
+
===========================================================
16
23
17
-
Before you submit a bug report read
18
-
'Documentation/admin-guide/reporting-issues.rst'.
24
+
*Note: the following process assumes you prepared everything for a bisection.
25
+
This includes having a Git clone with the appropriate sources, installing the
26
+
software required to build and install kernels, as well as a .config file stored
27
+
in a safe place (the following example assumes '~/prepared_kernel_.config') to
28
+
use as pristine base at each bisection step; ideally, you have also worked out
29
+
a fully reliable and straight-forward way to reproduce the regression, too.*
19
30
20
-
Devices not appearing
21
-
=====================
31
+
* Preparation: start the bisection and tell Git about the points in the history
32
+
you consider to be working and broken, which Git calls 'good' and 'bad'::
22
33
23
-
Often this is caused by udev/systemd. Check that first before blaming it
24
-
on the kernel.
34
+
git bisect start
35
+
git bisect good v6.0
36
+
git bisect bad v6.1
25
37
26
-
Finding patch that caused a bug
27
-
===============================
38
+
Instead of Git tags like 'v6.0' and 'v6.1' you can specify commit-ids, too.
28
39
29
-
Using the provided tools with ``git`` makes finding bugs easy provided the bug
30
-
is reproducible.
40
+
1. Copy your prepared .config into the build directory and adjust it to the
41
+
needs of the codebase Git checked out for testing::
31
42
32
-
Steps to do it:
43
+
cp ~/prepared_kernel_.config .config
44
+
make olddefconfig
33
45
34
-
- build the Kernel from its git source
35
-
- start bisect with [#f1]_::
46
+
2. Now build, install, and boot a kernel. This might fail for unrelated reasons,
47
+
for example, when a compile error happens at the current stage of the
48
+
bisection a later change resolves. In such cases run ``git bisect skip`` and
49
+
go back to step 1.
36
50
37
-
$ git bisect start
51
+
3. Check if the functionality that regressed works in the kernel you just built.
38
52
39
-
- mark the broken changeset with::
53
+
If it works, execute::
40
54
41
-
$ git bisect bad [commit]
55
+
git bisect good
42
56
43
-
- mark a changeset where the code is known to work with::
57
+
If it is broken, run::
44
58
45
-
$ git bisect good [commit]
59
+
git bisect bad
46
60
47
-
- rebuild the Kernel and test
48
-
- interact with git bisect by using either::
61
+
Note, getting this wrong just once will send the rest of the bisection
62
+
totally off course. To prevent having to start anew later you thus want to
63
+
ensure what you tell Git is correct; it is thus often wise to spend a few
64
+
minutes more on testing in case your reproducer is unreliable.
49
65
50
-
$ git bisect good
66
+
After issuing one of these two commands, Git will usually check out another
67
+
bisection point and print something like 'Bisecting: 675 revisions left to
68
+
test after this (roughly 10 steps)'. In that case go back to step 1.
51
69
52
-
or::
70
+
If Git instead prints something like 'cafecaca0c0dacafecaca0c0dacafecaca0c0da
71
+
is the first bad commit', then you have finished the bisection. In that case
72
+
move to the next point below. Note, right after displaying that line Git will
73
+
show some details about the culprit including its patch description; this can
74
+
easily fill your terminal, so you might need to scroll up to see the message
75
+
mentioning the culprit's commit-id.
53
76
54
-
$ git bisect bad
77
+
In case you missed Git's output, you can always run ``git bisect log`` to
78
+
print the status: it will show how many steps remain or mention the result of
79
+
the bisection.
55
80
56
-
depending if the bug happened on the changeset you're testing
57
-
- After some interactions, git bisect will give you the changeset that
58
-
likely caused the bug.
81
+
* Recommended complementary task: put the bisection log and the current .config
82
+
file aside for the bug report; furthermore tell Git to reset the sources to
83
+
the state before the bisection::
59
84
60
-
- For example, if you know that the current version is bad, and version
61
-
4.8 is good, you could do::
85
+
git bisect log > ~/bisection-log
86
+
cp .config ~/bisection-config-culprit
87
+
git bisect reset
62
88
63
-
$ git bisect start
64
-
$ git bisect bad # Current version is bad
65
-
$ git bisect good v4.8
89
+
* Recommended optional task: try reverting the culprit on top of the latest
90
+
codebase and check if that fixes your bug; if that is the case, it validates
91
+
the bisection and enables developers to resolve the regression through a
92
+
revert.
93
+
94
+
To try this, update your clone and check out latest mainline. Then tell Git
95
+
to revert the change by specifying its commit-id::
96
+
97
+
git revert --no-edit cafec0cacaca0
98
+
99
+
Git might reject this, for example when the bisection landed on a merge
100
+
commit. In that case, abandon the attempt. Do the same, if Git fails to revert
101
+
the culprit on its own because later changes depend on it -- at least unless
102
+
you bisected a stable or longterm kernel series, in which case you want to
103
+
check out its latest codebase and try a revert there.
104
+
105
+
If a revert succeeds, build and test another kernel to check if reverting
106
+
resolved your regression.
107
+
108
+
With that the process is complete. Now report the regression as described by
109
+
Documentation/admin-guide/reporting-issues.rst.
66
110
67
111
68
-
.. [#f1] You can, optionally, provide both good and bad arguments at git
69
-
start with ``git bisect start [BAD] [GOOD]``
112
+
Additional reading material
113
+
---------------------------
70
114
71
-
For further references, please read:
115
+
* The `man page for 'git bisect' <https://git-scm.com/docs/git-bisect>`_ and
116
+
`fighting regressions with 'git bisect' <https://git-scm.com/docs/git-bisect-lk2009.html>`_
117
+
in the Git documentation.
118
+
* `Working with git bisect <https://nathanchance.dev/posts/working-with-git-bisect/>`_
119
+
from kernel developer Nathan Chancellor.
120
+
* `Using Git bisect to figure out when brokenness was introduced <http://webchick.net/node/99>`_.
121
+
* `Fully automated bisecting with 'git bisect run' <https://lwn.net/Articles/317154>`_.
72
122
73
-
- The man page for ``git-bisect``
74
-
- `Fighting regressions with git bisect <https://www.kernel.org/pub/software/scm/git/docs/git-bisect-lk2009.html>`_
75
-
- `Fully automated bisecting with "git bisect run" <https://lwn.net/Articles/317154>`_
76
-
- `Using Git bisect to figure out when brokenness was introduced <http://webchick.net/node/99>`_
123
+
..
124
+
end-of-content
125
+
..
126
+
This document is maintained by Thorsten Leemhuis <linux@leemhuis.info>. If
127
+
you spot a typo or small mistake, feel free to let him know directly and
128
+
he'll fix it. You are free to do the same in a mostly informal way if you
129
+
want to contribute changes to the text -- but for copyright reasons please CC
130
+
linux-doc@vger.kernel.org and 'sign-off' your contribution as
131
+
Documentation/process/submitting-patches.rst explains in the section 'Sign
132
+
your work - the Developer's Certificate of Origin'.
133
+
..
134
+
This text is available under GPL-2.0+ or CC-BY-4.0, as stated at the top
135
+
of the file. If you want to distribute this text under CC-BY-4.0 only,
136
+
please use 'The Linux kernel development community' for author attribution
137
+
and link this as source:
138
+
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/bug-bisect.rst
139
+
140
+
..
141
+
Note: Only the content of this RST file as found in the Linux kernel sources
142
+
is available under CC-BY-4.0, as versions of this text that were processed
143
+
(for example by the kernel's build system) might contain content taken from
144
+
files which use a more restrictive license.
+9
-8
Documentation/admin-guide/bug-hunting.rst
+9
-8
Documentation/admin-guide/bug-hunting.rst
···
244
244
Once you find where the bug happened, by inspecting its location,
245
245
you could either try to fix it yourself or report it upstream.
246
246
247
-
In order to report it upstream, you should identify the mailing list
248
-
used for the development of the affected code. This can be done by using
249
-
the ``get_maintainer.pl`` script.
247
+
In order to report it upstream, you should identify the bug tracker, if any, or
248
+
mailing list used for the development of the affected code. This can be done by
249
+
using the ``get_maintainer.pl`` script.
250
250
251
251
For example, if you find a bug at the gspca's sonixj.c file, you can get
252
252
its maintainers with::
253
253
254
-
$ ./scripts/get_maintainer.pl -f drivers/media/usb/gspca/sonixj.c
254
+
$ ./scripts/get_maintainer.pl --bug -f drivers/media/usb/gspca/sonixj.c
255
255
Hans Verkuil <hverkuil@xs4all.nl> (odd fixer:GSPCA USB WEBCAM DRIVER,commit_signer:1/1=100%)
256
256
Mauro Carvalho Chehab <mchehab@kernel.org> (maintainer:MEDIA INPUT INFRASTRUCTURE (V4L/DVB),commit_signer:1/1=100%)
257
257
Tejun Heo <tj@kernel.org> (commit_signer:1/1=100%)
···
267
267
- The driver maintainer (Hans Verkuil);
268
268
- The subsystem maintainer (Mauro Carvalho Chehab);
269
269
- The driver and/or subsystem mailing list (linux-media@vger.kernel.org);
270
-
- the Linux Kernel mailing list (linux-kernel@vger.kernel.org).
270
+
- The Linux Kernel mailing list (linux-kernel@vger.kernel.org);
271
+
- The bug reporting URIs for the driver/subsystem (none in the above example).
271
272
272
-
Usually, the fastest way to have your bug fixed is to report it to mailing
273
-
list used for the development of the code (linux-media ML) copying the
274
-
driver maintainer (Hans).
273
+
If the listing contains bug reporting URIs at the end, please prefer them over
274
+
email. Otherwise, please report bugs to the mailing list used for the
275
+
development of the code (linux-media ML) copying the driver maintainer (Hans).
275
276
276
277
If you are totally stumped as to whom to send the report, and
277
278
``get_maintainer.pl`` didn't provide you anything useful, send it to
+9
-4
Documentation/admin-guide/device-mapper/dm-crypt.rst
+9
-4
Documentation/admin-guide/device-mapper/dm-crypt.rst
···
162
162
163
163
164
164
Module parameters::
165
-
166
165
max_read_size
167
-
max_write_size
168
-
Maximum size of read or write requests. When a request larger than this size
166
+
Maximum size of read requests. When a request larger than this size
169
167
is received, dm-crypt will split the request. The splitting improves
170
168
concurrency (the split requests could be encrypted in parallel by multiple
171
-
cores), but it also causes overhead. The user should tune these parameters to
169
+
cores), but it also causes overhead. The user should tune this parameters to
170
+
fit the actual workload.
171
+
172
+
max_write_size
173
+
Maximum size of write requests. When a request larger than this size
174
+
is received, dm-crypt will split the request. The splitting improves
175
+
concurrency (the split requests could be encrypted in parallel by multiple
176
+
cores), but it also causes overhead. The user should tune this parameters to
172
177
fit the actual workload.
173
178
174
179
+12
Documentation/admin-guide/kernel-parameters.txt
+12
Documentation/admin-guide/kernel-parameters.txt
···
517
517
Format: <io>,<irq>,<mode>
518
518
See header of drivers/net/hamradio/baycom_ser_hdx.c.
519
519
520
+
bdev_allow_write_mounted=
521
+
Format: <bool>
522
+
Control the ability to open a mounted block device
523
+
for writing, i.e., allow / disallow writes that bypass
524
+
the FS. This was implemented as a means to prevent
525
+
fuzzers from crashing the kernel by overwriting the
526
+
metadata underneath a mounted FS without its awareness.
527
+
This also prevents destructive formatting of mounted
528
+
filesystems by naive storage tooling that don't use
529
+
O_EXCL. Default is Y and can be changed through the
530
+
Kconfig option CONFIG_BLK_DEV_WRITE_MOUNTED.
531
+
520
532
bert_disable [ACPI]
521
533
Disable BERT OS support on buggy BIOSes.
522
534
+2
Documentation/admin-guide/tainted-kernels.rst
+2
Documentation/admin-guide/tainted-kernels.rst
+2
-2
Documentation/arch/arm/stm32/stm32-dma-mdma-chaining.rst
+2
-2
Documentation/arch/arm/stm32/stm32-dma-mdma-chaining.rst
···
359
359
descriptor you want a callback to be called at the end of the transfer
360
360
(dmaengine_prep_slave_sg()) or the period (dmaengine_prep_dma_cyclic()).
361
361
Depending on the direction, set the callback on the descriptor that finishes
362
-
the overal transfer:
362
+
the overall transfer:
363
363
364
364
* DMA_DEV_TO_MEM: set the callback on the "MDMA" descriptor
365
365
* DMA_MEM_TO_DEV: set the callback on the "DMA" descriptor
···
371
371
As STM32 MDMA channel transfer is triggered by STM32 DMA, you must issue
372
372
STM32 MDMA channel before STM32 DMA channel.
373
373
374
-
If any, your callback will be called to warn you about the end of the overal
374
+
If any, your callback will be called to warn you about the end of the overall
375
375
transfer or the period completion.
376
376
377
377
Don't forget to terminate both channels. STM32 DMA channel is configured in
+1
-1
Documentation/arch/arm64/cpu-hotplug.rst
+1
-1
Documentation/arch/arm64/cpu-hotplug.rst
···
26
26
while the system is running, and ACPI is not able to sufficiently describe
27
27
them.
28
28
29
-
e.g. New CPUs come with new caches, but the platform's cache toplogy is
29
+
e.g. New CPUs come with new caches, but the platform's cache topology is
30
30
described in a static table, the PPTT. How caches are shared between CPUs is
31
31
not discoverable, and must be described by firmware.
32
32
+1
-1
Documentation/arch/powerpc/ultravisor.rst
+1
-1
Documentation/arch/powerpc/ultravisor.rst
···
134
134
135
135
* PTCR and partition table entries (partition table is in secure
136
136
memory). An attempt to write to PTCR will cause a Hypervisor
137
-
Emulation Assitance interrupt.
137
+
Emulation Assistance interrupt.
138
138
139
139
* LDBAR (LD Base Address Register) and IMC (In-Memory Collection)
140
140
non-architected registers. An attempt to write to them will cause a
+1
-1
Documentation/arch/riscv/vector.rst
+1
-1
Documentation/arch/riscv/vector.rst
···
15
15
these interfaces is to give init systems a way to modify the availability of V
16
16
for processes running under its domain. Calling these interfaces is not
17
17
recommended in libraries routines because libraries should not override policies
18
-
configured from the parant process. Also, users must noted that these interfaces
18
+
configured from the parent process. Also, users must note that these interfaces
19
19
are not portable to non-Linux, nor non-RISC-V environments, so it is discourage
20
20
to use in a portable code. To get the availability of V in an ELF program,
21
21
please read :c:macro:`COMPAT_HWCAP_ISA_V` bit of :c:macro:`ELF_HWCAP` in the
+1
-1
Documentation/arch/x86/mds.rst
+1
-1
Documentation/arch/x86/mds.rst
···
162
162
3. It would take a large number of these precisely-timed NMIs to mount
163
163
an actual attack. There's presumably not enough bandwidth.
164
164
4. The NMI in question occurs after a VERW, i.e. when user state is
165
-
restored and most interesting data is already scrubbed. Whats left
165
+
restored and most interesting data is already scrubbed. What's left
166
166
is only the data that NMI touches, and that may or may not be of
167
167
any interest.
168
168
+2
-2
Documentation/arch/x86/x86_64/fsgs.rst
+2
-2
Documentation/arch/x86/x86_64/fsgs.rst
···
125
125
FSGSBASE instructions compiler support
126
126
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
127
127
128
-
GCC version 4.6.4 and newer provide instrinsics for the FSGSBASE
128
+
GCC version 4.6.4 and newer provide intrinsics for the FSGSBASE
129
129
instructions. Clang 5 supports them as well.
130
130
131
131
=================== ===========================
···
135
135
_writegsbase_u64() Write the GS base register
136
136
=================== ===========================
137
137
138
-
To utilize these instrinsics <immintrin.h> must be included in the source
138
+
To utilize these intrinsics <immintrin.h> must be included in the source
139
139
code and the compiler option -mfsgsbase has to be added.
140
140
141
141
Compiler support for FS/GS based addressing
+11
-11
Documentation/block/bfq-iosched.rst
+11
-11
Documentation/block/bfq-iosched.rst
···
9
9
- BFQ guarantees a high system and application responsiveness, and a
10
10
low latency for time-sensitive applications, such as audio or video
11
11
players;
12
-
- BFQ distributes bandwidth, and not just time, among processes or
12
+
- BFQ distributes bandwidth, not just time, among processes or
13
13
groups (switching back to time distribution when needed to keep
14
14
throughput high).
15
15
···
111
111
112
112
If some additional workload happens to be executed in parallel, then
113
113
BFQ executes the I/O-related components of typical code-development
114
-
tasks (compilation, checkout, merge, ...) much more quickly than CFQ,
114
+
tasks (compilation, checkout, merge, etc.) much more quickly than CFQ,
115
115
NOOP or DEADLINE.
116
116
117
117
High throughput
···
127
127
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
128
128
129
129
BFQ distributes the device throughput, and not just the device time,
130
-
among I/O-bound applications in proportion their weights, with any
130
+
among I/O-bound applications in proportion to their weights, with any
131
131
workload and regardless of the device parameters. From these bandwidth
132
-
guarantees, it is possible to compute tight per-I/O-request delay
132
+
guarantees, it is possible to compute a tight per-I/O-request delay
133
133
guarantees by a simple formula. If not configured for strict service
134
134
guarantees, BFQ switches to time-based resource sharing (only) for
135
135
applications that would otherwise cause a throughput loss.
···
199
199
200
200
- On flash-based storage with internal queueing of commands
201
201
(typically NCQ), device idling happens to be always detrimental
202
-
for throughput. So, with these devices, BFQ performs idling
202
+
to throughput. So, with these devices, BFQ performs idling
203
203
only when strictly needed for service guarantees, i.e., for
204
204
guaranteeing low latency or fairness. In these cases, overall
205
205
throughput may be sub-optimal. No solution currently exists to
···
212
212
and to reduce their latency. The most important action taken to
213
213
achieve this goal is to give to the queues associated with these
214
214
applications more than their fair share of the device
215
-
throughput. For brevity, we call just "weight-raising" the whole
215
+
throughput. For brevity, we call it just "weight-raising" the whole
216
216
sets of actions taken by BFQ to privilege these queues. In
217
217
particular, BFQ provides a milder form of weight-raising for
218
218
interactive applications, and a stronger form for soft real-time
···
231
231
responsive in detecting interleaved I/O (cooperating processes),
232
232
that it enables BFQ to achieve a high throughput, by queue
233
233
merging, even for queues for which CFQ needs a different
234
-
mechanism, preemption, to get a high throughput. As such EQM is a
234
+
mechanism, preemption, to get a high throughput. As such, EQM is a
235
235
unified mechanism to achieve a high throughput with interleaved
236
236
I/O.
237
237
···
254
254
- First, with any proportional-share scheduler, the maximum
255
255
deviation with respect to an ideal service is proportional to
256
256
the maximum budget (slice) assigned to queues. As a consequence,
257
-
BFQ can keep this deviation tight not only because of the
257
+
BFQ can keep this deviation tight, not only because of the
258
258
accurate service of B-WF2Q+, but also because BFQ *does not*
259
259
need to assign a larger budget to a queue to let the queue
260
260
receive a higher fraction of the device throughput.
···
327
327
slice_idle
328
328
----------
329
329
330
-
This parameter specifies how long BFQ should idle for next I/O
330
+
This parameter specifies how long BFQ should idle for the next I/O
331
331
request, when certain sync BFQ queues become empty. By default
332
332
slice_idle is a non-zero value. Idling has a double purpose: boosting
333
333
throughput and making sure that the desired throughput distribution is
···
365
365
order then corresponds to the dispatch order, the strict_guarantees
366
366
tunable must be set too.
367
367
368
-
There is an important flipside for idling: apart from the above cases
368
+
There is an important flip side to idling: apart from the above cases
369
369
where it is beneficial also for throughput, idling can severely impact
370
370
throughput. One important case is random workload. Because of this
371
371
issue, BFQ tends to avoid idling as much as possible, when it is not
···
475
475
476
476
Maximum amount of service, measured in sectors, that can be provided
477
477
to a BFQ queue once it is set in service (of course within the limits
478
-
of the above timeout). According to what said in the description of
478
+
of the above timeout). According to what was said in the description of
479
479
the algorithm, larger values increase the throughput in proportion to
480
480
the percentage of sequential I/O requests issued. The price of larger
481
481
values is that they coarsen the granularity of short-term bandwidth
+3
-2
Documentation/core-api/memory-allocation.rst
+3
-2
Documentation/core-api/memory-allocation.rst
···
45
45
* If the allocation is performed from an atomic context, e.g interrupt
46
46
handler, use ``GFP_NOWAIT``. This flag prevents direct reclaim and
47
47
IO or filesystem operations. Consequently, under memory pressure
48
-
``GFP_NOWAIT`` allocation is likely to fail. Allocations which
49
-
have a reasonable fallback should be using ``GFP_NOWARN``.
48
+
``GFP_NOWAIT`` allocation is likely to fail. Users of this flag need
49
+
to provide a suitable fallback to cope with such failures where
50
+
appropriate.
50
51
* If you think that accessing memory reserves is justified and the kernel
51
52
will be stressed unless allocation succeeds, you may use ``GFP_ATOMIC``.
52
53
* Untrusted allocations triggered from userspace should be a subject
+2
-1
Documentation/dev-tools/kcsan.rst
+2
-1
Documentation/dev-tools/kcsan.rst
···
361
361
-----------------------
362
362
363
363
An alternative data race detection approach for the kernel can be found in the
364
-
`Kernel Thread Sanitizer (KTSAN) <https://github.com/google/ktsan/wiki>`_.
364
+
`Kernel Thread Sanitizer (KTSAN)
365
+
<https://github.com/google/kernel-sanitizers/blob/master/KTSAN.md>`_.
365
366
KTSAN is a happens-before data race detector, which explicitly establishes the
366
367
happens-before order between memory operations, which can then be used to
367
368
determine data races as defined in `Data Races`_.
+54
Documentation/doc-guide/checktransupdate.rst
+54
Documentation/doc-guide/checktransupdate.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
3
+
Checking for needed translation updates
4
+
=======================================
5
+
6
+
This script helps track the translation status of the documentation in
7
+
different locales, i.e., whether the documentation is up-to-date with
8
+
the English counterpart.
9
+
10
+
How it works
11
+
------------
12
+
13
+
It uses ``git log`` command to track the latest English commit from the
14
+
translation commit (order by author date) and the latest English commits
15
+
from HEAD. If any differences occur, the file is considered as out-of-date,
16
+
then commits that need to be updated will be collected and reported.
17
+
18
+
Features implemented
19
+
20
+
- check all files in a certain locale
21
+
- check a single file or a set of files
22
+
- provide options to change output format
23
+
- track the translation status of files that have no translation
24
+
25
+
Usage
26
+
-----
27
+
28
+
::
29
+
30
+
./scripts/checktransupdate.py --help
31
+
32
+
Please refer to the output of argument parser for usage details.
33
+
34
+
Samples
35
+
36
+
- ``./scripts/checktransupdate.py -l zh_CN``
37
+
This will print all the files that need to be updated in the zh_CN locale.
38
+
- ``./scripts/checktransupdate.py Documentation/translations/zh_CN/dev-tools/testing-overview.rst``
39
+
This will only print the status of the specified file.
40
+
41
+
Then the output is something like:
42
+
43
+
::
44
+
45
+
Documentation/dev-tools/kfence.rst
46
+
No translation in the locale of zh_CN
47
+
48
+
Documentation/translations/zh_CN/dev-tools/testing-overview.rst
49
+
commit 42fb9cfd5b18 ("Documentation: dev-tools: Add link to RV docs")
50
+
1 commits needs resolving in total
51
+
52
+
Features to be implemented
53
+
54
+
- files can be a folder instead of only a file
+1
Documentation/doc-guide/index.rst
+1
Documentation/doc-guide/index.rst
+1
-1
Documentation/dontdiff
+1
-1
Documentation/dontdiff
+1
-1
Documentation/driver-api/driver-model/devres.rst
+1
-1
Documentation/driver-api/driver-model/devres.rst
···
391
391
devm_pci_remap_cfgspace() : ioremap PCI configuration space
392
392
devm_pci_remap_cfg_resource() : ioremap PCI configuration space resource
393
393
394
-
pcim_enable_device() : after success, all PCI ops become managed
394
+
pcim_enable_device() : after success, some PCI ops become managed
395
395
pcim_iomap() : do iomap() on a single BAR
396
396
pcim_iomap_regions() : do request_region() and iomap() on multiple BARs
397
397
pcim_iomap_regions_request_all() : do request_region() on all and iomap() on multiple BARs
+4
-4
Documentation/driver-api/iio/buffers.rst
+4
-4
Documentation/driver-api/iio/buffers.rst
···
15
15
IIO buffer sysfs interface
16
16
==========================
17
17
An IIO buffer has an associated attributes directory under
18
-
:file:`/sys/bus/iio/iio:device{X}/buffer/*`. Here are some of the existing
19
-
attributes:
18
+
:file:`/sys/bus/iio/devices/iio:device{X}/buffer/*`. Here are some of the
19
+
existing attributes:
20
20
21
21
* :file:`length`, the total number of data samples (capacity) that can be
22
22
stored by the buffer.
···
28
28
The meta information associated with a channel reading placed in a buffer is
29
29
called a scan element. The important bits configuring scan elements are
30
30
exposed to userspace applications via the
31
-
:file:`/sys/bus/iio/iio:device{X}/scan_elements/` directory. This directory contains
32
-
attributes of the following form:
31
+
:file:`/sys/bus/iio/devices/iio:device{X}/scan_elements/` directory. This
32
+
directory contains attributes of the following form:
33
33
34
34
* :file:`enable`, used for enabling a channel. If and only if its attribute
35
35
is non *zero*, then a triggered capture will contain data samples for this
+7
-7
Documentation/driver-api/iio/core.rst
+7
-7
Documentation/driver-api/iio/core.rst
···
24
24
25
25
There are two ways for a user space application to interact with an IIO driver.
26
26
27
-
1. :file:`/sys/bus/iio/iio:device{X}/`, this represents a hardware sensor
27
+
1. :file:`/sys/bus/iio/devices/iio:device{X}/`, this represents a hardware sensor
28
28
and groups together the data channels of the same chip.
29
29
2. :file:`/dev/iio:device{X}`, character device node interface used for
30
30
buffered data transfer and for events information retrieval.
···
51
51
52
52
Attributes are sysfs files used to expose chip info and also allowing
53
53
applications to set various configuration parameters. For device with
54
-
index X, attributes can be found under /sys/bus/iio/iio:deviceX/ directory.
55
-
Common attributes are:
54
+
index X, attributes can be found under /sys/bus/iio/devices/iio:deviceX/
55
+
directory. Common attributes are:
56
56
57
57
* :file:`name`, description of the physical chip.
58
58
* :file:`dev`, shows the major:minor pair associated with
···
140
140
This channel's definition will generate two separate sysfs files for raw data
141
141
retrieval:
142
142
143
-
* :file:`/sys/bus/iio/iio:device{X}/in_intensity_ir_raw`
144
-
* :file:`/sys/bus/iio/iio:device{X}/in_intensity_both_raw`
143
+
* :file:`/sys/bus/iio/devices/iio:device{X}/in_intensity_ir_raw`
144
+
* :file:`/sys/bus/iio/devices/iio:device{X}/in_intensity_both_raw`
145
145
146
146
one file for processed data:
147
147
148
-
* :file:`/sys/bus/iio/iio:device{X}/in_illuminance_input`
148
+
* :file:`/sys/bus/iio/devices/iio:device{X}/in_illuminance_input`
149
149
150
150
and one shared sysfs file for sampling frequency:
151
151
152
-
* :file:`/sys/bus/iio/iio:device{X}/sampling_frequency`.
152
+
* :file:`/sys/bus/iio/devices/iio:device{X}/sampling_frequency`.
153
153
154
154
Here is how we can make use of the channel's indexing::
155
155
+21
-1
Documentation/fault-injection/fault-injection.rst
+21
-1
Documentation/fault-injection/fault-injection.rst
···
141
141
default is 'Y', setting it to 'N' will also inject failures into
142
142
highmem/user allocations (__GFP_HIGHMEM allocations).
143
143
144
+
- /sys/kernel/debug/failslab/cache-filter
145
+
Format: { 'Y' | 'N' }
146
+
147
+
default is 'N', setting it to 'Y' will only inject failures when
148
+
objects are requests from certain caches.
149
+
150
+
Select the cache by writing '1' to /sys/kernel/slab/<cache>/failslab:
151
+
144
152
- /sys/kernel/debug/failslab/ignore-gfp-wait:
145
153
- /sys/kernel/debug/fail_page_alloc/ignore-gfp-wait:
146
154
···
291
283
There are 4 types of errors defined in include/asm-generic/error-injection.h
292
284
293
285
EI_ETYPE_NULL
294
-
This function will return `NULL` if it fails. e.g. return an allocateed
286
+
This function will return `NULL` if it fails. e.g. return an allocated
295
287
object address.
296
288
297
289
EI_ETYPE_ERRNO
···
466
458
rmdir tmpmnt
467
459
losetup -d $DEVICE
468
460
rm testfile.img
461
+
462
+
------------------------------------------------------------------------------
463
+
464
+
- Inject only skbuff allocation failures ::
465
+
466
+
# mark skbuff_head_cache as faulty
467
+
echo 1 > /sys/kernel/slab/skbuff_head_cache/failslab
468
+
# Turn on cache filter (off by default)
469
+
echo 1 > /sys/kernel/debug/failslab/cache-filter
470
+
# Turn on fault injection
471
+
echo 1 > /sys/kernel/debug/failslab/times
472
+
echo 1 > /sys/kernel/debug/failslab/probability
469
473
470
474
471
475
Tool to run command with failslab or fail_page_alloc
+1
-1
Documentation/filesystems/9p.rst
+1
-1
Documentation/filesystems/9p.rst
···
31
31
* PROSE I/O: Using 9p to enable Application Partitions
32
32
http://plan9.escet.urjc.es/iwp9/cready/PROSE_iwp9_2006.pdf
33
33
* VirtFS: A Virtualization Aware File System pass-through
34
-
http://goo.gl/3WPDg
34
+
https://kernel.org/doc/ols/2010/ols2010-pages-109-120.pdf
35
35
36
36
Usage
37
37
=====
+2
-2
Documentation/filesystems/autofs.rst
+2
-2
Documentation/filesystems/autofs.rst
···
18
18
19
19
2. The names and locations of filesystems can be stored in
20
20
a remote database and can change at any time. The content
21
-
in that data base at the time of access will be used to provide
21
+
in that database at the time of access will be used to provide
22
22
a target for the access. The interpretation of names in the
23
23
filesystem can even be programmatic rather than database-backed,
24
24
allowing wildcards for example, and can vary based on the user who
···
423
423
and objects are expired if the are not in use.
424
424
425
425
**AUTOFS_EXP_FORCED** causes the in use status to be ignored
426
-
and objects are expired ieven if they are in use. This assumes
426
+
and objects are expired even if they are in use. This assumes
427
427
that the daemon has requested this because it is capable of
428
428
performing the umount.
429
429
+3
-3
Documentation/filesystems/journalling.rst
+3
-3
Documentation/filesystems/journalling.rst
···
137
137
138
138
JBD2 to also allows you to perform file-system specific delta commits known as
139
139
fast commits. In order to use fast commits, you will need to set following
140
-
callbacks that perform correspodning work:
140
+
callbacks that perform corresponding work:
141
141
142
142
`journal->j_fc_cleanup_cb`: Cleanup function called after every full commit and
143
143
fast commit.
···
149
149
gets permission from JBD2 to do so by calling the function
150
150
:c:func:`jbd2_fc_begin_commit()`. Once a fast commit is done, the client
151
151
file system should tell JBD2 about it by calling
152
-
:c:func:`jbd2_fc_end_commit()`. If file system wants JBD2 to perform a full
152
+
:c:func:`jbd2_fc_end_commit()`. If the file system wants JBD2 to perform a full
153
153
commit immediately after stopping the fast commit it can do so by calling
154
154
:c:func:`jbd2_fc_end_commit_fallback()`. This is useful if fast commit operation
155
155
fails for some reason and the only way to guarantee consistency is for JBD2 to
···
199
199
.. kernel-doc:: fs/jbd2/recovery.c
200
200
:internal:
201
201
202
-
Transasction Level
202
+
Transaction Level
203
203
~~~~~~~~~~~~~~~~~~
204
204
205
205
.. kernel-doc:: fs/jbd2/transaction.c
+1
-1
Documentation/gpu/komeda-kms.rst
+1
-1
Documentation/gpu/komeda-kms.rst
···
86
86
- Single display mode
87
87
Two pipelines work together to drive only one display output.
88
88
89
-
On this mode, pipeline_B doesn't work indenpendently, but outputs its
89
+
On this mode, pipeline_B doesn't work independently, but outputs its
90
90
composition result into pipeline_A, and its pixel timing also derived from
91
91
pipeline_A.timing_ctrlr. The pipeline_B works just like a "slave" of
92
92
pipeline_A(master)
+1
-1
Documentation/leds/leds-mlxcpld.rst
+1
-1
Documentation/leds/leds-mlxcpld.rst
+5
-5
Documentation/mm/hmm.rst
+5
-5
Documentation/mm/hmm.rst
···
66
66
Finally, with the advance of high level language constructs (in C++ but in
67
67
other languages too) it is now possible for the compiler to leverage GPUs and
68
68
other devices without programmer knowledge. Some compiler identified patterns
69
-
are only do-able with a shared address space. It is also more reasonable to use
69
+
are only doable with a shared address space. It is also more reasonable to use
70
70
a shared address space for all other patterns.
71
71
72
72
···
267
267
code across drivers.
268
268
269
269
Before migrating pages to device private memory, special device private
270
-
``struct page`` need to be created. These will be used as special "swap"
270
+
``struct page`` needs to be created. These will be used as special "swap"
271
271
page table entries so that a CPU process will fault if it tries to access
272
272
a page that has been migrated to device private memory.
273
273
···
322
322
The ``invalidate_range_start()`` callback is passed a
323
323
``struct mmu_notifier_range`` with the ``event`` field set to
324
324
``MMU_NOTIFY_MIGRATE`` and the ``owner`` field set to
325
-
the ``args->pgmap_owner`` field passed to migrate_vma_setup(). This is
325
+
the ``args->pgmap_owner`` field passed to migrate_vma_setup(). This
326
326
allows the device driver to skip the invalidation callback and only
327
327
invalidate device private MMU mappings that are actually migrating.
328
328
This is explained more in the next section.
···
405
405
406
406
This replaces all mappings for pages in the given range with special swap
407
407
entries. Any attempt to access the swap entry results in a fault which is
408
-
resovled by replacing the entry with the original mapping. A driver gets
408
+
resolved by replacing the entry with the original mapping. A driver gets
409
409
notified that the mapping has been changed by MMU notifiers, after which point
410
410
it will no longer have exclusive access to the page. Exclusive access is
411
411
guaranteed to last until the driver drops the page lock and page reference, at
···
431
431
against same memory cgroup a regular page would be accounted to. This does
432
432
simplify migration to and from device memory. This also means that migration
433
433
back from device memory to regular memory cannot fail because it would
434
-
go above memory cgroup limit. We might revisit this choice latter on once we
434
+
go above memory cgroup limit. We might revisit this choice later on once we
435
435
get more experience in how device memory is used and its impact on memory
436
436
resource control.
437
437
+4
-4
Documentation/mm/vmalloced-kernel-stacks.rst
+4
-4
Documentation/mm/vmalloced-kernel-stacks.rst
···
110
110
`kernel/fork.c <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/kernel/fork.c>`.
111
111
112
112
stack_vm_area pointer in task_struct keeps track of the virtually allocated
113
-
stack and a non-null stack_vm_area pointer serves as a indication that the
113
+
stack and a non-null stack_vm_area pointer serves as an indication that the
114
114
virtually mapped kernel stacks are enabled.
115
115
116
116
::
···
120
120
Stack overflow handling
121
121
-----------------------
122
122
123
-
Leading and trailing guard pages help detect stack overflows. When stack
124
-
overflows into the guard pages, handlers have to be careful not overflow
123
+
Leading and trailing guard pages help detect stack overflows. When the stack
124
+
overflows into the guard pages, handlers have to be careful not to overflow
125
125
the stack again. When handlers are called, it is likely that very little
126
126
stack space is left.
127
127
···
148
148
- THREAD_INFO_IN_TASK gets rid of arch-specific thread_info entirely and
149
149
simply embed the thread_info (containing only flags) and 'int cpu' into
150
150
task_struct.
151
-
- The thread stack can be free'ed as soon as the task is dead (without
151
+
- The thread stack can be freed as soon as the task is dead (without
152
152
waiting for RCU) and then, if vmapped stacks are in use, cache the
153
153
entire stack for reuse on the same cpu.
+3
-3
Documentation/nvme/feature-and-quirk-policy.rst
+3
-3
Documentation/nvme/feature-and-quirk-policy.rst
···
1
1
.. SPDX-License-Identifier: GPL-2.0
2
2
3
-
=======================================
4
-
Linux NVMe feature and and quirk policy
5
-
=======================================
3
+
===================================
4
+
Linux NVMe feature and quirk policy
5
+
===================================
6
6
7
7
This file explains the policy used to decide what is supported by the
8
8
Linux NVMe driver and what is not.
+3
-3
Documentation/process/backporting.rst
+3
-3
Documentation/process/backporting.rst
···
73
73
your source tree. Don't forget to cherry-pick with ``-x`` if you want a
74
74
written record of where the patch came from!
75
75
76
-
Note that if you are submiting a patch for stable, the format is
76
+
Note that if you are submitting a patch for stable, the format is
77
77
slightly different; the first line after the subject line needs tobe
78
78
either::
79
79
···
147
147
It's important to always identify the commit or commits that caused the
148
148
conflict, as otherwise you cannot be confident in the correctness of
149
149
your resolution. As an added bonus, especially if the patch is in an
150
-
area you're not that famliar with, the changelogs of these commits will
150
+
area you're not that familiar with, the changelogs of these commits will
151
151
often give you the context to understand the code and potential problems
152
152
or pitfalls with your conflict resolution.
153
153
···
197
197
Another way to find prerequisite commits (albeit only the most recent
198
198
one for a given conflict) is to run ``git blame``. In this case, you
199
199
need to run it against the parent commit of the patch you are
200
-
cherry-picking and the file where the conflict appared, i.e.::
200
+
cherry-picking and the file where the conflict appeared, i.e.::
201
201
202
202
git blame <commit>^ -- <path>
203
203
+1
-1
Documentation/process/coding-style.rst
+1
-1
Documentation/process/coding-style.rst
···
986
986
987
987
A reasonable rule of thumb is to not put inline at functions that have more
988
988
than 3 lines of code in them. An exception to this rule are the cases where
989
-
a parameter is known to be a compiletime constant, and as a result of this
989
+
a parameter is known to be a compile time constant, and as a result of this
990
990
constantness you *know* the compiler will be able to optimize most of your
991
991
function away at compile time. For a good example of this later case, see
992
992
the kmalloc() inline function.
+1
-1
Documentation/process/email-clients.rst
+1
-1
Documentation/process/email-clients.rst
···
216
216
using Mutt to send patches through Gmail::
217
217
218
218
# .muttrc
219
-
# ================ IMAP ====================
219
+
# ================ IMAP ====================
220
220
set imap_user = 'yourusername@gmail.com'
221
221
set imap_pass = 'yourpassword'
222
222
set spoolfile = imaps://imap.gmail.com/INBOX
+1
-1
Documentation/process/maintainer-tip.rst
+1
-1
Documentation/process/maintainer-tip.rst
···
154
154
155
155
We modify the hot cpu handling to cancel the delayed work on the dying
156
156
cpu and run the worker immediately on a different cpu in same domain. We
157
-
donot flush the worker because the MBM overflow worker reschedules the
157
+
do not flush the worker because the MBM overflow worker reschedules the
158
158
worker on same CPU and scans the domain->cpu_mask to get the domain
159
159
pointer.
160
160
+8
Documentation/process/submitting-patches.rst
+8
Documentation/process/submitting-patches.rst
···
842
842
and not in some internal, accessible only to you tree - otherwise it
843
843
would be worthless.
844
844
845
+
Tooling
846
+
-------
847
+
848
+
Many of the technical aspects of this process can be automated using
849
+
b4, documented at <https://b4.docs.kernel.org/en/latest/>. This can
850
+
help with things like tracking dependencies, running checkpatch and
851
+
with formatting and sending mails.
852
+
845
853
References
846
854
----------
847
855
+1
-1
Documentation/scheduler/completion.rst
+1
-1
Documentation/scheduler/completion.rst
+1
Documentation/scheduler/index.rst
+1
Documentation/scheduler/index.rst
+6
-4
Documentation/scheduler/sched-design-CFS.rst
+6
-4
Documentation/scheduler/sched-design-CFS.rst
···
8
8
1. OVERVIEW
9
9
============
10
10
11
-
CFS stands for "Completely Fair Scheduler," and is the new "desktop" process
12
-
scheduler implemented by Ingo Molnar and merged in Linux 2.6.23. It is the
13
-
replacement for the previous vanilla scheduler's SCHED_OTHER interactivity
14
-
code.
11
+
CFS stands for "Completely Fair Scheduler," and is the "desktop" process
12
+
scheduler implemented by Ingo Molnar and merged in Linux 2.6.23. When
13
+
originally merged, it was the replacement for the previous vanilla
14
+
scheduler's SCHED_OTHER interactivity code. Nowadays, CFS is making room
15
+
for EEVDF, for which documentation can be found in
16
+
Documentation/scheduler/sched-eevdf.rst.
15
17
16
18
80% of CFS's design can be summed up in a single sentence: CFS basically models
17
19
an "ideal, precise multi-tasking CPU" on real hardware.
+43
Documentation/scheduler/sched-eevdf.rst
+43
Documentation/scheduler/sched-eevdf.rst
···
1
+
===============
2
+
EEVDF Scheduler
3
+
===============
4
+
5
+
The "Earliest Eligible Virtual Deadline First" (EEVDF) was first introduced
6
+
in a scientific publication in 1995 [1]. The Linux kernel began
7
+
transitioning to EEVDF in version 6.6 (as a new option in 2024), moving
8
+
away from the earlier Completely Fair Scheduler (CFS) in favor of a version
9
+
of EEVDF proposed by Peter Zijlstra in 2023 [2-4]. More information
10
+
regarding CFS can be found in
11
+
Documentation/scheduler/sched-design-CFS.rst.
12
+
13
+
Similarly to CFS, EEVDF aims to distribute CPU time equally among all
14
+
runnable tasks with the same priority. To do so, it assigns a virtual run
15
+
time to each task, creating a "lag" value that can be used to determine
16
+
whether a task has received its fair share of CPU time. In this way, a task
17
+
with a positive lag is owed CPU time, while a negative lag means the task
18
+
has exceeded its portion. EEVDF picks tasks with lag greater or equal to
19
+
zero and calculates a virtual deadline (VD) for each, selecting the task
20
+
with the earliest VD to execute next. It's important to note that this
21
+
allows latency-sensitive tasks with shorter time slices to be prioritized,
22
+
which helps with their responsiveness.
23
+
24
+
There are ongoing discussions on how to manage lag, especially for sleeping
25
+
tasks; but at the time of writing EEVDF uses a "decaying" mechanism based
26
+
on virtual run time (VRT). This prevents tasks from exploiting the system
27
+
by sleeping briefly to reset their negative lag: when a task sleeps, it
28
+
remains on the run queue but marked for "deferred dequeue," allowing its
29
+
lag to decay over VRT. Hence, long-sleeping tasks eventually have their lag
30
+
reset. Finally, tasks can preempt others if their VD is earlier, and tasks
31
+
can request specific time slices using the new sched_setattr() system call,
32
+
which further facilitates the job of latency-sensitive applications.
33
+
34
+
REFERENCES
35
+
==========
36
+
37
+
[1] https://citeseerx.ist.psu.edu/document?repid=rep1&type=pdf&doi=805acf7726282721504c8f00575d91ebfd750564
38
+
39
+
[2] https://lore.kernel.org/lkml/a79014e6-ea83-b316-1e12-2ae056bda6fa@linux.vnet.ibm.com/
40
+
41
+
[3] https://lwn.net/Articles/969062/
42
+
43
+
[4] https://lwn.net/Articles/925371/
+2
Documentation/sphinx/kerneldoc-preamble.sty
+2
Documentation/sphinx/kerneldoc-preamble.sty
···
199
199
% Inactivate CJK after tableofcontents
200
200
\apptocmd{\sphinxtableofcontents}{\kerneldocCJKoff}{}{}
201
201
\xeCJKsetup{CJKspace = true}% For inter-phrase space of Korean TOC
202
+
% Suppress extra white space at latin .. non-latin in literal blocks
203
+
\AtBeginEnvironment{sphinxVerbatim}{\CJKsetecglue{}}
202
204
}{ % Don't enable CJK
203
205
% Custom macros to on/off CJK and switch CJK fonts (Dummy)
204
206
\newcommand{\kerneldocCJKon}{}
+18
Documentation/translations/ko_KR/core-api/wrappers/memory-barriers.rst
+18
Documentation/translations/ko_KR/core-api/wrappers/memory-barriers.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
This is a simple wrapper to bring memory-barriers.txt into the RST world
3
+
until such a time as that file can be converted directly.
4
+
5
+
=========================
6
+
리눅스 커널 메모리 배리어
7
+
=========================
8
+
9
+
.. raw:: latex
10
+
11
+
\footnotesize
12
+
13
+
.. include:: ../../memory-barriers.txt
14
+
:literal:
15
+
16
+
.. raw:: latex
17
+
18
+
\normalsize
Documentation/translations/ko_KR/howto.rst
Documentation/translations/ko_KR/process/howto.rst
Documentation/translations/ko_KR/howto.rst
Documentation/translations/ko_KR/process/howto.rst
+3
-13
Documentation/translations/ko_KR/index.rst
+3
-13
Documentation/translations/ko_KR/index.rst
···
11
11
.. toctree::
12
12
:maxdepth: 1
13
13
14
-
howto
15
-
16
-
17
-
리눅스 커널 메모리 배리어
18
-
-------------------------
14
+
process/howto
15
+
core-api/wrappers/memory-barriers.rst
19
16
20
17
.. raw:: latex
21
18
22
-
\footnotesize
23
-
24
-
.. include:: ./memory-barriers.txt
25
-
:literal:
26
-
27
-
.. raw:: latex
28
-
29
-
}\kerneldocEndKR
19
+
}\kerneldocEndKR
+1
Documentation/translations/sp_SP/scheduler/index.rst
+1
Documentation/translations/sp_SP/scheduler/index.rst
+4
-4
Documentation/translations/sp_SP/scheduler/sched-design-CFS.rst
+4
-4
Documentation/translations/sp_SP/scheduler/sched-design-CFS.rst
···
14
14
15
15
CFS viene de las siglas en inglés de "Gestor de tareas totalmente justo"
16
16
("Completely Fair Scheduler"), y es el nuevo gestor de tareas de escritorio
17
-
implementado por Ingo Molnar e integrado en Linux 2.6.23. Es el sustituto de
18
-
el previo gestor de tareas SCHED_OTHER.
19
-
20
-
Nota: El planificador EEVDF fue incorporado más recientemente al kernel.
17
+
implementado por Ingo Molnar e integrado en Linux 2.6.23. Es el sustituto
18
+
del previo gestor de tareas SCHED_OTHER. Hoy en día se está abriendo camino
19
+
para el gestor de tareas EEVDF, cuya documentación se puede ver en
20
+
Documentation/scheduler/sched-eevdf.rst
21
21
22
22
El 80% del diseño de CFS puede ser resumido en una única frase: CFS
23
23
básicamente modela una "CPU ideal, precisa y multi-tarea" sobre hardware
+58
Documentation/translations/sp_SP/scheduler/sched-eevdf.rst
+58
Documentation/translations/sp_SP/scheduler/sched-eevdf.rst
···
1
+
2
+
.. include:: ../disclaimer-sp.rst
3
+
4
+
:Original: Documentation/scheduler/sched-eevdf.rst
5
+
:Translator: Sergio González Collado <sergio.collado@gmail.com>
6
+
7
+
======================
8
+
Gestor de tareas EEVDF
9
+
======================
10
+
11
+
El gestor de tareas EEVDF, del inglés: "Earliest Eligible Virtual Deadline
12
+
First", fue presentado por primera vez en una publicación científica en
13
+
1995 [1]. El kernel de Linux comenzó a transicionar hacia EEVPF en la
14
+
versión 6.6 (y como una nueva opción en 2024), alejándose del gestor
15
+
de tareas CFS, en favor de una versión de EEVDF propuesta por Peter
16
+
Zijlstra en 2023 [2-4]. Más información relativa a CFS puede encontrarse
17
+
en Documentation/scheduler/sched-design-CFS.rst.
18
+
19
+
De forma parecida a CFS, EEVDF intenta distribuir el tiempo de ejecución
20
+
de la CPU de forma equitativa entre todas las tareas que tengan la misma
21
+
prioridad y puedan ser ejecutables. Para eso, asigna un tiempo de
22
+
ejecución virtual a cada tarea, creando un "retraso" que puede ser usado
23
+
para determinar si una tarea ha recibido su cantidad justa de tiempo
24
+
de ejecución en la CPU. De esta manera, una tarea con un "retraso"
25
+
positivo, es porque se le debe tiempo de ejecución, mientras que una
26
+
con "retraso" negativo implica que la tarea ha excedido su cuota de
27
+
tiempo. EEVDF elige las tareas con un "retraso" mayor igual a cero y
28
+
calcula un tiempo límite de ejecución virtual (VD, del inglés: virtual
29
+
deadline) para cada una, eligiendo la tarea con la VD más próxima para
30
+
ser ejecutada a continuación. Es importante darse cuenta que esto permite
31
+
que la tareas que sean sensibles a la latencia que tengan porciones de
32
+
tiempos de ejecución de CPU más cortos ser priorizadas, lo cual ayuda con
33
+
su menor tiempo de respuesta.
34
+
35
+
Ahora mismo se está discutiendo cómo gestionar esos "retrasos", especialmente
36
+
en tareas que estén en un estado durmiente; pero en el momento en el que
37
+
se escribe este texto EEVDF usa un mecanismo de "decaimiento" basado en el
38
+
tiempo virtual de ejecución (VRT, del inglés: virtual run time). Esto previene
39
+
a las tareas de abusar del sistema simplemente durmiendo brevemente para
40
+
reajustar su retraso negativo: cuando una tarea duerme, esta permanece en
41
+
la cola de ejecución pero marcada para "desencolado diferido", permitiendo
42
+
a su retraso decaer a lo largo de VRT. Por tanto, las tareas que duerman
43
+
por más tiempo eventualmente eliminarán su retraso. Finalmente, las tareas
44
+
pueden adelantarse a otras si su VD es más próximo en el tiempo, y las
45
+
tareas podrán pedir porciones de tiempo específicas con la nueva llamada
46
+
del sistema sched_setattr(), todo esto facilitara el trabajo de las aplicaciones
47
+
que sean sensibles a las latencias.
48
+
49
+
REFERENCIAS
50
+
===========
51
+
52
+
[1] https://citeseerx.ist.psu.edu/document?repid=rep1&type=pdf&doi=805acf7726282721504c8f00575d91ebfd750564
53
+
54
+
[2] https://lore.kernel.org/lkml/a79014e6-ea83-b316-1e12-2ae056bda6fa@linux.vnet.ibm.com/
55
+
56
+
[3] https://lwn.net/Articles/969062/
57
+
58
+
[4] https://lwn.net/Articles/925371/
-1
Documentation/translations/zh_CN/admin-guide/index.rst
-1
Documentation/translations/zh_CN/admin-guide/index.rst
+2
-2
Documentation/translations/zh_CN/admin-guide/reporting-issues.rst
+2
-2
Documentation/translations/zh_CN/admin-guide/reporting-issues.rst
···
300
300
添加到回归跟踪列表中，以确保它不会被忽略。
301
301
302
302
什么是安全问题留给您自己判断。在继续之前，请考虑阅读
303
-
Documentation/translations/zh_CN/admin-guide/security-bugs.rst ，
303
+
Documentation/translations/zh_CN/process/security-bugs.rst ，
304
304
因为它提供了如何最恰当地处理安全问题的额外细节。
305
305
306
306
当发生了完全无法接受的糟糕事情时，此问题就是一个“非常严重的问题”。例如，
···
983
983
报告，请将报告的文本转发到这些地址；但请在报告的顶部加上注释，表明您提交了
984
984
报告，并附上工单链接。
985
985
986
-
更多信息请参见 Documentation/translations/zh_CN/admin-guide/security-bugs.rst 。
986
+
更多信息请参见 Documentation/translations/zh_CN/process/security-bugs.rst 。
987
987
988
988
989
989
发布报告后的责任
+26
-16
Documentation/translations/zh_CN/admin-guide/security-bugs.rst
Documentation/translations/zh_CN/process/security-bugs.rst
+26
-16
Documentation/translations/zh_CN/admin-guide/security-bugs.rst
Documentation/translations/zh_CN/process/security-bugs.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0-or-later
2
+
1
3
.. include:: ../disclaimer-zh_CN.rst
2
4
3
5
:Original: :doc:`../../../process/security-bugs`
···
7
5
:译者:
8
6
9
7
吴想成 Wu XiangCheng <bobwxc@email.cn>
8
+
慕冬亮 Dongliang Mu <dzm91@hust.edu.cn>
10
9
11
10
安全缺陷
12
11
=========
···
20
17
21
18
可以通过电子邮件<security@kernel.org>联系Linux内核安全团队。这是一个安全人员
22
19
的私有列表，他们将帮助验证错误报告并开发和发布修复程序。如果您已经有了一个
23
-
修复，请将其包含在您的报告中，这样可以大大加快进程。安全团队可能会从区域维护
20
+
修复，请将其包含在您的报告中，这样可以大大加快处理进程。安全团队可能会从区域维护
24
21
人员那里获得额外的帮助，以理解和修复安全漏洞。
25
22
26
23
与任何缺陷一样，提供的信息越多，诊断和修复就越容易。如果您不清楚哪些信息有用，
27
24
请查看“Documentation/translations/zh_CN/admin-guide/reporting-issues.rst”中
28
-
概述的步骤。任何利用漏洞的攻击代码都非常有用，未经报告者同意不会对外发布，除
29
-
非已经公开。
25
+
概述的步骤。任何利用漏洞的攻击代码都非常有用，未经报告者同意不会对外发布，
26
+
除非已经公开。
30
27
31
28
请尽可能发送无附件的纯文本电子邮件。如果所有的细节都藏在附件里，那么就很难对
32
29
一个复杂的问题进行上下文引用的讨论。把它想象成一个
···
52
49
换句话说，我们唯一感兴趣的是修复缺陷。提交给安全列表的所有其他资料以及对报告
53
50
的任何后续讨论，即使在解除限制之后，也将永久保密。
54
51
55
-
协调
56
-
------
52
+
与其他团队协调
53
+
--------------
57
54
58
-
对敏感缺陷（例如那些可能导致权限提升的缺陷）的修复可能需要与私有邮件列表
59
-
<linux-distros@vs.openwall.org>进行协调，以便分发供应商做好准备，在公开披露
60
-
上游补丁时发布一个已修复的内核。发行版将需要一些时间来测试建议的补丁，通常
61
-
会要求至少几天的限制，而供应商更新发布更倾向于周二至周四。若合适，安全团队
62
-
可以协助这种协调，或者报告者可以从一开始就包括linux发行版。在这种情况下，请
63
-
记住在电子邮件主题行前面加上“[vs]”，如linux发行版wiki中所述：
64
-
<http://oss-security.openwall.org/wiki/mailing-lists/distros#how-to-use-the-lists>。
55
+
虽然内核安全团队仅关注修复漏洞，但还有其他组织关注修复发行版上的安全问题以及协调
56
+
操作系统厂商的漏洞披露。协调通常由 "linux-distros" 邮件列表处理，而披露则由
57
+
公共 "oss-security" 邮件列表进行。两者紧密关联且被展示在 linux-distros 维基：
58
+
<https://oss-security.openwall.org/wiki/mailing-lists/distros>
59
+
60
+
请注意，这三个列表的各自政策和规则是不同的，因为它们追求不同的目标。内核安全团队
61
+
与其他团队之间的协调很困难，因为对于内核安全团队，保密期（即最大允许天数）是从补丁
62
+
可用时开始，而 "linux-distros" 则从首次发布到列表时开始计算，无论是否存在补丁。
63
+
64
+
因此，内核安全团队强烈建议，作为一位潜在安全问题的报告者，在受影响代码的维护者
65
+
接受补丁之前，且在您阅读上述发行版维基页面并完全理解联系 "linux-distros"
66
+
邮件列表会对您和内核社区施加的要求之前，不要联系 "linux-distros" 邮件列表。
67
+
这也意味着通常情况下不要同时抄送两个邮件列表，除非在协调时有已接受但尚未合并的补丁。
68
+
换句话说，在补丁被接受之前，不要抄送 "linux-distros"；在修复程序被合并之后，
69
+
不要抄送内核安全团队。
65
70
66
71
CVE分配
67
72
--------
68
73
69
-
安全团队通常不分配CVE，我们也不需要它们来进行报告或修复，因为这会使过程不必
70
-
要的复杂化，并可能耽误缺陷处理。如果报告者希望在公开披露之前分配一个CVE编号，
71
-
他们需要联系上述的私有linux-distros列表。当在提供补丁之前已有这样的CVE编号时，
72
-
如报告者愿意，最好在提交消息中提及它。
74
+
安全团队不分配 CVE，同时我们也不需要 CVE 来报告或修复漏洞，因为这会使过程不必要
75
+
的复杂化，并可能延误漏洞处理。如果报告者希望为确认的问题分配一个 CVE 编号，
76
+
可以联系 :doc:`内核 CVE 分配团队 <../process/cve>` 获取。
73
77
74
78
保密协议
75
79
---------
+1
-1
Documentation/translations/zh_CN/dev-tools/index.rst
+1
-1
Documentation/translations/zh_CN/dev-tools/index.rst
+320
Documentation/translations/zh_CN/dev-tools/kcsan.rst
+320
Documentation/translations/zh_CN/dev-tools/kcsan.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
3
+
.. include:: ../disclaimer-zh_CN.rst
4
+
5
+
:Original: Documentation/dev-tools/kcsan.rst
6
+
:Translator: 刘浩阳 Haoyang Liu <tttturtleruss@hust.edu.cn>
7
+
8
+
内核并发消毒剂(KCSAN)
9
+
=====================
10
+
11
+
内核并发消毒剂（KCSAN）是一个动态竞争检测器，依赖编译时插桩，并且使用基于观察
12
+
点的采样方法来检测竞争。KCSAN 的主要目的是检测 `数据竞争`_。
13
+
14
+
使用
15
+
----
16
+
17
+
KCSAN 受 GCC 和 Clang 支持。使用 GCC 需要版本 11 或更高，使用 Clang 也需要
18
+
版本 11 或更高。
19
+
20
+
为了启用 KCSAN，用如下参数配置内核::
21
+
22
+
CONFIG_KCSAN = y
23
+
24
+
KCSAN 提供了几个其他的配置选项来自定义行为（见 ``lib/Kconfig.kcsan`` 中的各自的
25
+
帮助文档以获取更多信息）。
26
+
27
+
错误报告
28
+
~~~~~~~~
29
+
30
+
一个典型数据竞争的报告如下所示::
31
+
32
+
==================================================================
33
+
BUG: KCSAN: data-race in test_kernel_read / test_kernel_write
34
+
35
+
write to 0xffffffffc009a628 of 8 bytes by task 487 on cpu 0:
36
+
test_kernel_write+0x1d/0x30
37
+
access_thread+0x89/0xd0
38
+
kthread+0x23e/0x260
39
+
ret_from_fork+0x22/0x30
40
+
41
+
read to 0xffffffffc009a628 of 8 bytes by task 488 on cpu 6:
42
+
test_kernel_read+0x10/0x20
43
+
access_thread+0x89/0xd0
44
+
kthread+0x23e/0x260
45
+
ret_from_fork+0x22/0x30
46
+
47
+
value changed: 0x00000000000009a6 -> 0x00000000000009b2
48
+
49
+
Reported by Kernel Concurrency Sanitizer on:
50
+
CPU: 6 PID: 488 Comm: access_thread Not tainted 5.12.0-rc2+ #1
51
+
Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.14.0-2 04/01/2014
52
+
==================================================================
53
+
54
+
报告的头部提供了一个关于竞争中涉及到的函数的简短总结。随后是竞争中的两个线程的
55
+
访问类型和堆栈信息。如果 KCSAN 发现了一个值的变化，那么那个值的旧值和新值会在
56
+
“value changed”这一行单独显示。
57
+
58
+
另一个不太常见的数据竞争类型的报告如下所示::
59
+
60
+
==================================================================
61
+
BUG: KCSAN: data-race in test_kernel_rmw_array+0x71/0xd0
62
+
63
+
race at unknown origin, with read to 0xffffffffc009bdb0 of 8 bytes by task 515 on cpu 2:
64
+
test_kernel_rmw_array+0x71/0xd0
65
+
access_thread+0x89/0xd0
66
+
kthread+0x23e/0x260
67
+
ret_from_fork+0x22/0x30
68
+
69
+
value changed: 0x0000000000002328 -> 0x0000000000002329
70
+
71
+
Reported by Kernel Concurrency Sanitizer on:
72
+
CPU: 2 PID: 515 Comm: access_thread Not tainted 5.12.0-rc2+ #1
73
+
Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.14.0-2 04/01/2014
74
+
==================================================================
75
+
76
+
这个报告是当另一个竞争线程不可能被发现，但是可以从观测的内存地址的值改变而推断
77
+
出来的时候生成的。这类报告总是会带有“value changed”行。这类报告的出现通常是因
78
+
为在竞争线程中缺少插桩，也可能是因为其他原因，比如 DMA 访问。这类报告只会在
79
+
设置了内核参数 ``CONFIG_KCSAN_REPORT_RACE_UNKNOWN_ORIGIN=y`` 时才会出现，而这
80
+
个参数是默认启用的。
81
+
82
+
选择性分析
83
+
~~~~~~~~~~
84
+
85
+
对于一些特定的访问，函数，编译单元或者整个子系统，可能需要禁用数据竞争检测。
86
+
对于静态黑名单，有如下可用的参数：
87
+
88
+
* KCSAN 支持使用 ``data_race(expr)`` 注解，这个注解告诉 KCSAN 任何由访问
89
+
``expr`` 所引起的数据竞争都应该被忽略，其产生的行为后果被认为是安全的。请查阅
90
+
`在 LKMM 中 "标记共享内存访问"`_ 获得更多信息。
91
+
92
+
* 与 ``data_race(...)`` 相似，可以使用类型限定符 ``__data_racy`` 来标记一个变量
93
+
，所有访问该变量而导致的数据竞争都是故意为之并且应该被 KCSAN 忽略::
94
+
95
+
struct foo {
96
+
...
97
+
int __data_racy stats_counter;
98
+
...
99
+
};
100
+
101
+
* 使用函数属性 ``__no_kcsan`` 可以对整个函数禁用数据竞争检测::
102
+
103
+
__no_kcsan
104
+
void foo(void) {
105
+
...
106
+
107
+
为了动态限制该为哪些函数生成报告，查阅 `Debug 文件系统接口`_ 黑名单/白名单特性。
108
+
109
+
* 为特定的编译单元禁用数据竞争检测，将下列参数加入到 ``Makefile`` 中::
110
+
111
+
KCSAN_SANITIZE_file.o := n
112
+
113
+
* 为 ``Makefile`` 中的所有编译单元禁用数据竞争检测，将下列参数添加到相应的
114
+
``Makefile`` 中::
115
+
116
+
KCSAN_SANITIZE := n
117
+
118
+
.. _在 LKMM 中 "标记共享内存访问": https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/memory-model/Documentation/access-marking.txt
119
+
120
+
此外，KCSAN 可以根据偏好设置显示或隐藏整个类别的数据竞争。可以使用如下
121
+
Kconfig 参数进行更改:
122
+
123
+
* ``CONFIG_KCSAN_REPORT_VALUE_CHANGE_ONLY``: 如果启用了该参数并且通过观测点
124
+
(watchpoint) 观测到一个有冲突的写操作，但是对应的内存地址中存储的值没有改变，
125
+
则不会报告这起数据竞争。
126
+
127
+
* ``CONFIG_KCSAN_ASSUME_PLAIN_WRITES_ATOMIC``: 假设默认情况下，不超过字大小的简
128
+
单对齐写入操作是原子的。假设这些写入操作不会受到不安全的编译器优化影响，从而导
129
+
致数据竞争。该选项使 KCSAN 不报告仅由不超过字大小的简单对齐写入操作引起
130
+
的冲突所导致的数据竞争。
131
+
132
+
* ``CONFIG_KCSAN_PERMISSIVE``: 启用额外的宽松规则来忽略某些常见类型的数据竞争。
133
+
与上面的规则不同，这条规则更加复杂，涉及到值改变模式，访问类型和地址。这个
134
+
选项依赖编译选项 ``CONFIG_KCSAN_REPORT_VALUE_CHANGE_ONLY=y``。请查看
135
+
``kernel/kcsan/permissive.h`` 获取更多细节。对于只侧重于特定子系统而不是整个
136
+
内核报告的测试者和维护者，建议禁用该选项。
137
+
138
+
要使用尽可能严格的规则，选择 ``CONFIG_KCSAN_STRICT=y``，这将配置 KCSAN 尽可
139
+
能紧密地遵循 Linux 内核内存一致性模型（LKMM）。
140
+
141
+
Debug 文件系统接口
142
+
~~~~~~~~~~~~~~~~~~
143
+
144
+
文件 ``/sys/kernel/debug/kcsan`` 提供了如下接口：
145
+
146
+
* 读 ``/sys/kernel/debug/kcsan`` 返回不同的运行时统计数据。
147
+
148
+
* 将 ``on`` 或 ``off`` 写入 ``/sys/kernel/debug/kcsan`` 允许打开或关闭 KCSAN。
149
+
150
+
* 将 ``!some_func_name`` 写入 ``/sys/kernel/debug/kcsan`` 会将
151
+
``some_func_name`` 添加到报告过滤列表中，该列表（默认）会将数据竞争报告中的顶
152
+
层堆栈帧是列表中函数的情况列入黑名单。
153
+
154
+
* 将 ``blacklist`` 或 ``whitelist`` 写入 ``/sys/kernel/debug/kcsan`` 会改变报告
155
+
过滤行为。例如，黑名单的特性可以用来过滤掉经常发生的数据竞争。白名单特性可以帮
156
+
助复现和修复测试。
157
+
158
+
性能调优
159
+
~~~~~~~~
160
+
161
+
影响 KCSAN 整体的性能和 bug 检测能力的核心参数是作为内核命令行参数公开的，其默认
162
+
值也可以通过相应的 Kconfig 选项更改。
163
+
164
+
* ``kcsan.skip_watch`` (``CONFIG_KCSAN_SKIP_WATCH``): 在另一个观测点设置之前每
165
+
个 CPU 要跳过的内存操作次数。更加频繁的设置观测点将增加观察到竞争情况的可能性
166
+
。这个参数对系统整体的性能和竞争检测能力影响最显著。
167
+
168
+
* ``kcsan.udelay_task`` (``CONFIG_KCSAN_UDELAY_TASK``): 对于任务，观测点设置之
169
+
后暂停执行的微秒延迟。值越大，检测到竞争情况的可能性越高。
170
+
171
+
* ``kcsan.udelay_interrupt`` (``CONFIG_KCSAN_UDELAY_INTERRUPT``): 对于中断，
172
+
观测点设置之后暂停执行的微秒延迟。中断对于延迟的要求更加严格，其延迟通常应该小
173
+
于为任务选择的延迟。
174
+
175
+
它们可以通过 ``/sys/module/kcsan/parameters/`` 在运行时进行调整。
176
+
177
+
数据竞争
178
+
--------
179
+
180
+
在一次执行中，如果两个内存访问存在 *冲突*，在不同的线程中并发执行，并且至少
181
+
有一个访问是 *简单访问*，则它们就形成了 *数据竞争*。如果它们访问了同一个内存地址并且
182
+
至少有一个是写操作，则称它们存在 *冲突*。有关更详细的讨论和定义，见
183
+
`LKMM 中的 "简单访问和数据竞争"`_。
184
+
185
+
.. _LKMM 中的 "简单访问和数据竞争": https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/memory-model/Documentation/explanation.txt#n1922
186
+
187
+
与 Linux 内核内存一致性模型(LKMM)的关系
188
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
189
+
190
+
LKMM 定义了各种内存操作的传播和排序规则，让开发者可以推理并发代码。最终这允许确
191
+
定并发代码可能的执行情况并判断这些代码是否存在数据竞争。
192
+
193
+
KCSAN 可以识别 *被标记的原子操作* （ ``READ_ONCE``, ``WRITE_ONCE`` , ``atomic_*``
194
+
等），以及内存屏障所隐含的一部分顺序保证。启用 ``CONFIG_KCSAN_WEAK_MEMORY=y``
195
+
配置，KCSAN 会对加载或存储缓冲区进行建模，并可以检测遗漏的
196
+
``smp_mb()``, ``smp_wmb()``, ``smp_rmb()``, ``smp_store_release()``，以及所有的
197
+
具有等效隐含内存屏障的 ``atomic_*`` 操作。
198
+
199
+
请注意，KCSAN 不会报告所有由于缺失内存顺序而导致的数据竞争，特别是在需要内存屏障
200
+
来禁止后续内存操作在屏障之前重新排序的情况下。因此，开发人员应该仔细考虑那些未
201
+
被检查的内存顺序要求。
202
+
203
+
数据竞争以外的竞争检测
204
+
---------------------------
205
+
206
+
对于有着复杂并发设计的代码，竞争状况不总是表现为数据竞争。如果并发操作引起了意
207
+
料之外的系统行为，则认为发生了竞争状况。另一方面，数据竞争是在 C 语言层面定义
208
+
的。内核定义了一些宏定义用来检测非数据竞争的漏洞并发代码的属性。
209
+
210
+
.. note::
211
+
为了不引入新的文档编译警告，这里不展示宏定义的具体内容，如果想查看具体
212
+
宏定义可以结合原文（Documentation/dev-tools/kcsan.rst）阅读。
213
+
214
+
实现细节
215
+
--------
216
+
217
+
KCSAN 需要观测两个并发访问。特别重要的是，我们想要（a）增加观测到竞争的机会（尤
218
+
其是很少发生的竞争），以及（b）能够实际观测到这些竞争。我们可以通过（a）注入
219
+
不同的延迟，以及（b）使用地址观测点（或断点）来实现。
220
+
221
+
如果我们在设置了地址观察点的情况下故意延迟一个内存访问，然后观察到观察点被触发
222
+
，那么两个对同一地址的访问就发生了竞争。使用硬件观察点，这是 `DataCollider
223
+
<http://usenix.org/legacy/events/osdi10/tech/full_papers/Erickson.pdf>`_ 中采用
224
+
的方法。与 DataCollider 不同，KCSAN 不使用硬件观察点，而是依赖于编译器插桩和“软
225
+
观测点”。
226
+
227
+
在 KCSAN 中，观察点是通过一种高效的编码实现的，该编码将访问类型、大小和地址存储
228
+
在一个长整型变量中；使用“软观察点”的好处是具有可移植性和更大的灵活性。然后，
229
+
KCSAN依赖于编译器对普通访问的插桩。对于每个插桩的普通访问：
230
+
231
+
1. 检测是否存在一个符合的观测点，如果存在，并且至少有一个操作是写操作，则我们发
232
+
现了一个竞争访问。
233
+
234
+
2. 如果不存在匹配的观察点，则定期的设置一个观测点并随机延迟一小段时间。
235
+
236
+
3. 在延迟前检查数据值，并在延迟后重新检查数据值；如果值不匹配，我们推测存在一个
237
+
未知来源的竞争状况。
238
+
239
+
为了检测普通访问和标记访问之间的数据竞争，KCSAN 也对标记访问进行标记，但仅用于
240
+
检查是否存在观察点；即 KCSAN 不会在标记访问上设置观察点。通过不在标记操作上设
241
+
置观察点，如果对一个变量的所有并发访问都被正确标记，KCSAN 将永远不会触发观察点
242
+
，因此也不会报告这些访问。
243
+
244
+
弱内存建模
245
+
~~~~~~~~~~
246
+
247
+
KCSAN 通过建模访问重新排序（使用 ``CONFIG_KCSAN_WEAK_MEMORY=y``）来检测由于缺少
248
+
内存屏障而导致的数据竞争。每个设置了观察点的普通内存访问也会被选择在其函数范围
249
+
内进行模拟重新排序（最多一个正在进行的访问）。
250
+
251
+
一旦某个访问被选择用于重新排序，它将在函数范围内与每个其他访问进行检查。如果遇
252
+
到适当的内存屏障，该访问将不再被考虑进行模拟重新排序。
253
+
254
+
当内存操作的结果应该由屏障排序时，KCSAN 可以检测到仅由于缺失屏障而导致的冲突的
255
+
数据竞争。考虑下面的例子::
256
+
257
+
int x, flag;
258
+
void T1(void)
259
+
{
260
+
x = 1; // data race!
261
+
WRITE_ONCE(flag, 1); // correct: smp_store_release(&flag, 1)
262
+
}
263
+
void T2(void)
264
+
{
265
+
while (!READ_ONCE(flag)); // correct: smp_load_acquire(&flag)
266
+
... = x; // data race!
267
+
}
268
+
269
+
当启用了弱内存建模，KCSAN 将考虑对 ``T1`` 中的 ``x`` 进行模拟重新排序。在写入
270
+
``flag`` 之后，x再次被检查是否有并发访问：因为 ``T2`` 可以在写入
271
+
``flag`` 之后继续进行，因此检测到数据竞争。如果遇到了正确的屏障， ``x`` 在正确
272
+
释放 ``flag`` 后将不会被考虑重新排序，因此不会检测到数据竞争。
273
+
274
+
在复杂性上的权衡以及实际的限制意味着只能检测到一部分由于缺失内存屏障而导致的数
275
+
据竞争。由于当前可用的编译器支持，KCSAN 的实现仅限于建模“缓冲”（延迟访问）的
276
+
效果，因为运行时不能“预取”访问。同时要注意，观测点只设置在普通访问上，这是唯
277
+
一一个 KCSAN 会模拟重新排序的访问类型。这意味着标记访问的重新排序不会被建模。
278
+
279
+
上述情况的一个后果是获取 (acquire) 操作不需要屏障插桩（不需要预取）。此外，引
280
+
入地址或控制依赖的标记访问不需要特殊处理（标记访问不能重新排序，后续依赖的访问
281
+
不能被预取）。
282
+
283
+
关键属性
284
+
~~~~~~~~
285
+
286
+
1. **内存开销**：整体的内存开销只有几 MiB，取决于配置。当前的实现是使用一个小长
287
+
整型数组来编码观测点信息，几乎可以忽略不计。
288
+
289
+
2. **性能开销**：KCSAN 的运行时旨在性能开销最小化，使用一个高效的观测点编码，在
290
+
快速路径中不需要获取任何锁。在拥有 8 个 CPU 的系统上的内核启动来说：
291
+
292
+
- 使用默认 KCSAN 配置时，性能下降 5 倍；
293
+
- 仅因运行时快速路径开销导致性能下降 2.8 倍（设置非常大的
294
+
``KCSAN_SKIP_WATCH`` 并取消设置 ``KCSAN_SKIP_WATCH_RANDOMIZE``）。
295
+
296
+
3. **注解开销**：KCSAN 运行时之外需要的注释很少。因此，随着内核的发展维护的开
297
+
销也很小。
298
+
299
+
4. **检测设备的竞争写入**：由于设置观测点时会检查数据值，设备的竞争写入也可以
300
+
被检测到。
301
+
302
+
5. **内存排序**：KCSAN 只了解一部分 LKMM 排序规则；这可能会导致漏报数据竞争（
303
+
假阴性）。
304
+
305
+
6. **分析准确率**： 对于观察到的执行，由于使用采样策略，分析是 *不健全* 的
306
+
（可能有假阴性），但期望得到完整的分析（没有假阳性）。
307
+
308
+
考虑的替代方案
309
+
--------------
310
+
311
+
一个内核数据竞争检测的替代方法是 `Kernel Thread Sanitizer (KTSAN)
312
+
<https://github.com/google/kernel-sanitizers/blob/master/KTSAN.md>`_。KTSAN 是一
313
+
个基于先行发生关系（happens-before）的数据竞争检测器，它显式建立内存操作之间的先
314
+
后发生顺序，这可以用来确定 `数据竞争`_ 中定义的数据竞争。
315
+
316
+
为了建立正确的先行发生关系，KTSAN 必须了解 LKMM 的所有排序规则和同步原语。不幸
317
+
的是，任何遗漏都会导致大量的假阳性，这在包含众多自定义同步机制的内核上下文中特
318
+
别有害。为了跟踪前因后果关系，KTSAN 的实现需要为每个内存位置提供元数据（影子内
319
+
存），这意味着每页内存对应 4 页影子内存，在大型系统上可能会带来数十 GiB 的开销
320
+
。
+55
Documentation/translations/zh_CN/doc-guide/checktransupdate.rst
+55
Documentation/translations/zh_CN/doc-guide/checktransupdate.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
3
+
.. include:: ../disclaimer-zh_CN.rst
4
+
5
+
:Original: Documentation/doc-guide/checktransupdate.rst
6
+
7
+
:译者: 慕冬亮 Dongliang Mu <dzm91@hust.edu.cn>
8
+
9
+
检查翻译更新
10
+
11
+
这个脚本帮助跟踪不同语言的文档翻译状态，即文档是否与对应的英文版本保持更新。
12
+
13
+
工作原理
14
+
------------
15
+
16
+
它使用 ``git log`` 命令来跟踪翻译提交的最新英文提交（按作者日期排序）和英文文档的
17
+
最新提交。如果有任何差异，则该文件被认为是过期的，然后需要更新的提交将被收集并报告。
18
+
19
+
实现的功能
20
+
21
+
- 检查特定语言中的所有文件
22
+
- 检查单个文件或一组文件
23
+
- 提供更改输出格式的选项
24
+
- 跟踪没有翻译过的文件的翻译状态
25
+
26
+
用法
27
+
-----
28
+
29
+
::
30
+
31
+
./scripts/checktransupdate.py --help
32
+
33
+
具体用法请参考参数解析器的输出
34
+
35
+
示例
36
+
37
+
- ``./scripts/checktransupdate.py -l zh_CN``
38
+
这将打印 zh_CN 语言中需要更新的所有文件。
39
+
- ``./scripts/checktransupdate.py Documentation/translations/zh_CN/dev-tools/testing-overview.rst``
40
+
这将只打印指定文件的状态。
41
+
42
+
然后输出类似如下的内容：
43
+
44
+
::
45
+
46
+
Documentation/dev-tools/kfence.rst
47
+
No translation in the locale of zh_CN
48
+
49
+
Documentation/translations/zh_CN/dev-tools/testing-overview.rst
50
+
commit 42fb9cfd5b18 ("Documentation: dev-tools: Add link to RV docs")
51
+
1 commits needs resolving in total
52
+
53
+
待实现的功能
54
+
55
+
- 文件参数可以是文件夹而不仅仅是单个文件
+1
Documentation/translations/zh_CN/doc-guide/index.rst
+1
Documentation/translations/zh_CN/doc-guide/index.rst
+1
-1
Documentation/translations/zh_CN/index.rst
+1
-1
Documentation/translations/zh_CN/index.rst
+126
Documentation/translations/zh_CN/kbuild/gcc-plugins.rst
+126
Documentation/translations/zh_CN/kbuild/gcc-plugins.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
3
+
.. include:: ../disclaimer-zh_CN.rst
4
+
5
+
:Original: Documentation/kbuild/gcc-plugins.rst
6
+
:Translator: 慕冬亮 Dongliang Mu <dzm91@hust.edu.cn>
7
+
8
+
================
9
+
GCC 插件基础设施
10
+
================
11
+
12
+
13
+
介绍
14
+
====
15
+
16
+
GCC 插件是为编译器提供额外功能的可加载模块 [1]_。它们对于运行时插装和静态分析非常有用。
17
+
我们可以在编译过程中通过回调 [2]_，GIMPLE [3]_，IPA [4]_ 和 RTL Passes [5]_
18
+
（译者注：Pass 是编译器所采用的一种结构化技术，用于完成编译对象的分析、优化或转换等功能）
19
+
来分析、修改和添加更多的代码。
20
+
21
+
内核的 GCC 插件基础设施支持构建树外模块、交叉编译和在单独的目录中构建。插件源文件必须由
22
+
C++ 编译器编译。
23
+
24
+
目前 GCC 插件基础设施只支持一些架构。搜索 "select HAVE_GCC_PLUGINS" 来查找支持
25
+
GCC 插件的架构。
26
+
27
+
这个基础设施是从 grsecurity [6]_ 和 PaX [7]_ 移植过来的。
28
+
29
+
--
30
+
31
+
.. [1] https://gcc.gnu.org/onlinedocs/gccint/Plugins.html
32
+
.. [2] https://gcc.gnu.org/onlinedocs/gccint/Plugin-API.html#Plugin-API
33
+
.. [3] https://gcc.gnu.org/onlinedocs/gccint/GIMPLE.html
34
+
.. [4] https://gcc.gnu.org/onlinedocs/gccint/IPA.html
35
+
.. [5] https://gcc.gnu.org/onlinedocs/gccint/RTL.html
36
+
.. [6] https://grsecurity.net/
37
+
.. [7] https://pax.grsecurity.net/
38
+
39
+
40
+
目的
41
+
====
42
+
43
+
GCC 插件的设计目的是提供一个用于试验 GCC 或 Clang 上游没有的潜在编译器功能的场所。
44
+
一旦它们的实用性得到验证，这些功能将被添加到 GCC（和 Clang）的上游。随后，在所有
45
+
支持的 GCC 版本都支持这些功能后，它们会被从内核中移除。
46
+
47
+
具体来说，新插件应该只实现上游编译器（GCC 和 Clang）不支持的功能。
48
+
49
+
当 Clang 中存在 GCC 中不存在的某项功能时，应努力将该功能做到 GCC 上游（而不仅仅
50
+
是作为内核专用的 GCC 插件），以使整个生态都能从中受益。
51
+
52
+
类似的，如果 GCC 插件提供的功能在 Clang 中 **不** 存在，但该功能被证明是有用的，也应
53
+
努力将该功能上传到 GCC（和 Clang）。
54
+
55
+
在上游 GCC 提供了某项功能后，该插件将无法在相应的 GCC 版本（以及更高版本）下编译。
56
+
一旦所有内核支持的 GCC 版本都提供了该功能，该插件将从内核中移除。
57
+
58
+
59
+
文件
60
+
====
61
+
62
+
**$(src)/scripts/gcc-plugins**
63
+
64
+
这是 GCC 插件的目录。
65
+
66
+
**$(src)/scripts/gcc-plugins/gcc-common.h**
67
+
68
+
这是 GCC 插件的兼容性头文件。
69
+
应始终包含它，而不是单独的 GCC 头文件。
70
+
71
+
**$(src)/scripts/gcc-plugins/gcc-generate-gimple-pass.h,
72
+
$(src)/scripts/gcc-plugins/gcc-generate-ipa-pass.h,
73
+
$(src)/scripts/gcc-plugins/gcc-generate-simple_ipa-pass.h,
74
+
$(src)/scripts/gcc-plugins/gcc-generate-rtl-pass.h**
75
+
76
+
这些头文件可以自动生成 GIMPLE、SIMPLE_IPA、IPA 和 RTL passes 的注册结构。
77
+
与手动创建结构相比，它们更受欢迎。
78
+
79
+
80
+
用法
81
+
====
82
+
83
+
你必须为你的 GCC 版本安装 GCC 插件头文件，以 Ubuntu 上的 gcc-10 为例::
84
+
85
+
apt-get install gcc-10-plugin-dev
86
+
87
+
或者在 Fedora 上::
88
+
89
+
dnf install gcc-plugin-devel libmpc-devel
90
+
91
+
或者在 Fedora 上使用包含插件的交叉编译器时::
92
+
93
+
dnf install libmpc-devel
94
+
95
+
在内核配置中启用 GCC 插件基础设施与一些你想使用的插件::
96
+
97
+
CONFIG_GCC_PLUGINS=y
98
+
CONFIG_GCC_PLUGIN_LATENT_ENTROPY=y
99
+
...
100
+
101
+
运行 gcc（本地或交叉编译器），确保能够检测到插件头文件::
102
+
103
+
gcc -print-file-name=plugin
104
+
CROSS_COMPILE=arm-linux-gnu- ${CROSS_COMPILE}gcc -print-file-name=plugin
105
+
106
+
"plugin" 这个词意味着它们没有被检测到::
107
+
108
+
plugin
109
+
110
+
完整的路径则表示插件已经被检测到::
111
+
112
+
/usr/lib/gcc/x86_64-redhat-linux/12/plugin
113
+
114
+
编译包括插件在内的最小工具集::
115
+
116
+
make scripts
117
+
118
+
或者直接在内核中运行 make，使用循环复杂性 GCC 插件编译整个内核。
119
+
120
+
121
+
4. 如何添加新的 GCC 插件
122
+
========================
123
+
124
+
GCC 插件位于 scripts/gcc-plugins/。你需要将插件源文件放在 scripts/gcc-plugins/ 目录下。
125
+
子目录创建并不支持，你必须添加在 scripts/gcc-plugins/Makefile、scripts/Makefile.gcc-plugins
126
+
和相关的 Kconfig 文件中。
+39
Documentation/translations/zh_CN/kbuild/headers_install.rst
+39
Documentation/translations/zh_CN/kbuild/headers_install.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
3
+
.. include:: ../disclaimer-zh_CN.rst
4
+
5
+
:Original: Documentation/kbuild/headers_install.rst
6
+
:Translator: 慕冬亮 Dongliang Mu <dzm91@hust.edu.cn>
7
+
8
+
============================
9
+
导出内核头文件供用户空间使用
10
+
============================
11
+
12
+
"make headers_install" 命令以适合于用户空间程序的形式导出内核头文件。
13
+
14
+
Linux 内核导出的头文件描述了用户空间程序尝试使用内核服务的 API。这些内核
15
+
头文件被系统的 C 库（例如 glibc 和 uClibc）用于定义可用的系统调用，以及
16
+
与这些系统调用一起使用的常量和结构。C 库的头文件包括来自 linux 子目录的
17
+
内核头文件。系统的 libc 头文件通常被安装在默认位置 /usr/include，而内核
18
+
头文件在该位置的子目录中（主要是 /usr/include/linux 和 /usr/include/asm）。
19
+
20
+
内核头文件向后兼容，但不向前兼容。这意味着使用旧内核头文件的 C 库构建的程序
21
+
可以在新内核上运行（尽管它可能无法访问新特性），但使用新内核头文件构建的程序
22
+
可能无法在旧内核上运行。
23
+
24
+
"make headers_install" 命令可以在内核源代码的顶层目录中运行（或使用标准
25
+
的树外构建）。它接受两个可选参数::
26
+
27
+
make headers_install ARCH=i386 INSTALL_HDR_PATH=/usr
28
+
29
+
ARCH 表明为其生成头文件的架构，默认为当前架构。导出内核头文件的 linux/asm
30
+
目录是基于特定平台的，要查看支持架构的完整列表，使用以下命令::
31
+
32
+
ls -d include/asm-* | sed 's/.*-//'
33
+
34
+
INSTALL_HDR_PATH 表明头文件的安装位置，默认为 "./usr"。
35
+
36
+
该命令会在 INSTALL_HDR_PATH 中自动创建创建一个 'include' 目录，而头文件
37
+
会被安装在 INSTALL_HDR_PATH/include 中。
38
+
39
+
内核头文件导出的基础设施由 David Woodhouse <dwmw2@infradead.org> 维护。
+35
Documentation/translations/zh_CN/kbuild/index.rst
+35
Documentation/translations/zh_CN/kbuild/index.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
3
+
.. include:: ../disclaimer-zh_CN.rst
4
+
5
+
:Original: Documentation/kbuild/index.rst
6
+
:Translator: 慕冬亮 Dongliang Mu <dzm91@hust.edu.cn>
7
+
8
+
============
9
+
内核编译系统
10
+
============
11
+
12
+
.. toctree::
13
+
:maxdepth: 1
14
+
15
+
headers_install
16
+
gcc-plugins
17
+
18
+
TODO:
19
+
20
+
- kconfig-language
21
+
- kconfig-macro-language
22
+
- kbuild
23
+
- kconfig
24
+
- makefiles
25
+
- modules
26
+
- issues
27
+
- reproducible-builds
28
+
- llvm
29
+
30
+
.. only:: subproject and html
31
+
32
+
目录
33
+
=====
34
+
35
+
* :ref:`genindex`
+2
-1
Documentation/translations/zh_CN/process/index.rst
+2
-1
Documentation/translations/zh_CN/process/index.rst
+1
-1
Documentation/translations/zh_CN/process/submitting-patches.rst
+1
-1
Documentation/translations/zh_CN/process/submitting-patches.rst
···
208
208
如果您有修复可利用安全漏洞的补丁，请将该补丁发送到 security@kernel.org 。对于
209
209
严重的bug，可以考虑短期禁令以允许分销商（有时间）向用户发布补丁；在这种情况下，
210
210
显然不应将补丁发送到任何公共列表。
211
-
参见 Documentation/translations/zh_CN/admin-guide/security-bugs.rst 。
211
+
参见 Documentation/translations/zh_CN/process/security-bugs.rst 。
212
212
213
213
修复已发布内核中严重错误的补丁程序应该抄送给稳定版维护人员，方法是把以下列行
214
214
放进补丁的签准区（注意，不是电子邮件收件人）::
+2
-2
Documentation/translations/zh_TW/admin-guide/reporting-issues.rst
+2
-2
Documentation/translations/zh_TW/admin-guide/reporting-issues.rst
···
301
301
添加到迴歸跟蹤列表中，以確保它不會被忽略。
302
302
303
303
什麼是安全問題留給您自己判斷。在繼續之前，請考慮閱讀
304
-
Documentation/translations/zh_CN/admin-guide/security-bugs.rst ，
304
+
Documentation/translations/zh_CN/process/security-bugs.rst ，
305
305
因爲它提供瞭如何最恰當地處理安全問題的額外細節。
306
306
307
307
當發生了完全無法接受的糟糕事情時，此問題就是一個“非常嚴重的問題”。例如，
···
984
984
報告，請將報告的文本轉發到這些地址；但請在報告的頂部加上註釋，表明您提交了
985
985
報告，並附上工單鏈接。
986
986
987
-
更多信息請參見 Documentation/translations/zh_CN/admin-guide/security-bugs.rst 。
987
+
更多信息請參見 Documentation/translations/zh_CN/process/security-bugs.rst 。
988
988
989
989
990
990
發佈報告後的責任
+1
-1
Documentation/translations/zh_TW/process/submitting-patches.rst
+1
-1
Documentation/translations/zh_TW/process/submitting-patches.rst
···
209
209
如果您有修復可利用安全漏洞的補丁，請將該補丁發送到 security@kernel.org 。對於
210
210
嚴重的bug，可以考慮短期禁令以允許分銷商（有時間）向用戶發佈補丁；在這種情況下，
211
211
顯然不應將補丁發送到任何公共列表。
212
-
參見 Documentation/translations/zh_CN/admin-guide/security-bugs.rst 。
212
+
參見 Documentation/translations/zh_CN/process/security-bugs.rst 。
213
213
214
214
修復已發佈內核中嚴重錯誤的補丁程序應該抄送給穩定版維護人員，方法是把以下列行
215
215
放進補丁的籤準區（注意，不是電子郵件收件人）::
+2
Documentation/userspace-api/ioctl/ioctl-number.rst
+2
Documentation/userspace-api/ioctl/ioctl-number.rst
···
78
78
0x03 all linux/hdreg.h
79
79
0x04 D2-DC linux/umsdos_fs.h Dead since 2.6.11, but don't reuse these.
80
80
0x06 all linux/lp.h
81
+
0x07 9F-D0 linux/vmw_vmci_defs.h, uapi/linux/vm_sockets.h
81
82
0x09 all linux/raid/md_u.h
82
83
0x10 00-0F drivers/char/s390/vmcp.h
83
84
0x10 10-1F arch/s390/include/uapi/sclp_ctl.h
···
293
292
't' 80-8F linux/isdn_ppp.h
294
293
't' 90-91 linux/toshiba.h toshiba and toshiba_acpi SMM
295
294
'u' 00-1F linux/smb_fs.h gone
295
+
'u' 00-2F linux/ublk_cmd.h conflict!
296
296
'u' 20-3F linux/uvcvideo.h USB video class host driver
297
297
'u' 40-4f linux/udmabuf.h userspace dma-buf misc device
298
298
'v' 00-1F linux/ext2_fs.h conflict!
+1
Documentation/virt/kvm/index.rst
+1
Documentation/virt/kvm/index.rst
+89
Documentation/virt/kvm/loongarch/hypercalls.rst
+89
Documentation/virt/kvm/loongarch/hypercalls.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
3
+
===================================
4
+
The LoongArch paravirtual interface
5
+
===================================
6
+
7
+
KVM hypercalls use the HVCL instruction with code 0x100 and the hypercall
8
+
number is put in a0. Up to five arguments may be placed in registers a1 - a5.
9
+
The return value is placed in v0 (an alias of a0).
10
+
11
+
Source code for this interface can be found in arch/loongarch/kvm*.
12
+
13
+
Querying for existence
14
+
======================
15
+
16
+
To determine if the host is running on KVM, we can utilize the cpucfg()
17
+
function at index CPUCFG_KVM_BASE (0x40000000).
18
+
19
+
The CPUCFG_KVM_BASE range, spanning from 0x40000000 to 0x400000FF, The
20
+
CPUCFG_KVM_BASE range between 0x40000000 - 0x400000FF is marked as reserved.
21
+
Consequently, all current and future processors will not implement any
22
+
feature within this range.
23
+
24
+
On a KVM-virtualized Linux system, a read operation on cpucfg() at index
25
+
CPUCFG_KVM_BASE (0x40000000) returns the magic string 'KVM\0'.
26
+
27
+
Once you have determined that your host is running on a paravirtualization-
28
+
capable KVM, you may now use hypercalls as described below.
29
+
30
+
KVM hypercall ABI
31
+
=================
32
+
33
+
The KVM hypercall ABI is simple, with one scratch register a0 (v0) and at most
34
+
five generic registers (a1 - a5) used as input parameters. The FP (Floating-
35
+
point) and vector registers are not utilized as input registers and must
36
+
remain unmodified during a hypercall.
37
+
38
+
Hypercall functions can be inlined as it only uses one scratch register.
39
+
40
+
The parameters are as follows:
41
+
42
+
======== ================= ================
43
+
Register IN OUT
44
+
======== ================= ================
45
+
a0 function number Return code
46
+
a1 1st parameter -
47
+
a2 2nd parameter -
48
+
a3 3rd parameter -
49
+
a4 4th parameter -
50
+
a5 5th parameter -
51
+
======== ================= ================
52
+
53
+
The return codes may be one of the following:
54
+
55
+
==== =========================
56
+
Code Meaning
57
+
==== =========================
58
+
0 Success
59
+
-1 Hypercall not implemented
60
+
-2 Bad Hypercall parameter
61
+
==== =========================
62
+
63
+
KVM Hypercalls Documentation
64
+
============================
65
+
66
+
The template for each hypercall is as follows:
67
+
68
+
1. Hypercall name
69
+
2. Purpose
70
+
71
+
1. KVM_HCALL_FUNC_IPI
72
+
------------------------
73
+
74
+
:Purpose: Send IPIs to multiple vCPUs.
75
+
76
+
- a0: KVM_HCALL_FUNC_IPI
77
+
- a1: Lower part of the bitmap for destination physical CPUIDs
78
+
- a2: Higher part of the bitmap for destination physical CPUIDs
79
+
- a3: The lowest physical CPUID in the bitmap
80
+
81
+
The hypercall lets a guest send multiple IPIs (Inter-Process Interrupts) with
82
+
at most 128 destinations per hypercall. The destinations are represented in a
83
+
bitmap contained in the first two input registers (a1 and a2).
84
+
85
+
Bit 0 of a1 corresponds to the physical CPUID in the third input register (a3)
86
+
and bit 1 corresponds to the physical CPUID in a3+1, and so on.
87
+
88
+
PV IPI on LoongArch includes both PV IPI multicast sending and PV IPI receiving,
89
+
and SWI is used for PV IPI inject since there is no VM-exits accessing SWI registers.
+10
Documentation/virt/kvm/loongarch/index.rst
+10
Documentation/virt/kvm/loongarch/index.rst
+1
-1
Documentation/watchdog/watchdog-api.rst
+1
-1
Documentation/watchdog/watchdog-api.rst
···
249
249
support the GETBOOTSTATUS call.
250
250
251
251
Some drivers can measure the temperature using the GETTEMP ioctl. The
252
-
returned value is the temperature in degrees fahrenheit::
252
+
returned value is the temperature in degrees Fahrenheit::
253
253
254
254
int temperature;
255
255
ioctl(fd, WDIOC_GETTEMP, &temperature);
+3
MAINTAINERS
+3
MAINTAINERS
···
6753
6753
M: Jonathan Corbet <corbet@lwn.net>
6754
6754
L: workflows@vger.kernel.org
6755
6755
S: Maintained
6756
+
F: Documentation/dev-tools/
6756
6757
F: Documentation/maintainer/
6757
6758
F: Documentation/process/
6758
6759
···
6761
6760
M: Thorsten Leemhuis <linux@leemhuis.info>
6762
6761
L: linux-doc@vger.kernel.org
6763
6762
S: Maintained
6763
+
F: Documentation/admin-guide/bug-bisect.rst
6764
6764
F: Documentation/admin-guide/quickly-build-trimmed-linux.rst
6765
6765
F: Documentation/admin-guide/reporting-issues.rst
6766
6766
F: Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst
···
12362
12360
L: loongarch@lists.linux.dev
12363
12361
S: Maintained
12364
12362
T: git git://git.kernel.org/pub/scm/virt/kvm/kvm.git
12363
+
F: Documentation/virt/kvm/loongarch/
12365
12364
F: arch/loongarch/include/asm/kvm*
12366
12365
F: arch/loongarch/include/uapi/asm/kvm*
12367
12366
F: arch/loongarch/kvm/
+140
-72
scripts/checktransupdate.py
+140
-72
scripts/checktransupdate.py
···
10
10
11
11
The usage is as follows:
12
12
- ./scripts/checktransupdate.py -l zh_CN
13
-
This will print all the files that need to be updated in the zh_CN locale.
13
+
This will print all the files that need to be updated or translated in the zh_CN locale.
14
14
- ./scripts/checktransupdate.py Documentation/translations/zh_CN/dev-tools/testing-overview.rst
15
15
This will only print the status of the specified file.
16
16
17
17
The output is something like:
18
-
Documentation/translations/zh_CN/dev-tools/testing-overview.rst (1 commits)
18
+
Documentation/dev-tools/kfence.rst
19
+
No translation in the locale of zh_CN
20
+
21
+
Documentation/translations/zh_CN/dev-tools/testing-overview.rst
19
22
commit 42fb9cfd5b18 ("Documentation: dev-tools: Add link to RV docs")
23
+
1 commits needs resolving in total
20
24
"""
21
25
22
26
import os
23
-
from argparse import ArgumentParser, BooleanOptionalAction
27
+
import time
28
+
import logging
29
+
from argparse import ArgumentParser, ArgumentTypeError, BooleanOptionalAction
24
30
from datetime import datetime
25
-
26
-
flag_p_c = False
27
-
flag_p_uf = False
28
-
flag_debug = False
29
-
30
-
31
-
def dprint(*args, **kwargs):
32
-
if flag_debug:
33
-
print("[DEBUG] ", end="")
34
-
print(*args, **kwargs)
35
31
36
32
37
33
def get_origin_path(file_path):
34
+
"""Get the origin path from the translation path"""
38
35
paths = file_path.split("/")
39
36
tidx = paths.index("translations")
40
37
opaths = paths[:tidx]
···
40
43
41
44
42
45
def get_latest_commit_from(file_path, commit):
43
-
command = "git log --pretty=format:%H%n%aD%n%cD%n%n%B {} -1 -- {}".format(
44
-
commit, file_path
45
-
)
46
-
dprint(command)
46
+
"""Get the latest commit from the specified commit for the specified file"""
47
+
command = f"git log --pretty=format:%H%n%aD%n%cD%n%n%B {commit} -1 -- {file_path}"
48
+
logging.debug(command)
47
49
pipe = os.popen(command)
48
50
result = pipe.read()
49
51
result = result.split("\n")
50
52
if len(result) <= 1:
51
53
return None
52
54
53
-
dprint("Result: {}".format(result[0]))
55
+
logging.debug("Result: %s", result[0])
54
56
55
57
return {
56
58
"hash": result[0],
···
60
64
61
65
62
66
def get_origin_from_trans(origin_path, t_from_head):
67
+
"""Get the latest origin commit from the translation commit"""
63
68
o_from_t = get_latest_commit_from(origin_path, t_from_head["hash"])
64
69
while o_from_t is not None and o_from_t["author_date"] > t_from_head["author_date"]:
65
70
o_from_t = get_latest_commit_from(origin_path, o_from_t["hash"] + "^")
66
71
if o_from_t is not None:
67
-
dprint("tracked origin commit id: {}".format(o_from_t["hash"]))
72
+
logging.debug("tracked origin commit id: %s", o_from_t["hash"])
68
73
return o_from_t
69
74
70
75
71
76
def get_commits_count_between(opath, commit1, commit2):
72
-
command = "git log --pretty=format:%H {}...{} -- {}".format(commit1, commit2, opath)
73
-
dprint(command)
77
+
"""Get the commits count between two commits for the specified file"""
78
+
command = f"git log --pretty=format:%H {commit1}...{commit2} -- {opath}"
79
+
logging.debug(command)
74
80
pipe = os.popen(command)
75
81
result = pipe.read().split("\n")
76
82
# filter out empty lines
···
81
83
82
84
83
85
def pretty_output(commit):
84
-
command = "git log --pretty='format:%h (\"%s\")' -1 {}".format(commit)
85
-
dprint(command)
86
+
"""Pretty print the commit message"""
87
+
command = f"git log --pretty='format:%h (\"%s\")' -1 {commit}"
88
+
logging.debug(command)
86
89
pipe = os.popen(command)
87
90
return pipe.read()
88
91
89
92
93
+
def valid_commit(commit):
94
+
"""Check if the commit is valid or not"""
95
+
msg = pretty_output(commit)
96
+
return "Merge tag" not in msg
97
+
90
98
def check_per_file(file_path):
99
+
"""Check the translation status for the specified file"""
91
100
opath = get_origin_path(file_path)
92
101
93
102
if not os.path.isfile(opath):
94
-
dprint("Error: Cannot find the origin path for {}".format(file_path))
103
+
logging.error("Cannot find the origin path for {file_path}")
95
104
return
96
105
97
106
o_from_head = get_latest_commit_from(opath, "HEAD")
98
107
t_from_head = get_latest_commit_from(file_path, "HEAD")
99
108
100
109
if o_from_head is None or t_from_head is None:
101
-
print("Error: Cannot find the latest commit for {}".format(file_path))
110
+
logging.error("Cannot find the latest commit for %s", file_path)
102
111
return
103
112
104
113
o_from_t = get_origin_from_trans(opath, t_from_head)
105
114
106
115
if o_from_t is None:
107
-
print("Error: Cannot find the latest origin commit for {}".format(file_path))
116
+
logging.error("Error: Cannot find the latest origin commit for %s", file_path)
108
117
return
109
118
110
119
if o_from_head["hash"] == o_from_t["hash"]:
111
-
if flag_p_uf:
112
-
print("No update needed for {}".format(file_path))
113
-
return
120
+
logging.debug("No update needed for %s", file_path)
114
121
else:
115
-
print("{}".format(file_path), end="\t")
122
+
logging.info(file_path)
116
123
commits = get_commits_count_between(
117
124
opath, o_from_t["hash"], o_from_head["hash"]
118
125
)
119
-
print("({} commits)".format(len(commits)))
120
-
if flag_p_c:
121
-
for commit in commits:
122
-
msg = pretty_output(commit)
123
-
if "Merge tag" not in msg:
124
-
print("commit", msg)
126
+
count = 0
127
+
for commit in commits:
128
+
if valid_commit(commit):
129
+
logging.info("commit %s", pretty_output(commit))
130
+
count += 1
131
+
logging.info("%d commits needs resolving in total\n", count)
132
+
133
+
134
+
def valid_locales(locale):
135
+
"""Check if the locale is valid or not"""
136
+
script_path = os.path.dirname(os.path.abspath(__file__))
137
+
linux_path = os.path.join(script_path, "..")
138
+
if not os.path.isdir(f"{linux_path}/Documentation/translations/{locale}"):
139
+
raise ArgumentTypeError("Invalid locale: {locale}")
140
+
return locale
141
+
142
+
143
+
def list_files_with_excluding_folders(folder, exclude_folders, include_suffix):
144
+
"""List all files with the specified suffix in the folder and its subfolders"""
145
+
files = []
146
+
stack = [folder]
147
+
148
+
while stack:
149
+
pwd = stack.pop()
150
+
# filter out the exclude folders
151
+
if os.path.basename(pwd) in exclude_folders:
152
+
continue
153
+
# list all files and folders
154
+
for item in os.listdir(pwd):
155
+
ab_item = os.path.join(pwd, item)
156
+
if os.path.isdir(ab_item):
157
+
stack.append(ab_item)
158
+
else:
159
+
if ab_item.endswith(include_suffix):
160
+
files.append(ab_item)
161
+
162
+
return files
163
+
164
+
165
+
class DmesgFormatter(logging.Formatter):
166
+
"""Custom dmesg logging formatter"""
167
+
def format(self, record):
168
+
timestamp = time.time()
169
+
formatted_time = f"[{timestamp:>10.6f}]"
170
+
log_message = f"{formatted_time} {record.getMessage()}"
171
+
return log_message
172
+
173
+
174
+
def config_logging(log_level, log_file="checktransupdate.log"):
175
+
"""configure logging based on the log level"""
176
+
# set up the root logger
177
+
logger = logging.getLogger()
178
+
logger.setLevel(log_level)
179
+
180
+
# Create console handler
181
+
console_handler = logging.StreamHandler()
182
+
console_handler.setLevel(log_level)
183
+
184
+
# Create file handler
185
+
file_handler = logging.FileHandler(log_file)
186
+
file_handler.setLevel(log_level)
187
+
188
+
# Create formatter and add it to the handlers
189
+
formatter = DmesgFormatter()
190
+
console_handler.setFormatter(formatter)
191
+
file_handler.setFormatter(formatter)
192
+
193
+
# Add the handler to the logger
194
+
logger.addHandler(console_handler)
195
+
logger.addHandler(file_handler)
125
196
126
197
127
198
def main():
199
+
"""Main function of the script"""
128
200
script_path = os.path.dirname(os.path.abspath(__file__))
129
201
linux_path = os.path.join(script_path, "..")
130
202
···
202
134
parser.add_argument(
203
135
"-l",
204
136
"--locale",
137
+
default="zh_CN",
138
+
type=valid_locales,
205
139
help="Locale to check when files are not specified",
206
140
)
141
+
207
142
parser.add_argument(
208
-
"--print-commits",
143
+
"--print-missing-translations",
209
144
action=BooleanOptionalAction,
210
145
default=True,
211
-
help="Print commits between the origin and the translation",
146
+
help="Print files that do not have translations",
212
147
)
213
148
214
149
parser.add_argument(
215
-
"--print-updated-files",
216
-
action=BooleanOptionalAction,
217
-
default=False,
218
-
help="Print files that do no need to be updated",
219
-
)
150
+
'--log',
151
+
default='INFO',
152
+
choices=['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'],
153
+
help='Set the logging level')
220
154
221
155
parser.add_argument(
222
-
"--debug",
223
-
action=BooleanOptionalAction,
224
-
help="Print debug information",
225
-
default=False,
226
-
)
156
+
'--logfile',
157
+
default='checktransupdate.log',
158
+
help='Set the logging file (default: checktransupdate.log)')
227
159
228
160
parser.add_argument(
229
161
"files", nargs="*", help="Files to check, if not specified, check all files"
230
162
)
231
163
args = parser.parse_args()
232
164
233
-
global flag_p_c, flag_p_uf, flag_debug
234
-
flag_p_c = args.print_commits
235
-
flag_p_uf = args.print_updated_files
236
-
flag_debug = args.debug
165
+
# Configure logging based on the --log argument
166
+
log_level = getattr(logging, args.log.upper(), logging.INFO)
167
+
config_logging(log_level)
237
168
238
-
# get files related to linux path
169
+
# Get files related to linux path
239
170
files = args.files
240
171
if len(files) == 0:
241
-
if args.locale is not None:
242
-
files = (
243
-
os.popen(
244
-
"find {}/Documentation/translations/{} -type f".format(
245
-
linux_path, args.locale
246
-
)
247
-
)
248
-
.read()
249
-
.split("\n")
250
-
)
251
-
else:
252
-
files = (
253
-
os.popen(
254
-
"find {}/Documentation/translations -type f".format(linux_path)
255
-
)
256
-
.read()
257
-
.split("\n")
258
-
)
172
+
offical_files = list_files_with_excluding_folders(
173
+
os.path.join(linux_path, "Documentation"), ["translations", "output"], "rst"
174
+
)
259
175
260
-
files = list(filter(lambda x: x != "", files))
176
+
for file in offical_files:
177
+
# split the path into parts
178
+
path_parts = file.split(os.sep)
179
+
# find the index of the "Documentation" directory
180
+
kindex = path_parts.index("Documentation")
181
+
# insert the translations and locale after the Documentation directory
182
+
new_path_parts = path_parts[:kindex + 1] + ["translations", args.locale] \
183
+
+ path_parts[kindex + 1 :]
184
+
# join the path parts back together
185
+
new_file = os.sep.join(new_path_parts)
186
+
if os.path.isfile(new_file):
187
+
files.append(new_file)
188
+
else:
189
+
if args.print_missing_translations:
190
+
logging.info(os.path.relpath(os.path.abspath(file), linux_path))
191
+
logging.info("No translation in the locale of %s\n", args.locale)
192
+
261
193
files = list(map(lambda x: os.path.relpath(os.path.abspath(x), linux_path), files))
262
194
263
195
# cd to linux root directory
+15
-2
scripts/get_maintainer.pl
+15
-2
scripts/get_maintainer.pl
···
54
54
my $scm = 0;
55
55
my $tree = 1;
56
56
my $web = 0;
57
+
my $bug = 0;
57
58
my $subsystem = 0;
58
59
my $status = 0;
59
60
my $letters = "";
···
272
271
'scm!' => \$scm,
273
272
'tree!' => \$tree,
274
273
'web!' => \$web,
274
+
'bug!' => \$bug,
275
275
'letters=s' => \$letters,
276
276
'pattern-depth=i' => \$pattern_depth,
277
277
'k|keywords!' => \$keywords,
···
322
320
$status = 0;
323
321
$subsystem = 0;
324
322
$web = 0;
323
+
$bug = 0;
325
324
$keywords = 0;
326
325
$keywords_in_file = 0;
327
326
$interactive = 0;
328
327
} else {
329
-
my $selections = $email + $scm + $status + $subsystem + $web;
328
+
my $selections = $email + $scm + $status + $subsystem + $web + $bug;
330
329
if ($selections == 0) {
331
-
die "$P: Missing required option: email, scm, status, subsystem or web\n";
330
+
die "$P: Missing required option: email, scm, status, subsystem, web or bug\n";
332
331
}
333
332
}
334
333
···
634
631
my @list_to = ();
635
632
my @scm = ();
636
633
my @web = ();
634
+
my @bug = ();
637
635
my @subsystem = ();
638
636
my @status = ();
639
637
my %deduplicate_name_hash = ();
···
664
660
if ($web) {
665
661
@web = uniq(@web);
666
662
output(@web);
663
+
}
664
+
665
+
if ($bug) {
666
+
@bug = uniq(@bug);
667
+
output(@bug);
667
668
}
668
669
669
670
exit($exit);
···
856
847
@list_to = ();
857
848
@scm = ();
858
849
@web = ();
850
+
@bug = ();
859
851
@subsystem = ();
860
852
@status = ();
861
853
%deduplicate_name_hash = ();
···
1079
1069
--status => print status if any
1080
1070
--subsystem => print subsystem name if any
1081
1071
--web => print website(s) if any
1072
+
--bug => print bug reporting info if any
1082
1073
1083
1074
Output type options:
1084
1075
--separator [, ] => separator for multiple entries on 1 line
···
1393
1382
push(@scm, $pvalue . $suffix);
1394
1383
} elsif ($ptype eq "W") {
1395
1384
push(@web, $pvalue . $suffix);
1385
+
} elsif ($ptype eq "B") {
1386
+
push(@bug, $pvalue . $suffix);
1396
1387
} elsif ($ptype eq "S") {
1397
1388
push(@status, $pvalue . $suffix);
1398
1389
}