tty: convert "TTY Struct Flags" to an enum

Convert TTY_* macros (flags) to an enum. This allows for easier
kernel-doc (the comment needed fine tuning), grouping of these nicely,
and proper checking.

Note that these are bit positions. So they are used such as
test_bit(TTY_THROTTLED, ...). Given these are not the user API (only
in-kernel API/ABI), the bit positions are NOT preserved in this patch.
All are renumbered naturally using the enum-auto-numbering.

Signed-off-by: Jiri Slaby (SUSE) <jirislaby@kernel.org>
Link: https://lore.kernel.org/r/20250317070046.24386-2-jirislaby@kernel.org
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

diff --git a/Documentation/driver-api/tty/tty_struct.rst b/Documentation/driver-api/tty/tty_struct.rst
index c72f5a4293b2cf925fe4856015c6fd62d6ba61f8..29caf1c1ca5f3ffd50124c9481a32f883085e4bd 100644 (file)
--- a/Documentation/driver-api/tty/tty_struct.rst
+++ b/Documentation/driver-api/tty/tty_struct.rst
@@ -72,7 +72,7 @@ TTY Struct Flags
 ================
 
 .. kernel-doc:: include/linux/tty.h
-   :doc: TTY Struct Flags
+   :identifiers: tty_struct_flags
 
 TTY Struct Reference
 ====================

diff --git a/include/linux/tty.h b/include/linux/tty.h
index 2372f9357240d1ec95bc5f887b73f04f58ff29ac..6bb4fb3845f0afdf1edaabf8161a64fd35169776 100644 (file)
--- a/include/linux/tty.h
+++ b/include/linux/tty.h
@@ -251,7 +251,7 @@ struct tty_file_private {
 };
 
 /**
- * DOC: TTY Struct Flags
+ * enum tty_struct_flags - TTY Struct Flags
  *
  * These bits are used in the :c:member:`tty_struct.flags` field.
  *
@@ -260,62 +260,64 @@ struct tty_file_private {
  * tty->write.  Thus, you must use the inline functions set_bit() and
  * clear_bit() to make things atomic.
  *
- * TTY_THROTTLED
+ * @TTY_THROTTLED:
  *     Driver input is throttled. The ldisc should call
  *     :c:member:`tty_driver.unthrottle()` in order to resume reception when
  *     it is ready to process more data (at threshold min).
  *
- * TTY_IO_ERROR
+ * @TTY_IO_ERROR:
  *     If set, causes all subsequent userspace read/write calls on the tty to
  *     fail, returning -%EIO. (May be no ldisc too.)
  *
- * TTY_OTHER_CLOSED
+ * @TTY_OTHER_CLOSED:
  *     Device is a pty and the other side has closed.
  *
- * TTY_EXCLUSIVE
+ * @TTY_EXCLUSIVE:
  *     Exclusive open mode (a single opener).
  *
- * TTY_DO_WRITE_WAKEUP
+ * @TTY_DO_WRITE_WAKEUP:
  *     If set, causes the driver to call the
  *     :c:member:`tty_ldisc_ops.write_wakeup()` method in order to resume
  *     transmission when it can accept more data to transmit.
  *
- * TTY_LDISC_OPEN
+ * @TTY_LDISC_OPEN:
  *     Indicates that a line discipline is open. For debugging purposes only.
  *
- * TTY_PTY_LOCK
+ * @TTY_PTY_LOCK:
  *     A flag private to pty code to implement %TIOCSPTLCK/%TIOCGPTLCK logic.
  *
- * TTY_NO_WRITE_SPLIT
+ * @TTY_NO_WRITE_SPLIT:
  *     Prevent driver from splitting up writes into smaller chunks (preserve
  *     write boundaries to driver).
  *
- * TTY_HUPPED
+ * @TTY_HUPPED:
  *     The TTY was hung up. This is set post :c:member:`tty_driver.hangup()`.
  *
- * TTY_HUPPING
+ * @TTY_HUPPING:
  *     The TTY is in the process of hanging up to abort potential readers.
  *
- * TTY_LDISC_CHANGING
+ * @TTY_LDISC_CHANGING:
  *     Line discipline for this TTY is being changed. I/O should not block
  *     when this is set. Use tty_io_nonblock() to check.
  *
- * TTY_LDISC_HALTED
+ * @TTY_LDISC_HALTED:
  *     Line discipline for this TTY was stopped. No work should be queued to
  *     this ldisc.
  */
-#define TTY_THROTTLED          0
-#define TTY_IO_ERROR           1
-#define TTY_OTHER_CLOSED       2
-#define TTY_EXCLUSIVE          3
-#define TTY_DO_WRITE_WAKEUP    5
-#define TTY_LDISC_OPEN         11
-#define TTY_PTY_LOCK           16
-#define TTY_NO_WRITE_SPLIT     17
-#define TTY_HUPPED             18
-#define TTY_HUPPING            19
-#define TTY_LDISC_CHANGING     20
-#define TTY_LDISC_HALTED       22
+enum tty_struct_flags {
+       TTY_THROTTLED,
+       TTY_IO_ERROR,
+       TTY_OTHER_CLOSED,
+       TTY_EXCLUSIVE,
+       TTY_DO_WRITE_WAKEUP,
+       TTY_LDISC_OPEN,
+       TTY_PTY_LOCK,
+       TTY_NO_WRITE_SPLIT,
+       TTY_HUPPED,
+       TTY_HUPPING,
+       TTY_LDISC_CHANGING,
+       TTY_LDISC_HALTED,
+};
 
 static inline bool tty_io_nonblock(struct tty_struct *tty, struct file *file)
 {