mirror of https://lore.kernel.org/lkml/
 help / color / mirror / Atom feed
From: John Ogness <john.ogness@linutronix.de>
To: Petr Mladek <pmladek@suse.com>
Cc: Sergey Senozhatsky <senozhatsky@chromium.org>,
	Steven Rostedt <rostedt@goodmis.org>,
	Thomas Gleixner <tglx@linutronix.de>,
	linux-kernel@vger.kernel.org,
	Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Subject: [PATCH printk v6 05/30] printk: nbcon: Add detailed doc for write_atomic()
Date: Mon, 27 May 2024 08:43:24 +0206	[thread overview]
Message-ID: <20240527063749.391035-6-john.ogness@linutronix.de> (raw)
In-Reply-To: <20240527063749.391035-1-john.ogness@linutronix.de>

The write_atomic() callback has special requirements and is
allowed to use special helper functions. Provide detailed
documentation of the callback so that a developer has a
chance of implementing it correctly.

Signed-off-by: John Ogness <john.ogness@linutronix.de>
Reviewed-by: Petr Mladek <pmladek@suse.com>
---
 include/linux/console.h | 33 +++++++++++++++++++++++++++++----
 1 file changed, 29 insertions(+), 4 deletions(-)

diff --git a/include/linux/console.h b/include/linux/console.h
index 54b98e4f0544..3291cc340f1a 100644
--- a/include/linux/console.h
+++ b/include/linux/console.h
@@ -285,7 +285,7 @@ struct nbcon_write_context {
 /**
  * struct console - The console descriptor structure
  * @name:		The name of the console driver
- * @write:		Write callback to output messages (Optional)
+ * @write:		Legacy write callback to output messages (Optional)
  * @read:		Read callback for console input (Optional)
  * @device:		The underlying TTY device driver (Optional)
  * @unblank:		Callback to unblank the console (Optional)
@@ -302,7 +302,6 @@ struct nbcon_write_context {
  * @data:		Driver private data
  * @node:		hlist node for the console list
  *
- * @write_atomic:	Write callback for atomic context
  * @nbcon_state:	State for nbcon consoles
  * @nbcon_seq:		Sequence number of the next record for nbcon to print
  * @pbufs:		Pointer to nbcon private buffer
@@ -327,8 +326,34 @@ struct console {
 	struct hlist_node	node;
 
 	/* nbcon console specific members */
-	void			(*write_atomic)(struct console *con,
-						struct nbcon_write_context *wctxt);
+
+	/**
+	 * @write_atomic:
+	 *
+	 * NBCON callback to write out text in any context.
+	 *
+	 * This callback is called with the console already acquired. However,
+	 * a higher priority context is allowed to take it over by default.
+	 *
+	 * The callback must call nbcon_enter_unsafe() and nbcon_exit_unsafe()
+	 * around any code where the takeover is not safe, for example, when
+	 * manipulating the serial port registers.
+	 *
+	 * nbcon_enter_unsafe() will fail if the context has lost the console
+	 * ownership in the meantime. In this case, the callback is no longer
+	 * allowed to go forward. It must back out immediately and carefully.
+	 * The buffer content is also no longer trusted since it no longer
+	 * belongs to the context.
+	 *
+	 * The callback should allow the takeover whenever it is safe. It
+	 * increases the chance to see messages when the system is in trouble.
+	 *
+	 * The callback can be called from any context (including NMI).
+	 * Therefore it must avoid usage of any locking and instead rely
+	 * on the console ownership for synchronization.
+	 */
+	void (*write_atomic)(struct console *con, struct nbcon_write_context *wctxt);
+
 	atomic_t		__private nbcon_state;
 	atomic_long_t		__private nbcon_seq;
 	struct printk_buffers	*pbufs;
-- 
2.39.2


  parent reply	other threads:[~2024-05-27  6:38 UTC|newest]

Thread overview: 36+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2024-05-27  6:37 [PATCH printk v6 00/30] wire up write_atomic() printing John Ogness
2024-05-27  6:37 ` [PATCH printk v6 01/30] printk: Add notation to console_srcu locking John Ogness
2024-05-27  6:37 ` [PATCH printk v6 02/30] printk: Properly deal with nbcon consoles on seq init John Ogness
2024-05-27  6:37 ` [PATCH printk v6 03/30] printk: nbcon: Remove return value for write_atomic() John Ogness
2024-05-27  6:37 ` [PATCH printk v6 04/30] printk: Check printk_deferred_enter()/_exit() usage John Ogness
2024-05-27  6:37 ` John Ogness [this message]
2024-05-27  6:37 ` [PATCH printk v6 06/30] printk: nbcon: Add callbacks to synchronize with driver John Ogness
2024-05-27  6:37 ` [PATCH printk v6 07/30] printk: nbcon: Use driver synchronization while (un)registering John Ogness
2024-05-27  6:37 ` [PATCH printk v6 08/30] serial: core: Provide low-level functions to lock port John Ogness
2024-05-27  6:37 ` [PATCH printk v6 09/30] serial: core: Introduce wrapper to set @uart_port->cons John Ogness
2024-05-27  6:37 ` [PATCH printk v6 10/30] console: Improve console_srcu_read_flags() comments John Ogness
2024-05-27  6:37 ` [PATCH printk v6 11/30] nbcon: Add API to acquire context for non-printing operations John Ogness
2024-05-27  6:37 ` [PATCH printk v6 12/30] serial: core: Implement processing in port->lock wrapper John Ogness
2024-05-27  6:37 ` [PATCH printk v6 13/30] printk: nbcon: Do not rely on proxy headers John Ogness
2024-05-27  6:37 ` [PATCH printk v6 14/30] printk: nbcon: Fix kerneldoc for enums John Ogness
2024-05-27  6:37 ` [PATCH printk v6 15/30] printk: Make console_is_usable() available to nbcon John Ogness
2024-05-27  6:37 ` [PATCH printk v6 16/30] printk: Let console_is_usable() handle nbcon John Ogness
2024-05-27  6:37 ` [PATCH printk v6 17/30] printk: Add @flags argument for console_is_usable() John Ogness
2024-05-27  6:37 ` [PATCH printk v6 18/30] printk: nbcon: Add helper to assign priority based on CPU state John Ogness
2024-05-27  6:37 ` [PATCH printk v6 19/30] printk: nbcon: Provide function to flush using write_atomic() John Ogness
2024-05-28  9:30   ` Petr Mladek
2024-05-27  6:37 ` [PATCH printk v6 20/30] printk: Track registered boot consoles John Ogness
2024-05-27  6:37 ` [PATCH printk v6 21/30] printk: nbcon: Use nbcon consoles in console_flush_all() John Ogness
2024-05-27  6:37 ` [PATCH printk v6 22/30] printk: nbcon: Add unsafe flushing on panic John Ogness
2024-05-27  6:37 ` [PATCH printk v6 23/30] printk: Avoid console_lock dance if no legacy or boot consoles John Ogness
2024-05-27  6:37 ` [PATCH printk v6 24/30] printk: Track nbcon consoles John Ogness
2024-05-27  6:37 ` [PATCH printk v6 25/30] printk: Coordinate direct printing in panic John Ogness
2024-05-27  6:37 ` [PATCH printk v6 26/30] printk: nbcon: Implement emergency sections John Ogness
2024-05-28  9:57   ` Petr Mladek
2024-05-27  6:37 ` [PATCH printk v6 27/30] panic: Mark emergency section in warn John Ogness
2024-05-27  6:37 ` [PATCH printk v6 28/30] panic: Mark emergency section in oops John Ogness
2024-05-27  6:37 ` [PATCH printk v6 29/30] rcu: Mark emergency sections in rcu stalls John Ogness
2024-05-28 10:04   ` Petr Mladek
2024-05-27  6:37 ` [PATCH printk v6 30/30] lockdep: Mark emergency sections in lockdep splats John Ogness
2024-05-28 10:10 ` [PATCH printk v6 00/30] wire up write_atomic() printing Petr Mladek
2024-05-28 13:35   ` Petr Mladek

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20240527063749.391035-6-john.ogness@linutronix.de \
    --to=john.ogness@linutronix.de \
    --cc=gregkh@linuxfoundation.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=pmladek@suse.com \
    --cc=rostedt@goodmis.org \
    --cc=senozhatsky@chromium.org \
    --cc=tglx@linutronix.de \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox

all inboxes | Powered by JetHome®