* [PATCH] Documentation: improve line discipline method descriptions
@ 2015-07-13 22:56 Tilman Schmidt
2015-07-14 19:12 ` Paul Bolle
0 siblings, 1 reply; 5+ messages in thread
From: Tilman Schmidt @ 2015-07-13 22:56 UTC (permalink / raw)
To: Greg Kroah-Hartman, Jiri Slaby; +Cc: Peter Hurley, Paul Bolle, linux-kernel
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 <tilman@imap.cc>
---
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
^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH] Documentation: improve line discipline method descriptions
2015-07-13 22:56 [PATCH] Documentation: improve line discipline method descriptions Tilman Schmidt
@ 2015-07-14 19:12 ` Paul Bolle
2015-09-29 23:45 ` [PATCH v2] " Tilman Schmidt
0 siblings, 1 reply; 5+ messages in thread
From: Paul Bolle @ 2015-07-14 19:12 UTC (permalink / raw)
To: Tilman Schmidt, Greg Kroah-Hartman, Jiri Slaby; +Cc: Peter Hurley, linux-kernel
On di, 2015-07-14 at 00:56 +0200, Tilman Schmidt wrote:
> --- a/Documentation/serial/tty.txt
> +++ b/Documentation/serial/tty.txt
> + Should [...] set receive_room
> + in the tty_struct to an appropriate value to
> + indicate more data can be sent.
If "appropriate value" could be changed into something less vague
(either in this patch or in a future follow up patch) that would be
really nice.
Thanks,
Paul Bolle
^ permalink raw reply [flat|nested] 5+ messages in thread
* [PATCH v2] Documentation: improve line discipline method descriptions
2015-07-14 19:12 ` Paul Bolle
@ 2015-09-29 23:45 ` Tilman Schmidt
2015-09-30 14:03 ` Peter Hurley
2015-10-06 20:24 ` Paul Bolle
0 siblings, 2 replies; 5+ messages in thread
From: Tilman Schmidt @ 2015-09-29 23:45 UTC (permalink / raw)
To: Greg Kroah-Hartman, Jiri Slaby
Cc: Peter Hurley, Paul Bolle, linux-kernel, netdev
Mention that the ldisc open method must set tty->receive_room, and
that many methods are optional. Add description of receive_buf2 method.
Signed-off-by: Tilman Schmidt <tilman@imap.cc>
---
Documentation/serial/tty.txt | 60 ++++++++++++++++++++++++++++----------------
1 file changed, 39 insertions(+), 21 deletions(-)
diff --git a/Documentation/serial/tty.txt b/Documentation/serial/tty.txt
index 973c8ad..bc3842d 100644
--- a/Documentation/serial/tty.txt
+++ b/Documentation/serial/tty.txt
@@ -39,8 +39,13 @@ 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 the maximum amount of data
+ the line discipline is willing to accept from the
+ driver with a single call to receive_buf().
+ Returning an error will prevent the ldisc from
+ being attached. Can sleep.
close() - This is called on a terminal when the line
discipline is being unplugged. At the point of
@@ -52,9 +57,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 +81,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.9.2.459.g68773ac
^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH v2] Documentation: improve line discipline method descriptions
2015-09-29 23:45 ` [PATCH v2] " Tilman Schmidt
@ 2015-09-30 14:03 ` Peter Hurley
2015-10-06 20:24 ` Paul Bolle
1 sibling, 0 replies; 5+ messages in thread
From: Peter Hurley @ 2015-09-30 14:03 UTC (permalink / raw)
To: Tilman Schmidt
Cc: Greg Kroah-Hartman, Jiri Slaby, Paul Bolle, linux-kernel, netdev
On 09/29/2015 07:45 PM, Tilman Schmidt wrote:
> Mention that the ldisc open method must set tty->receive_room, and
> that many methods are optional. Add description of receive_buf2 method.
Thanks, Tilman!
Reviewed-by: Peter Hurley <peter@hurleysoftware.com>
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH v2] Documentation: improve line discipline method descriptions
2015-09-29 23:45 ` [PATCH v2] " Tilman Schmidt
2015-09-30 14:03 ` Peter Hurley
@ 2015-10-06 20:24 ` Paul Bolle
1 sibling, 0 replies; 5+ messages in thread
From: Paul Bolle @ 2015-10-06 20:24 UTC (permalink / raw)
To: Tilman Schmidt, Greg Kroah-Hartman, Jiri Slaby
Cc: Peter Hurley, linux-kernel, netdev
Hi Tilman,
On wo, 2015-09-30 at 01:45 +0200, Tilman Schmidt wrote:
> --- a/Documentation/serial/tty.txt
> +++ b/Documentation/serial/tty.txt
> + Should [...] set receive_room
> + in the tty_struct to the maximum amount of data
> + the line discipline is willing to accept from the
> + driver with a single call to receive_buf().
A lot clearer than v1! (I do assume the TTY people will shout if that
sentence isn't actually correct.)
Thanks for looking into this, again.
Paul Bolle
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2015-10-06 20:25 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2015-07-13 22:56 [PATCH] Documentation: improve line discipline method descriptions Tilman Schmidt
2015-07-14 19:12 ` Paul Bolle
2015-09-29 23:45 ` [PATCH v2] " Tilman Schmidt
2015-09-30 14:03 ` Peter Hurley
2015-10-06 20:24 ` Paul Bolle
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).