mirror of
https://github.com/linux-msm/laptops-kernel.git
synced 2026-08-13 14:19:53 -07:00
Merge tag 'docs-7.1' of git://git.kernel.org/pub/scm/linux/kernel/git/docs/linux
Pull documentation updates from Jonathan Corbet:
"A busier cycle than I had expected for docs, including:
- Translations: some overdue updates to the Japanese translations,
Chinese translations for some of the Rust documentation, and the
beginnings of a Portuguese translation.
- New documents covering CPU isolation, managed interrupts, debugging
Python gbb scripts, and more.
- More tooling work from Mauro, reducing docs-build warnings, adding
self tests, improving man-page output, bringing in a proper C
tokenizer to replace (some of) the mess of kernel-doc regexes, and
more.
- Update and synchronize changes.rst and scripts/ver_linux, and put
both into alphabetical order.
... and a long list of documentation updates, typo fixes, and general
improvements"
* tag 'docs-7.1' of git://git.kernel.org/pub/scm/linux/kernel/git/docs/linux: (162 commits)
Documentation: core-api: real-time: correct spelling
doc: Add CPU Isolation documentation
Documentation: Add managed interrupts
Documentation: seq_file: drop 2.6 reference
docs/zh_CN: update rust/index.rst translation
docs/zh_CN: update rust/quick-start.rst translation
docs/zh_CN: update rust/coding-guidelines.rst translation
docs/zh_CN: update rust/arch-support.rst translation
docs/zh_CN: sync process/2.Process.rst with English version
docs/zh_CN: fix an inconsistent statement in dev-tools/testing-overview
tracing: Documentation: Update histogram-design.rst for fn() handling
docs: sysctl: Add documentation for /proc/sys/xen/
Docs: hid: intel-ish-hid: make long URL usable
Documentation/kernel-parameters: fix architecture alignment for pt, nopt, and nobypass
sched/doc: Update yield_task description in sched-design-CFS
Documentation/rtla: Convert links to RST format
docs: fix typos and duplicated words across documentation
docs: fix typo in zoran driver documentation
docs: add an Assisted-by mention to submitting-patches.rst
Revert "scripts/checkpatch: add Assisted-by: tag validation"
...
This commit is contained in:
Linus Torvalds
@@ -618,7 +618,7 @@ cache_replacement_policy
|
||||
One of either lru, fifo or random.
|
||||
|
||||
freelist_percent
|
||||
Size of the freelist as a percentage of nbuckets. Can be written to to
|
||||
Size of the freelist as a percentage of nbuckets. Can be written to
|
||||
increase the number of buckets kept on the freelist, which lets you
|
||||
artificially reduce the size of the cache at runtime. Mostly for testing
|
||||
purposes (i.e. testing how different size caches affect your hit rate).
|
||||
|
||||
@@ -0,0 +1,357 @@
|
||||
.. SPDX-License-Identifier: GPL-2.0
|
||||
|
||||
=============
|
||||
CPU Isolation
|
||||
=============
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
"CPU Isolation" means leaving a CPU exclusive to a given workload
|
||||
without any undesired code interference from the kernel.
|
||||
|
||||
Those interferences, commonly pointed out as "noise", can be triggered
|
||||
by asynchronous events (interrupts, timers, scheduler preemption by
|
||||
workqueues and kthreads, ...) or synchronous events (syscalls and page
|
||||
faults).
|
||||
|
||||
Such noise usually goes unnoticed. After all, synchronous events are a
|
||||
component of the requested kernel service. And asynchronous events are
|
||||
either sufficiently well-distributed by the scheduler when executed
|
||||
as tasks or reasonably fast when executed as interrupt. The timer
|
||||
interrupt can even execute 1024 times per seconds without a significant
|
||||
and measurable impact most of the time.
|
||||
|
||||
However some rare and extreme workloads can be quite sensitive to
|
||||
those kinds of noise. This is the case, for example, with high
|
||||
bandwidth network processing that can't afford losing a single packet
|
||||
or very low latency network processing. Typically those use cases
|
||||
involve DPDK, bypassing the kernel networking stack and performing
|
||||
direct access to the networking device from userspace.
|
||||
|
||||
In order to run a CPU without or with limited kernel noise, the
|
||||
related housekeeping work needs to be either shut down, migrated or
|
||||
offloaded.
|
||||
|
||||
Housekeeping
|
||||
============
|
||||
|
||||
In the CPU isolation terminology, housekeeping is the work, often
|
||||
asynchronous, that the kernel needs to process in order to maintain
|
||||
all its services. It matches the noises and disturbances enumerated
|
||||
above except when at least one CPU is isolated. Then housekeeping may
|
||||
make use of further coping mechanisms if CPU-tied work must be
|
||||
offloaded.
|
||||
|
||||
Housekeeping CPUs are the non-isolated CPUs where the kernel noise
|
||||
is moved away from isolated CPUs.
|
||||
|
||||
The isolation can be implemented in several ways depending on the
|
||||
nature of the noise:
|
||||
|
||||
- Unbound work, where "unbound" means not tied to any CPU, can be
|
||||
simply migrated away from isolated CPUs to housekeeping CPUs.
|
||||
This is the case of unbound workqueues, kthreads and timers.
|
||||
|
||||
- Bound work, where "bound" means tied to a specific CPU, usually
|
||||
can't be moved away as-is by nature. Either:
|
||||
|
||||
- The work must switch to a locked implementation. E.g.:
|
||||
This is the case of RCU with CONFIG_RCU_NOCB_CPU.
|
||||
|
||||
- The related feature must be shut down and considered
|
||||
incompatible with isolated CPUs. E.g.: Lockup watchdog,
|
||||
unreliable clocksources, etc...
|
||||
|
||||
- An elaborate and heavyweight coping mechanism stands as a
|
||||
replacement. E.g.: the timer tick is shut down on nohz_full
|
||||
CPUs but with the constraint of running a single task on
|
||||
them. A significant cost penalty is added on kernel entry/exit
|
||||
and a residual 1Hz scheduler tick is offloaded to housekeeping
|
||||
CPUs.
|
||||
|
||||
In any case, housekeeping work has to be handled, which is why there
|
||||
must be at least one housekeeping CPU in the system, preferably more
|
||||
if the machine runs a lot of CPUs. For example one per node on NUMA
|
||||
systems.
|
||||
|
||||
Also CPU isolation often means a tradeoff between noise-free isolated
|
||||
CPUs and added overhead on housekeeping CPUs, sometimes even on
|
||||
isolated CPUs entering the kernel.
|
||||
|
||||
Isolation features
|
||||
==================
|
||||
|
||||
Different levels of isolation can be configured in the kernel, each of
|
||||
which has its own drawbacks and tradeoffs.
|
||||
|
||||
Scheduler domain isolation
|
||||
--------------------------
|
||||
|
||||
This feature isolates a CPU from the scheduler topology. As a result,
|
||||
the target isn't part of the load balancing. Tasks won't migrate
|
||||
either from or to it unless affined explicitly.
|
||||
|
||||
As a side effect the CPU is also isolated from unbound workqueues and
|
||||
unbound kthreads.
|
||||
|
||||
Requirements
|
||||
~~~~~~~~~~~~
|
||||
|
||||
- CONFIG_CPUSETS=y for the cpusets-based interface
|
||||
|
||||
Tradeoffs
|
||||
~~~~~~~~~
|
||||
|
||||
By nature, the system load is overall less distributed since some CPUs
|
||||
are extracted from the global load balancing.
|
||||
|
||||
Interfaces
|
||||
~~~~~~~~~~
|
||||
|
||||
- Documentation/admin-guide/cgroup-v2.rst cpuset isolated partitions are recommended
|
||||
because they are tunable at runtime.
|
||||
|
||||
- The 'isolcpus=' kernel boot parameter with the 'domain' flag is a
|
||||
less flexible alternative that doesn't allow for runtime
|
||||
reconfiguration.
|
||||
|
||||
IRQs isolation
|
||||
--------------
|
||||
|
||||
Isolate the IRQs whenever possible, so that they don't fire on the
|
||||
target CPUs.
|
||||
|
||||
Interfaces
|
||||
~~~~~~~~~~
|
||||
|
||||
- The file /proc/irq/\*/smp_affinity as explained in detail in
|
||||
Documentation/core-api/irq/irq-affinity.rst page.
|
||||
|
||||
- The "irqaffinity=" kernel boot parameter for a default setting.
|
||||
|
||||
- The "managed_irq" flag in the "isolcpus=" kernel boot parameter
|
||||
tries a best effort affinity override for managed IRQs.
|
||||
|
||||
Full Dynticks (aka nohz_full)
|
||||
-----------------------------
|
||||
|
||||
Full dynticks extends the dynticks idle mode, which stops the tick when
|
||||
the CPU is idle, to CPUs running a single task in userspace. That is,
|
||||
the timer tick is stopped if the environment allows it.
|
||||
|
||||
Global timer callbacks are also isolated from the nohz_full CPUs.
|
||||
|
||||
Requirements
|
||||
~~~~~~~~~~~~
|
||||
|
||||
- CONFIG_NO_HZ_FULL=y
|
||||
|
||||
Constraints
|
||||
~~~~~~~~~~~
|
||||
|
||||
- The isolated CPUs must run a single task only. Multitask requires
|
||||
the tick to maintain preemption. This is usually fine since the
|
||||
workload usually can't stand the latency of random context switches.
|
||||
|
||||
- No call to the kernel from isolated CPUs, at the risk of triggering
|
||||
random noise.
|
||||
|
||||
- No use of POSIX CPU timers on isolated CPUs.
|
||||
|
||||
- Architecture must have a stable and reliable clocksource (no
|
||||
unreliable TSC that requires the watchdog).
|
||||
|
||||
|
||||
Tradeoffs
|
||||
~~~~~~~~~
|
||||
|
||||
In terms of cost, this is the most invasive isolation feature. It is
|
||||
assumed to be used when the workload spends most of its time in
|
||||
userspace and doesn't rely on the kernel except for preparatory
|
||||
work because:
|
||||
|
||||
- RCU adds more overhead due to the locked, offloaded and threaded
|
||||
callbacks processing (the same that would be obtained with "rcu_nocbs"
|
||||
boot parameter).
|
||||
|
||||
- Kernel entry/exit through syscalls, exceptions and IRQs are more
|
||||
costly due to fully ordered RmW operations that maintain userspace
|
||||
as RCU extended quiescent state. Also the CPU time is accounted on
|
||||
kernel boundaries instead of periodically from the tick.
|
||||
|
||||
- Housekeeping CPUs must run a 1Hz residual remote scheduler tick
|
||||
on behalf of the isolated CPUs.
|
||||
|
||||
Checklist
|
||||
=========
|
||||
|
||||
You have set up each of the above isolation features but you still
|
||||
observe jitters that trash your workload? Make sure to check a few
|
||||
elements before proceeding.
|
||||
|
||||
Some of these checklist items are similar to those of real-time
|
||||
workloads:
|
||||
|
||||
- Use mlock() to prevent your pages from being swapped away. Page
|
||||
faults are usually not compatible with jitter sensitive workloads.
|
||||
|
||||
- Avoid SMT to prevent your hardware thread from being "preempted"
|
||||
by another one.
|
||||
|
||||
- CPU frequency changes may induce subtle sorts of jitter in a
|
||||
workload. Cpufreq should be used and tuned with caution.
|
||||
|
||||
- Deep C-states may result in latency issues upon wake-up. If this
|
||||
happens to be a problem, C-states can be limited via kernel boot
|
||||
parameters such as processor.max_cstate or intel_idle.max_cstate.
|
||||
More finegrained tunings are described in
|
||||
Documentation/admin-guide/pm/cpuidle.rst page
|
||||
|
||||
- Your system may be subject to firmware-originating interrupts - x86 has
|
||||
System Management Interrupts (SMIs) for example. Check your system BIOS
|
||||
to disable such interference, and with some luck your vendor will have
|
||||
a BIOS tuning guidance for low-latency operations.
|
||||
|
||||
|
||||
Full isolation example
|
||||
======================
|
||||
|
||||
In this example, the system has 8 CPUs and the 8th is to be fully
|
||||
isolated. Since CPUs start from 0, the 8th CPU is CPU 7.
|
||||
|
||||
Kernel parameters
|
||||
-----------------
|
||||
|
||||
Set the following kernel boot parameters to disable SMT and setup tick
|
||||
and IRQ isolation:
|
||||
|
||||
- Full dynticks: nohz_full=7
|
||||
|
||||
- IRQs isolation: irqaffinity=0-6
|
||||
|
||||
- Managed IRQs isolation: isolcpus=managed_irq,7
|
||||
|
||||
- Prevent SMT: nosmt
|
||||
|
||||
The full command line is then:
|
||||
|
||||
nohz_full=7 irqaffinity=0-6 isolcpus=managed_irq,7 nosmt
|
||||
|
||||
CPUSET configuration (cgroup v2)
|
||||
--------------------------------
|
||||
|
||||
Assuming cgroup v2 is mounted to /sys/fs/cgroup, the following script
|
||||
isolates CPU 7 from scheduler domains.
|
||||
|
||||
::
|
||||
|
||||
cd /sys/fs/cgroup
|
||||
# Activate the cpuset subsystem
|
||||
echo +cpuset > cgroup.subtree_control
|
||||
# Create partition to be isolated
|
||||
mkdir test
|
||||
cd test
|
||||
echo +cpuset > cgroup.subtree_control
|
||||
# Isolate CPU 7
|
||||
echo 7 > cpuset.cpus
|
||||
echo "isolated" > cpuset.cpus.partition
|
||||
|
||||
The userspace workload
|
||||
----------------------
|
||||
|
||||
Fake a pure userspace workload, the program below runs a dummy
|
||||
userspace loop on the isolated CPU 7.
|
||||
|
||||
::
|
||||
|
||||
#include <stdio.h>
|
||||
#include <fcntl.h>
|
||||
#include <unistd.h>
|
||||
#include <errno.h>
|
||||
int main(void)
|
||||
{
|
||||
// Move the current task to the isolated cpuset (bind to CPU 7)
|
||||
int fd = open("/sys/fs/cgroup/test/cgroup.procs", O_WRONLY);
|
||||
if (fd < 0) {
|
||||
perror("Can't open cpuset file...\n");
|
||||
return 0;
|
||||
}
|
||||
|
||||
write(fd, "0\n", 2);
|
||||
close(fd);
|
||||
|
||||
// Run an endless dummy loop until the launcher kills us
|
||||
while (1)
|
||||
;
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
Build it and save for later step:
|
||||
|
||||
::
|
||||
|
||||
# gcc user_loop.c -o user_loop
|
||||
|
||||
The launcher
|
||||
------------
|
||||
|
||||
The below launcher runs the above program for 10 seconds and traces
|
||||
the noise resulting from preempting tasks and IRQs.
|
||||
|
||||
::
|
||||
|
||||
TRACING=/sys/kernel/tracing/
|
||||
# Make sure tracing is off for now
|
||||
echo 0 > $TRACING/tracing_on
|
||||
# Flush previous traces
|
||||
echo > $TRACING/trace
|
||||
# Record disturbance from other tasks
|
||||
echo 1 > $TRACING/events/sched/sched_switch/enable
|
||||
# Record disturbance from interrupts
|
||||
echo 1 > $TRACING/events/irq_vectors/enable
|
||||
# Now we can start tracing
|
||||
echo 1 > $TRACING/tracing_on
|
||||
# Run the dummy user_loop for 10 seconds on CPU 7
|
||||
./user_loop &
|
||||
USER_LOOP_PID=$!
|
||||
sleep 10
|
||||
kill $USER_LOOP_PID
|
||||
# Disable tracing and save traces from CPU 7 in a file
|
||||
echo 0 > $TRACING/tracing_on
|
||||
cat $TRACING/per_cpu/cpu7/trace > trace.7
|
||||
|
||||
If no specific problem arose, the output of trace.7 should look like
|
||||
the following:
|
||||
|
||||
::
|
||||
|
||||
<idle>-0 [007] d..2. 1980.976624: sched_switch: prev_comm=swapper/7 prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=user_loop next_pid=1553 next_prio=120
|
||||
user_loop-1553 [007] d.h.. 1990.946593: reschedule_entry: vector=253
|
||||
user_loop-1553 [007] d.h.. 1990.946593: reschedule_exit: vector=253
|
||||
|
||||
That is, no specific noise triggered between the first trace and the
|
||||
second during 10 seconds when user_loop was running.
|
||||
|
||||
Debugging
|
||||
=========
|
||||
|
||||
Of course things are never so easy, especially on this matter.
|
||||
Chances are that actual noise will be observed in the aforementioned
|
||||
trace.7 file.
|
||||
|
||||
The best way to investigate further is to enable finer grained
|
||||
tracepoints such as those of subsystems producing asynchronous
|
||||
events: workqueue, timer, irq_vector, etc... It also can be
|
||||
interesting to enable the tick_stop event to diagnose why the tick is
|
||||
retained when that happens.
|
||||
|
||||
Some tools may also be useful for higher level analysis:
|
||||
|
||||
- Documentation/tools/rtla/rtla.rst provides a suite of tools to analyze
|
||||
latency and noise in the system. For example Documentation/tools/rtla/rtla-osnoise.rst
|
||||
runs a kernel tracer that analyzes and output a summary of the noises.
|
||||
|
||||
- dynticks-testing does something similar to rtla-osnoise but in userspace. It is available
|
||||
at git://git.kernel.org/pub/scm/linux/kernel/git/frederic/dynticks-testing.git
|
||||
@@ -94,6 +94,7 @@ likely to be of interest on almost any system.
|
||||
|
||||
cgroup-v2
|
||||
cgroup-v1/index
|
||||
cpu-isolation
|
||||
cpu-load
|
||||
mm/index
|
||||
module-signing
|
||||
|
||||
@@ -2630,15 +2630,11 @@ Kernel parameters
|
||||
Intel machines). This can be used to prevent the usage
|
||||
of an available hardware IOMMU.
|
||||
|
||||
[X86]
|
||||
pt
|
||||
[X86]
|
||||
nopt
|
||||
[PPC/POWERNV]
|
||||
nobypass
|
||||
nobypass [PPC/POWERNV]
|
||||
Disable IOMMU bypass, using IOMMU for PCI devices.
|
||||
|
||||
[X86]
|
||||
AMD Gart HW IOMMU-specific options:
|
||||
|
||||
<size>
|
||||
@@ -6761,7 +6757,7 @@ Kernel parameters
|
||||
Default is 'on'.
|
||||
|
||||
initramfs_options= [KNL]
|
||||
Specify mount options for for the initramfs mount.
|
||||
Specify mount options for the initramfs mount.
|
||||
|
||||
rootfstype= [KNL] Set root filesystem type
|
||||
|
||||
|
||||
@@ -287,7 +287,7 @@ level.
|
||||
Check presence of other Intel(R) SST features
|
||||
---------------------------------------------
|
||||
|
||||
Each of the performance profiles also specifies weather there is support of
|
||||
Each of the performance profiles also specifies whether there is support of
|
||||
other two Intel(R) SST features (Intel(R) Speed Select Technology - Base Frequency
|
||||
(Intel(R) SST-BF) and Intel(R) Speed Select Technology - Turbo Frequency (Intel
|
||||
SST-TF)).
|
||||
|
||||
@@ -349,12 +349,14 @@ again.
|
||||
|
||||
.. _submit_improvements_qbtl:
|
||||
|
||||
Did you run into trouble following any of the above steps that is not cleared up
|
||||
by the reference section below? Or do you have ideas how to improve the text?
|
||||
Then please take a moment of your time and let the maintainer of this document
|
||||
know by email (Thorsten Leemhuis <linux@leemhuis.info>), ideally while CCing the
|
||||
Linux docs mailing list (linux-doc@vger.kernel.org). Such feedback is vital to
|
||||
improve this document further, which is in everybody's interest, as it will
|
||||
Did you run into trouble following the step-by-step guide not cleared up by the
|
||||
reference section below? Did you spot errors? Or do you have ideas on how to
|
||||
improve the guide?
|
||||
|
||||
If any of that applies, please let the developers know by sending a short note
|
||||
or a patch to Thorsten Leemhuis <linux@leemhuis.info> while ideally CCing the
|
||||
public Linux docs mailing list <linux-doc@vger.kernel.org>. Such feedback is
|
||||
vital to improve this text further, which is in everybody's interest, as it will
|
||||
enable more people to master the task described here.
|
||||
|
||||
Reference section for the step-by-step guide
|
||||
|
||||
@@ -48,6 +48,16 @@ Once the report is out, answer any questions that come up and help where you
|
||||
can. That includes keeping the ball rolling by occasionally retesting with newer
|
||||
releases and sending a status update afterwards.
|
||||
|
||||
..
|
||||
Note: If you see this note, you are reading the text's source file. You
|
||||
might want to switch to a rendered version: It makes it a lot easier to
|
||||
read and navigate this document -- especially when you want to look something
|
||||
up in the reference section, then jump back to where you left off.
|
||||
..
|
||||
Find the latest rendered version of this text here:
|
||||
https://docs.kernel.org/admin-guide/reporting-issues.html
|
||||
|
||||
|
||||
Step-by-step guide how to report issues to the kernel maintainers
|
||||
=================================================================
|
||||
|
||||
@@ -231,45 +241,54 @@ kernels regularly rebased on those. If that is the case, follow these steps:
|
||||
The reference section below explains each of these steps in more detail.
|
||||
|
||||
|
||||
Conclusion of the step-by-step guide
|
||||
------------------------------------
|
||||
|
||||
Did you run into trouble following the step-by-step guide not cleared up by the
|
||||
reference section below? Did you spot errors? Or do you have ideas on how to
|
||||
improve the guide?
|
||||
|
||||
If any of that applies, please let the developers know by sending a short note
|
||||
or a patch to Thorsten Leemhuis <linux@leemhuis.info> while ideally CCing the
|
||||
public Linux docs mailing list <linux-doc@vger.kernel.org>. Such feedback is
|
||||
vital to improve this text further, which is in everybody's interest, as it will
|
||||
enable more people to master the task described here.
|
||||
|
||||
|
||||
Reference section: Reporting issues to the kernel maintainers
|
||||
=============================================================
|
||||
|
||||
The detailed guides above outline all the major steps in brief fashion, which
|
||||
should be enough for most people. But sometimes there are situations where even
|
||||
experienced users might wonder how to actually do one of those steps. That's
|
||||
what this section is for, as it will provide a lot more details on each of the
|
||||
above steps. Consider this as reference documentation: it's possible to read it
|
||||
from top to bottom. But it's mainly meant to skim over and a place to look up
|
||||
details how to actually perform those steps.
|
||||
The step-by-step guide above outlines all the major steps in brief fashion,
|
||||
which usually covers everything required. But even experienced users will
|
||||
sometimes wonder how to actually realize some of those steps or why they are
|
||||
needed; there are also corner cases the guide ignores for readability. That is
|
||||
what the entries in this reference section are for, which provide additional
|
||||
information for each of the steps in the guide.
|
||||
|
||||
A few words of general advice before digging into the details:
|
||||
A few words of general advice:
|
||||
|
||||
* The Linux kernel developers are well aware this process is complicated and
|
||||
demands more than other FLOSS projects. We'd love to make it simpler. But
|
||||
that would require work in various places as well as some infrastructure,
|
||||
which would need constant maintenance; nobody has stepped up to do that
|
||||
work, so that's just how things are for now.
|
||||
* The Linux developers are well aware that reporting bugs to them is more
|
||||
complicated and demanding than in other FLOSS projects. Some of it is because
|
||||
the kernel is different, among others due to its mail-driven development
|
||||
process and because it consists mostly of drivers. Some of it is because
|
||||
improving things would require work in several technical areas and people
|
||||
triaging bugs –– and nobody has stepped up to do or fund that work.
|
||||
|
||||
* A warranty or support contract with some vendor doesn't entitle you to
|
||||
request fixes from developers in the upstream Linux kernel community: such
|
||||
contracts are completely outside the scope of the Linux kernel, its
|
||||
development community, and this document. That's why you can't demand
|
||||
anything such a contract guarantees in this context, not even if the
|
||||
developer handling the issue works for the vendor in question. If you want
|
||||
to claim your rights, use the vendor's support channel instead. When doing
|
||||
so, you might want to mention you'd like to see the issue fixed in the
|
||||
upstream Linux kernel; motivate them by saying it's the only way to ensure
|
||||
the fix in the end will get incorporated in all Linux distributions.
|
||||
* A warranty or support contract with some vendor doesn't entitle you to
|
||||
request fixes from the upstream Linux developers: Such contracts are
|
||||
completely outside the scope of the upstream Linux kernel, its development
|
||||
community, and this document -- even if those handling the issue work for the
|
||||
vendor who issued the contract. If you want to claim your rights, use the
|
||||
vendor's support channel.
|
||||
|
||||
* If you never reported an issue to a FLOSS project before you should consider
|
||||
reading `How to Report Bugs Effectively
|
||||
<https://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_, `How To Ask
|
||||
Questions The Smart Way
|
||||
<http://www.catb.org/esr/faqs/smart-questions.html>`_, and `How to ask good
|
||||
questions <https://jvns.ca/blog/good-questions/>`_.
|
||||
* If you never reported an issue to a FLOSS project before, consider skimming
|
||||
guides like `How to ask good questions
|
||||
<https://jvns.ca/blog/good-questions/>`_, `How To Ask Questions The Smart Way
|
||||
<http://www.catb.org/esr/faqs/smart-questions.html>`_, and `How to Report
|
||||
Bugs Effectively <https://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_,.
|
||||
|
||||
With that off the table, find below the details on how to properly report
|
||||
issues to the Linux kernel developers.
|
||||
With that off the table, find below details for the steps from the detailed
|
||||
guide on reporting issues to the Linux kernel developers.
|
||||
|
||||
|
||||
Make sure you're using the upstream Linux kernel
|
||||
@@ -1674,72 +1693,59 @@ for the subsystem where the issue seems to have its roots; CC the mailing list
|
||||
for the subsystem as well as the stable mailing list (stable@vger.kernel.org).
|
||||
|
||||
|
||||
Why some issues won't get any reaction or remain unfixed after being reported
|
||||
=============================================================================
|
||||
Appendix: Why it is somewhat hard to report kernel bugs
|
||||
=======================================================
|
||||
|
||||
When reporting a problem to the Linux developers, be aware only 'issues of high
|
||||
priority' (regressions, security issues, severe problems) are definitely going
|
||||
to get resolved. The maintainers or if all else fails Linus Torvalds himself
|
||||
will make sure of that. They and the other kernel developers will fix a lot of
|
||||
other issues as well. But be aware that sometimes they can't or won't help; and
|
||||
sometimes there isn't even anyone to send a report to.
|
||||
The Linux kernel developers are well aware that reporting bugs to them is harder
|
||||
than in other Free/Libre Open Source Projects. Many reasons for that lie in the
|
||||
nature of kernels, Linux' development model, and how the world uses the kernel:
|
||||
|
||||
This is best explained with kernel developers that contribute to the Linux
|
||||
kernel in their spare time. Quite a few of the drivers in the kernel were
|
||||
written by such programmers, often because they simply wanted to make their
|
||||
hardware usable on their favorite operating system.
|
||||
* *Most kernels of Linux distributions are totally unsuitable for reporting bugs
|
||||
upstream.* The reference section above already explained this in detail:
|
||||
outdated codebases as well as modifications and add-ons lead to kernel bugs
|
||||
that were fixed upstream a long time ago or never happened there in the first
|
||||
place. Developers of other Open Source software face these problems as well,
|
||||
but the situation is a lot worse when it comes to the kernel, as the changes
|
||||
and their impact are much more severe -- which is why many kernel developers
|
||||
expect reports with kernels built from fresh and nearly unmodified sources.
|
||||
|
||||
These programmers most of the time will happily fix problems other people
|
||||
report. But nobody can force them to do, as they are contributing voluntarily.
|
||||
* *Bugs often only occur in a special environment.* That is because Linux is
|
||||
mostly drivers and can be used in a multitude of ways. Developers often do not
|
||||
have a matching setup at hand -- and therefore frequently must rely on bug
|
||||
reporters for isolating a problems's cause and testing proposed fixes.
|
||||
|
||||
Then there are situations where such developers really want to fix an issue,
|
||||
but can't: sometimes they lack hardware programming documentation to do so.
|
||||
This often happens when the publicly available docs are superficial or the
|
||||
driver was written with the help of reverse engineering.
|
||||
* *The kernel has hundreds of maintainers, but all-rounders are very rare.* That
|
||||
again is and effect caused by the multitude of features and drivers, due to
|
||||
which many kernel developers know little about lower or higher layers related
|
||||
to their code and even less about other areas.
|
||||
|
||||
Sooner or later spare time developers will also stop caring for the driver.
|
||||
Maybe their test hardware broke, got replaced by something more fancy, or is so
|
||||
old that it's something you don't find much outside of computer museums
|
||||
anymore. Sometimes developer stops caring for their code and Linux at all, as
|
||||
something different in their life became way more important. In some cases
|
||||
nobody is willing to take over the job as maintainer – and nobody can be forced
|
||||
to, as contributing to the Linux kernel is done on a voluntary basis. Abandoned
|
||||
drivers nevertheless remain in the kernel: they are still useful for people and
|
||||
removing would be a regression.
|
||||
* *It is hard finding where to report issues to, among others, due to the lack
|
||||
of a central bug tracker.* This is something even some kernel developers
|
||||
dislike, but that's the situation everyone has to deal with currently.
|
||||
|
||||
The situation is not that different with developers that are paid for their
|
||||
work on the Linux kernel. Those contribute most changes these days. But their
|
||||
employers sooner or later also stop caring for their code or make its
|
||||
programmer focus on other things. Hardware vendors for example earn their money
|
||||
mainly by selling new hardware; quite a few of them hence are not investing
|
||||
much time and energy in maintaining a Linux kernel driver for something they
|
||||
stopped selling years ago. Enterprise Linux distributors often care for a
|
||||
longer time period, but in new versions often leave support for old and rare
|
||||
hardware aside to limit the scope. Often spare time contributors take over once
|
||||
a company orphans some code, but as mentioned above: sooner or later they will
|
||||
leave the code behind, too.
|
||||
* *Stable and longterm kernels are primarily maintained by a dedicated 'stable
|
||||
team', which only handles regressions introduced within stable and longterm
|
||||
series.* When someone reports a bug, say, using Linux 6.1.2, the team will,
|
||||
therefore, always ask if mainline is affected: if the bug already happened
|
||||
in 6.1 or occurs with latest mainline (say, 6.2-rc3), they in everybody's
|
||||
interest shove it to the regular developers, as those know the code best.
|
||||
|
||||
Priorities are another reason why some issues are not fixed, as maintainers
|
||||
quite often are forced to set those, as time to work on Linux is limited.
|
||||
That's true for spare time or the time employers grant their developers to
|
||||
spend on maintenance work on the upstream kernel. Sometimes maintainers also
|
||||
get overwhelmed with reports, even if a driver is working nearly perfectly. To
|
||||
not get completely stuck, the programmer thus might have no other choice than
|
||||
to prioritize issue reports and reject some of them.
|
||||
* *Linux developers are free to focus on latest mainline.* Some, thus, react
|
||||
coldly to reports about bugs in, say, Linux 6.0 when 6.1 is already out;
|
||||
even the latter might not be enough once 6.2-rc1 is out. Some will also not
|
||||
be very welcoming to reports with 6.1.5 or 6.1.6, as the problem might be a
|
||||
series-specific regression the stable team (see above) caused and must fix.
|
||||
|
||||
But don't worry too much about all of this, a lot of drivers have active
|
||||
maintainers who are quite interested in fixing as many issues as possible.
|
||||
|
||||
|
||||
Closing words
|
||||
=============
|
||||
|
||||
Compared with other Free/Libre & Open Source Software it's hard to report
|
||||
issues to the Linux kernel developers: the length and complexity of this
|
||||
document and the implications between the lines illustrate that. But that's how
|
||||
it is for now. The main author of this text hopes documenting the state of the
|
||||
art will lay some groundwork to improve the situation over time.
|
||||
* *Sometimes there is nobody to help.* Sometimes this is due to the lack of
|
||||
hardware documentation -- for example, when a driver was built using reverse
|
||||
engineering or was taken over by spare-time developers when the hardware
|
||||
manufacturer left it behind. Other times there is nobody to even report bugs
|
||||
to: when maintainers move on without a replacement, their code often remains
|
||||
in the kernel as long as it's useful.
|
||||
|
||||
Some of these aspects could be improved to facilitate bug reporting -- many
|
||||
Linux kernel developers are well aware of this and would be glad if a few
|
||||
individuals or an entity would make this their mission.
|
||||
|
||||
..
|
||||
end-of-content
|
||||
|
||||
@@ -0,0 +1,47 @@
|
||||
=================
|
||||
/proc/sys/crypto/
|
||||
=================
|
||||
|
||||
These files show up in ``/proc/sys/crypto/``, depending on the
|
||||
kernel configuration:
|
||||
|
||||
.. contents:: :local:
|
||||
|
||||
fips_enabled
|
||||
============
|
||||
|
||||
Read-only flag that indicates whether FIPS mode is enabled.
|
||||
|
||||
- ``0``: FIPS mode is disabled (default).
|
||||
- ``1``: FIPS mode is enabled.
|
||||
|
||||
This value is set at boot time via the ``fips=1`` kernel command line
|
||||
parameter. When enabled, the cryptographic API will restrict the use
|
||||
of certain algorithms and perform self-tests to ensure compliance with
|
||||
FIPS (Federal Information Processing Standards) requirements, such as
|
||||
FIPS 140-2 and the newer FIPS 140-3, depending on the kernel
|
||||
configuration and the module in use.
|
||||
|
||||
fips_name
|
||||
=========
|
||||
|
||||
Read-only file that contains the name of the FIPS module currently in use.
|
||||
The value is typically configured via the ``CONFIG_CRYPTO_FIPS_NAME``
|
||||
kernel configuration option.
|
||||
|
||||
fips_version
|
||||
============
|
||||
|
||||
Read-only file that contains the version string of the FIPS module.
|
||||
If ``CONFIG_CRYPTO_FIPS_CUSTOM_VERSION`` is set, it uses the value from
|
||||
``CONFIG_CRYPTO_FIPS_VERSION``. Otherwise, it defaults to the kernel
|
||||
release version (``UTS_RELEASE``).
|
||||
|
||||
Copyright (c) 2026, Shubham Chakraborty <chakrabortyshubham66@gmail.com>
|
||||
|
||||
For general info and legal blurb, please look in
|
||||
Documentation/admin-guide/sysctl/index.rst.
|
||||
|
||||
.. See scripts/check-sysctl-docs to keep this up to date:
|
||||
.. scripts/check-sysctl-docs -vtable="crypto" \
|
||||
.. $(git grep -l register_sysctl_)
|
||||
@@ -0,0 +1,52 @@
|
||||
================
|
||||
/proc/sys/debug/
|
||||
================
|
||||
|
||||
These files show up in ``/proc/sys/debug/``, depending on the
|
||||
kernel configuration:
|
||||
|
||||
.. contents:: :local:
|
||||
|
||||
exception-trace
|
||||
===============
|
||||
|
||||
This flag controls whether the kernel prints information about unhandled
|
||||
signals (like segmentation faults) to the kernel log (``dmesg``).
|
||||
|
||||
- ``0``: Unhandled signals are not traced.
|
||||
- ``1``: Information about unhandled signals is printed.
|
||||
|
||||
The default value is ``1`` on most architectures (like x86, MIPS, RISC-V),
|
||||
but it is ``0`` on **arm64**.
|
||||
|
||||
The actual information printed and the context provided varies
|
||||
significantly depending on the CPU architecture. For example:
|
||||
|
||||
- On **x86**, it typically prints the instruction pointer (IP), error
|
||||
code, and address that caused a page fault.
|
||||
- On **PowerPC**, it may print the next instruction pointer (NIP),
|
||||
link register (LR), and other relevant registers.
|
||||
|
||||
When enabled, this feature is often rate-limited to prevent the kernel
|
||||
log from being flooded during a crash loop.
|
||||
|
||||
kprobes-optimization
|
||||
====================
|
||||
|
||||
This flag enables or disables the optimization of Kprobes on certain
|
||||
architectures (like x86).
|
||||
|
||||
- ``0``: Kprobes optimization is turned off.
|
||||
- ``1``: Kprobes optimization is turned on (default).
|
||||
|
||||
For more details on Kprobes and its optimization, please refer to
|
||||
Documentation/trace/kprobes.rst.
|
||||
|
||||
Copyright (c) 2026, Shubham Chakraborty <chakrabortyshubham66@gmail.com>
|
||||
|
||||
For general info and legal blurb, please look in
|
||||
Documentation/admin-guide/sysctl/index.rst.
|
||||
|
||||
.. See scripts/check-sysctl-docs to keep this up to date:
|
||||
.. scripts/check-sysctl-docs -vtable="debug" \
|
||||
.. $(git grep -l register_sysctl_)
|
||||
@@ -67,8 +67,8 @@ This documentation is about:
|
||||
=============== ===============================================================
|
||||
abi/ execution domains & personalities
|
||||
<$ARCH> tuning controls for various CPU architecture (e.g. csky, s390)
|
||||
crypto/ <undocumented>
|
||||
debug/ <undocumented>
|
||||
crypto/ cryptographic subsystem
|
||||
debug/ debugging features
|
||||
dev/ device specific information (e.g. dev/cdrom/info)
|
||||
fs/ specific filesystems
|
||||
filehandle, inode, dentry and quota tuning
|
||||
@@ -84,7 +84,7 @@ sunrpc/ SUN Remote Procedure Call (NFS)
|
||||
user/ Per user namespace limits
|
||||
vm/ memory management tuning
|
||||
buffer and cache management
|
||||
xen/ <undocumented>
|
||||
xen/ Xen hypervisor controls
|
||||
=============== ===============================================================
|
||||
|
||||
These are the subdirs I have on my system or have been discovered by
|
||||
@@ -96,9 +96,12 @@ it :-)
|
||||
:maxdepth: 1
|
||||
|
||||
abi
|
||||
crypto
|
||||
debug
|
||||
fs
|
||||
kernel
|
||||
net
|
||||
sunrpc
|
||||
user
|
||||
vm
|
||||
xen
|
||||
|
||||
@@ -0,0 +1,31 @@
|
||||
===============
|
||||
/proc/sys/xen/
|
||||
===============
|
||||
|
||||
Copyright (c) 2026, Shubham Chakraborty <chakrabortyshubham66@gmail.com>
|
||||
|
||||
For general info and legal blurb, please look in
|
||||
Documentation/admin-guide/sysctl/index.rst.
|
||||
|
||||
------------------------------------------------------------------------------
|
||||
|
||||
These files show up in ``/proc/sys/xen/``, depending on the
|
||||
kernel configuration:
|
||||
|
||||
.. contents:: :local:
|
||||
|
||||
balloon/hotplug_unpopulated
|
||||
===========================
|
||||
|
||||
This flag controls whether unpopulated memory ranges are automatically
|
||||
hotplugged as system RAM.
|
||||
|
||||
- ``0``: Unpopulated ranges are not hotplugged (default).
|
||||
- ``1``: Unpopulated ranges are automatically hotplugged.
|
||||
|
||||
When enabled, the Xen balloon driver will add memory regions that are
|
||||
marked as unpopulated in the Xen memory map to the system as usable RAM.
|
||||
This allows for dynamic memory expansion in Xen guest domains.
|
||||
|
||||
This option is only available when the kernel is built with
|
||||
``CONFIG_XEN_BALLOON_MEMORY_HOTPLUG`` enabled.
|
||||
@@ -74,7 +74,7 @@ a particular type of taint. It's best to leave that to the aforementioned
|
||||
script, but if you need something quick you can use this shell command to check
|
||||
which bits are set::
|
||||
|
||||
$ for i in $(seq 18); do echo $(($i-1)) $(($(cat /proc/sys/kernel/tainted)>>($i-1)&1));done
|
||||
$ for i in $(seq 20); do echo $(($i-1)) $(($(cat /proc/sys/kernel/tainted)>>($i-1)&1));done
|
||||
|
||||
Table for decoding tainted state
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@@ -1062,16 +1062,15 @@ Conclusion
|
||||
|
||||
You have reached the end of the step-by-step guide.
|
||||
|
||||
Did you run into trouble following any of the above steps not cleared up by the
|
||||
reference section below? Did you spot errors? Or do you have ideas how to
|
||||
Did you run into trouble following the step-by-step guide not cleared up by the
|
||||
reference section below? Did you spot errors? Or do you have ideas on how to
|
||||
improve the guide?
|
||||
|
||||
If any of that applies, please take a moment and let the maintainer of this
|
||||
document know by email (Thorsten Leemhuis <linux@leemhuis.info>), ideally while
|
||||
CCing the Linux docs mailing list (linux-doc@vger.kernel.org). Such feedback is
|
||||
vital to improve this text further, which is in everybody's interest, as it
|
||||
will enable more people to master the task described here -- and hopefully also
|
||||
improve similar guides inspired by this one.
|
||||
If any of that applies, please let the developers know by sending a short note
|
||||
or a patch to Thorsten Leemhuis <linux@leemhuis.info> while ideally CCing the
|
||||
public Linux docs mailing list <linux-doc@vger.kernel.org>. Such feedback is
|
||||
vital to improve this text further, which is in everybody's interest, as it will
|
||||
enable more people to master the task described here.
|
||||
|
||||
|
||||
Reference section for the step-by-step guide
|
||||
|
||||
@@ -455,6 +455,7 @@ if html_theme == "alabaster":
|
||||
# The name of an image file (relative to this directory) to place at the top
|
||||
# of the sidebar.
|
||||
html_logo = "images/logo.svg"
|
||||
html_favicon = "images/logo.svg"
|
||||
|
||||
# Output file base name for HTML help builder.
|
||||
htmlhelp_basename = "TheLinuxKerneldoc"
|
||||
|
||||
@@ -15,7 +15,7 @@ various deferrals etc...
|
||||
Sometimes housekeeping is just some unbound work (unbound workqueues,
|
||||
unbound timers, ...) that gets easily assigned to non-isolated CPUs.
|
||||
But sometimes housekeeping is tied to a specific CPU and requires
|
||||
elaborated tricks to be offloaded to non-isolated CPUs (RCU_NOCB, remote
|
||||
elaborate tricks to be offloaded to non-isolated CPUs (RCU_NOCB, remote
|
||||
scheduler tick, etc...).
|
||||
|
||||
Thus, a housekeeping CPU can be considered as the reverse of an isolated
|
||||
|
||||
@@ -9,3 +9,4 @@ IRQs
|
||||
irq-affinity
|
||||
irq-domain
|
||||
irqflags-tracing
|
||||
managed_irq
|
||||
|
||||
@@ -0,0 +1,116 @@
|
||||
.. SPDX-License-Identifier: GPL-2.0
|
||||
|
||||
===========================
|
||||
Affinity managed interrupts
|
||||
===========================
|
||||
|
||||
The IRQ core provides support for managing interrupts according to a specified
|
||||
CPU affinity. Under normal operation, an interrupt is associated with a
|
||||
particular CPU. If that CPU is taken offline, the interrupt is migrated to
|
||||
another online CPU.
|
||||
|
||||
Devices with large numbers of interrupt vectors can stress the available vector
|
||||
space. For example, an NVMe device with 128 I/O queues typically requests one
|
||||
interrupt per queue on systems with at least 128 CPUs. Two such devices
|
||||
therefore request 256 interrupts. On x86, the interrupt vector space is
|
||||
notoriously low, providing only 256 vectors per CPU, and the kernel reserves a
|
||||
subset of these, further reducing the number available for device interrupts.
|
||||
In practice this is not an issue because the interrupts are distributed across
|
||||
many CPUs, so each CPU only receives a small number of vectors.
|
||||
|
||||
During system suspend, however, all secondary CPUs are taken offline and all
|
||||
interrupts are migrated to the single CPU that remains online. This can exhaust
|
||||
the available interrupt vectors on that CPU and cause the suspend operation to
|
||||
fail.
|
||||
|
||||
Affinity‑managed interrupts address this limitation. Each interrupt is assigned
|
||||
a CPU affinity mask that specifies the set of CPUs on which the interrupt may
|
||||
be targeted. When a CPU in the mask goes offline, the interrupt is moved to the
|
||||
next CPU in the mask. If the last CPU in the mask goes offline, the interrupt
|
||||
is shut down. Drivers using affinity‑managed interrupts must ensure that the
|
||||
associated queue is quiesced before the interrupt is disabled so that no
|
||||
further interrupts are generated. When a CPU in the affinity mask comes back
|
||||
online, the interrupt is re‑enabled.
|
||||
|
||||
Implementation
|
||||
--------------
|
||||
|
||||
Devices must provide per‑instance interrupts, such as per‑I/O‑queue interrupts
|
||||
for storage devices like NVMe. The driver allocates interrupt vectors with the
|
||||
required affinity settings using struct irq_affinity. For MSI‑X devices, this
|
||||
is done via pci_alloc_irq_vectors_affinity() with the PCI_IRQ_AFFINITY flag
|
||||
set.
|
||||
|
||||
Based on the provided affinity information, the IRQ core attempts to spread the
|
||||
interrupts evenly across the system. The affinity masks are computed during
|
||||
this allocation step, but the final IRQ assignment is performed when
|
||||
request_irq() is invoked.
|
||||
|
||||
Isolated CPUs
|
||||
-------------
|
||||
|
||||
The affinity of managed interrupts is handled entirely in the kernel and cannot
|
||||
be modified from user space through the /proc interfaces. The managed_irq
|
||||
sub‑parameter of the isolcpus boot option specifies a CPU mask that managed
|
||||
interrupts should attempt to avoid. This isolation is best‑effort and only
|
||||
applies if the automatically assigned interrupt mask also contains online CPUs
|
||||
outside the avoided mask. If the requested mask contains only isolated CPUs,
|
||||
the setting has no effect.
|
||||
|
||||
CPUs listed in the avoided mask remain part of the interrupt’s affinity mask.
|
||||
This means that if all non‑isolated CPUs go offline while isolated CPUs remain
|
||||
online, the interrupt will be assigned to one of the isolated CPUs.
|
||||
|
||||
The following examples assume a system with 8 CPUs.
|
||||
|
||||
- A QEMU instance is booted with "-device virtio-scsi-pci".
|
||||
The MSI‑X device exposes 11 interrupts: 3 "management" interrupts and 8
|
||||
"queue" interrupts. The driver requests the 8 queue interrupts, each of which
|
||||
is affine to exactly one CPU. If that CPU goes offline, the interrupt is shut
|
||||
down.
|
||||
|
||||
Assuming interrupt 48 is one of the queue interrupts, the following appears::
|
||||
|
||||
/proc/irq/48/effective_affinity_list:7
|
||||
/proc/irq/48/smp_affinity_list:7
|
||||
|
||||
This indicates that the interrupt is served only by CPU7. Shutting down CPU7
|
||||
does not migrate the interrupt to another CPU::
|
||||
|
||||
/proc/irq/48/effective_affinity_list:0
|
||||
/proc/irq/48/smp_affinity_list:7
|
||||
|
||||
This can be verified via the debugfs interface
|
||||
(/sys/kernel/debug/irq/irqs/48). The dstate field will include
|
||||
IRQD_IRQ_DISABLED, IRQD_IRQ_MASKED and IRQD_MANAGED_SHUTDOWN.
|
||||
|
||||
- A QEMU instance is booted with "-device virtio-scsi-pci,num_queues=2"
|
||||
and the kernel command line includes:
|
||||
"irqaffinity=0,1 isolcpus=domain,2-7 isolcpus=managed_irq,1-3,5-7".
|
||||
The MSI‑X device exposes 5 interrupts: 3 management interrupts and 2 queue
|
||||
interrupts. The management interrupts follow the irqaffinity= setting. The
|
||||
queue interrupts are spread across available CPUs::
|
||||
|
||||
/proc/irq/47/effective_affinity_list:0
|
||||
/proc/irq/47/smp_affinity_list:0-3
|
||||
/proc/irq/48/effective_affinity_list:4
|
||||
/proc/irq/48/smp_affinity_list:4-7
|
||||
|
||||
The two queue interrupts are evenly distributed. Interrupt 48 is placed on CPU4
|
||||
because the managed_irq mask avoids CPUs 5–7 when possible.
|
||||
|
||||
Replacing the managed_irq argument with "isolcpus=managed_irq,1-3,4-5,7"
|
||||
results in::
|
||||
|
||||
/proc/irq/48/effective_affinity_list:6
|
||||
/proc/irq/48/smp_affinity_list:4-7
|
||||
|
||||
Interrupt 48 is now served on CPU6 because the system avoids CPUs 4, 5 and
|
||||
7. If CPU6 is taken offline, the interrupt migrates to one of the "isolated"
|
||||
CPUs::
|
||||
|
||||
/proc/irq/48/effective_affinity_list:7
|
||||
/proc/irq/48/smp_affinity_list:4-7
|
||||
|
||||
The interrupt is shut down once all CPUs listed in its smp_affinity mask are
|
||||
offline.
|
||||
@@ -96,7 +96,7 @@ NODE_CANCEL_ADDING_FIRST_MEMORY
|
||||
Generated if NODE_ADDING_FIRST_MEMORY fails.
|
||||
|
||||
NODE_ADDED_FIRST_MEMORY
|
||||
Generated when memory has become available fo this node for the first time.
|
||||
Generated when memory has become available for this node for the first time.
|
||||
|
||||
NODE_REMOVING_LAST_MEMORY
|
||||
Generated when the last memory available to this node is about to be offlined.
|
||||
|
||||
@@ -103,6 +103,42 @@ For debugging purposes there are also two conditionally-compiled macros:
|
||||
pr_debug() and pr_devel(), which are compiled-out unless ``DEBUG`` (or
|
||||
also ``CONFIG_DYNAMIC_DEBUG`` in the case of pr_debug()) is defined.
|
||||
|
||||
Avoiding lockups from excessive printk() use
|
||||
============================================
|
||||
|
||||
.. note::
|
||||
|
||||
This section is relevant only for legacy console drivers (those not
|
||||
using the nbcon API) and !PREEMPT_RT kernels. Once all console drivers
|
||||
are updated to nbcon, this documentation can be removed.
|
||||
|
||||
Using ``printk()`` in hot paths (such as interrupt handlers, timer
|
||||
callbacks, or high-frequency network receive routines) with legacy
|
||||
consoles (e.g., ``console=ttyS0``) may cause lockups. Legacy consoles
|
||||
synchronously acquire ``console_sem`` and block while flushing messages,
|
||||
potentially disabling interrupts long enough to trigger hard or soft
|
||||
lockup detectors.
|
||||
|
||||
To avoid this:
|
||||
|
||||
- Use rate-limited variants (e.g., ``pr_*_ratelimited()``) or one-time
|
||||
macros (e.g., ``pr_*_once()``) to reduce message frequency.
|
||||
- Assign lower log levels (e.g., ``KERN_DEBUG``) to non-essential messages
|
||||
and filter console output via ``console_loglevel``.
|
||||
- Use ``printk_deferred()`` to log messages immediately to the ringbuffer
|
||||
and defer console printing. This is a workaround for legacy consoles.
|
||||
- Port legacy console drivers to the non-blocking ``nbcon`` API (indicated
|
||||
by ``CON_NBCON``). This is the preferred solution, as nbcon consoles
|
||||
offload message printing to a dedicated kernel thread.
|
||||
|
||||
For temporary debugging, ``trace_printk()`` can be used, but it must not
|
||||
appear in mainline code. See ``Documentation/trace/debugging.rst`` for
|
||||
more information.
|
||||
|
||||
If more permanent output is needed in a hot path, trace events can be used.
|
||||
See ``Documentation/trace/events.rst`` and
|
||||
``samples/trace_events/trace-events-sample.[ch]``.
|
||||
|
||||
|
||||
Function reference
|
||||
==================
|
||||
|
||||
@@ -74,7 +74,7 @@ Exception handlers
|
||||
Enabling interrupts is especially important on PREEMPT_RT, where certain
|
||||
locks, such as spinlock_t, become sleepable. For example, handling an
|
||||
invalid opcode may result in sending a SIGILL signal to the user task. A
|
||||
debug excpetion will send a SIGTRAP signal.
|
||||
debug exception will send a SIGTRAP signal.
|
||||
In both cases, if the exception occurred in user space, it is safe to enable
|
||||
interrupts early. Sending a signal requires both interrupts and kernel
|
||||
preemption to be enabled.
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user