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

From the main tty_port functions, only tty_port_destroy() was
documented. Document more of them, so that we can reference them in
Documentation/ later in this series.

Signed-off-by: Jiri Slaby <jslaby@suse.cz>
---
 drivers/tty/tty_port.c | 54 ++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 52 insertions(+), 2 deletions(-)

diff --git a/drivers/tty/tty_port.c b/drivers/tty/tty_port.c
index ebb441ee92d5..7709ce655f44 100644
--- a/drivers/tty/tty_port.c
+++ b/drivers/tty/tty_port.c
@@ -59,6 +59,15 @@ const struct tty_port_client_operations tty_port_default_client_ops = {
 };
 EXPORT_SYMBOL_GPL(tty_port_default_client_ops);
 
+/**
+ * tty_port_init -- initialize tty_port
+ * @port: tty_port to initialize
+ *
+ * Initializes the state of struct tty_port. When a port was initialized using
+ * this function, one has to destroy the port by tty_port_destroy(). Either
+ * indirectly by using &tty_port refcounting (tty_port_put()) or directly if
+ * refcounting is not used.
+ */
 void tty_port_init(struct tty_port *port)
 {
 	memset(port, 0, sizeof(*port));
@@ -267,6 +276,13 @@ static void tty_port_destructor(struct kref *kref)
 		kfree(port);
 }
 
+/**
+ * tty_port_put -- drop a reference to tty_port
+ * @port: port to drop a reference of (can be NULL)
+ *
+ * The final put will destroy and free up the @port using
+ * @port->ops->destruct() hook, or using kfree() if not provided.
+ */
 void tty_port_put(struct tty_port *port)
 {
 	if (port)
@@ -312,6 +328,16 @@ void tty_port_tty_set(struct tty_port *port, struct tty_struct *tty)
 }
 EXPORT_SYMBOL(tty_port_tty_set);
 
+/**
+ * tty_port_shutdown - internal helper to shutdown the device
+ * @port: tty port to be shut down
+ * @tty: the associated tty
+ *
+ * It is used by tty_port_hangup() and tty_port_close(). Its task is to
+ * shutdown the device if it was initialized (note consoles remain
+ * functioning). It lowers DTR/RTS (if @tty has HUPCL set) and invokes
+ * @port->ops->shutdown().
+ */
 static void tty_port_shutdown(struct tty_port *port, struct tty_struct *tty)
 {
 	mutex_lock(&port->mutex);
@@ -559,7 +585,21 @@ static void tty_port_drain_delay(struct tty_port *port, struct tty_struct *tty)
 	schedule_timeout_interruptible(timeout);
 }
 
-/* Caller holds tty lock. */
+/**
+ * tty_port_close_start - helper for tty->ops->close, part 1/2
+ * @port: tty_port of the device
+ * @tty: tty being closed
+ * @filp: passed file pointer
+ *
+ * Decrements and checks open count. Flushes the port if this is the last
+ * close. That means, dropping the data from the outpu buffer on the device and
+ * waiting for sending logic to finish. The rest of close handling is performed
+ * in tty_port_close_end().
+ *
+ * Locking: Caller holds tty lock.
+ *
+ * Return: 1 if this is the last close, otherwise 0
+ */
 int tty_port_close_start(struct tty_port *port,
 				struct tty_struct *tty, struct file *filp)
 {
@@ -605,7 +645,17 @@ int tty_port_close_start(struct tty_port *port,
 }
 EXPORT_SYMBOL(tty_port_close_start);
 
-/* Caller holds tty lock */
+/**
+ * tty_port_close_end - helper for tty->ops->close, part 2/2
+ * @port: tty_port of the device
+ * @tty: tty being closed
+ *
+ * This is a continuation of the first part: tty_port_close_start(). This
+ * should be called after turning off the device. It flushes the data from the
+ * line discipline and delays the close by @port->close_delay.
+ *
+ * Locking: Caller holds tty lock.
+ */
 void tty_port_close_end(struct tty_port *port, struct tty_struct *tty)
 {
 	unsigned long flags;
-- 
2.34.0


  parent reply	other threads:[~2021-11-26  8:21 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 ` [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 ` Jiri Slaby [this message]
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-19-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 18/23] tty: add kernel-doc for more tty_port functions' \
    /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).