[PATCH 0/9] serial: doc: Low Level Serial API Documentation Improvements

[PATCH 0/9] serial: doc: Low Level Serial API Documentation Improvements

[Geert Uytterhoeven]

	Hi Russell, Greg, Jiri, Jon,

This patch series contains improvements to the low level serial driver
API documentation.

Thanks for your comments!

Geert Uytterhoeven (9):
  serial: doc: Un-document non-existing uart_write_console()
  serial: doc: Un-document obsolete tmpbuf_sem
  serial: doc: Document .throttle()
  serial: doc: Document .unthrottle()
  serial: doc: Document .set_ldisc()
  serial: doc: .break_ctl() is called with port->mutex() held
  serial: doc: Spelling s/divsor/divisor/
  serial: doc: Grammar s/function are/functions are/
  serial: doc: Correct return type of mctrl_gpio_to_gpiod()

 Documentation/serial/driver | 40 +++++++++++++++++++++++++---------------
 1 file changed, 25 insertions(+), 15 deletions(-)

-- 
1.9.1

Gr{oetje,eeting}s,

						Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
							    -- Linus Torvalds

[PATCH 1/9] serial: doc: Un-document non-existing uart_write_console()

[Geert Uytterhoeven]

uart_write_console() never existed, not even when the "new
uart_write_console function" was documented.

Fixes: 67ab7f596b6adbae ("[SERIAL] Update serial driver documentation")
Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
---
 Documentation/serial/driver | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/Documentation/serial/driver b/Documentation/serial/driver
index 379468e12680dbfb..e7c6f86ee06f9927 100644
--- a/Documentation/serial/driver
+++ b/Documentation/serial/driver
@@ -28,11 +28,6 @@ The serial core provides a few helper functions.  This includes identifing
 the correct port structure (via uart_get_console) and decoding command line
 arguments (uart_parse_options).
 
-There is also a helper function (uart_write_console) which performs a
-character by character write, translating newlines to CRLF sequences.
-Driver writers are recommended to use this function rather than implementing
-their own version.
-
 
 Locking
 -------
-- 
1.9.1

[PATCH 2/9] serial: doc: Un-document obsolete tmpbuf_sem

[Geert Uytterhoeven]

