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 03/23] tty: add kernel-doc for tty_driver
Date: Fri, 26 Nov 2021 09:15:51 +0100	[thread overview]
Message-ID: <20211126081611.11001-4-jslaby@suse.cz> (raw)
In-Reply-To: <20211126081611.11001-1-jslaby@suse.cz>

tty_driver used to have only short comments along its members. Convert
them into proper kernel-doc comments in front of the structure. And add
some more explanation to them where needed.

The whole structure handling is documented at the end too.

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

diff --git a/include/linux/tty_driver.h b/include/linux/tty_driver.h
index 795b94ccdeb6..3622404a678d 100644
--- a/include/linux/tty_driver.h
+++ b/include/linux/tty_driver.h
@@ -291,23 +291,61 @@ struct tty_operations {
 	int (*proc_show)(struct seq_file *, void *);
 } __randomize_layout;
 
+/**
+ * struct tty_driver -- driver for TTY devices
+ *
+ * @magic: set to %TTY_DRIVER_MAGIC in __tty_alloc_driver()
+ * @kref: reference counting. Reaching zero frees all the internals and the
+ *	  driver.
+ * @cdevs: allocated/registered character /dev devices
+ * @owner: modules owning this driver. Used drivers cannot be rmmod'ed.
+ *	   Automatically set by tty_alloc_driver().
+ * @driver_name: name of the driver used in /proc/tty
+ * @name: used for constructing /dev node name
+ * @name_base: used as a number base for constructing /dev node name
+ * @major: major /dev device number (zero for autoassignment)
+ * @minor_start: the first minor /dev device number
+ * @num: number of devices allocated
+ * @type: type of tty driver (%TTY_DRIVER_TYPE_)
+ * @subtype: subtype of tty driver (%SYSTEM_TYPE_, %PTY_TYPE_, %SERIAL_TYPE_)
+ * @init_termios: termios to set to each tty initially (e.g. %tty_std_termios)
+ * @flags: tty driver flags (%TTY_DRIVER_)
+ * @proc_entry: proc fs entry, used internally
+ * @other: driver of the linked tty; only used for the PTY driver
+ * @ttys: array of active &struct tty_struct, set by tty_standard_install()
+ * @ports: array of &struct tty_port; can be set during initialization by
+ *	   tty_port_link_device() and similar
+ * @termios: storage for termios at each TTY close for the next open
+ * @driver_state: pointer to driver's arbitrary data
+ * @ops: driver hooks for TTYs. Set them using tty_set_operations(). Use &struct
+ *	 tty_port helpers in them as much as possible.
+ * @tty_drivers: used internally to link tty_drivers together
+ *
+ * The usual handling of &struct tty_driver is to allocate it by
+ * tty_alloc_driver(), set up all the necessary members, and register it by
+ * tty_register_driver(). At last, the driver is torn down by calling
+ * tty_unregister_driver() followed by tty_driver_kref_put().
+ *
+ * The fields required to be set before calling tty_register_driver() include
+ * @driver_name, @name, @type, @subtype, @init_termios, and @ops.
+ */
 struct tty_driver {
-	int	magic;		/* magic number for this structure */
-	struct kref kref;	/* Reference management */
+	int	magic;
+	struct kref kref;
 	struct cdev **cdevs;
 	struct module	*owner;
 	const char	*driver_name;
 	const char	*name;
-	int	name_base;	/* offset of printed name */
-	int	major;		/* major device number */
-	int	minor_start;	/* start of minor device number */
-	unsigned int	num;	/* number of devices allocated */
-	short	type;		/* type of tty driver */
-	short	subtype;	/* subtype of tty driver */
-	struct ktermios init_termios; /* Initial termios */
-	unsigned long	flags;		/* tty driver flags */
-	struct proc_dir_entry *proc_entry; /* /proc fs entry */
-	struct tty_driver *other; /* only used for the PTY driver */
+	int	name_base;
+	int	major;
+	int	minor_start;
+	unsigned int	num;
+	short	type;
+	short	subtype;
+	struct ktermios init_termios;
+	unsigned long	flags;
+	struct proc_dir_entry *proc_entry;
+	struct tty_driver *other;
 
 	/*
 	 * Pointer to the tty data structures
-- 
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 ` Jiri Slaby [this message]
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 ` [PATCH 10/23] tty: reformat TTY_DRIVER_ flags " Jiri Slaby
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-4-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 03/23] tty: add kernel-doc for tty_driver' \
    /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).