tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

Documentation: printk: Add section about avoiding lockups

Add a section 'Avoiding lockups from excessive printk() use' to
printk-basics.rst, explaining the risk of calling printk() in hot paths
with legacy consoles and suggesting alternatives.

The section covers:
- Rate-limited and one-time printing variants
- Log level filtering
- printk_deferred() for legacy consoles
- Porting to nbcon API (preferred solution)
- Using tracepoints for permanent debugging

This documentation is relevant only for legacy console drivers and
!PREEMPT_RT kernels.

Suggested-by: Petr Mladek <pmladek@suse.com>
Suggested-by: John Ogness <john.ogness@linutronix.de>
Signed-off-by: h3288824963 <3288824963@qq.com>
Reviewed-by: John Ogness <john.ogness@linutronix.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <tencent_FB5B7DCFFB10BCDE325397D1202226779D09@qq.com>

authored by

h3288824963 and committed by
Jonathan Corbet 04c612f6 5e6df46d

+36
+36
Documentation/core-api/printk-basics.rst
··· 103 103 pr_debug() and pr_devel(), which are compiled-out unless ``DEBUG`` (or 104 104 also ``CONFIG_DYNAMIC_DEBUG`` in the case of pr_debug()) is defined. 105 105 106 + Avoiding lockups from excessive printk() use 107 + ============================================ 108 + 109 + .. note:: 110 + 111 + This section is relevant only for legacy console drivers (those not 112 + using the nbcon API) and !PREEMPT_RT kernels. Once all console drivers 113 + are updated to nbcon, this documentation can be removed. 114 + 115 + Using ``printk()`` in hot paths (such as interrupt handlers, timer 116 + callbacks, or high-frequency network receive routines) with legacy 117 + consoles (e.g., ``console=ttyS0``) may cause lockups. Legacy consoles 118 + synchronously acquire ``console_sem`` and block while flushing messages, 119 + potentially disabling interrupts long enough to trigger hard or soft 120 + lockup detectors. 121 + 122 + To avoid this: 123 + 124 + - Use rate-limited variants (e.g., ``pr_*_ratelimited()``) or one-time 125 + macros (e.g., ``pr_*_once()``) to reduce message frequency. 126 + - Assign lower log levels (e.g., ``KERN_DEBUG``) to non-essential messages 127 + and filter console output via ``console_loglevel``. 128 + - Use ``printk_deferred()`` to log messages immediately to the ringbuffer 129 + and defer console printing. This is a workaround for legacy consoles. 130 + - Port legacy console drivers to the non-blocking ``nbcon`` API (indicated 131 + by ``CON_NBCON``). This is the preferred solution, as nbcon consoles 132 + offload message printing to a dedicated kernel thread. 133 + 134 + For temporary debugging, ``trace_printk()`` can be used, but it must not 135 + appear in mainline code. See ``Documentation/trace/debugging.rst`` for 136 + more information. 137 + 138 + If more permanent output is needed in a hot path, trace events can be used. 139 + See ``Documentation/trace/events.rst`` and 140 + ``samples/trace_events/trace-events-sample.[ch]``. 141 + 106 142 107 143 Function reference 108 144 ==================