LKML Archive on lore.kernel.org
help / color / mirror / Atom feed
From: Jiri Slaby <jslaby@suse.cz>
To: gregkh@linuxfoundation.org
Cc: linux-serial@vger.kernel.org, linux-kernel@vger.kernel.org,
	Jiri Slaby <jslaby@suse.cz>
Subject: [PATCH 10/23] tty: reformat TTY_DRIVER_ flags into kernel-doc
Date: Fri, 26 Nov 2021 09:15:58 +0100	[thread overview]
Message-ID: <20211126081611.11001-11-jslaby@suse.cz> (raw)
In-Reply-To: <20211126081611.11001-1-jslaby@suse.cz>

We want to reference TTY_DRIVER_* flags in Documentation/ later in this
series. But the current documentation in the TTY_DRIVER_*'s header does
not allow that. Reformat it to kernel-doc using "DOC" directive and
line-feeds, so that we can include it as it is.

Signed-off-by: Jiri Slaby <jslaby@suse.cz>
---
 include/linux/tty_driver.h | 90 ++++++++++++++++++++------------------
 1 file changed, 47 insertions(+), 43 deletions(-)

diff --git a/include/linux/tty_driver.h b/include/linux/tty_driver.h
index 41274d551e28..4841d8069c07 100644
--- a/include/linux/tty_driver.h
+++ b/include/linux/tty_driver.h
@@ -492,49 +492,53 @@ static inline void tty_set_operations(struct tty_driver *driver,
 /* tty driver magic number */
 #define TTY_DRIVER_MAGIC		0x5402
 
-/*
- * tty driver flags
- * 
- * TTY_DRIVER_RESET_TERMIOS --- requests the tty layer to reset the
- * 	termios setting when the last process has closed the device.
- * 	Used for PTY's, in particular.
- * 
- * TTY_DRIVER_REAL_RAW --- if set, indicates that the driver will
- * 	guarantee never to set any special character handling
- * 	flags if ((IGNBRK || (!BRKINT && !PARMRK)) && (IGNPAR ||
- * 	!INPCK)).  That is, if there is no reason for the driver to
- * 	send notifications of parity and break characters up to the
- * 	line driver, it won't do so.  This allows the line driver to
- *	optimize for this case if this flag is set.  (Note that there
- * 	is also a promise, if the above case is true, not to signal
- * 	overruns, either.)
- *
- * TTY_DRIVER_DYNAMIC_DEV --- if set, the individual tty devices need
- *	to be registered with a call to tty_register_device() when the
- *	device is found in the system and unregistered with a call to
- *	tty_unregister_device() so the devices will be show up
- *	properly in sysfs.  If not set, driver->num entries will be
- *	created by the tty core in sysfs when tty_register_driver() is
- *	called.  This is to be used by drivers that have tty devices
- *	that can appear and disappear while the main tty driver is
- *	registered with the tty core.
- *
- * TTY_DRIVER_DEVPTS_MEM -- don't use the standard arrays, instead
- *	use dynamic memory keyed through the devpts filesystem.  This
- *	is only applicable to the pty driver.
- *
- * TTY_DRIVER_HARDWARE_BREAK -- hardware handles break signals. Pass
- *	the requested timeout to the caller instead of using a simple
- *	on/off interface.
- *
- * TTY_DRIVER_DYNAMIC_ALLOC -- do not allocate structures which are
- *	needed per line for this driver as it would waste memory.
- *	The driver will take care.
- *
- * TTY_DRIVER_UNNUMBERED_NODE -- do not create numbered /dev nodes. In
- *	other words create /dev/ttyprintk and not /dev/ttyprintk0.
- *	Applicable only when a driver for a single tty device is
- *	being allocated.
+/**
+ * DOC: TTY Driver Flags
+ *
+ * TTY_DRIVER_RESET_TERMIOS
+ *	Requests the tty layer to reset the termios setting when the last
+ *	process has closed the device. Used for PTYs, in particular.
+ *
+ * TTY_DRIVER_REAL_RAW
+ *	Indicates that the driver will guarantee not to set any special
+ *	character handling flags if this is set for the tty:
+ *
+ *	``(IGNBRK || (!BRKINT && !PARMRK)) && (IGNPAR || !INPCK)``
+ *
+ *	That is, if there is no reason for the driver to
+ *	send notifications of parity and break characters up to the line
+ *	driver, it won't do so.  This allows the line driver to optimize for
+ *	this case if this flag is set.  (Note that there is also a promise, if
+ *	the above case is true, not to signal overruns, either.)
+ *
+ * TTY_DRIVER_DYNAMIC_DEV
+ *	The individual tty devices need to be registered with a call to
+ *	tty_register_device() when the device is found in the system and
+ *	unregistered with a call to tty_unregister_device() so the devices will
+ *	be show up properly in sysfs.  If not set, all &tty_driver.num entries
+ *	will be created by the tty core in sysfs when tty_register_driver() is
+ *	called.  This is to be used by drivers that have tty devices that can
+ *	appear and disappear while the main tty driver is registered with the
+ *	tty core.
+ *
+ * TTY_DRIVER_DEVPTS_MEM
+ *	Don't use the standard arrays (&tty_driver.ttys and
+ *	&tty_driver.termios), instead use dynamic memory keyed through the
+ *	devpts filesystem. This is only applicable to the PTY driver.
+ *
+ * TTY_DRIVER_HARDWARE_BREAK
+ *	Hardware handles break signals. Pass the requested timeout to the
+ *	&tty_operations.break_ctl instead of using a simple on/off interface.
+ *
+ * TTY_DRIVER_DYNAMIC_ALLOC
+ *	Do not allocate structures which are needed per line for this driver
+ *	(&tty_driver.ports) as it would waste memory. The driver will take
+ *	care. This is only applicable to the PTY driver.
+ *
+ * TTY_DRIVER_UNNUMBERED_NODE
+ *	Do not create numbered ``/dev`` nodes. For example, create
+ *	``/dev/ttyprintk`` and not ``/dev/ttyprintk0``. Applicable only when a
+ *	driver for a single tty device is being allocated.
  */
 #define TTY_DRIVER_INSTALLED		0x0001
 #define TTY_DRIVER_RESET_TERMIOS	0x0002
-- 
2.34.0


  parent reply	other threads:[~2021-11-26  8:18 UTC|newest]

Thread overview: 25+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-11-26  8:15 [PATCH 00/23] tty: documentation revamp Jiri Slaby
2021-11-26  8:15 ` [PATCH 01/23] tty: finish kernel-doc of tty_struct members Jiri Slaby
2021-11-26  8:15 ` [PATCH 02/23] tty: add kernel-doc for tty_port Jiri Slaby
2021-11-26  8:15 ` [PATCH 03/23] tty: add kernel-doc for tty_driver Jiri Slaby
2021-11-26  8:15 ` [PATCH 04/23] tty: add kernel-doc for tty_operations Jiri Slaby
2021-11-26  8:15 ` [PATCH 05/23] tty: add kernel-doc for tty_port_operations Jiri Slaby
2021-11-26  8:15 ` [PATCH 06/23] tty: add kernel-doc for tty_ldisc_ops Jiri Slaby
2021-11-26  8:15 ` [PATCH 07/23] tty: combine tty_operations triple docs into kernel-doc Jiri Slaby
2021-11-26  8:15 ` [PATCH 08/23] tty: combine tty_ldisc_ops " Jiri Slaby
2021-11-26  8:15 ` [PATCH 09/23] tty: reformat tty_struct::flags " Jiri Slaby
2021-11-26  8:15 ` Jiri Slaby [this message]
2021-11-26  8:15 ` [PATCH 11/23] tty: reformat kernel-doc in tty_port.c Jiri Slaby
2021-11-26  8:16 ` [PATCH 12/23] tty: reformat kernel-doc in tty_io.c Jiri Slaby
2021-11-26  8:16 ` [PATCH 13/23] tty: reformat kernel-doc in tty_ldisc.c Jiri Slaby
2021-11-26  8:16 ` [PATCH 14/23] tty: reformat kernel-doc in tty_buffer.c Jiri Slaby
2021-11-26  8:16 ` [PATCH 15/23] tty: fix kernel-doc in n_tty.c Jiri Slaby
2021-11-26  8:16 ` [PATCH 16/23] tty: reformat " Jiri Slaby
2021-11-26  8:16 ` [PATCH 17/23] tty: add kernel-doc for more tty_driver functions Jiri Slaby
2021-11-26  8:16 ` [PATCH 18/23] tty: add kernel-doc for more tty_port functions Jiri Slaby
2021-11-26  8:16 ` [PATCH 19/23] tty: move tty_ldisc docs to new Documentation/tty/ Jiri Slaby
2021-11-26  8:16 ` [PATCH 20/23] tty: make tty_ldisc docs up-to-date Jiri Slaby
2021-11-26  8:16 ` [PATCH 21/23] tty: more kernel-doc for tty_ldisc Jiri Slaby
2021-11-26  8:16 ` [PATCH 22/23] tty: add kernel-doc for tty_standard_install Jiri Slaby
2021-11-26  8:16 ` [PATCH 23/23] Documentation: add TTY chapter Jiri Slaby
2021-11-26 15:28 ` [PATCH 00/23] tty: documentation revamp Greg KH

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=20211126081611.11001-11-jslaby@suse.cz \
    --to=jslaby@suse.cz \
    --cc=gregkh@linuxfoundation.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux-serial@vger.kernel.org \
    --subject='Re: [PATCH 10/23] tty: reformat TTY_DRIVER_ flags into kernel-doc' \
    /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

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).