2024-02-18 18:58:18

by John Ogness

Subject: [PATCH printk v2 09/26] 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 <[email protected]>
---
include/linux/console.h | 34 ++++++++++++++++++++++++++++++----
1 file changed, 30 insertions(+), 4 deletions(-)

diff --git a/include/linux/console.h b/include/linux/console.h
index e4fc6f7c1496..5c55faa013e8 100644
--- a/include/linux/console.h
+++ b/include/linux/console.h
@@ -278,7 +278,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)
@@ -295,7 +295,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
@@ -320,8 +319,35 @@ struct console {
struct hlist_node node;

/* nbcon console specific members */
- bool (*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. The
+ * callback can use nbcon_can_proceed() at any time to verify that
+ * it is still the owner of the console. In the case that it has
+ * lost ownership, it is no longer allowed to go forward. In this
+ * case it must back out immediately and carefully. The buffer
+ * content is also no longer trusted since it no longer belongs to
+ * the context.
+ *
+ * If the callback needs to perform actions where ownership is not
+ * allowed to be taken over, nbcon_enter_unsafe() and
+ * nbcon_exit_unsafe() can be used to mark such sections. These
+ * functions are also points of possible ownership transfer. If
+ * either function returns false, ownership has been lost.
+ *
+ * This 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.
+ *
+ * Returns true if all text was successfully written out and
+ * ownership was never lost, otherwise false.
+ */
+ bool (*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

2024-02-23 13:12:01

by Petr Mladek

Subject: Re: [PATCH printk v2 09/26] printk: nbcon: Add detailed doc for write_atomic()

On Sun 2024-02-18 20:03:09, John Ogness wrote:
> 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 <[email protected]>

Reviewed-by: Petr Mladek <[email protected]>

Best Regards,
Petr