| 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
| ||
|
Message-Id: <20181018223707.9891-8-tobin@kernel.org>
Date: Fri, 19 Oct 2018 09:37:07 +1100
From: "Tobin C. Harding" <tobin@...nel.org>
To: Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
Jiri Slaby <jslaby@...e.com>
Cc: "Tobin C. Harding" <tobin@...nel.org>,
Geert Uytterhoeven <geert@...ux-m68k.org>,
linux-kernel@...r.kernel.org
Subject: [PATCH v2 7/7] tty: Fix section format
Currently sections (specifically 'Return:' and 'Context:') are
non-uniform and/or incorrectly labelled. We should use the format
outlined in Documentation/doc-guide/kernel-doc.rst. This patch is a bit
of a mash up because text is on occasions mixed up in the current
comments.
- Use 'Context:' (Replaces 'Locking')
* Context: Describes whether the function can sleep, what locks it
* takes, releases, or expects to be held. It can extend over
* multiple lines.
- Use 'Return:'
* Return: Describe the return value of foobar.
*
* The return value description can also have multiple paragraphs, and
* should be placed at the end of the comment block.
- If brief description is too long spilt it up into brief and longer.
* A longer description, with more discussion of the function
* function_name() that might be useful to those using or modifying
* it. Begins with an empty comment line, and may include additional
* embedded empty comment lines.
Fix brief description if missing and long description present.
This patch leaves some instances of 'Locking:' still in the code (if I
was not _sure_ of the documented locking or if changing it would make
the comment less legible).
Signed-off-by: Tobin C. Harding <tobin@...nel.org>
---
drivers/tty/hvc/hvc_console.c | 4 +-
drivers/tty/hvc/hvc_iucv.c | 14 +--
drivers/tty/mips_ejtag_fdc.c | 4 +-
drivers/tty/n_gsm.c | 37 ++++----
drivers/tty/n_hdlc.c | 14 +--
drivers/tty/n_tracerouter.c | 14 ++-
drivers/tty/n_tracesink.c | 20 ++---
drivers/tty/n_tty.c | 117 ++++++++++++-------------
drivers/tty/pty.c | 19 ++--
drivers/tty/serial/8250/8250_core.c | 14 +--
drivers/tty/serial/amba-pl011.c | 2 +-
drivers/tty/serial/earlycon.c | 4 +-
drivers/tty/serial/ifx6x60.c | 12 +--
drivers/tty/serial/serial_txx9.c | 5 +-
drivers/tty/serial/xilinx_uartps.c | 21 +++--
drivers/tty/tty_audit.c | 9 +-
drivers/tty/tty_baudrate.c | 31 +++----
drivers/tty/tty_buffer.c | 26 +++---
drivers/tty/tty_io.c | 129 +++++++++++++---------------
drivers/tty/tty_ioctl.c | 15 ++--
drivers/tty/tty_jobctrl.c | 20 ++---
drivers/tty/tty_ldisc.c | 43 +++++-----
drivers/tty/tty_port.c | 8 +-
drivers/tty/vt/consolemap.c | 4 +-
drivers/tty/vt/keyboard.c | 6 +-
drivers/tty/vt/selection.c | 10 ++-
drivers/tty/vt/vt.c | 26 +++---
27 files changed, 310 insertions(+), 318 deletions(-)
diff --git a/drivers/tty/hvc/hvc_console.c b/drivers/tty/hvc/hvc_console.c
index 6d57d0bfff5d..9379de272995 100644
--- a/drivers/tty/hvc/hvc_console.c
+++ b/drivers/tty/hvc/hvc_console.c
@@ -569,7 +569,7 @@ static int hvc_write(struct tty_struct *tty, const unsigned char *buf, int count
* The routine shall not be called within an atomic context because it
* might sleep.
*
- * Locking: hp->lock
+ * Context: Take hp->lock
*/
static void hvc_set_winsz(struct work_struct *work)
{
@@ -784,7 +784,7 @@ EXPORT_SYMBOL_GPL(hvc_poll);
* Stores the specified window size information in the hvc structure of @hp.
* The function schedule the tty resize update.
*
- * Locking: Locking free; the function MUST be called holding hp->lock
+ * Context: Locking free; the function MUST be called holding hp->lock
*/
void __hvc_resize(struct hvc_struct *hp, struct winsize ws)
{
diff --git a/drivers/tty/hvc/hvc_iucv.c b/drivers/tty/hvc/hvc_iucv.c
index 2af1e5751bd6..0de673b29b31 100644
--- a/drivers/tty/hvc/hvc_iucv.c
+++ b/drivers/tty/hvc/hvc_iucv.c
@@ -147,7 +147,8 @@ static struct hvc_iucv_private *hvc_iucv_get_private(uint32_t num)
* required for receiving and sending data with IUCV.
* Note: The total message size arises from the internal buffer size and the
* members of the iucv_tty_msg structure.
- * The function returns NULL if memory allocation has failed.
+ *
+ * Return: NULL if memory allocation has failed.
*/
static struct iucv_tty_buffer *alloc_tty_buffer(size_t size, gfp_t flags)
{
@@ -210,9 +211,9 @@ static void destroy_tty_buffer_list(struct list_head *list)
* If all message data has been written, the message is removed from
* the input queue.
*
- * The function returns the number of bytes written to the terminal, zero if
- * there are no pending data messages available or if there is no established
- * IUCV path.
+ * Return: The number of bytes written to the terminal, zero if there are no
+ * pending data messages available or if there is no established IUCV path.
+ *
* If the IUCV path has been severed, then -EPIPE is returned to cause a
* hang up (that is issued by the HVC layer).
*/
@@ -309,9 +310,8 @@ static int hvc_iucv_write(struct hvc_iucv_private *priv,
* If an IUCV communication path has been established, pending IUCV messages
* are received and data is copied into buffer @buf up to @count bytes.
*
- * Locking: The routine gets called under an irqsave() spinlock; and
- * the routine locks the struct hvc_iucv_private->lock to call
- * helper functions.
+ * Context: The routine gets called under an irqsave() spinlock; locks
+ * the struct hvc_iucv_private->lock to call helper functions.
*/
static int hvc_iucv_get_chars(uint32_t vtermno, char *buf, int count)
{
diff --git a/drivers/tty/mips_ejtag_fdc.c b/drivers/tty/mips_ejtag_fdc.c
index 4c1cd49ae95b..6d2e9e145770 100644
--- a/drivers/tty/mips_ejtag_fdc.c
+++ b/drivers/tty/mips_ejtag_fdc.c
@@ -409,7 +409,7 @@ static struct mips_ejtag_fdc_console mips_ejtag_fdc_con = {
* Write a single block of data out to the debug adapter. If the circular buffer
* is wrapped then only the first block is written.
*
- * Returns: The number of bytes that were written.
+ * Return: The number of bytes that were written.
*/
static unsigned int mips_ejtag_fdc_put_chan(struct mips_ejtag_fdc_tty *priv,
unsigned int chan)
@@ -643,7 +643,7 @@ static void mips_ejtag_fdc_handle(struct mips_ejtag_fdc_tty *priv)
*
* It simply triggers the common FDC handler code.
*
- * Returns: IRQ_HANDLED if an FDC interrupt was pending.
+ * Return: IRQ_HANDLED if an FDC interrupt was pending.
* IRQ_NONE otherwise.
*/
static irqreturn_t mips_ejtag_fdc_isr(int irq, void *dev_id)
diff --git a/drivers/tty/n_gsm.c b/drivers/tty/n_gsm.c
index c65a9afb7cc4..fbc8d0a15676 100644
--- a/drivers/tty/n_gsm.c
+++ b/drivers/tty/n_gsm.c
@@ -393,7 +393,8 @@ static inline u8 gsm_fcs_add_block(u8 fcs, u8 *c, int len)
* @c: byte going into the EA
*
* Processes one byte of an EA. Updates the passed variable
- * and returns 1 if the EA is now completely read
+ *
+ * Return: 1 if the EA is now completely read.
*/
static int gsm_read_ea(unsigned int *val, u8 c)
{
@@ -701,8 +702,9 @@ static void gsm_data_kick(struct gsm_mux *gsm)
* @msg: message queued
*
* Add data to the transmit queue and try and get stuff moving
- * out of the mux tty if not already doing so. The Caller must hold
- * the gsm tx lock.
+ * out of the mux tty if not already doing so.
+ *
+ * Context: The Caller must hold the gsm tx lock.
*/
static void __gsm_data_queue(struct gsm_dlci *dlci, struct gsm_msg *msg)
{
@@ -751,8 +753,9 @@ static void __gsm_data_queue(struct gsm_dlci *dlci, struct gsm_msg *msg)
* @msg: message queued
*
* Add data to the transmit queue and try and get stuff moving
- * out of the mux tty if not already doing so. Take the
- * the gsm tx lock and dlci lock.
+ * out of the mux tty if not already doing so.
+ *
+ * Context: Take the gsm tx lock and dlci lock.
*/
static void gsm_data_queue(struct gsm_dlci *dlci, struct gsm_msg *msg)
{
@@ -771,7 +774,7 @@ static void gsm_data_queue(struct gsm_dlci *dlci, struct gsm_msg *msg)
* is data. Keep to the MRU of the mux. This path handles the usual tty
* interface which is a byte stream with optional modem data.
*
- * Caller must hold the tx_lock of the mux.
+ * Context: Caller must hold the tx_lock of the mux.
*/
static int gsm_dlci_data_output(struct gsm_mux *gsm, struct gsm_dlci *dlci)
{
@@ -823,7 +826,7 @@ static int gsm_dlci_data_output(struct gsm_mux *gsm, struct gsm_dlci *dlci)
* is data. Keep to the MRU of the mux. This path handles framed data
* queued as skbuffs to the DLCI.
*
- * Caller must hold the tx_lock of the mux.
+ * Context: Caller must hold the tx_lock of the mux.
*/
static int gsm_dlci_data_output_framed(struct gsm_mux *gsm,
struct gsm_dlci *dlci)
@@ -1266,7 +1269,9 @@ static void gsm_control_response(struct gsm_mux *gsm, unsigned int command,
* @gsm: gsm mux
* @ctrl: frame to send
*
- * Send out a pending control command (called under control lock)
+ * Send out a pending control command.
+
+ * Context: Called under control lock.
*/
static void gsm_control_transmit(struct gsm_mux *gsm, struct gsm_control *ctrl)
{
@@ -1360,8 +1365,10 @@ static struct gsm_control *gsm_control_send(struct gsm_mux *gsm,
* @control: control we are waiting on
*
* Waits for the control to complete or time out. Frees any used
- * resources and returns 0 for success, or an error if the remote
- * rejected or ignored the request.
+ * resources.
+ *
+ * Return: 0 for success, or an error if the remote rejected or
+ * ignored the request.
*/
static int gsm_control_wait(struct gsm_mux *gsm, struct gsm_control *control)
{
@@ -1641,7 +1648,7 @@ static struct gsm_dlci *gsm_dlci_alloc(struct gsm_mux *gsm, int addr)
*
* Free up a DLCI.
*
- * Can sleep.
+ * Context: Can sleep.
*/
static void gsm_dlci_free(struct tty_port *port)
{
@@ -1674,7 +1681,7 @@ static void gsm_destroy_network(struct gsm_dlci *dlci);
* Release a DLCI. Actual free is deferred until either
* mux is closed or tty is closed - whichever is last.
*
- * Can sleep.
+ * Context: Can sleep.
*/
static void gsm_dlci_release(struct gsm_dlci *dlci)
{
@@ -2381,7 +2388,7 @@ static void gsmld_write_wakeup(struct tty_struct *tty)
* parallel readers and must handle this ourselves. We may also get
* a hangup. Always called in user context, may sleep.
*
- * This code must be sure never to sleep through a hangup.
+ * Context: This code must be sure never to sleep through a hangup.
*/
static ssize_t gsmld_read(struct tty_struct *tty, struct file *file,
unsigned char __user *buf, size_t nr)
@@ -2422,8 +2429,8 @@ static ssize_t gsmld_write(struct tty_struct *tty, struct file *file,
* for special events. This code is not serialized with respect to
* other events save open/close.
*
- * This code must be sure never to sleep through a hangup.
- * Called without the kernel lock held - fine
+ * Context: This code must be sure never to sleep through a hangup.
+ * Called without the kernel lock held - fine.
*/
static __poll_t gsmld_poll(struct tty_struct *tty, struct file *file,
poll_table *wait)
diff --git a/drivers/tty/n_hdlc.c b/drivers/tty/n_hdlc.c
index 5b0c776a43a2..af134fd20838 100644
--- a/drivers/tty/n_hdlc.c
+++ b/drivers/tty/n_hdlc.c
@@ -321,7 +321,7 @@ static void n_hdlc_tty_close(struct tty_struct *tty)
* n_hdlc_tty_open() - called when line discipline changed to n_hdlc
* @tty - pointer to tty info structure
*
- * Returns 0 if success, otherwise error code
+ * Return: 0 if success, otherwise error code.
*/
static int n_hdlc_tty_open (struct tty_struct *tty)
{
@@ -555,7 +555,7 @@ static void n_hdlc_tty_receive(struct tty_struct *tty, const __u8 *data,
* @buf - pointer to returned data buffer
* @nr - size of returned data buffer
*
- * Returns the number of bytes returned or error code.
+ * Return: The number of bytes returned or error code.
*/
static ssize_t n_hdlc_tty_read(struct tty_struct *tty, struct file *file,
__u8 __user *buf, size_t nr)
@@ -639,7 +639,7 @@ static ssize_t n_hdlc_tty_read(struct tty_struct *tty, struct file *file,
* @data - pointer to transmit data (one frame)
* @count - size of transmit frame in bytes
*
- * Returns the number of bytes written (or error code).
+ * Return: The number of bytes written or error code.
*/
static ssize_t n_hdlc_tty_write(struct tty_struct *tty, struct file *file,
const unsigned char *data, size_t count)
@@ -723,7 +723,7 @@ static ssize_t n_hdlc_tty_write(struct tty_struct *tty, struct file *file,
* @cmd - IOCTL command code
* @arg - argument for IOCTL call (cmd dependent)
*
- * Returns command dependent result.
+ * Return: Command dependent result.
*/
static int n_hdlc_tty_ioctl(struct tty_struct *tty, struct file *file,
unsigned int cmd, unsigned long arg)
@@ -795,7 +795,7 @@ static int n_hdlc_tty_ioctl(struct tty_struct *tty, struct file *file,
* Determine which operations (read/write) will not block and return info
* to caller.
*
- * Returns a bit mask containing info on which ops will not block.
+ * Return: A bit mask containing info on which ops will not block.
*/
static __poll_t n_hdlc_tty_poll(struct tty_struct *tty, struct file *filp,
poll_table *wait)
@@ -830,7 +830,7 @@ static __poll_t n_hdlc_tty_poll(struct tty_struct *tty, struct file *filp,
/**
* n_hdlc_alloc() - allocate an n_hdlc instance data structure
*
- * Returns a pointer to newly created structure if success, otherwise %NULL
+ * Return: A pointer to newly created structure if success, otherwise %NULL.
*/
static struct n_hdlc *n_hdlc_alloc(void)
{
@@ -920,7 +920,7 @@ static void n_hdlc_buf_put(struct n_hdlc_buf_list *buf_list,
* Remove and return an HDLC buffer from the head of the specified HDLC buffer
* list.
*
- * Returns a pointer to HDLC buffer if available, otherwise %NULL.
+ * Return: A pointer to HDLC buffer if available, otherwise %NULL.
*/
static struct n_hdlc_buf *n_hdlc_buf_get(struct n_hdlc_buf_list *buf_list)
{
diff --git a/drivers/tty/n_tracerouter.c b/drivers/tty/n_tracerouter.c
index f7a2616145cf..a54e1aed019f 100644
--- a/drivers/tty/n_tracerouter.c
+++ b/drivers/tty/n_tracerouter.c
@@ -53,10 +53,9 @@ static DEFINE_MUTEX(routelock);
* n_tracerouter_open() - Called when a tty is opened by a SW entity.
* @tty: terminal device to the ldisc.
*
- * Return:
- * 0 for success.
- *
* Caveats: This should only be opened one time per SW entity.
+ *
+ * Return: 0 for success.
*/
static int n_tracerouter_open(struct tty_struct *tty)
{
@@ -114,8 +113,7 @@ static void n_tracerouter_close(struct tty_struct *tty)
* -EIO should be used just to show that there was an intent not to have
* this function implemented. Return value based on read() man pages.
*
- * Return:
- * -EINVAL
+ * Return: -EINVAL
*/
static ssize_t n_tracerouter_read(struct tty_struct *tty, struct file *file,
unsigned char __user *buf, size_t nr) {
@@ -138,8 +136,7 @@ static ssize_t n_tracerouter_read(struct tty_struct *tty, struct file *file,
* just to show that there was an intent not to have this function
* implemented. Return value based on write() man pages.
*
- * Return:
- * -EINVAL
+ * Return: -EINVAL
*/
static ssize_t n_tracerouter_write(struct tty_struct *tty, struct file *file,
const unsigned char *buf, size_t nr) {
@@ -188,8 +185,7 @@ static struct tty_ldisc_ops tty_ptirouter_ldisc = {
*
* Registers this module as a line discipline driver.
*
- * Return:
- * 0 for success, any other value error.
+ * Return: 0 for success, any other value error.
*/
static int __init n_tracerouter_init(void)
{
diff --git a/drivers/tty/n_tracesink.c b/drivers/tty/n_tracesink.c
index 8feeea7d33b6..fc5013f34d51 100644
--- a/drivers/tty/n_tracesink.c
+++ b/drivers/tty/n_tracesink.c
@@ -51,15 +51,12 @@ static DEFINE_MUTEX(writelock);
* n_tracesink_open() - Called when a tty is opened by a SW entity.
* @tty: terminal device to the ldisc.
*
- * Return:
- * 0 for success,
- * -EFAULT = couldn't get a tty kref n_tracesink will sit
- * on top of
- * -EEXIST = open() called successfully once and it cannot
- * be called again.
- *
* Caveats: open() should only be successful the first time a
* SW entity calls it.
+ *
+ * Return: 0 for success. -EFAULT = couldn't get a tty kref n_tracesink
+ * will sit on top of. -EEXIST = open() called successfully once
+ * and it cannot be called again.
*/
static int n_tracesink_open(struct tty_struct *tty)
{
@@ -111,8 +108,7 @@ static void n_tracesink_close(struct tty_struct *tty)
* -EIO should be used just to show that there was an intent not to have
* this function implemented. Return value based on read() man pages.
*
- * Return:
- * -EINVAL
+ * Return: -EINVAL
*/
static ssize_t n_tracesink_read(struct tty_struct *tty, struct file *file,
unsigned char __user *buf, size_t nr) {
@@ -135,8 +131,7 @@ static ssize_t n_tracesink_read(struct tty_struct *tty, struct file *file,
* just to show that there was an intent not to have this function
* implemented. Return value based on write() man pages.
*
- * Return:
- * -EINVAL
+ * Return: -EINVAL
*/
static ssize_t n_tracesink_write(struct tty_struct *tty, struct file *file,
const unsigned char *buf, size_t nr) {
@@ -192,8 +187,7 @@ static struct tty_ldisc_ops tty_n_tracesink = {
*
* Registers this module as a line discipline driver.
*
- * Return:
- * 0 for success, any other value error.
+ * Return: 0 for success, any other value error.
*/
static int __init n_tracesink_init(void)
{
diff --git a/drivers/tty/n_tty.c b/drivers/tty/n_tty.c
index 3e2b59e99153..23d77ddd187f 100644
--- a/drivers/tty/n_tty.c
+++ b/drivers/tty/n_tty.c
@@ -193,10 +193,8 @@ static int tty_copy_to_user(struct tty_struct *tty, void __user *to,
*
* Re-schedules the flip buffer work if it may have stopped
*
- * Caller holds exclusive termios_rwsem
- * or
- * n_tty_read()/consumer path:
- * holds non-exclusive termios_rwsem
+ * Context: Caller holds exclusive termios_rwsem or
+ * n_tty_read()/consumer path: holds non-exclusive termios_rwsem
*/
static void n_tty_kick_worker(struct tty_struct *tty)
{
@@ -306,8 +304,8 @@ static void n_tty_check_unthrottle(struct tty_struct *tty)
*
* Add a character to the tty read_buf queue.
*
- * n_tty_receive_buf()/producer path:
- * caller holds non-exclusive termios_rwsem
+ * Context: n_tty_receive_buf()/producer path: caller holds
+ * non-exclusive termios_rwsem.
*/
static inline void put_tty_queue(unsigned char c, struct n_tty_data *ldata)
{
@@ -320,10 +318,9 @@ static inline void put_tty_queue(unsigned char c, struct n_tty_data *ldata)
* @tty: terminal to reset
*
* Reset the read buffer counters and clear the flags.
- * Called from n_tty_open() and n_tty_flush_buffer().
*
- * Locking: caller holds exclusive termios_rwsem
- * (or locking is not required)
+ * Context: Called from n_tty_open() and n_tty_flush_buffer(). Caller
+ * holds exclusive termios_rwsem (or locking is not required).
*/
static void reset_buffer_flags(struct n_tty_data *ldata)
{
@@ -359,7 +356,7 @@ static void n_tty_packet_mode_flush(struct tty_struct *tty)
* Holds termios_rwsem to exclude producer/consumer while
* buffer indices are reset.
*
- * Locking: ctrl_lock, exclusive termios_rwsem
+ * Context: ctrl_lock, exclusive termios_rwsem.
*/
static void n_tty_flush_buffer(struct tty_struct *tty)
{
@@ -412,11 +409,11 @@ static inline int is_continuation(unsigned char c, struct tty_struct *tty)
* and NLDLY. They simply aren't relevant in the world today.
* If you ever need them, add them here.
*
- * Returns the number of bytes of buffer space used or -1 if
- * no space left.
+ * Context: should be called under the output_lock to protect
+ * the column state and space left in the buffer.
*
- * Locking: should be called under the output_lock to protect
- * the column state and space left in the buffer
+ * Return: The number of bytes of buffer space used or -1 if
+ * no space left.
*/
static int do_output_char(unsigned char c, struct tty_struct *tty, int space)
{
@@ -485,12 +482,13 @@ static int do_output_char(unsigned char c, struct tty_struct *tty, int space)
* @tty: terminal device
*
* Output one character with OPOST processing.
- * Returns -1 when the output device is full and the character
- * must be retried.
*
- * Locking: output_lock to protect column state and space left
+ * Context: output_lock to protect column state and space left
* (also, this is called from n_tty_write under the
- * tty layer write lock)
+ * tty layer write lock).
+ *
+ * Return: -1 when the output device is full and the character
+ * must be retried.
*/
static int process_output(unsigned char c, struct tty_struct *tty)
{
@@ -516,16 +514,17 @@ static int process_output(unsigned char c, struct tty_struct *tty)
* @nr: number of bytes to output
*
* Output a block of characters with OPOST processing.
- * Returns the number of characters output.
*
* This path is used to speed up block console writes, among other
* things when processing blocks of output data. It handles only
* the simple cases normally found and helps to generate blocks of
* symbols for the console driver and thus improve performance.
*
- * Locking: output_lock to protect column state and space left
+ * Context: output_lock to protect column state and space left
* (also, this is called from n_tty_write under the
- * tty layer write lock)
+ * tty layer write lock).
+ *
+ * Return: The number of characters output.
*/
static ssize_t process_output_block(struct tty_struct *tty,
const unsigned char *buf, unsigned int nr)
@@ -608,7 +607,7 @@ static ssize_t process_output_block(struct tty_struct *tty,
* are prioritized. Also, when control characters are echoed with a
* prefixed "^", the pair is treated atomically and thus not separated.
*
- * Locking: callers must hold output_lock
+ * Context: Caller must hold output_lock.
*/
static size_t __process_echoes(struct tty_struct *tty)
{
@@ -952,8 +951,8 @@ static inline void finish_erasing(struct n_tty_data *ldata)
* present in the stream from the driver layer. Handles the complexities
* of UTF-8 multibyte symbols.
*
- * n_tty_receive_buf()/producer path:
- * caller holds non-exclusive termios_rwsem
+ * Context: n_tty_receive_buf()/producer path: caller holds
+ * non-exclusive termios_rwsem
*/
static void eraser(unsigned char c, struct tty_struct *tty)
{
@@ -1085,7 +1084,7 @@ static void eraser(unsigned char c, struct tty_struct *tty)
* buffer is 'output'. The signal is processed first to alert any current
* readers or writers to discontinue and exit their i/o loops.
*
- * Locking: ctrl_lock
+ * Context: ctrl_lock
*/
static void __isig(int sig, struct tty_struct *tty)
{
@@ -1138,8 +1137,8 @@ static void isig(int sig, struct tty_struct *tty)
* An RS232 break event has been hit in the incoming bitstream. This
* can cause a variety of events depending upon the termios settings.
*
- * n_tty_receive_buf()/producer path:
- * caller holds non-exclusive termios_rwsem
+ * Context: n_tty_receive_buf()/producer path: caller holds
+ * non-exclusive termios_rwsem.
*
* Note: may get exclusive termios_rwsem if flushing input buffer
*/
@@ -1193,8 +1192,8 @@ static void n_tty_receive_overrun(struct tty_struct *tty)
* Process a parity error and queue the right data to indicate
* the error case if necessary.
*
- * n_tty_receive_buf()/producer path:
- * caller holds non-exclusive termios_rwsem
+ * Context: n_tty_receive_buf()/producer path: caller holds
+ * non-exclusive termios_rwsem
*/
static void n_tty_receive_parity_error(struct tty_struct *tty, unsigned char c)
{
@@ -1236,11 +1235,11 @@ n_tty_receive_signal_char(struct tty_struct *tty, int signal, unsigned char c)
* This is serialized with respect to itself by the rules for the
* driver above.
*
- * n_tty_receive_buf()/producer path:
- * caller holds non-exclusive termios_rwsem
- * publishes canon_head if canonical mode is active
+ * Context: n_tty_receive_buf()/producer path: caller holds
+ * non-exclusive termios_rwsem publishes canon_head if
+ * canonical mode is active.
*
- * Returns 1 if LNEXT was received, else returns 0
+ * Return: 1 if LNEXT was received, else returns 0.
*/
static int
n_tty_receive_char_special(struct tty_struct *tty, unsigned char c)
@@ -1649,8 +1648,6 @@ static void __receive_buf(struct tty_struct *tty, const unsigned char *cp,
* not from interrupt context. The driver is responsible for making
* calls one at a time and in order (or using flush_to_ldisc)
*
- * Returns the # of input chars from @cp which were processed.
- *
* In canonical mode, the maximum line length is 4096 chars (including
* the line termination char); lines longer than 4096 chars are
* truncated. After 4095 chars, input data is still processed but
@@ -1666,9 +1663,10 @@ static void __receive_buf(struct tty_struct *tty, const unsigned char *cp,
* maximum canon line of 4096 chars when the mode is switched to
* non-canonical.
*
- * n_tty_receive_buf()/producer path:
- * claims non-exclusive termios_rwsem
- * publishes commit_head or canon_head
+ * Context: n_tty_receive_buf()/producer path: claims non-exclusive
+ * termios_rwsem publishes commit_head or canon_head.
+ *
+ * Return: The number of input chars from @cp which were processed.
*/
static int
n_tty_receive_buf_common(struct tty_struct *tty, const unsigned char *cp,
@@ -1763,7 +1761,7 @@ static int n_tty_receive_buf2(struct tty_struct *tty, const unsigned char *cp,
* guaranteed that this function will not be re-entered or in progress
* when the ldisc is closed.
*
- * Locking: Caller holds tty->termios_rwsem
+ * Context: Caller holds tty->termios_rwsem.
*/
static void n_tty_set_termios(struct tty_struct *tty, struct ktermios *old)
{
@@ -1873,10 +1871,11 @@ static void n_tty_close(struct tty_struct *tty)
* n_tty_open() - open an ldisc
* @tty: terminal to open
*
- * Called when this line discipline is being attached to the
- * terminal device. Can sleep. Called serialized so that no
- * other events will occur in parallel. No further open will occur
- * until a close.
+ * Called when this line discipline is being attached to the terminal
+ * device. Called serialized so that no other events will occur in
+ * parallel. No further open will occur until a close.
+ *
+ * Context: Can sleep.
*/
static int n_tty_open(struct tty_struct *tty)
{
@@ -1924,11 +1923,9 @@ static inline int input_available_p(struct tty_struct *tty, int poll)
* buffer, and once to drain the space from the (physical) beginning of
* the buffer to head pointer.
*
- * Called under the ldata->atomic_read_lock sem
- *
- * n_tty_read()/consumer path:
- * caller holds non-exclusive termios_rwsem
- * read_tail published
+ * Context: Called under the ldata->atomic_read_lock sem.
+ * n_tty_read()/consumer path: caller holds non-exclusive
+ * termios_rwsem read_tail published.
*/
static int copy_from_read_buf(struct tty_struct *tty,
unsigned char __user **b,
@@ -1979,11 +1976,9 @@ static int copy_from_read_buf(struct tty_struct *tty,
* This causes data already processed as input to be immediately available
* as input although a newline has not been received.
*
- * Called under the atomic_read_lock mutex
- *
- * n_tty_read()/consumer path:
- * caller holds non-exclusive termios_rwsem
- * read_tail published
+ * Context: Called under the atomic_read_lock mutex.
+ * n_tty_read()/consumer path: caller holds non-exclusive
+ * termios_rwsem read_tail published.
*/
static int canon_copy_from_read_buf(struct tty_struct *tty,
unsigned char __user **b,
@@ -2061,9 +2056,9 @@ extern ssize_t redirected_tty_write(struct file *, const char __user *,
* and if appropriate send any needed signals and return a negative
* error code if action should be taken.
*
- * Locking: redirected write test is safe
+ * Context: redirected write test is safe
* current->signal->tty check is safe
- * ctrl_lock to safely reference tty->pgrp
+ * ctrl_lock to safely reference tty->pgrp.
*/
static int job_control(struct tty_struct *tty, struct file *file)
{
@@ -2093,9 +2088,8 @@ static int job_control(struct tty_struct *tty, struct file *file)
*
* This code must be sure never to sleep through a hangup.
*
- * n_tty_read()/consumer path:
- * claims non-exclusive termios_rwsem
- * publishes read_tail
+ * Context: n_tty_read()/consumer path: claims non-exclusive
+ * termios_rwsem publishes read_tail.
*/
static ssize_t n_tty_read(struct tty_struct *tty, struct file *file,
unsigned char __user *buf, size_t nr)
@@ -2261,9 +2255,9 @@ static ssize_t n_tty_read(struct tty_struct *tty, struct file *file,
*
* This code must be sure never to sleep through a hangup.
*
- * Locking: output_lock to protect column state and space left
+ * Context: output_lock to protect column state and space left
* (note that the process_output*() functions take this
- * lock themselves)
+ * lock themselves).
*/
static ssize_t n_tty_write(struct tty_struct *tty, struct file *file,
const unsigned char *buf, size_t nr)
@@ -2363,7 +2357,8 @@ static ssize_t n_tty_write(struct tty_struct *tty, struct file *file,
* other events save open/close.
*
* This code must be sure never to sleep through a hangup.
- * Called without the kernel lock held - fine
+ *
+ * Context: Called without the kernel lock held - fine.
*/
static __poll_t n_tty_poll(struct tty_struct *tty, struct file *file,
poll_table *wait)
diff --git a/drivers/tty/pty.c b/drivers/tty/pty.c
index 35cb13995c1c..c3db7d6d7b5b 100644
--- a/drivers/tty/pty.c
+++ b/drivers/tty/pty.c
@@ -369,7 +369,7 @@ static void pty_stop(struct tty_struct *tty)
* Perform the initial set up for the tty/pty pair. Called from the
* tty layer when the port is first opened.
*
- * Locking: the caller must hold the tty_mutex
+ * Context: The caller must hold the tty_mutex.
*/
static int pty_common_install(struct tty_driver *driver, struct tty_struct *tty,
bool legacy)
@@ -687,8 +687,9 @@ static long pty_unix98_compat_ioctl(struct tty_struct *tty,
* @driver: ptm driver
* @idx: tty index
*
- * Look up a pty master device. Called under the tty_mutex for now.
- * This provides our locking.
+ * Look up a pty master device.
+ *
+ * Context: Called under the tty_mutex for now. This provides our locking.
*/
static struct tty_struct *ptm_unix98_lookup(struct tty_driver *driver,
struct file *file, int idx)
@@ -702,8 +703,10 @@ static struct tty_struct *ptm_unix98_lookup(struct tty_driver *driver,
* @driver: pts driver
* @idx: tty index
*
- * Look up a pty master device. Called under the tty_mutex for now.
- * This provides our locking for the tty pointer.
+ * Look up a pty master device.
+ *
+ * Context: Called under the tty_mutex for now. This provides our
+ * locking for the tty pointer.
*/
static struct tty_struct *pts_unix98_lookup(struct tty_driver *driver,
struct file *file, int idx)
@@ -787,9 +790,9 @@ static const struct tty_operations pty_unix98_ops = {
*
* Allocate a unix98 pty master device from the ptmx driver.
*
- * Locking: tty_mutex protects the init_dev work. tty->count should
- * protect the rest.
- * allocated_ptys_lock handles the list of free pty numbers
+ * Context: tty_mutex protects the init_dev work. tty->count should
+ * protect the rest. allocated_ptys_lock handles the list
+ * of free pty numbers.
*/
static int ptmx_open(struct inode *inode, struct file *filp)
{
diff --git a/drivers/tty/serial/8250/8250_core.c b/drivers/tty/serial/8250/8250_core.c
index 63d7537a1db1..e5157e0679de 100644
--- a/drivers/tty/serial/8250/8250_core.c
+++ b/drivers/tty/serial/8250/8250_core.c
@@ -404,9 +404,10 @@ static struct uart_8250_port serial8250_ports[UART_NR];
* This struct *must* *not* be used to perform a 8250 or serial core operation
* which is not accessible otherwise. Its only purpose is to make the struct
* accessible to the runtime-pm callbacks for context suspend/restore.
- * The lock assumption made here is none because runtime-pm suspend/resume
- * callbacks should not be invoked if there is any operation performed on the
- * port.
+ *
+ * Context: The lock assumption made here is none because runtime-pm
+ * suspend/resume callbacks should not be invoked if there is any
+ * operation performed on the port.
*/
struct uart_8250_port *serial8250_get_port(int line)
{
@@ -624,7 +625,7 @@ static int univ8250_console_setup(struct console *co, char *options)
* Performs console setup for a match (as required by interface)
* If no <options> are specified, then assume the h/w is already setup.
*
- * Returns 0 if console matches; otherwise non-zero to use default matching
+ * Return: 0 if console matches; otherwise non-zero to use default matching.
*/
static int univ8250_console_match(struct console *co, char *name, int idx,
char *options)
@@ -1066,8 +1067,9 @@ EXPORT_SYMBOL(serial8250_register_8250_port);
* serial8250_unregister_port() - remove a 16x50 serial port at runtime
* @line: serial line number
*
- * Remove one serial port. This may not be called from interrupt
- * context. We hand the port back to the our control.
+ * Remove one serial port. We hand the port back to the our control.
+ *
+ * Context: This may not be called from interrupt context.
*/
void serial8250_unregister_port(int line)
{
diff --git a/drivers/tty/serial/amba-pl011.c b/drivers/tty/serial/amba-pl011.c
index 589adc597923..73fd98fd13e4 100644
--- a/drivers/tty/serial/amba-pl011.c
+++ b/drivers/tty/serial/amba-pl011.c
@@ -2355,7 +2355,7 @@ static int __init pl011_console_setup(struct console *co, char *options)
* Performs console setup for a match (as required by interface)
* If no <options> are specified, then assume the h/w is already setup.
*
- * Returns 0 if console matches; otherwise non-zero to use default matching
+ * Return: 0 if console matches; otherwise non-zero to use default matching.
*/
static int __init pl011_console_match(struct console *co, char *name, int idx,
char *options)
diff --git a/drivers/tty/serial/earlycon.c b/drivers/tty/serial/earlycon.c
index 85bd5a5d7f39..f56703c10ac6 100644
--- a/drivers/tty/serial/earlycon.c
+++ b/drivers/tty/serial/earlycon.c
@@ -164,8 +164,8 @@ static int __init register_earlycon(char *buf, const struct earlycon_id *match)
* <options> string in the 'options' parameter; all other forms set
* the parameter to NULL.
*
- * Returns 0 if an attempt to register the earlycon was made,
- * otherwise negative error code
+ * Return: 0 if an attempt to register the earlycon was made,
+ * otherwise negative error code.
*/
int __init setup_earlycon(char *buf)
{
diff --git a/drivers/tty/serial/ifx6x60.c b/drivers/tty/serial/ifx6x60.c
index 63c8b9f8c7b7..6d3a9cfaad34 100644
--- a/drivers/tty/serial/ifx6x60.c
+++ b/drivers/tty/serial/ifx6x60.c
@@ -169,12 +169,10 @@ ifx_spi_power_state_clear(struct ifx_spi_device *ifx_dev, unsigned char val)
}
/**
- * swap_buf_8()
+ * swap_buf_8() - Swap the contents of a buffer into big endian format.
* @buf: our buffer
* @len: number of bytes (not words) in the buffer
* @end: end of buffer
- *
- * Swap the contents of a buffer into big endian format
*/
static inline void swap_buf_8(unsigned char *buf, int len, void *end)
{
@@ -183,12 +181,10 @@ static inline void swap_buf_8(unsigned char *buf, int len, void *end)
}
/**
- * swap_buf_16()
+ * swap_buf_16() - Swap the contents of a buffer into big endian format.
* @buf: our buffer
* @len: number of bytes (not words) in the buffer
* @end: end of buffer
- *
- * Swap the contents of a buffer into big endian format
*/
static inline void swap_buf_16(unsigned char *buf, int len, void *end)
{
@@ -208,12 +204,10 @@ static inline void swap_buf_16(unsigned char *buf, int len, void *end)
}
/**
- * swap_buf_32()
+ * swap_buf_32() - Swap the contents of a buffer into big endian format.
* @buf: our buffer
* @len: number of bytes (not words) in the buffer
* @end: end of buffer
- *
- * Swap the contents of a buffer into big endian format
*/
static inline void swap_buf_32(unsigned char *buf, int len, void *end)
{
diff --git a/drivers/tty/serial/serial_txx9.c b/drivers/tty/serial/serial_txx9.c
index b6b17d5005f6..621217e4ee27 100644
--- a/drivers/tty/serial/serial_txx9.c
+++ b/drivers/tty/serial/serial_txx9.c
@@ -1059,8 +1059,9 @@ static int serial_txx9_register_port(struct uart_port *port)
* serial_txx9_unregister_port() - remove a txx9 serial port at runtime
* @line: serial line number
*
- * Remove one serial port. This may not be called from interrupt
- * context. We hand the port back to the our control.
+ * Remove one serial port. We hand the port back to the our control.
+ *
+ * Context: This may not be called from interrupt context.
*/
static void serial_txx9_unregister_port(int line)
{
diff --git a/drivers/tty/serial/xilinx_uartps.c b/drivers/tty/serial/xilinx_uartps.c
index 5ed85c49bbce..527dd273fccb 100644
--- a/drivers/tty/serial/xilinx_uartps.c
+++ b/drivers/tty/serial/xilinx_uartps.c
@@ -204,7 +204,6 @@ struct cdns_platform_data {
* cdns_uart_handle_rx() - Handle the received bytes along with Rx errors.
* @dev_id: Id of the UART port
* @isrstatus: The interrupt status register value as read
- * Return: None
*/
static void cdns_uart_handle_rx(void *dev_id, unsigned int isrstatus)
{
@@ -299,7 +298,6 @@ static void cdns_uart_handle_rx(void *dev_id, unsigned int isrstatus)
/**
* cdns_uart_handle_tx() - Handle the bytes to be Txed.
* @dev_id: Id of the UART port
- * Return: None
*/
static void cdns_uart_handle_tx(void *dev_id)
{
@@ -378,8 +376,6 @@ static irqreturn_t cdns_uart_isr(int irq, void *dev_id)
* @rbdiv: BDIV value (return value)
* @rcd: CD value (return value)
* @div8: Value for clk_sel bit in mod (return value)
- * Return: baud rate, requested baud when possible, or actual baud when there
- * was too much error, zero if no valid divisors are found.
*
* Formula to obtain baud rate is
* baud_tx/rx rate = clk/CD * (BDIV + 1)
@@ -390,6 +386,9 @@ static irqreturn_t cdns_uart_isr(int irq, void *dev_id)
* CD and BDIV depends on values in
* baud rate generate register
* baud rate clock divisor register
+ *
+ * Return: Baud rate, requested baud when possible, or actual baud when
+ * there was too much error, zero if no valid divisors are found.
*/
static unsigned int cdns_uart_calc_baud_divs(unsigned int clk,
unsigned int baud, u32 *rbdiv, u32 *rcd, int *div8)
@@ -437,6 +436,7 @@ static unsigned int cdns_uart_calc_baud_divs(unsigned int clk,
* cdns_uart_set_baud_rate() - Calculate and set the baud rate
* @port: Handle to the uart port structure
* @baud: Baud rate to set
+ *
* Return: baud rate, requested baud when possible, or actual baud when there
* was too much error, zero if no valid divisors are found.
*/
@@ -472,6 +472,7 @@ static unsigned int cdns_uart_set_baud_rate(struct uart_port *port,
* @nb: Notifier block
* @event: Notify event
* @data: Notifier data
+ *
* Return: NOTIFY_OK or NOTIFY_DONE on success, NOTIFY_BAD on error.
*/
static int cdns_uart_clk_notifier_cb(struct notifier_block *nb,
@@ -665,11 +666,13 @@ static void cdns_uart_break_ctl(struct uart_port *port, int ctl)
}
/**
- * cdns_uart_set_termios() - termios operations, handling data length, parity,
- * stop bits, flow control, baud rate
+ * cdns_uart_set_termios() - termios operations
* @port: Handle to the uart port structure
* @termios: Handle to the input termios structure
* @old: Values of the previously saved termios structure
+ *
+ * Termios operations, handling data length, parity, stop bits,
+ * flow control, baud rate.
*/
static void cdns_uart_set_termios(struct uart_port *port,
struct ktermios *termios, struct ktermios *old)
@@ -938,11 +941,11 @@ static int cdns_uart_verify_port(struct uart_port *port,
}
/**
- * cdns_uart_request_port() - Claim the memory region attached to cdns_uart port,
- * called when the driver adds a cdns_uart port via
- * uart_add_one_port()
+ * cdns_uart_request_port() - Claim the memory region attached to cdns_uart port.
* @port: Handle to the uart port structure
*
+ * Called when the driver adds a cdns_uart port via uart_add_one_port().
+ *
* Return: 0 on success, negative errno otherwise.
*/
static int cdns_uart_request_port(struct uart_port *port)
diff --git a/drivers/tty/tty_audit.c b/drivers/tty/tty_audit.c
index 54574c8d677e..34d1b09b69a1 100644
--- a/drivers/tty/tty_audit.c
+++ b/drivers/tty/tty_audit.c
@@ -149,7 +149,7 @@ void tty_audit_tiocsti(struct tty_struct *tty, char ch)
/**
* tty_audit_push() - Flush current's pending audit data
*
- * Returns 0 if success, -EPERM if tty audit is disabled
+ * Return: 0 if success, -EPERM if tty audit is disabled.
*/
int tty_audit_push(void)
{
@@ -170,9 +170,10 @@ int tty_audit_push(void)
/**
* tty_audit_buf_get() - Get an audit buffer.
*
- * Get an audit buffer, allocate it if necessary. Return %NULL
- * if out of memory or ERR_PTR(-ESRCH) if tty_audit_exit() has already
- * occurred. Otherwise, return a new reference to the buffer.
+ * Get an audit buffer, allocate it if necessary.
+ *
+ * Return: %NULL if out of memory or ERR_PTR(-ESRCH) if tty_audit_exit()
+ * has already occurred. Otherwise, return a new reference to the buffer.
*/
static struct tty_audit_buf *tty_audit_buf_get(void)
{
diff --git a/drivers/tty/tty_baudrate.c b/drivers/tty/tty_baudrate.c
index fac79ff29fb1..1bb4c3fb61b2 100644
--- a/drivers/tty/tty_baudrate.c
+++ b/drivers/tty/tty_baudrate.c
@@ -50,12 +50,12 @@ static int n_baud_table = ARRAY_SIZE(baud_table);
* tty_termios_baud_rate()
* @termios: termios structure
*
- * Convert termios baud rate data into a speed. This should be called
- * with the termios lock held if this termios is a terminal termios
- * structure. May change the termios data. Device drivers can call this
- * function but should use ->c_[io]speed directly as they are updated.
+ * Convert termios baud rate data into a speed.
*
- * Locking: none
+ * Context: This should be called with the termios lock held if this termios
+ * is a terminal termios structure. May change the termios data.
+ * Device drivers can call this function but should use ->c_[io]speed
+ * directly as they are updated.
*/
speed_t tty_termios_baud_rate(struct ktermios *termios)
{
@@ -84,12 +84,12 @@ EXPORT_SYMBOL(tty_termios_baud_rate);
* tty_termios_input_baud_rate()
* @termios: termios structure
*
- * Convert termios baud rate data into a speed. This should be called
- * with the termios lock held if this termios is a terminal termios
- * structure. May change the termios data. Device drivers can call this
- * function but should use ->c_[io]speed directly as they are updated.
+ * Convert termios baud rate data into a speed.
*
- * Locking: none
+ * Context: This should be called with the termios lock held if this termios
+ * is a terminal termios structure. May change the termios data.
+ * Device drivers can call this function but should use ->c_[io]speed
+ * directly as they are updated.
*/
speed_t tty_termios_input_baud_rate(struct ktermios *termios)
{
@@ -133,11 +133,11 @@ EXPORT_SYMBOL(tty_termios_input_baud_rate);
* desired speed. We allow small margins and preserve as much of possible
* of the input intent to keep compatibility.
*
- * Locking: Caller should hold termios lock. This is already held
- * when calling this function from the driver termios handler.
- *
* The ifdefs deal with platforms whose owners have yet to update them
* and will all go away once this is done.
+ *
+ * Context: Caller should hold termios lock. This is already held
+ * when calling this function from the driver termios handler.
*/
void tty_termios_encode_baud_rate(struct ktermios *termios,
speed_t ibaud, speed_t obaud)
@@ -227,8 +227,9 @@ EXPORT_SYMBOL_GPL(tty_termios_encode_baud_rate);
* @obad: output baud rate
*
* Update the current termios data for the tty with the new speed
- * settings. The caller must hold the termios_rwsem for the tty in
- * question.
+ * settings.
+ *
+ * Context: The caller must hold the termios_rwsem for the tty in question.
*/
void tty_encode_baud_rate(struct tty_struct *tty, speed_t ibaud, speed_t obaud)
{
diff --git a/drivers/tty/tty_buffer.c b/drivers/tty/tty_buffer.c
index 447f235eeb0c..46eee0e3b285 100644
--- a/drivers/tty/tty_buffer.c
+++ b/drivers/tty/tty_buffer.c
@@ -146,8 +146,8 @@ void tty_buffer_free_all(struct tty_port *port)
* We round our buffers off in 256 character chunks to get better
* allocation behaviour.
*
- * Return NULL if out of memory or the allocation would exceed the
- * per device queue
+ * Return: NULL if out of memory or the allocation would exceed the
+ * per device queue.
*/
static struct tty_buffer *tty_buffer_alloc(struct tty_port *port, size_t size)
{
@@ -208,8 +208,8 @@ static void tty_buffer_free(struct tty_port *port, struct tty_buffer *b)
* flush all the buffers containing receive data. If ld != NULL,
* flush the ldisc input buffer.
*
- * Locking: takes buffer lock to ensure single-threaded flip buffer
- * 'consumer'
+ * Context: Takes buffer lock to ensure single-threaded flip buffer
+ * 'consumer'.
*/
void tty_buffer_flush(struct tty_struct *tty, struct tty_ldisc *ld)
{
@@ -300,7 +300,9 @@ EXPORT_SYMBOL_GPL(tty_buffer_request_room);
* @size: size
*
* Queue a series of bytes to the tty buffering. All the characters
- * passed are marked with the supplied flag. Returns the number added.
+ * passed are marked with the supplied flag.
+ *
+ * Return: The number of bytes added.
*/
int tty_insert_flip_string_fixed_flag(struct tty_port *port,
const unsigned char *chars, char flag, size_t size)
@@ -334,8 +336,9 @@ EXPORT_SYMBOL(tty_insert_flip_string_fixed_flag);
* @size: size
*
* Queue a series of bytes to the tty buffering. For each character
- * the flags array indicates the status of the character. Returns the
- * number added.
+ * the flags array indicates the status of the character.
+ *
+ * Return: The number of bytes added.
*/
int tty_insert_flip_string_flags(struct tty_port *port,
const unsigned char *chars, const char *flags, size_t size)
@@ -443,7 +446,7 @@ EXPORT_SYMBOL_GPL(tty_prepare_flip_string);
* Callers other than flush_to_ldisc() need to exclude the kworker
* from concurrent use of the line discipline, see paste_selection().
*
- * Returns the number of bytes processed
+ * Return: The number of bytes processed.
*/
int tty_ldisc_receive_buf(struct tty_ldisc *ld, const unsigned char *p,
char *f, int count)
@@ -484,8 +487,8 @@ receive_buf(struct tty_port *port, struct tty_buffer *head, int count)
*
* The receive_buf method is single threaded for each tty instance.
*
- * Locking: takes buffer lock to ensure single-threaded flip buffer
- * 'consumer'
+ * Context: Takes buffer lock to ensure single-threaded flip buffer
+ * 'consumer'.
*/
static void flush_to_ldisc(struct work_struct *work)
{
@@ -535,10 +538,11 @@ static void flush_to_ldisc(struct work_struct *work)
* @port: tty port to push
*
* Queue a push of the terminal flip buffers to the line discipline.
- * Can be called from IRQ/atomic context.
*
* In the event of the queue being busy for flipping the work will be
* held off and retried later.
+ *
+ * Context: Can be called from IRQ/atomic context.
*/
void tty_flip_buffer_push(struct tty_port *port)
{
diff --git a/drivers/tty/tty_io.c b/drivers/tty/tty_io.c
index 938c9966c459..6d161eba0684 100644
--- a/drivers/tty/tty_io.c
+++ b/drivers/tty/tty_io.c
@@ -163,7 +163,7 @@ static void release_tty(struct tty_struct *tty, int idx);
*
* Free the write buffers, tty queue and tty memory itself.
*
- * Locking: none. Must be called after tty is definitely unused
+ * Context: No locks taken. Must be called after tty is definitely unused.
*/
static void free_tty_struct(struct tty_struct *tty)
{
@@ -238,7 +238,7 @@ static void tty_del_file(struct file *file)
* Convert a tty structure into a name. The name reflects the kernel
* naming policy and if udev is in use may not reflect user space
*
- * Locking: none
+ * Context: No locks taken.
*/
const char *tty_name(const struct tty_struct *tty)
{
@@ -309,7 +309,7 @@ static int check_tty_count(struct tty_struct *tty, const char *routine)
* This routine returns a tty driver structure, given a device number
* and also passes back the index number.
*
- * Locking: caller must hold tty_mutex
+ * Context: Caller must hold tty_mutex.
*/
static struct tty_driver *get_tty_driver(dev_t device, int *index)
{
@@ -334,7 +334,7 @@ static struct tty_driver *get_tty_driver(dev_t device, int *index)
* like (4, 64) or (188, 1). If no corresponding driver is registered then
* the function returns -ENODEV.
*
- * Locking: this acquires tty_mutex to protect the tty_drivers list from
+ * Context: Acquires tty_mutex to protect the tty_drivers list from
* being modified while we are traversing it, and makes sure to
* release it before exiting.
*/
@@ -750,8 +750,7 @@ EXPORT_SYMBOL(tty_hung_up_p);
* called from any context, may be under the tty atomic_write_lock
* but not always.
*
- * Locking:
- * flow_lock
+ * Context: Takes flow_lock.
*/
void __stop_tty(struct tty_struct *tty)
{
@@ -780,8 +779,7 @@ EXPORT_SYMBOL(stop_tty);
* tty was previous stopped and is now being started, the driver
* start method is invoked and the line discipline woken.
*
- * Locking:
- * flow_lock
+ * Context: Takes flow_lock.
*/
void __start_tty(struct tty_struct *tty)
{
@@ -827,9 +825,8 @@ static void tty_update_time(struct timespec64 *time)
* Perform the read system call function on this terminal device. Checks
* for hung up devices before calling the line discipline method.
*
- * Locking:
- * Locks the line discipline internally while needed. Multiple
- * read calls may be outstanding in parallel.
+ * Context: Locks the line discipline internally while needed. Multiple
+ * read calls may be outstanding in parallel.
*/
static ssize_t tty_read(struct file *file, char __user *buf, size_t count,
loff_t *ppos)
@@ -999,11 +996,10 @@ void tty_write_message(struct tty_struct *tty, char *msg)
*
* 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.
+ * Context: 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 file *file, const char __user *buf,
size_t count, loff_t *ppos)
@@ -1054,7 +1050,7 @@ ssize_t redirected_tty_write(struct file *file, const char __user *buf,
*
* Send a high priority character to the tty even if stopped
*
- * Locking: none for xchar method, write ordering for write method.
+ * Context: Takes termios_rwsem and write ordering for write method.
*/
int tty_send_xchar(struct tty_struct *tty, char ch)
{
@@ -1092,7 +1088,7 @@ static char ptychar[] = "pqrstuvwxyzabcde";
* Generate a name from a driver reference and write it to the output
* buffer.
*
- * Locking: None
+ * Context: No locks taken.
*/
static void pty_line_name(struct tty_driver *driver, int index, char *p)
{
@@ -1112,7 +1108,7 @@ static void pty_line_name(struct tty_driver *driver, int index, char *p)
* Generate a name from a driver reference and write it to the output
* buffer.
*
- * Locking: None
+ * Context: No locks taken.
*/
static ssize_t tty_line_name(struct tty_driver *driver, int index, char *p)
{
@@ -1131,7 +1127,7 @@ static ssize_t tty_line_name(struct tty_driver *driver, int index, char *p)
* Return the tty, if found. If not found, return NULL or ERR_PTR() if the
* driver lookup() method returns an error.
*
- * Locking: tty_mutex must be held. If the tty is found, bump the tty kref.
+ * Context: tty_mutex must be held. If the tty is found, bump the tty kref.
*/
static struct tty_struct *tty_driver_lookup_tty(struct tty_driver *driver,
struct file *file, int idx)
@@ -1200,7 +1196,7 @@ EXPORT_SYMBOL_GPL(tty_standard_install);
* for ensuring any need additional structures are allocated and
* configured.
*
- * Locking: tty_mutex for now
+ * Context: tty_mutex for now.
*/
static int tty_driver_install_tty(struct tty_driver *driver,
struct tty_struct *tty)
@@ -1214,10 +1210,10 @@ static int tty_driver_install_tty(struct tty_driver *driver,
* @driver: the driver for the tty
* @idx: the minor number
*
- * Remvoe a tty object from the driver tables. The tty->index field
+ * Remove a tty object from the driver tables. The tty->index field
* will be set by the time this is called.
*
- * Locking: tty_mutex for now
+ * Context: tty_mutex for now.
*/
static void tty_driver_remove_tty(struct tty_driver *driver, struct tty_struct *tty)
{
@@ -1273,10 +1269,6 @@ static int tty_reopen(struct tty_struct *tty)
* could also be an active device. The pty drivers require special
* handling because of this.
*
- * Locking:
- * The function is called under the tty_mutex, which
- * protects us from the tty struct or driver itself going away.
- *
* On exit the tty device has the line discipline attached and
* a reference count of 1. If a pair was created for pty/tty use
* and the other was a pty master then it too has a reference count of 1.
@@ -1285,6 +1277,9 @@ static int tty_reopen(struct tty_struct *tty)
* failed open. The new code protects the open with a mutex, so it's
* really quite straightforward. The mutex locking can probably be
* relaxed for the (most common) case of reopening a tty.
+ *
+ * Context: The function is called under the tty_mutex, which
+ * protects us from the tty struct or driver itself going away.
*/
struct tty_struct *tty_init_dev(struct tty_driver *driver, int idx)
{
@@ -1399,12 +1394,11 @@ static void tty_flush_works(struct tty_struct *tty)
* driver table slots. This function is called when a device is no longer
* in use. It also gets called when setup of a device fails.
*
- * Locking:
- * takes the file list lock internally when working on the list
- * of ttys that the driver keeps.
- *
* This method gets called from a work queue so that the driver private
* cleanup ops can sleep (needed for USB at least)
+ *
+ * Context: Takes the file list lock internally when working on the list
+ * of ttys that the driver keeps.
*/
static void release_one_tty(struct work_struct *work)
{
@@ -1599,15 +1593,14 @@ EXPORT_SYMBOL_GPL(tty_release_struct);
* Called the last time each file handle is closed that references
* this tty. There may however be several such references.
*
- * Locking:
- * Takes bkl. See tty_release_dev
- *
* Even releasing the tty structures is a tricky business.. We have
* to be very careful that the structures are all released at the
* same time, as interrupts might otherwise get the wrong pointers.
*
* WSH 09/09/97: rewritten to avoid some nasty race conditions that could
* lead to double frees or releasing memory still in use.
+ *
+ * Context: Takes bkl. See tty_release_dev
*/
int tty_release(struct inode *inode, struct file *filp)
{
@@ -1840,12 +1833,12 @@ static struct tty_driver *tty_lookup_driver(dev_t device, struct file *filp,
* makes sure it's not already opened and performs the first-time
* tty initialization.
*
- * Returns the locked initialized &tty_struct
- *
- * Claims the global tty_mutex to serialize:
+ * Context: Claims the global tty_mutex to serialize:
* - concurrent first-time tty initialization
* - concurrent tty driver removal w/ lookup
* - concurrent tty removal from driver table
+ *
+ * Return: The locked initialized &tty_struct.
*/
struct tty_struct *tty_kopen(dev_t device)
{
@@ -1891,12 +1884,12 @@ EXPORT_SYMBOL_GPL(tty_kopen);
* Performs the driver lookup, checks for a reopen, or otherwise
* performs the first-time tty initialization.
*
- * Returns the locked initialized or re-opened &tty_struct
- *
- * Claims the global tty_mutex to serialize:
+ * Context: Claims the global tty_mutex to serialize:
* - concurrent first-time tty initialization
* - concurrent tty driver removal w/ lookup
* - concurrent tty removal from driver table
+ *
+ * Return: The locked initialized or re-opened &tty_struct.
*/
static struct tty_struct *tty_open_by_driver(dev_t device, struct inode *inode,
struct file *filp)
@@ -1966,7 +1959,7 @@ static struct tty_struct *tty_open_by_driver(dev_t device, struct inode *inode,
* The termios state of a pty is reset on first open so that
* settings don't persist across reuse.
*
- * Locking: tty_mutex protects tty, tty_lookup_driver and tty_init_dev.
+ * Context: tty_mutex protects tty, tty_lookup_driver and tty_init_dev.
* tty->count should protect the rest.
* ->siglock protects ->signal/->sighand
*
@@ -2053,8 +2046,8 @@ static int tty_open(struct inode *inode, struct file *filp)
* Call the line discipline polling method to obtain the poll
* status of the device.
*
- * Locking: locks called line discipline but ldisc poll method
- * may be re-entered freely by other callers.
+ * Context: Locks called line discipline but ldisc poll method
+ * may be re-entered freely by other callers.
*/
static __poll_t tty_poll(struct file *filp, poll_table *wait)
{
@@ -2132,9 +2125,8 @@ static int tty_fasync(int fd, struct file *filp, int on)
*
* FIXME: does not honour flow control ??
*
- * Locking:
- * Called functions take tty_ldiscs_lock
- * current->signal->tty check is safe without locks
+ * Context: Called functions take tty_ldiscs_lock
+ * current->signal->tty check is safe without locks
*
* FIXME: may race normal receive processing
*/
@@ -2163,7 +2155,7 @@ static int tiocsti(struct tty_struct *tty, char __user *p)
*
* Copies the kernel idea of the window size into the user buffer.
*
- * Locking: tty->winsize_mutex is taken to ensure the winsize data
+ * Context: tty->winsize_mutex is taken to ensure the winsize data
* is consistent.
*/
static int tiocgwinsz(struct tty_struct *tty, struct winsize __user *arg)
@@ -2217,10 +2209,9 @@ EXPORT_SYMBOL(tty_do_resize);
* this is just advisory information but for the Linux console it
* actually has driver level meaning and triggers a VC resize.
*
- * Locking:
- * Driver dependent. The default do_resize method takes the
- * tty termios mutex and ctrl_lock. The console takes its own lock
- * then calls into the default method.
+ * Context: Driver dependent. The default do_resize method takes the
+ * tty termios mutex and ctrl_lock. The console takes its own lock
+ * then calls into the default method.
*/
static int tiocswinsz(struct tty_struct *tty, struct winsize __user *arg)
{
@@ -2240,7 +2231,7 @@ static int tiocswinsz(struct tty_struct *tty, struct winsize __user *arg)
*
* Allow the administrator to move the redirected console device
*
- * Locking: uses redirect_lock to guard the redirect information
+ * Context: Uses redirect_lock to guard the redirect information.
*/
static int tioccons(struct file *file)
{
@@ -2275,7 +2266,7 @@ static int tioccons(struct file *file)
* the generic functionality existed. This piece of history is preserved
* in the expected tty API of posix OS's.
*
- * Locking: none, the open file handle ensures it won't go away.
+ * Context: No locks taken, the open file handle ensures it won't go away.
*/
static int fionbio(struct file *file, int __user *p)
{
@@ -2300,7 +2291,7 @@ static int fionbio(struct file *file, int __user *p)
*
* Set the line discipline according to user request.
*
- * Locking: see tty_set_ldisc, this function is just a helper
+ * Context: Please see tty_set_ldisc, this function is just a helper.
*/
static int tiocsetd(struct tty_struct *tty, int __user *p)
{
@@ -2322,8 +2313,8 @@ static int tiocsetd(struct tty_struct *tty, int __user *p)
*
* Retrieves the line discipline id directly from the ldisc.
*
- * Locking: waits for ldisc reference (in case the line discipline
- * is changing or the tty is being hungup)
+ * Context: Waits for ldisc reference (in case the line discipline
+ * is changing or the tty is being hungup).
*/
static int tiocgetd(struct tty_struct *tty, int __user *p)
{
@@ -2346,9 +2337,7 @@ static int tiocgetd(struct tty_struct *tty, int __user *p)
* Perform a timed break on hardware that lacks its own driver level
* timed break functionality.
*
- * Locking:
- * atomic_write_lock serializes
- *
+ * Context: atomic_write_lock serializes.
*/
static int send_break(struct tty_struct *tty, unsigned int duration)
{
@@ -2386,7 +2375,7 @@ static int send_break(struct tty_struct *tty, unsigned int duration)
* Obtain the modem status bits from the tty driver if the feature
* is supported. Return -EINVAL if it is not available.
*
- * Locking: none (up to the driver)
+ * Context: No locks taken (up to the driver).
*/
static int tty_tiocmget(struct tty_struct *tty, int __user *p)
{
@@ -2410,7 +2399,7 @@ static int tty_tiocmget(struct tty_struct *tty, int __user *p)
* Set the modem status bits from the tty driver if the feature
* is supported. Return -EINVAL if it is not available.
*
- * Locking: none (up to the driver)
+ * Context: No locks taken (up to the driver).
*/
static int tty_tiocmset(struct tty_struct *tty, unsigned int cmd,
unsigned __user *p)
@@ -2776,7 +2765,7 @@ static struct device *tty_get_device(struct tty_struct *tty)
*
* This subroutine allocates and initializes a tty structure.
*
- * Locking: none - tty in question is not exposed at this point
+ * Locking: No locks taken - tty in question is not exposed at this point.
*/
struct tty_struct *alloc_tty_struct(struct tty_driver *driver, int idx)
{
@@ -2824,10 +2813,12 @@ struct tty_struct *alloc_tty_struct(struct tty_driver *driver, int idx)
* @ch: character
*
* Write one byte to the tty using the provided put_char method
- * if present. Returns the number of characters successfully output.
+ * if present.
*
* Note: the specific put_char operation in the driver layer may go
* away soon. Don't call it directly, use this method
+ *
+ * Return: The number of characters successfully output.
*/
int tty_put_char(struct tty_struct *tty, unsigned char ch)
{
@@ -2864,15 +2855,15 @@ static int tty_cdev_add(struct tty_driver *driver, dev_t dev,
* This field is optional, if there is no known struct device
* for this tty device it can be set to NULL safely.
*
- * Returns a pointer to the struct device for this tty device
- * (or ERR_PTR(-EFOO) on error).
- *
* This call is required to be made to register an individual tty device
* if the tty driver's flags have the TTY_DRIVER_DYNAMIC_DEV bit set. If
* that bit is not set, this function should not be called by a tty
* driver.
*
* Locking: ??
+ *
+ * Return: A pointer to the struct device for this tty device
+ * (or ERR_PTR(-EFOO) on error).
*/
struct device *tty_register_device(struct tty_driver *driver, unsigned index,
struct device *device)
@@ -2897,15 +2888,15 @@ static void tty_device_create_release(struct device *dev)
* @drvdata: Driver data to be set to device.
* @attr_grp: Attribute group to be set on device.
*
- * Returns a pointer to the struct device for this tty device
- * (or ERR_PTR(-EFOO) on error).
- *
* This call is required to be made to register an individual tty device
* if the tty driver's flags have the TTY_DRIVER_DYNAMIC_DEV bit set. If
* that bit is not set, this function should not be called by a tty
* driver.
*
* Locking: ??
+ *
+ * Return: A pointer to the struct device for this tty device
+ * (or ERR_PTR(-EFOO) on error).
*/
struct device *tty_register_device_attr(struct tty_driver *driver,
unsigned index, struct device *device,
diff --git a/drivers/tty/tty_ioctl.c b/drivers/tty/tty_ioctl.c
index ca5d3923342d..d23872fb2ad8 100644
--- a/drivers/tty/tty_ioctl.c
+++ b/drivers/tty/tty_ioctl.c
@@ -147,7 +147,7 @@ EXPORT_SYMBOL(tty_unthrottle);
* throttle due to race conditions when throttling is conditional
* on factors evaluated prior to throttling.
*
- * Returns 0 if tty is throttled (or was already throttled)
+ * Return: 0 if tty is throttled (or was already throttled).
*/
int tty_throttle_safe(struct tty_struct *tty)
{
@@ -177,7 +177,7 @@ int tty_throttle_safe(struct tty_struct *tty)
* unthrottle due to race conditions when unthrottling is conditional
* on factors evaluated prior to unthrottling.
*
- * Returns 0 if tty is unthrottled (or was already unthrottled)
+ * Return: 0 if tty is unthrottled (or was already unthrottled).
*/
int tty_unthrottle_safe(struct tty_struct *tty)
{
@@ -206,7 +206,7 @@ int tty_unthrottle_safe(struct tty_struct *tty)
* Wait for characters pending in a tty driver to hit the wire, or
* for a timeout to occur (eg due to flow control)
*
- * Locking: none
+ * Context: No locks taken.
*/
void tty_wait_until_sent(struct tty_struct *tty, long timeout)
{
@@ -301,7 +301,7 @@ EXPORT_SYMBOL(tty_termios_hw_change);
* Perform updates to the termios values set on this terminal.
* A master pty's termios should never be set.
*
- * Locking: termios_rwsem
+ * Context: Takes termios_rwsem.
*/
int tty_set_termios(struct tty_struct *tty, struct ktermios *new_termios)
{
@@ -347,8 +347,7 @@ EXPORT_SYMBOL_GPL(tty_set_termios);
* Helper function to prepare termios data and run necessary other
* functions before using tty_set_termios to do the actual changes.
*
- * Locking:
- * Called functions take ldisc and termios_rwsem locks
+ * Context: Takes termios_rwsem. Called functions take ldisc.
*/
static int set_termios(struct tty_struct *tty, void __user *arg, int opt)
{
@@ -551,7 +550,7 @@ static void set_sgflags(struct ktermios *termios, int flags)
* Updates a terminal from the legacy BSD style terminal information
* structure.
*
- * Locking: termios_rwsem
+ * Context: Takes termios_rwsem.
*/
static int set_sgttyb(struct tty_struct *tty, struct sgttyb __user *sgttyb)
{
@@ -662,6 +661,8 @@ static int set_ltchars(struct tty_struct *tty, struct ltchars __user *ltchars)
*
* Perform a change to the CLOCAL state and call into the driver
* layer to make it visible. All done with the termios rwsem
+ *
+ * Context: Takes termios_rwsem.
*/
static int tty_change_softcar(struct tty_struct *tty, int arg)
{
diff --git a/drivers/tty/tty_jobctrl.c b/drivers/tty/tty_jobctrl.c
index 3b5c822d360d..629452b9fe08 100644
--- a/drivers/tty/tty_jobctrl.c
+++ b/drivers/tty/tty_jobctrl.c
@@ -26,7 +26,7 @@ static int is_ignored(int sig)
* not in the foreground, send a SIGTTOU. If the signal is blocked or
* ignored, go ahead and perform the operation. (POSIX 7.2)
*
- * Locking: ctrl_lock
+ * Context: Takes ctrl_lock.
*/
int __tty_check_change(struct tty_struct *tty, int sig)
{
@@ -87,9 +87,8 @@ void proc_clear_tty(struct task_struct *p)
* Only callable by the session leader and only if it does not already have
* a controlling terminal.
*
- * Caller must hold: tty_lock()
- * a readlock on tasklist_lock
- * sighand lock
+ * Context: Caller must hold tty_lock(), a readlock on tasklist_lock, and
+ * sighand lock.
*/
static void __proc_set_tty(struct tty_struct *tty)
{
@@ -335,10 +334,9 @@ void no_tty(void)
* This ioctl is used to manage job control. It permits a session
* leader to set this tty as the controlling tty for the session.
*
- * Locking:
- * Takes tty_lock() to serialize proc_set_tty() for this tty
- * Takes tasklist_lock internally to walk sessions
- * Takes ->siglock() when updating signal->tty
+ * Context: Takes tty_lock() to serialize proc_set_tty() for this tty
+ * Takes tasklist_lock internally to walk sessions
+ * Takes ->siglock() when updating signal->tty
*/
static int tiocsctty(struct tty_struct *tty, struct file *file, int arg)
{
@@ -438,7 +436,7 @@ static struct pid *session_of_pgrp(struct pid *pgrp)
* Obtain the process group of the tty. If there is no process group
* return an error.
*
- * Locking: none. Reference to current->signal->tty is safe.
+ * Context: No Locks taken. Reference to current->signal->tty is safe.
*/
static int tiocgpgrp(struct tty_struct *tty, struct tty_struct *real_tty, pid_t __user *p)
{
@@ -465,7 +463,7 @@ static int tiocgpgrp(struct tty_struct *tty, struct tty_struct *real_tty, pid_t
* Set the process group of the tty to the session passed. Only
* permitted where the tty session is our session.
*
- * Locking: RCU, ctrl lock
+ * Context: RCU, ctrl lock
*/
static int tiocspgrp(struct tty_struct *tty, struct tty_struct *real_tty, pid_t __user *p)
{
@@ -512,7 +510,7 @@ static int tiocspgrp(struct tty_struct *tty, struct tty_struct *real_tty, pid_t
* Obtain the session id of the tty. If there is no session
* return an error.
*
- * Locking: none. Reference to current->signal->tty is safe.
+ * Context: No locks taken. Reference to current->signal->tty is safe.
*/
static int tiocgsid(struct tty_struct *tty, struct tty_struct *real_tty, pid_t __user *p)
{
diff --git a/drivers/tty/tty_ldisc.c b/drivers/tty/tty_ldisc.c
index d54985ea6088..b9c62682996d 100644
--- a/drivers/tty/tty_ldisc.c
+++ b/drivers/tty/tty_ldisc.c
@@ -54,8 +54,7 @@ static struct tty_ldisc_ops *tty_ldiscs[NR_LDISCS];
* is set up as unreferenced and then made available to the kernel
* from this point onwards.
*
- * Locking:
- * takes tty_ldiscs_lock to guard against ldisc races
+ * Context: Takes tty_ldiscs_lock to guard against ldisc races.
*/
int tty_register_ldisc(int disc, struct tty_ldisc_ops *new_ldisc)
{
@@ -83,8 +82,7 @@ EXPORT_SYMBOL(tty_register_ldisc);
* Remove a line discipline from the kernel providing it is not
* currently in use.
*
- * Locking:
- * takes tty_ldiscs_lock to guard against ldisc races
+ * Context: Takes tty_ldiscs_lock to guard against ldisc races.
*/
int tty_unregister_ldisc(int disc)
{
@@ -141,17 +139,16 @@ static void put_ldops(struct tty_ldisc_ops *ldops)
* Takes a reference to a line discipline. Deals with refcounts and
* module locking counts.
*
- * Returns: -EINVAL if the discipline index is not [N_TTY..NR_LDISCS] or
- * if the discipline is not registeredn
- * -EAGAIN if request_module() failed to load or register the
- * the discipline
- * -ENOMEM if allocation failure
+ * Context: Takes tty_ldiscs_lock to guard against ldisc races.
*
- * Otherwise, returns a pointer to the discipline and bumps the
- * ref count
+ * Return: -EINVAL if the discipline index is not [N_TTY..NR_LDISCS] or
+ * if the discipline is not registered
+ * -EAGAIN if request_module() failed to load or register the
+ * the discipline
+ * -ENOMEM if allocation failure
*
- * Locking:
- * takes tty_ldiscs_lock to guard against ldisc races
+ * Otherwise, returns a pointer to the discipline and bumps the
+ * ref count.
*/
static struct tty_ldisc *tty_ldisc_get(struct tty_struct *tty, int disc)
{
@@ -241,9 +238,6 @@ const struct seq_operations tty_ldiscs_seq_ops = {
* reference to it. If the line discipline is in flux then
* wait patiently until it changes.
*
- * Returns: NULL if the tty has been hungup and not re-opened with
- * a new file descriptor, otherwise valid ldisc reference
- *
* Note: Must not be called from an IRQ/timer context. The caller
* must also be careful not to hold other locks that will deadlock
* against a discipline change, such as an existing ldisc reference
@@ -251,6 +245,9 @@ const struct seq_operations tty_ldiscs_seq_ops = {
*
* Note: a file_operations routine (read/poll/write) should use this
* function to wait for any ldisc lifetime events to finish.
+ *
+ * Return: NULL if the tty has been hungup and not re-opened with
+ * a new file descriptor, otherwise valid ldisc reference
*/
struct tty_ldisc *tty_ldisc_ref_wait(struct tty_struct *tty)
{
@@ -413,7 +410,7 @@ EXPORT_SYMBOL_GPL(tty_ldisc_flush);
* prevent the ldisc driver from re-using stale information for
* the new ldisc instance.
*
- * Locking: takes termios_rwsem
+ * Context: Takes termios_rwsem.
*/
static void tty_set_termios_ldisc(struct tty_struct *tty, int disc)
{
@@ -433,7 +430,7 @@ static void tty_set_termios_ldisc(struct tty_struct *tty, int disc)
* A helper opening method. Also a convenient debugging and check
* point.
*
- * Locking: always called with BTM already held.
+ * Context: Always called with BTM already held.
*/
static int tty_ldisc_open(struct tty_struct *tty, struct tty_ldisc *ld)
{
@@ -640,7 +637,7 @@ static void tty_reset_termios(struct tty_struct *tty)
* is dropped and tty->ldisc reset to NULL. The caller can then retry
* with N_TTY instead.
*
- * Returns 0 if successful, otherwise error code < 0
+ * Return: 0 if successful, otherwise error code < 0.
*/
int tty_ldisc_reinit(struct tty_struct *tty, int disc)
{
@@ -677,8 +674,8 @@ int tty_ldisc_reinit(struct tty_struct *tty, int disc)
* event. In that situation we must also switch back to N_TTY properly
* before we reset the termios data.
*
- * Locking: We can take the ldisc mutex as the rest of the code is
- * careful to allow for this.
+ * Context: We can take the ldisc mutex as the rest of the code is
+ * careful to allow for this.
*
* In the pty pair case this occurs in the close() path of the
* tty itself so we must be careful about locking rules.
@@ -801,8 +798,8 @@ int tty_ldisc_init(struct tty_struct *tty)
* tty_ldisc_deinit() - ldisc cleanup for new tty
* @tty: tty that was allocated recently
*
- * The tty structure must not becompletely set up (tty_ldisc_setup) when
- * this call is made.
+ * The tty structure must not be completely set up (tty_ldisc_setup) when
+ * this call is made.
*/
void tty_ldisc_deinit(struct tty_struct *tty)
{
diff --git a/drivers/tty/tty_port.c b/drivers/tty/tty_port.c
index d4dfe29a6348..c5770682ee7a 100644
--- a/drivers/tty/tty_port.c
+++ b/drivers/tty/tty_port.c
@@ -339,7 +339,7 @@ static void tty_port_shutdown(struct tty_port *port, struct tty_struct *tty)
* Perform port level tty hangup flag and count changes. Drop the tty
* reference.
*
- * Caller holds tty lock.
+ * Context: Caller holds tty lock.
*/
void tty_port_hangup(struct tty_port *port)
{
@@ -451,7 +451,7 @@ EXPORT_SYMBOL(tty_port_lower_dtr_rts);
* management of these lines. Note that the dtr/rts raise is done each
* iteration as a hangup may have previously dropped them while we wait.
*
- * Caller holds tty lock.
+ * Context: Caller holds tty lock.
*
* NB: May drop and reacquire tty lock when blocking, so tty and tty_port
* may have changed state (eg., may have been hung up).
@@ -623,7 +623,7 @@ EXPORT_SYMBOL(tty_port_close_end);
/**
* tty_port_close()
*
- * Caller holds tty lock
+ * Context: Caller holds tty lock.
*/
void tty_port_close(struct tty_port *port, struct tty_struct *tty,
struct file *filp)
@@ -658,7 +658,7 @@ EXPORT_SYMBOL_GPL(tty_port_install);
/**
* tty_port_open()
*
- * Caller holds tty lock.
+ * Context: Caller holds tty lock.
*
* NB: may drop and reacquire tty lock (in tty_port_block_til_ready()) so
* tty and tty_port may have changed state (eg., may be hung up now)
diff --git a/drivers/tty/vt/consolemap.c b/drivers/tty/vt/consolemap.c
index 74f4ef98aa7d..45bc49229fe5 100644
--- a/drivers/tty/vt/consolemap.c
+++ b/drivers/tty/vt/consolemap.c
@@ -654,7 +654,7 @@ int con_set_unimap(struct vc_data *vc, ushort ct, struct unipair __user *list)
* with. This routine is executed at video setup, and when the
* PIO_FONTRESET ioctl is called.
*
- * The caller must hold the console lock
+ * Context: The caller must hold the console lock.
*/
int con_set_default_unimap(struct vc_data *vc)
{
@@ -710,7 +710,7 @@ EXPORT_SYMBOL(con_set_default_unimap);
* @dst_vc: target
* @src_vt: source
*
- * The caller must hold the console lock when invoking this method
+ * Context: The caller must hold the console lock.
*/
int con_copy_unimap(struct vc_data *dst_vc, struct vc_data *src_vc)
{
diff --git a/drivers/tty/vt/keyboard.c b/drivers/tty/vt/keyboard.c
index 3c3eb14e1565..487e5af87173 100644
--- a/drivers/tty/vt/keyboard.c
+++ b/drivers/tty/vt/keyboard.c
@@ -1789,7 +1789,8 @@ int vt_do_diacrit(unsigned int cmd, void __user *udp, int perm)
* @arg: the requested mode
*
* Update the keyboard mode bits while holding the correct locks.
- * Return 0 for success or an error code.
+ *
+ * Return: 0 for success or an error code.
*/
int vt_do_kdskbmode(int console, unsigned int arg)
{
@@ -1829,7 +1830,8 @@ int vt_do_kdskbmode(int console, unsigned int arg)
* @arg: the requested meta state
*
* Update the keyboard meta bits while holding the correct locks.
- * Return 0 for success or an error code.
+ *
+ * Return: 0 for success or an error code.
*/
int vt_do_kdskbmeta(int console, unsigned int arg)
{
diff --git a/drivers/tty/vt/selection.c b/drivers/tty/vt/selection.c
index 473015beb0f2..309b3f043710 100644
--- a/drivers/tty/vt/selection.c
+++ b/drivers/tty/vt/selection.c
@@ -70,7 +70,9 @@ sel_pos(int n)
* clear_selection() - remove current selection
*
* Remove the current selection highlight, if any from the console
- * holding the selection. The caller must hold the console lock.
+ * holding the selection.
+ *
+ * Context: The caller must hold the console lock.
*/
void clear_selection(void)
{
@@ -101,8 +103,10 @@ static inline int inword(const u32 c)
* sel_loadlut() - load the LUT table
* @p: user table
*
- * Load the LUT table from user space. The caller must hold the console
- * lock. Make a temporary copy so a partial update doesn't make a mess.
+ * Load the LUT table from user space. Make a temporary copy so a
+ * partial update doesn't make a mess.
+ *
+ * Context: The caller must hold the console lock.
*/
int sel_loadlut(char __user *p)
{
diff --git a/drivers/tty/vt/vt.c b/drivers/tty/vt/vt.c
index dae5a7a82aee..e0c989647d7e 100644
--- a/drivers/tty/vt/vt.c
+++ b/drivers/tty/vt/vt.c
@@ -1140,8 +1140,8 @@ static inline int resize_screen(struct vc_data *vc, int width, int height,
* If the caller passes a tty structure then update the termios winsize
* information and perform any necessary signal handling.
*
- * Caller must hold the console semaphore. Takes the termios rwsem and
- * ctrl_lock of the tty IFF a tty is passed.
+ * Context: Caller must hold the console semaphore. Takes the termios_rwsem
+ * and ctrl_lock of the tty IFF a tty is passed.
*/
static int vc_do_resize(struct tty_struct *tty, struct vc_data *vc,
@@ -3797,10 +3797,10 @@ static void vtconsole_deinit_device(struct con_driver *con)
* con_is_bound() - checks if driver is bound to the console
* @csw: console driver
*
- * RETURNS: zero if unbound, nonzero if bound
- *
* Drivers can call this and if zero, they should release
* all resources allocated on con_startup()
+ *
+ * Return: zero if unbound, nonzero if bound.
*/
int con_is_bound(const struct consw *csw)
{
@@ -3825,9 +3825,8 @@ EXPORT_SYMBOL(con_is_bound);
* function needs to save the current console state, then put the console
* into a state suitable for the kernel debugger.
*
- * RETURNS:
- * Zero on success, nonzero if a failure occurred when trying to prepare
- * the console for the debugger.
+ * Return: Zero on success, nonzero if a failure occurred when trying to
+ * prepare the console for the debugger.
*/
int con_debug_enter(struct vc_data *vc)
{
@@ -3882,9 +3881,8 @@ EXPORT_SYMBOL_GPL(con_debug_enter);
* Restore the console state to what it was before the kernel debugger
* was invoked.
*
- * RETURNS:
- * Zero on success, nonzero if a failure occurred when trying to restore
- * the console.
+ * Return: Zero on success, nonzero if a failure occurred when trying
+ * to restore the console.
*/
int con_debug_leave(void)
{
@@ -3977,10 +3975,10 @@ static int do_register_con_driver(const struct consw *csw, int first, int last)
* do_unregister_con_driver() - unregister console driver from console layer
* @csw: console driver
*
- * DESCRIPTION: All drivers that registers to the console layer must
- * call this function upon exit, or if the console driver is in a state
- * where it won't be able to handle console services, such as the
- * framebuffer console without loaded framebuffer drivers.
+ * All drivers that registers to the console layer must call this function
+ * upon exit, or if the console driver is in a state where it won't be able
+ * to handle console services, such as the framebuffer console without
+ * loaded framebuffer drivers.
*
* The driver must unbind first prior to unregistration.
*/
--
2.17.1
Powered by blists - more mailing lists