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

tty_port 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 purpose and handling is documented at the end too --
some pieces of preexisting text moved to this place.

Signed-off-by: Jiri Slaby <jslaby@suse.cz>
---
 include/linux/tty_port.h | 104 ++++++++++++++++++++++++++-------------
 1 file changed, 70 insertions(+), 34 deletions(-)

diff --git a/include/linux/tty_port.h b/include/linux/tty_port.h
index 6e86e9e118b6..9091e1c8de4c 100644
--- a/include/linux/tty_port.h
+++ b/include/linux/tty_port.h
@@ -7,17 +7,6 @@
 #include <linux/tty_buffer.h>
 #include <linux/wait.h>
 
-/*
- * Port level information. Each device keeps its own port level information
- * so provide a common structure for those ports wanting to use common support
- * routines.
- *
- * The tty port has a different lifetime to the tty so must be kept apart.
- * In addition be careful as tty -> port mappings are valid for the life
- * of the tty object but in many cases port -> tty mappings are valid only
- * until a hangup so don't use the wrong path.
- */
-
 struct attribute_group;
 struct tty_driver;
 struct tty_port;
@@ -48,30 +37,77 @@ struct tty_port_client_operations {
 
 extern const struct tty_port_client_operations tty_port_default_client_ops;
 
+/**
+ * struct tty_port -- port level information
+ *
+ * @buf: buffer for this port, locked internally
+ * @tty: back pointer to &struct tty_struct, valid only if the tty is open. Use
+ *	 tty_port_tty_get() to obtain it (and tty_kref_put() to release).
+ * @itty: internal back pointer to &struct tty_struct. Avoid this. It should be
+ *	  eliminated in the long term.
+ * @ops: tty port operations (like activate, shutdown), see &struct
+ *	 tty_port_operations
+ * @client_ops: tty port client operations (like receive_buf, write_wakeup).
+ *		By default, tty_port_default_client_ops is used.
+ * @lock: lock protecting @tty
+ * @blocked_open: # of procs waiting for open in tty_port_block_til_ready()
+ * @count: usage count
+ * @open_wait: open waiters queue (waiting e.g. for a carrier)
+ * @delta_msr_wait: modem status change queue (waiting for MSR changes)
+ * @flags: user TTY flags (%ASYNC_)
+ * @iflags: internal flags (%TTY_PORT_)
+ * @console: when set, the port is a console
+ * @mutex: locking, for open, shutdown and other port operations
+ * @buf_mutex: @xmit_buf alloc lock
+ * @xmit_buf: optional xmit buffer used by some drivers
+ * @close_delay: delay in jiffies to wait when closing the port
+ * @closing_wait: delay in jiffies for output to be sent before closing
+ * @drain_delay: set to zero if no pure time based drain is needed else set to
+ *		 size of fifo
+ * @kref: references counter. Reaching zero calls @ops->destruct() if non-%NULL
+ *	  or frees the port otherwise.
+ * @client_data: pointer to private data, for @client_ops
+ *
+ * Each device keeps its own port level information. &struct tty_port was
+ * introduced as a common structure for such information. As every TTY device
+ * shall have a backing tty_port structure, every driver can use these members.
+ *
+ * The tty port has a different lifetime to the tty so must be kept apart.
+ * In addition be careful as tty -> port mappings are valid for the life
+ * of the tty object but in many cases port -> tty mappings are valid only
+ * until a hangup so don't use the wrong path.
+ *
+ * Tty port shall be initialized by tty_port_init() and shut down either by
+ * tty_port_destroy() (refcounting not used), or tty_port_put() (refcounting).
+ *
+ * There is a lot of helpers around &struct tty_port too. To name the most
+ * significant ones: tty_port_open(), tty_port_close() (or
+ * tty_port_close_start() and tty_port_close_end() separately if need be), and
+ * tty_port_hangup(). These call @ops->activate() and @ops->shutdown() as
+ * needed.
+ */
 struct tty_port {
-	struct tty_bufhead	buf;		/* Locked internally */
-	struct tty_struct	*tty;		/* Back pointer */
-	struct tty_struct	*itty;		/* internal back ptr */
-	const struct tty_port_operations *ops;	/* Port operations */
-	const struct tty_port_client_operations *client_ops; /* Port client operations */
-	spinlock_t		lock;		/* Lock protecting tty field */
-	int			blocked_open;	/* Waiting to open */
-	int			count;		/* Usage count */
-	wait_queue_head_t	open_wait;	/* Open waiters */
-	wait_queue_head_t	delta_msr_wait;	/* Modem status change */
-	unsigned long		flags;		/* User TTY flags ASYNC_ */
-	unsigned long		iflags;		/* Internal flags TTY_PORT_ */
-	unsigned char		console:1;	/* port is a console */
-	struct mutex		mutex;		/* Locking */
-	struct mutex		buf_mutex;	/* Buffer alloc lock */
-	unsigned char		*xmit_buf;	/* Optional buffer */
-	unsigned int		close_delay;	/* Close port delay */
-	unsigned int		closing_wait;	/* Delay for output */
-	int			drain_delay;	/* Set to zero if no pure time
-						   based drain is needed else
-						   set to size of fifo */
-	struct kref		kref;		/* Ref counter */
-	void 			*client_data;
+	struct tty_bufhead	buf;
+	struct tty_struct	*tty;
+	struct tty_struct	*itty;
+	const struct tty_port_operations *ops;
+	const struct tty_port_client_operations *client_ops;
+	spinlock_t		lock;
+	int			blocked_open;
+	int			count;
+	wait_queue_head_t	open_wait;
+	wait_queue_head_t	delta_msr_wait;
+	unsigned long		flags;
+	unsigned long		iflags;
+	unsigned char		console:1;
+	struct mutex		mutex;
+	struct mutex		buf_mutex;
+	unsigned char		*xmit_buf;
+	unsigned int		close_delay;
+	unsigned int		closing_wait;
+	int			drain_delay;
+	struct kref		kref;
+	void			*client_data;
 };
 
 /* tty_port::iflags bits -- use atomic bit ops */
-- 
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 ` Jiri Slaby [this message]
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 ` [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-3-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 02/23] tty: add kernel-doc for tty_port' \
    /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).