[PATCH v2 1/1] tty: n_tty: Fix some misdocumented functions

[PATCH v2 1/1] tty: n_tty: Fix some misdocumented functions

[Lee Jones]

Fixes the following W=1 kernel build warning(s):

 drivers/tty/n_tty.c:623: warning: expecting prototype for process_echoes(). Prototype was for __process_echoes() instead
 drivers/tty/n_tty.c:1109: warning: expecting prototype for isig(). Prototype was for __isig() instead
 drivers/tty/n_tty.c:1268: warning: expecting prototype for n_tty_receive_char(). Prototype was for n_tty_receive_char_special() instead
 drivers/tty/n_tty.c:2132: warning: Excess function parameter 'buf' description in 'n_tty_read'

Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Jiri Slaby <jirislaby@kernel.org>
Cc: "Andrew J. Kroll" <ag784@freenet.buffalo.edu>
Cc: processes-Sapan Bhatia <sapan@corewars.org>
Signed-off-by: Lee Jones <lee.jones@linaro.org>
---

v2: Rebased

 drivers/tty/n_tty.c | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/drivers/tty/n_tty.c b/drivers/tty/n_tty.c
index 0ec93f1a61f5d..56d3b43d8a3a4 100644
--- a/drivers/tty/n_tty.c
+++ b/drivers/tty/n_tty.c
@@ -596,7 +596,7 @@ static ssize_t process_output_block(struct tty_struct *tty,
 }
 
 /**
- *	process_echoes	-	write pending echo characters
+ *	__process_echoes	-	write pending echo characters
  *	@tty: terminal device
  *
  *	Write previously buffered echo (and other ldisc-generated)
@@ -1092,7 +1092,7 @@ static void eraser(unsigned char c, struct tty_struct *tty)
 }
 
 /**
- *	isig		-	handle the ISIG optio
+ *	__isig		-	handle the ISIG optio
  *	@sig: signal
  *	@tty: terminal
  *
@@ -1248,7 +1248,7 @@ n_tty_receive_signal_char(struct tty_struct *tty, int signal, unsigned char c)
 }
 
 /**
- *	n_tty_receive_char	-	perform processing
+ *	n_tty_receive_char_special	-	perform processing
  *	@tty: terminal device
  *	@c: character
  *
@@ -2042,11 +2042,11 @@ static int job_control(struct tty_struct *tty, struct file *file)
 }
 
 
-/**
+/*
  *	n_tty_read		-	read function for tty
  *	@tty: tty device
  *	@file: file object
- *	@buf: userspace buffer pointer
+ *	@kbuf: userspace buffer pointer
  *	@nr: size of I/O
  *
  *	Perform reads for the line discipline. We are guaranteed that the
-- 
2.31.1

Re: [PATCH v2 1/1] tty: n_tty: Fix some misdocumented functions

[Jiri Slaby]

On 26. 05. 21, 10:31, Lee Jones wrote:
> Fixes the following W=1 kernel build warning(s):
> 
>   drivers/tty/n_tty.c:623: warning: expecting prototype for process_echoes(). Prototype was for __process_echoes() instead
>   drivers/tty/n_tty.c:1109: warning: expecting prototype for isig(). Prototype was for __isig() instead
>   drivers/tty/n_tty.c:1268: warning: expecting prototype for n_tty_receive_char(). Prototype was for n_tty_receive_char_special() instead
>   drivers/tty/n_tty.c:2132: warning: Excess function parameter 'buf' description in 'n_tty_read'
> 
> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> Cc: Jiri Slaby <jirislaby@kernel.org>
> Cc: "Andrew J. Kroll" <ag784@freenet.buffalo.edu>
> Cc: processes-Sapan Bhatia <sapan@corewars.org>
> Signed-off-by: Lee Jones <lee.jones@linaro.org>
> ---
> 
> v2: Rebased
> 
>   drivers/tty/n_tty.c | 10 +++++-----
>   1 file changed, 5 insertions(+), 5 deletions(-)
> 
> diff --git a/drivers/tty/n_tty.c b/drivers/tty/n_tty.c
> index 0ec93f1a61f5d..56d3b43d8a3a4 100644
> --- a/drivers/tty/n_tty.c
> +++ b/drivers/tty/n_tty.c
...
> @@ -1248,7 +1248,7 @@ n_tty_receive_signal_char(struct tty_struct *tty, int signal, unsigned char c)
>   }
>   
>   /**
> - *	n_tty_receive_char	-	perform processing
> + *	n_tty_receive_char_special	-	perform processing

No, please move the doc to the function in this case instead.

>    *	@tty: terminal device
>    *	@c: character
>    *
> @@ -2042,11 +2042,11 @@ static int job_control(struct tty_struct *tty, struct file *file)
>   }
>   
>   
> -/**
> +/*

Why this?

>    *	n_tty_read		-	read function for tty
>    *	@tty: tty device
>    *	@file: file object
> - *	@buf: userspace buffer pointer
> + *	@kbuf: userspace buffer pointer
>    *	@nr: size of I/O
>    *
>    *	Perform reads for the line discipline. We are guaranteed that the
> 

thanks,
-- 
js
suse labs

Re: [PATCH v2 1/1] tty: n_tty: Fix some misdocumented functions

[Lee Jones]

On Thu, 27 May 2021, Jiri Slaby wrote:

> On 26. 05. 21, 10:31, Lee Jones wrote:
> > Fixes the following W=1 kernel build warning(s):
> > 
> >   drivers/tty/n_tty.c:623: warning: expecting prototype for process_echoes(). Prototype was for __process_echoes() instead
> >   drivers/tty/n_tty.c:1109: warning: expecting prototype for isig(). Prototype was for __isig() instead
> >   drivers/tty/n_tty.c:1268: warning: expecting prototype for n_tty_receive_char(). Prototype was for n_tty_receive_char_special() instead
> >   drivers/tty/n_tty.c:2132: warning: Excess function parameter 'buf' description in 'n_tty_read'
> > 
> > Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> > Cc: Jiri Slaby <jirislaby@kernel.org>
> > Cc: "Andrew J. Kroll" <ag784@freenet.buffalo.edu>
> > Cc: processes-Sapan Bhatia <sapan@corewars.org>
> > Signed-off-by: Lee Jones <lee.jones@linaro.org>
> > ---
> > 
> > v2: Rebased
> > 
> >   drivers/tty/n_tty.c | 10 +++++-----
> >   1 file changed, 5 insertions(+), 5 deletions(-)
> > 
> > diff --git a/drivers/tty/n_tty.c b/drivers/tty/n_tty.c
> > index 0ec93f1a61f5d..56d3b43d8a3a4 100644
> > --- a/drivers/tty/n_tty.c
> > +++ b/drivers/tty/n_tty.c
> ...
> > @@ -1248,7 +1248,7 @@ n_tty_receive_signal_char(struct tty_struct *tty, int signal, unsigned char c)
> >   }
> >   /**
> > - *	n_tty_receive_char	-	perform processing
> > + *	n_tty_receive_char_special	-	perform processing
> 
> No, please move the doc to the function in this case instead.

Oh, so this *really* is the doc for n_tty_receive_char()?

> >    *	@tty: terminal device
> >    *	@c: character
> >    *
> > @@ -2042,11 +2042,11 @@ static int job_control(struct tty_struct *tty, struct file *file)
> >   }
> > -/**
> > +/*
> 
> Why this?

Because the author has missed:

  void **cookie, unsigned long offset

Once these descriptions are provided, it can be re-promoted.

> >    *	n_tty_read		-	read function for tty
> >    *	@tty: tty device
> >    *	@file: file object
> > - *	@buf: userspace buffer pointer
> > + *	@kbuf: userspace buffer pointer
> >    *	@nr: size of I/O
> >    *
> >    *	Perform reads for the line discipline. We are guaranteed that the
> > 
> 
> thanks,

-- 
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog

Re: [PATCH v2 1/1] tty: n_tty: Fix some misdocumented functions

[Jiri Slaby]

On 27. 05. 21, 10:20, Lee Jones wrote:
> On Thu, 27 May 2021, Jiri Slaby wrote:
> 
>> On 26. 05. 21, 10:31, Lee Jones wrote:
>>> Fixes the following W=1 kernel build warning(s):
>>>
>>>    drivers/tty/n_tty.c:623: warning: expecting prototype for process_echoes(). Prototype was for __process_echoes() instead
>>>    drivers/tty/n_tty.c:1109: warning: expecting prototype for isig(). Prototype was for __isig() instead
>>>    drivers/tty/n_tty.c:1268: warning: expecting prototype for n_tty_receive_char(). Prototype was for n_tty_receive_char_special() instead
>>>    drivers/tty/n_tty.c:2132: warning: Excess function parameter 'buf' description in 'n_tty_read'
>>>
>>> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
>>> Cc: Jiri Slaby <jirislaby@kernel.org>
>>> Cc: "Andrew J. Kroll" <ag784@freenet.buffalo.edu>
>>> Cc: processes-Sapan Bhatia <sapan@corewars.org>
>>> Signed-off-by: Lee Jones <lee.jones@linaro.org>
>>> ---
>>>
>>> v2: Rebased
>>>
>>>    drivers/tty/n_tty.c | 10 +++++-----
>>>    1 file changed, 5 insertions(+), 5 deletions(-)
>>>
>>> diff --git a/drivers/tty/n_tty.c b/drivers/tty/n_tty.c
>>> index 0ec93f1a61f5d..56d3b43d8a3a4 100644
>>> --- a/drivers/tty/n_tty.c
>>> +++ b/drivers/tty/n_tty.c
>> ...
>>> @@ -1248,7 +1248,7 @@ n_tty_receive_signal_char(struct tty_struct *tty, int signal, unsigned char c)
>>>    }
>>>    /**
>>> - *	n_tty_receive_char	-	perform processing
>>> + *	n_tty_receive_char_special	-	perform processing
>>
>> No, please move the doc to the function in this case instead.
> 
> Oh, so this *really* is the doc for n_tty_receive_char()?

Yes, it is supposed to. See 4b1f79c2d7352605b567cab49de20d3b67762ee3, 
which omitted to move the comment.

> 
>>>     *	@tty: terminal device
>>>     *	@c: character
>>>     *
>>> @@ -2042,11 +2042,11 @@ static int job_control(struct tty_struct *tty, struct file *file)
>>>    }
>>> -/**
>>> +/*
>>
>> Why this?
> 
> Because the author has missed:
> 
>    void **cookie, unsigned long offset

Oh, that. The doc by far predates the recent cookie introduction.

> Once these descriptions are provided, it can be re-promoted.

OK, I will fix this later. I am just putting the pieces together to link 
all these TTY kernel-docs from Documentation/.

thanks,
-- 
js
suse labs