uart_info.tmpbuf and uart_info.tmpbuf_sem were removed in v2.6.10, in
full-history-linux commit a797ad7e3ae9cad4 ("[SERIAL] Clean up
serial_core.c write functions.").

Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
---
 Documentation/serial/driver | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/Documentation/serial/driver b/Documentation/serial/driver
index e7c6f86ee06f9927..61d520dea4c6e13a 100644
--- a/Documentation/serial/driver
+++ b/Documentation/serial/driver
@@ -36,8 +36,7 @@ It is the responsibility of the low level hardware driver to perform the
 necessary locking using port->lock.  There are some exceptions (which
 are described in the uart_ops listing below.)
 
-There are three locks.  A per-port spinlock, a per-port tmpbuf semaphore,
-and an overall semaphore.
+There are two locks.  A per-port spinlock, and an overall semaphore.
 
 From the core driver perspective, the port->lock locks the following
 data:
@@ -50,9 +49,6 @@ data:
 The low level driver is free to use this lock to provide any additional
 locking.
 
-The core driver uses the info->tmpbuf_sem lock to prevent multi-threaded
-access to the info->tmpbuf bouncebuffer used for port writes.
-
 The port_sem semaphore is used to protect against ports being added/
 removed or reconfigured at inappropriate times. Since v2.6.27, this
 semaphore has been the 'mutex' member of the tty_port struct, and
-- 
1.9.1

[PATCH 3/9] serial: doc: Document .throttle()

[Geert Uytterhoeven]

Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
---
 Documentation/serial/driver | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/serial/driver b/Documentation/serial/driver
index 61d520dea4c6e13a..50f3d94ed50b341e 100644
--- a/Documentation/serial/driver
+++ b/Documentation/serial/driver
@@ -126,6 +126,13 @@ hardware.
 	Interrupts: locally disabled.
 	This call must not sleep
 
+  throttle(port)
+	Notify the serial driver that input buffers for the line discipline are
+	close to full, and it should somehow signal that no more characters
+	should be sent to the serial port.
+
+	Locking: none.
+
   send_xchar(port,ch)
 	Transmit a high priority character, even if the port is stopped.
 	This is used to implement XON/XOFF flow control and tcflow().  If
-- 
1.9.1

[PATCH 4/9] serial: doc: Document .unthrottle()

[Geert Uytterhoeven]

Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
---
 Documentation/serial/driver | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/serial/driver b/Documentation/serial/driver
index 50f3d94ed50b341e..3b2a97d5ecc79491 100644
--- a/Documentation/serial/driver
+++ b/Documentation/serial/driver
@@ -133,6 +133,13 @@ hardware.
 
 	Locking: none.
 
+  unthrottle(port)
+	Notify the serial driver that characters can now be sent to the serial
+	port without fear of overrunning the input buffers of the line
+	disciplines.
+
+	Locking: none.
+
   send_xchar(port,ch)
 	Transmit a high priority character, even if the port is stopped.
 	This is used to implement XON/XOFF flow control and tcflow().  If
-- 
1.9.1

[PATCH 5/9] serial: doc: Document .set_ldisc()

[Geert Uytterhoeven]

Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
---
 Documentation/serial/driver | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Documentation/serial/driver b/Documentation/serial/driver
index 3b2a97d5ecc79491..3b08df5bcc17e944 100644
--- a/Documentation/serial/driver
+++ b/Documentation/serial/driver
@@ -259,6 +259,11 @@ hardware.
 	Interrupts: caller dependent.
 	This call must not sleep
 
+  set_ldisc(port,termios)
+	Notifier for discipline change. See Documentation/serial/tty.txt.
+
+	Locking: caller holds port->mutex
+
   pm(port,state,oldstate)
 	Perform any power management related activities on the specified
 	port.  State indicates the new state (defined by
-- 
1.9.1

[PATCH 6/9] serial: doc: .break_ctl() is called with port->mutex() held

[Geert Uytterhoeven]

Note that mutex_lock() should not be called with interrupts disabled.

Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
---
 Documentation/serial/driver | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/Documentation/serial/driver b/Documentation/serial/driver
index 3b08df5bcc17e944..09e73e061fcf795c 100644
--- a/Documentation/serial/driver
+++ b/Documentation/serial/driver
@@ -177,8 +177,7 @@ hardware.
 	should be terminated when another call is made with a zero
 	ctl.
 
-	Locking: none.
-	Interrupts: caller dependent.
+	Locking: caller holds port->mutex
 	This call must not sleep
 
   startup(port)
-- 
1.9.1

[PATCH 7/9] serial: doc: Spelling s/divsor/divisor/

[Geert Uytterhoeven]

Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
---
 Documentation/serial/driver | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/serial/driver b/Documentation/serial/driver
index 09e73e061fcf795c..3706a465fe2d7427 100644
--- a/Documentation/serial/driver
+++ b/Documentation/serial/driver
@@ -380,7 +380,7 @@ uart_get_baud_rate(port,termios,old,min,max)
 	Interrupts: n/a
 
 uart_get_divisor(port,baud)
-	Return the divsor (baud_base / baud) for the specified baud
+	Return the divisor (baud_base / baud) for the specified baud
 	rate, appropriately rounded.
 
 	If 38400 baud and custom divisor is selected, return the
-- 
1.9.1

[PATCH 8/9] serial: doc: Grammar s/function are/functions are/

[Geert Uytterhoeven]

Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
---
 Documentation/serial/driver | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/serial/driver b/Documentation/serial/driver
index 3706a465fe2d7427..ba84d1f38ca1d1e6 100644
--- a/Documentation/serial/driver
+++ b/Documentation/serial/driver
@@ -458,7 +458,7 @@ mctrl_gpio_init(port, idx):
 
 mctrl_gpio_free(dev, gpios):
 	This will free the requested gpios in mctrl_gpio_init().
-	As devm_* function are used, there's generally no need to call
+	As devm_* functions are used, there's generally no need to call
 	this function.
 
 mctrl_gpio_to_gpiod(gpios, gidx)
-- 
1.9.1

[PATCH 9/9] serial: doc: Correct return type of mctrl_gpio_to_gpiod()

[Geert Uytterhoeven]

Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
---
 Documentation/serial/driver | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/serial/driver b/Documentation/serial/driver
index ba84d1f38ca1d1e6..65de49a4b39e5baf 100644
--- a/Documentation/serial/driver
+++ b/Documentation/serial/driver
@@ -462,7 +462,8 @@ mctrl_gpio_free(dev, gpios):
 	this function.
 
 mctrl_gpio_to_gpiod(gpios, gidx)
-	This returns the gpio structure associated to the modem line index.
+	This returns the gpio_desc structure associated to the modem line
+	index.
 
 mctrl_gpio_set(gpios, mctrl):
 	This will sets the gpios according to the mctrl state.
-- 
1.9.1

Re: [PATCH 1/9] serial: doc: Un-document non-existing uart_write_console()

[Peter Hurley]

Hi Geert,

On 03/14/2016 08:16 AM, Geert Uytterhoeven wrote:
> uart_write_console() never existed, not even when the "new
> uart_write_console function" was documented.

Right. Should be uart_console_write()

> Fixes: 67ab7f596b6adbae ("[SERIAL] Update serial driver documentation")
> Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
> ---
>  Documentation/serial/driver | 5 -----
>  1 file changed, 5 deletions(-)
> 
> diff --git a/Documentation/serial/driver b/Documentation/serial/driver
> index 379468e12680dbfb..e7c6f86ee06f9927 100644
> --- a/Documentation/serial/driver
> +++ b/Documentation/serial/driver
> @@ -28,11 +28,6 @@ The serial core provides a few helper functions.  This includes identifing
>  the correct port structure (via uart_get_console) and decoding command line
>  arguments (uart_parse_options).
>  
> -There is also a helper function (uart_write_console) which performs a
> -character by character write, translating newlines to CRLF sequences.
> -Driver writers are recommended to use this function rather than implementing
> -their own version.
> -
>  
>  Locking
>  -------
> 

Re: [PATCH 2/9] serial: doc: Un-document obsolete tmpbuf_sem

[Peter Hurley]

On 03/14/2016 08:16 AM, Geert Uytterhoeven wrote:
> uart_info.tmpbuf and uart_info.tmpbuf_sem were removed in v2.6.10, in
> full-history-linux commit a797ad7e3ae9cad4 ("[SERIAL] Clean up
> serial_core.c write functions.").

Reviewed-by: Peter Hurley <peter@hurleysoftware.com>

Re: [PATCH 1/9] serial: doc: Un-document non-existing uart_write_console()

[Geert Uytterhoeven]

On Wed, Mar 16, 2016 at 5:01 PM, Peter Hurley <peter@hurleysoftware.com> wrote:
> On 03/14/2016 08:16 AM, Geert Uytterhoeven wrote:
>> uart_write_console() never existed, not even when the "new
>> uart_write_console function" was documented.
>
> Right. Should be uart_console_write()

Thx, I checked a few other possibilities, but couldn't find them.
Will update.

Gr{oetje,eeting}s,

                        Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds

Re: [PATCH 3/9] serial: doc: Document .throttle()

[Geert Uytterhoeven]

On Mon, Mar 14, 2016 at 4:16 PM, Geert Uytterhoeven
<geert+renesas@glider.be> wrote:
> Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
> ---
>  Documentation/serial/driver | 7 +++++++
>  1 file changed, 7 insertions(+)
>
> diff --git a/Documentation/serial/driver b/Documentation/serial/driver
> index 61d520dea4c6e13a..50f3d94ed50b341e 100644
> --- a/Documentation/serial/driver
> +++ b/Documentation/serial/driver
> @@ -126,6 +126,13 @@ hardware.
>         Interrupts: locally disabled.
>         This call must not sleep
>
> +  throttle(port)
> +       Notify the serial driver that input buffers for the line discipline are
> +       close to full, and it should somehow signal that no more characters
> +       should be sent to the serial port.
> +
> +       Locking: none.
> +

In the mean time I discovered this (and .unthrottle()) is used with hardware
assisted flow control only, and when it was introduced.
Will update the documentation accordingly.

Gr{oetje,eeting}s,

                        Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds

Re: [PATCH 3/9] serial: doc: Document .throttle()

[Peter Hurley]

On 03/14/2016 08:16 AM, Geert Uytterhoeven wrote:
> Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
> ---
>  Documentation/serial/driver | 7 +++++++
>  1 file changed, 7 insertions(+)
> 
> diff --git a/Documentation/serial/driver b/Documentation/serial/driver
> index 61d520dea4c6e13a..50f3d94ed50b341e 100644
> --- a/Documentation/serial/driver
> +++ b/Documentation/serial/driver
> @@ -126,6 +126,13 @@ hardware.
>  	Interrupts: locally disabled.
>  	This call must not sleep
>  
> +  throttle(port)
> +	Notify the serial driver that input buffers for the line discipline are
> +	close to full, and it should somehow signal that no more characters
> +	should be sent to the serial port.
> +
> +	Locking: none.

While it's true that no _serial_ locking is performed, the tty core
serializes throttle() and unthrottle(), and further guarantees termios
values will not be modified concurrently with throttle()/unthrottle().


> +
>    send_xchar(port,ch)
>  	Transmit a high priority character, even if the port is stopped.
>  	This is used to implement XON/XOFF flow control and tcflow().  If
> 

Re: [PATCH 6/9] serial: doc: .break_ctl() is called with port->mutex() held

[Peter Hurley]

On 03/14/2016 08:16 AM, Geert Uytterhoeven wrote:
> Note that mutex_lock() should not be called with interrupts disabled.
> 
> Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
> ---
>  Documentation/serial/driver | 3 +--
>  1 file changed, 1 insertion(+), 2 deletions(-)
> 
> diff --git a/Documentation/serial/driver b/Documentation/serial/driver
> index 3b08df5bcc17e944..09e73e061fcf795c 100644
> --- a/Documentation/serial/driver
> +++ b/Documentation/serial/driver
> @@ -177,8 +177,7 @@ hardware.
>  	should be terminated when another call is made with a zero
>  	ctl.
>  
> -	Locking: none.
> -	Interrupts: caller dependent.
> +	Locking: caller holds port->mutex


>  	This call must not sleep
           ^^^^^^^
And remove this line as well.

>  
>    startup(port)
> 

Re: [PATCH 5/9] serial: doc: Document .set_ldisc()

[Peter Hurley]

On 03/14/2016 08:16 AM, Geert Uytterhoeven wrote:

Reviewed-by: Peter Hurley <peter@hurleysoftware.com>

> Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
> ---
>  Documentation/serial/driver | 5 +++++
>  1 file changed, 5 insertions(+)
> 
> diff --git a/Documentation/serial/driver b/Documentation/serial/driver
> index 3b2a97d5ecc79491..3b08df5bcc17e944 100644
> --- a/Documentation/serial/driver
> +++ b/Documentation/serial/driver
> @@ -259,6 +259,11 @@ hardware.
>  	Interrupts: caller dependent.
>  	This call must not sleep
>  
> +  set_ldisc(port,termios)
> +	Notifier for discipline change. See Documentation/serial/tty.txt.
> +
> +	Locking: caller holds port->mutex
> +
>    pm(port,state,oldstate)
>  	Perform any power management related activities on the specified
>  	port.  State indicates the new state (defined by
> 

Re: [PATCH 0/9] serial: doc: Low Level Serial API Documentation Improvements

[Jonathan Corbet]

On Mon, 14 Mar 2016 16:16:08 +0100
Geert Uytterhoeven <geert+renesas@glider.be> wrote:

> This patch series contains improvements to the low level serial driver
> API documentation.

Hearing no objections, I've applied the set to the docs tree, thanks.

jon

Re: [PATCH 0/9] serial: doc: Low Level Serial API Documentation Improvements

[Geert Uytterhoeven]

Hi Jon,

On Thu, Mar 31, 2016 at 8:59 AM, Jonathan Corbet <corbet@lwn.net> wrote:
> On Mon, 14 Mar 2016 16:16:08 +0100
> Geert Uytterhoeven <geert+renesas@glider.be> wrote:
>
>> This patch series contains improvements to the low level serial driver
>> API documentation.
>
> Hearing no objections, I've applied the set to the docs tree, thanks.

There were a few from Peter Hurley, and I planned to send an updated
version soon.

Gr{oetje,eeting}s,

                        Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds