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

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

[Geert Uytterhoeven]

	Hi Greg, Jiri, Jon, Peter, Russell,

This patch series (against next-20160511) contains improvements to the low
level serial driver API documentation.

Thanks for your comments!

Geert Uytterhoeven (2):
  serial: doc: Always refer to tty_port->mutex
  serial: doc: Use port->state instead of info

 Documentation/serial/driver | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 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/2] serial: doc: Always refer to tty_port->mutex

[Geert Uytterhoeven]

Stop referring to the mutex member of the tty_port struct as
'port->mutex', as 'port' is ambiguous, and usually refers to the
uart_port struct in this document.  Use 'tty_port->mutex' instead,
following the single existing use.

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

diff --git a/Documentation/serial/driver b/Documentation/serial/driver
index 39701515832b70b0..90889c785809cde1 100644
--- a/Documentation/serial/driver
+++ b/Documentation/serial/driver
@@ -57,7 +57,7 @@ locking.
 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
-commonly referred to as the port mutex (or port->mutex).
+commonly referred to as the port mutex.
 
 
 uart_ops
@@ -186,7 +186,7 @@ hardware.
 	should be terminated when another call is made with a zero
 	ctl.
 
-	Locking: caller holds port->mutex
+	Locking: caller holds tty_port->mutex
 
   startup(port)
 	Grab any interrupt resources and initialise any low level driver
@@ -262,14 +262,14 @@ hardware.
 	Other flags may be used (eg, xon/xoff characters) if your
 	hardware supports hardware "soft" flow control.
 
-	Locking: caller holds port->mutex
+	Locking: caller holds tty_port->mutex
 	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
+	Locking: caller holds tty_port->mutex
 
   pm(port,state,oldstate)
 	Perform any power management related activities on the specified
-- 
1.9.1

[PATCH 2/2] serial: doc: Use port->state instead of info

[Geert Uytterhoeven]

As of commit ebd2c8f6d2ec4012 ("serial: kill off uart_info"), the
circular transmission buffer is part of struct uart_state instead of
struct uart_info. Make it clear this structure is pointed to from struct
uart_port.

Change 'circ' to 'circ_buf' to match the structure name while we're at
it.

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

diff --git a/Documentation/serial/driver b/Documentation/serial/driver
index 90889c785809cde1..da193e092fc3d531 100644
--- a/Documentation/serial/driver
+++ b/Documentation/serial/driver
@@ -48,8 +48,8 @@ data:
 
 	port->mctrl
 	port->icount
-	info->xmit.head (circ->head)
-	info->xmit.tail (circ->tail)
+	port->state->xmit.head (circ_buf->head)
+	port->state->xmit.tail (circ_buf->tail)
 
 The low level driver is free to use this lock to provide any additional
 locking.
@@ -204,7 +204,7 @@ hardware.
 	RTS nor DTR; this will have already been done via a separate
 	call to set_mctrl.
 
-	Drivers must not access port->info once this call has completed.
+	Drivers must not access port->state once this call has completed.
 
 	This method will only be called when there are no more users of
 	this port.
@@ -216,7 +216,7 @@ hardware.
 	Flush any write buffers, reset any DMA state and stop any
 	ongoing DMA transfers.
 
-	This will be called whenever the port->info->xmit circular
+	This will be called whenever the port->state->xmit circular
 	buffer is cleared.
 
 	Locking: port->lock taken.
-- 
1.9.1

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

[Jonathan Corbet]

On Wed, 11 May 2016 13:56:03 +0200
Geert Uytterhoeven <geert+renesas@glider.be> wrote:

> This patch series (against next-20160511) contains improvements to the low
> level serial driver API documentation.
> 
> Thanks for your comments!

I've applied both to the docs tree, thanks.

jon