Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752856AbbGMW5M (ORCPT ); Mon, 13 Jul 2015 18:57:12 -0400 Received: from gimli.pxnet.com ([89.1.7.7]:37339 "EHLO mail.pxnet.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751093AbbGMW5K (ORCPT ); Mon, 13 Jul 2015 18:57:10 -0400 X-Greylist: delayed 1184 seconds by postgrey-1.27 at vger.kernel.org; Mon, 13 Jul 2015 18:57:10 EDT Message-Id: From: Tilman Schmidt Subject: [PATCH] Documentation: improve line discipline method descriptions To: Greg Kroah-Hartman , Jiri Slaby Cc: Peter Hurley , Paul Bolle , linux-kernel@vger.kernel.org Date: Tue, 14 Jul 2015 00:56:59 +0200 (CEST) X-Greylist: Sender succeeded SMTP AUTH, not delayed by milter-greylist-4.2.7 (mail.pxnet.com [IPv6:2001:4dd0:f004:7::7]); Tue, 14 Jul 2015 00:57:03 +0200 (CEST) Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 4395 Lines: 105 Mention that the ldisc open method must reset tty->receive_room, and that many methods are optional. Add description of receive_buf2 method. Signed-off-by: Tilman Schmidt --- Documentation/serial/tty.txt | 59 +++++++++++++++++++++++++++--------------- 1 files changed, 38 insertions(+), 21 deletions(-) diff --git a/Documentation/serial/tty.txt b/Documentation/serial/tty.txt index 973c8ad..17624a0 100644 --- a/Documentation/serial/tty.txt +++ b/Documentation/serial/tty.txt @@ -39,8 +39,12 @@ TTY side interfaces: open() - Called when the line discipline is attached to the terminal. No other call into the line discipline for this tty will occur until it - completes successfully. Returning an error will - prevent the ldisc from being attached. Can sleep. + completes successfully. Should initialize any + state needed by the ldisc, and set receive_room + in the tty_struct to an appropriate value to + indicate more data can be sent. Returning an + error will prevent the ldisc from being attached. + May sleep. close() - This is called on a terminal when the line discipline is being unplugged. At the point of @@ -52,9 +56,16 @@ hangup() - Called when the tty line is hung up. No further calls into the ldisc code will occur. The return value is ignored. Can sleep. -write() - A process is writing data through the line - discipline. Multiple write calls are serialized - by the tty layer for the ldisc. May sleep. +read() - (optional) A process requests reading data from + the line. Multiple read calls may occur in parallel + and the ldisc must deal with serialization issues. + If not defined, the process will receive an EIO + error. May sleep. + +write() - (optional) A process requests writing data to the + line. Multiple write calls are serialized by the + tty layer for the ldisc. If not defined, the + process will receive an EIO error. May sleep. flush_buffer() - (optional) May be called at any point between open and close, and instructs the line discipline @@ -69,27 +80,33 @@ set_termios() - (optional) Called on termios structure changes. termios semaphore so allowed to sleep. Serialized against itself only. -read() - Move data from the line discipline to the user. - Multiple read calls may occur in parallel and the - ldisc must deal with serialization issues. May - sleep. - -poll() - Check the status for the poll/select calls. Multiple - poll calls may occur in parallel. May sleep. +poll() - (optional) Check the status for the poll/select + calls. Multiple poll calls may occur in parallel. + May sleep. -ioctl() - Called when an ioctl is handed to the tty layer - that might be for the ldisc. Multiple ioctl calls - may occur in parallel. May sleep. +ioctl() - (optional) Called when an ioctl is handed to the + tty layer that might be for the ldisc. Multiple + ioctl calls may occur in parallel. May sleep. -compat_ioctl() - Called when a 32 bit ioctl is handed to the tty layer - that might be for the ldisc. Multiple ioctl calls - may occur in parallel. May sleep. +compat_ioctl() - (optional) Called when a 32 bit ioctl is handed + to the tty layer that might be for the ldisc. + Multiple ioctl calls may occur in parallel. + May sleep. Driver Side Interfaces: -receive_buf() - Hand buffers of bytes from the driver to the ldisc - for processing. Semantics currently rather - mysterious 8( +receive_buf() - (optional) Called by the low-level driver to hand + a buffer of received bytes to the ldisc for + processing. The number of bytes is guaranteed not + to exceed the current value of tty->receive_room. + All bytes must be processed. + +receive_buf2() - (optional) Called by the low-level driver to hand + a buffer of received bytes to the ldisc for + processing. Returns the number of bytes processed. + + If both receive_buf() and receive_buf2() are + defined, receive_buf2() should be preferred. write_wakeup() - May be called at any point between open and close. The TTY_DO_WRITE_WAKEUP flag indicates if a call -- 1.7.1 -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/