[PATCH v2] Documentation: printk: Add section about avoiding lockups

[PATCH v2] Documentation: printk: Add section about avoiding lockups

[h3288824963]

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>
---
 Documentation/core-api/printk-basics.rst | 36 ++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/Documentation/core-api/printk-basics.rst b/Documentation/core-api/printk-basics.rst
index 2dde24ca7..48eaff0ce 100644
--- a/Documentation/core-api/printk-basics.rst
+++ b/Documentation/core-api/printk-basics.rst
@@ -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
 ==================
-- 
2.53.0.windows.1

Re: [PATCH v2] Documentation: printk: Add section about avoiding lockups

[John Ogness]

On 2026-03-17, h3288824963 <3288824963@qq.com> wrote:
> 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>

Thanks for addressing my concerns.

Reviewed-by: John Ogness <john.ogness@linutronix.de>

Re: [PATCH v2] Documentation: printk: Add section about avoiding lockups

[Jonathan Corbet]

John Ogness <john.ogness@linutronix.de> writes:

> On 2026-03-17, h3288824963 <3288824963@qq.com> wrote:
>> 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>
>
> Thanks for addressing my concerns.
>
> Reviewed-by: John Ogness <john.ogness@linutronix.de>

Applied, thanks.

jon