[PATCH tty-next 03/22] tty: Document locking for tty_port_open()

[Peter Hurley <peter@hurleysoftware.com>]

The tty lock is held when the tty driver's open method is called
(from the lone call-site, tty_open()). The call-tree audit [1] of
tty_port_open() is a closed graph of the callers of tty_port_open();
ie., all callers originate from only tty_open().

Of these callers, none drop the tty lock.

Also, document that tty_port_block_til_ready() may drop and reacquire
the tty lock when blocking, which means the tty or tty_port may have
changed state.

[1]
Call-tree audit of tty_port_open()

tty_open()
  tty->ops->open() --+
                     |
        rs_open():arch/ia64/hp/sim/simserial.c
       *line_open():arch/um/drivers/line.c
        gdm_tty_open():drivers/staging/gdm724x/gdm_tty.c
        fwtty_open():drivers/staging/fwserial/fwserial.c
        acm_tty_open():drivers/usb/class/cdc-acm.c
        serial_open():drivers/usb/serial/usb-serial.c
        pti_tty_driver_open():drivers/misc/pti.c
        ipoctal_open():drivers/ipack/devices/ipoctal.c
        isicom_open():drivers/tty/isicom.c
        dashtty_open():drivers/tty/metag_da.c
        goldfish_tty_open():drivers/tty/goldfish.c
        ehv_bc_tty_open():drivers/tty/ehv_bytechan.c
        mxser_open():drivers/tty/mxser.c
        kgdb_nmi_tty_open():drivers/tty/serial/kgdb_nmi.c
        ifx_spi_open():drivers/tty/serial/ifx6x60.c
        smd_tty_open():drivers/tty/serial/msm_smd_tty.c
        ntty_open():drivers/tty/nozomi.c
        capinc_tty_open():drivers/isdn/capi/capi.c
        tpk_open():drivers/char/ttyprintk.c
        sdio_uart_open():drivers/mmc/card/sdio_uart.c
        rfcomm_tty_open():net/bluetooth/rfcomm/tty.c
                     |
                     +- tty_port_open()

* line_open() is the .open method for 2 um drivers
  declared in ./arch/um/drivers/stdio_console.c and
  in ./arch/um/drivers/ssl.c, and not called directly

Signed-off-by: Peter Hurley <peter@hurleysoftware.com>
---
 drivers/tty/tty_port.c | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/drivers/tty/tty_port.c b/drivers/tty/tty_port.c
index bcc15f7..f469869 100644
--- a/drivers/tty/tty_port.c
+++ b/drivers/tty/tty_port.c
@@ -572,6 +572,14 @@ int tty_port_install(struct tty_port *port, struct tty_driver *driver,
 }
 EXPORT_SYMBOL_GPL(tty_port_install);
 
+/**
+ * tty_port_open
+ *
+ * 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)
+ */
 int tty_port_open(struct tty_port *port, struct tty_struct *tty,
 							struct file *filp)
 {
-- 
2.0.0