printk: nbcon: Add detailed doc for write_atomic()

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>
Link: https://lore.kernel.org/r/20240820063001.36405-8-john.ogness@linutronix.de
Signed-off-by: Petr Mladek <pmladek@suse.com>

diff --git a/include/linux/console.h b/include/linux/console.h
index 577b157fe4fb1a9bb0aff7669cfe53e0a1e40108..35c64ee3827b7f57e67fc87cf5fac1cf889eeb18 100644 (file)
--- a/include/linux/console.h
+++ b/include/linux/console.h
@@ -303,7 +303,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)
@@ -320,7 +320,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
@@ -345,8 +344,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. (Optional)
+        *
+        * 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;