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 14/18] printk: Document struct console
Date: Sat, 24 Sep 2022 02:10:50 +0206 [thread overview]
Message-ID: <20220924000454.3319186-15-john.ogness@linutronix.de> (raw)
In-Reply-To: <20220924000454.3319186-1-john.ogness@linutronix.de>
From: Thomas Gleixner <tglx@linutronix.de>
Add docbook comments to struct console.
Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: John Ogness <john.ogness@linutronix.de>
---
include/linux/console.h | 95 +++++++++++++++++++++++++++++------------
1 file changed, 68 insertions(+), 27 deletions(-)
diff --git a/include/linux/console.h b/include/linux/console.h
index 3bb5bc62e154..8ec24fe097d3 100644
--- a/include/linux/console.h
+++ b/include/linux/console.h
@@ -15,6 +15,7 @@
#define _LINUX_CONSOLE_H_ 1
#include <linux/atomic.h>
+#include <linux/bits.h>
#include <linux/rculist.h>
#include <linux/types.h>
@@ -139,37 +140,77 @@ static inline int con_debug_leave(void)
/*
* The interface for a console, or any other device that wants to capture
* console messages (printer driver?)
- *
- * If a console driver is marked CON_BOOT then it will be auto-unregistered
- * when the first real console is registered. This is for early-printk drivers.
*/
-#define CON_PRINTBUFFER (1)
-#define CON_CONSDEV (2) /* Preferred console, /dev/console */
-#define CON_ENABLED (4)
-#define CON_BOOT (8)
-#define CON_ANYTIME (16) /* Safe to call when cpu is offline */
-#define CON_BRL (32) /* Used for a braille device */
-#define CON_EXTENDED (64) /* Use the extended output format a la /dev/kmsg */
+/**
+ * cons_flags - General console flags
+ * @CON_PRINTBUFFER: On register, start from the oldest dmesg record
+ * @CON_CONSDEV: Questionable historical leftover to denote which console
+ * driver is the preferred console which is defining what
+ * backs up /dev/console
+ * @CON_ENABLED: Indicates if a console is allowed to print records. If false,
+ * the console also will not advance to later records.
+ * @CON_BOOT: Marks the console driver as early console driver which
+ * is used during boot before the real driver becomes available.
+ * It will be automatically unregistered unless the early console
+ * command line parameter for this console has the 'keep' option set.
+ * @CON_ANYTIME: A misnomed historical flag which tells the core code that the
+ * legacy @console::write callback can be invoked on a CPU which
+ * is marked OFFLINE. That's misleading as it suggests that there
+ * is no contextual limit for invoking the callback.
+ * @CON_BRL: Indicates a braille device which is exempt from receiving the
+ * printk spam for obvious reasons
+ * @CON_EXTENDED: The console supports the extended output format of /dev/kmesg
+ * which requires a larger output record buffer
+ */
+enum cons_flags {
+ CON_PRINTBUFFER = BIT(0),
+ CON_CONSDEV = BIT(1),
+ CON_ENABLED = BIT(2),
+ CON_BOOT = BIT(3),
+ CON_ANYTIME = BIT(4),
+ CON_BRL = BIT(5),
+ CON_EXTENDED = BIT(6),
+};
+/**
+ * struct console - The console descriptor structure
+ * @name: The name of the console driver
+ * @write: 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)
+ * @setup: Callback for initializing the console (Optional)
+ * @exit: Callback for teardown of the console (Optional)
+ * @match: Callback for matching a console (Optional)
+ * @flags: Console flags. See enum cons_flags
+ * @index: Console index, e.g. port number
+ * @cflag: TTY control mode flags
+ * @ispeed: TTY input speed
+ * @ospeed: TTY output speed
+ * @seq: Sequence number of the next ringbuffer record to print
+ * @dropped: Number of dropped ringbuffer records
+ * @data: Driver private data
+ * @node: hlist node for the console list
+ */
struct console {
- char name[16];
- void (*write)(struct console *, const char *, unsigned);
- int (*read)(struct console *, char *, unsigned);
- struct tty_driver *(*device)(struct console *, int *);
- void (*unblank)(void);
- int (*setup)(struct console *, char *);
- int (*exit)(struct console *);
- int (*match)(struct console *, char *name, int idx, char *options);
- short flags;
- short index;
- int cflag;
- uint ispeed;
- uint ospeed;
- u64 seq;
- unsigned long dropped;
- void *data;
- struct hlist_node node;
+ char name[16];
+ void (*write)(struct console *, const char *, unsigned);
+ int (*read)(struct console *, char *, unsigned);
+ struct tty_driver *(*device)(struct console *, int *);
+ void (*unblank)(void);
+ int (*setup)(struct console *, char *);
+ int (*exit)(struct console *);
+ int (*match)(struct console *, char *name, int idx, char *options);
+ short flags;
+ short index;
+ int cflag;
+ uint ispeed;
+ uint ospeed;
+ u64 seq;
+ unsigned long dropped;
+ void *data;
+ struct hlist_node node;
};
#ifdef CONFIG_LOCKDEP
--
2.30.2
next prev parent reply other threads:[~2022-09-24 0:06 UTC|newest]
Thread overview: 75+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-09-24 0:04 [PATCH printk 00/18] preparation for threaded/atomic printing John Ogness
2022-09-24 0:04 ` [PATCH printk 01/18] printk: Make pr_flush() static John Ogness
2022-09-26 14:12 ` Petr Mladek
2022-09-24 0:04 ` [PATCH printk 02/18] printk: Declare log_wait properly John Ogness
2022-09-26 14:22 ` Petr Mladek
2022-09-24 0:04 ` [PATCH printk 03/18] printk: Remove write only variable nr_ext_console_drivers John Ogness
2022-09-26 14:25 ` Petr Mladek
2022-09-24 0:04 ` [PATCH printk 04/18] printk: Remove bogus comment vs. boot consoles John Ogness
2022-09-26 14:26 ` Petr Mladek
2022-09-24 0:04 ` [PATCH printk 05/18] printk: Mark __printk percpu data ready __ro_after_init John Ogness
2022-09-26 14:27 ` Petr Mladek
2022-09-24 0:04 ` [PATCH printk 06/18] printk: Protect [un]register_console() with a mutex John Ogness
2022-09-24 9:31 ` Sergey Senozhatsky
2022-09-27 15:16 ` Petr Mladek
2022-09-28 9:46 ` Sergey Senozhatsky
2022-09-28 23:42 ` John Ogness
2022-09-29 15:43 ` Petr Mladek
2022-09-30 9:24 ` Petr Mladek
2022-09-30 14:16 ` John Ogness
2022-09-30 18:04 ` Petr Mladek
2022-09-30 20:26 ` John Ogness
2022-10-03 14:37 ` Petr Mladek
2022-10-03 19:35 ` John Ogness
2022-10-04 2:06 ` Sergey Senozhatsky
2022-10-04 7:28 ` Petr Mladek
2022-09-30 13:30 ` John Ogness
2022-09-24 0:04 ` [PATCH printk 07/18] printk: Convert console list walks for readers to list lock John Ogness
2022-09-27 14:07 ` Petr Mladek
2022-09-24 0:04 ` [PATCH printk 08/18] parisc: Put console abuse into one place John Ogness
2022-09-24 0:20 ` Steven Rostedt
2022-09-30 7:54 ` Petr Mladek
2022-09-24 0:04 ` [PATCH printk 09/18] serial: kgdboc: Lock console list in probe function John Ogness
2022-09-28 23:32 ` Doug Anderson
2022-09-30 8:07 ` Petr Mladek
2022-09-24 0:04 ` [PATCH printk 10/18] kgbd: Pretend that console list walk is safe John Ogness
2022-09-26 9:33 ` Aaron Tomlin
2022-09-28 23:32 ` Doug Anderson
2022-09-30 8:39 ` Petr Mladek
2022-09-30 13:44 ` John Ogness
2022-09-30 17:27 ` Petr Mladek
2022-09-24 0:04 ` [PATCH printk 11/18] printk: Convert console_drivers list to hlist John Ogness
2022-09-24 10:53 ` Sergey Senozhatsky
2022-09-24 17:20 ` Helge Deller
2022-09-25 0:43 ` Sergey Senozhatsky
2022-09-24 17:27 ` Helge Deller
2022-09-30 14:20 ` Petr Mladek
2022-09-30 16:53 ` Helge Deller
2022-09-30 19:46 ` John Ogness
2022-09-30 22:41 ` Helge Deller
2022-09-24 0:04 ` [PATCH printk 12/18] printk: Prepare for SCRU console list protection John Ogness
2022-09-24 10:58 ` Sergey Senozhatsky
2022-09-24 0:04 ` [PATCH printk 13/18] printk: Move buffer size defines John Ogness
2022-09-24 11:01 ` Sergey Senozhatsky
2022-10-07 9:11 ` Petr Mladek
2022-09-24 0:04 ` John Ogness [this message]
2022-09-24 11:08 ` [PATCH printk 14/18] printk: Document struct console Sergey Senozhatsky
2022-10-07 11:57 ` Petr Mladek
2022-09-24 0:04 ` [PATCH printk 15/18] printk: Add struct cons_text_buf John Ogness
2022-09-24 11:09 ` Sergey Senozhatsky
2022-10-07 15:15 ` Petr Mladek
2022-09-24 0:04 ` [PATCH printk 16/18] printk: Use " John Ogness
2022-09-24 11:34 ` Sergey Senozhatsky
2022-10-10 10:11 ` Petr Mladek
2022-09-24 0:04 ` [PATCH printk 17/18] printk: Use an output descriptor struct for emit John Ogness
2022-10-10 15:40 ` Petr Mladek
2022-09-24 0:04 ` [PATCH printk 18/18] printk: Handle dropped message smarter John Ogness
2022-09-26 4:19 ` Sergey Senozhatsky
2022-09-26 7:54 ` John Ogness
2022-09-26 9:18 ` Sergey Senozhatsky
2022-10-10 16:07 ` Petr Mladek
2022-09-26 9:22 ` Sergey Senozhatsky
2022-09-24 6:44 ` [PATCH printk 00/18] preparation for threaded/atomic printing Greg Kroah-Hartman
2022-09-25 15:23 ` John Ogness
2022-09-24 9:47 ` Sergey Senozhatsky
2022-09-29 16:33 ` 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=20220924000454.3319186-15-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;
as well as URLs for NNTP newsgroup(s).