linux-kernel - [PATCH 3/4] tty: fix kernel-doc for tty

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <20210519072153.3859-3-jslaby@suse.cz>
Date:   Wed, 19 May 2021 09:21:52 +0200
From:   Jiri Slaby <jslaby@...e.cz>
To:     gregkh@...uxfoundation.org
Cc:     linux-serial@...r.kernel.org, linux-kernel@...r.kernel.org,
        Jiri Slaby <jslaby@...e.cz>,
        Linus Torvalds <torvalds@...ux-foundation.org>
Subject: [PATCH 3/4] tty: fix kernel-doc for tty_{read,write}

After commits a9cbbb80e3e7 (tty: avoid using vfs_iocb_iter_write() for
redirected console writes) and dd78b0c483e3 (tty: implement read_iter),
the tty_read and tty_write kernel-doc comments don't match the code:
 tty_io.c:931: warning: Function parameter or member 'iocb' not described in 'tty_read'
 tty_io.c:931: warning: Function parameter or member 'to' not described in 'tty_read'
 tty_io.c:931: warning: Excess function parameter 'file' description in 'tty_read'
 tty_io.c:931: warning: Excess function parameter 'buf' description in 'tty_read'
 tty_io.c:931: warning: Excess function parameter 'count' description in 'tty_read'
 tty_io.c:931: warning: Excess function parameter 'ppos' description in 'tty_read'
 tty_io.c:1115: warning: Function parameter or member 'iocb' not described in 'file_tty_write'
 tty_io.c:1115: warning: Function parameter or member 'from' not described in 'file_tty_write'
 tty_io.c:1115: warning: expecting prototype for tty_write(). Prototype was for file_tty_write() instead

Fix them to correspond the reality, i.e. the switch from read/write to
read_iter/write_iter.

Signed-off-by: Jiri Slaby <jslaby@...e.cz>
Cc: Linus Torvalds <torvalds@...ux-foundation.org>
---
 drivers/tty/tty_io.c | 37 ++++++++++++++++---------------------
 1 file changed, 16 insertions(+), 21 deletions(-)

diff --git a/drivers/tty/tty_io.c b/drivers/tty/tty_io.c
index 8f9e89715a68..ad64232cecae 100644
--- a/drivers/tty/tty_io.c
+++ b/drivers/tty/tty_io.c
@@ -911,10 +911,8 @@ static int iterate_tty_read(struct tty_ldisc *ld, struct tty_struct *tty,
 
 /**
  *	tty_read	-	read method for tty device files
- *	@file: pointer to tty file
- *	@buf: user buffer
- *	@count: size of user buffer
- *	@ppos: unused
+ *	@iocb: kernel I/O control block
+ *	@to: destination for the data read
  *
  *	Perform the read system call function on this terminal device. Checks
  *	for hung up devices before calling the line discipline method.
@@ -1092,23 +1090,6 @@ void tty_write_message(struct tty_struct *tty, char *msg)
 	}
 }
 
-
-/**
- *	tty_write		-	write method for tty device file
- *	@file: tty file pointer
- *	@buf: user data to write
- *	@count: bytes to write
- *	@ppos: unused
- *
- *	Write data to a tty device via the line discipline.
- *
- *	Locking:
- *		Locks the line discipline as required
- *		Writes to the tty driver are serialized by the atomic_write_lock
- *	and are then processed in chunks to the device. The line discipline
- *	write method will not be invoked in parallel for each device.
- */
-
 static ssize_t file_tty_write(struct file *file, struct kiocb *iocb, struct iov_iter *from)
 {
 	struct tty_struct *tty = file_tty(file);
@@ -1133,6 +1114,20 @@ static ssize_t file_tty_write(struct file *file, struct kiocb *iocb, struct iov_
 	return ret;
 }
 
+/**
+ *	tty_write		-	write method for tty device file
+ *	@iocb: kernel I/O control block
+ *	@from: iov_iter with data to write
+ *
+ *	Write data to a tty device via the line discipline.
+ *
+ *	Locking:
+ *		Locks the line discipline as required
+ *		Writes to the tty driver are serialized by the atomic_write_lock
+ *		and are then processed in chunks to the device. The line
+ *		discipline write method will not be invoked in parallel for
+ *		each device.
+ */
 static ssize_t tty_write(struct kiocb *iocb, struct iov_iter *from)
 {
 	return file_tty_write(iocb->ki_filp, iocb, from);
-- 
2.31.1