Create a new directory in Documentation/ called tty. We will create more
documents in it in the next patches, so let's have this one in the very
same place.
Change title accordingly and all the headers. This is the way what other
documents look like in this directory in the next patches. So make this
unified.
And add a TOC.
Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20211126081611.11001-20-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
The only documented function for tty_driver structure
allocation/registration was __tty_alloc_driver(). Fix highlighting in
that comment.
And add kernel-doc headers to all tty_driver_kref_put(),
tty_register_driver(), and tty_unregister_driver() -- i.e. the main
ones. More to follow later.
Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20211126081611.11001-18-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Kernel-doc is a bit strict about some formatting. So fix these:
1) When there is a tab in comments, it thinks the line is a continuation
one. So the description of the functions end up as descriptions of
the last parameter described. Remove the tabs.
2) Remove newlines before parameters description and after the comments.
This was not wrong per se, only inconsistent with the rest of the
file.
3) Add periods to the end of sentences where appropriate.
4) Add "()" to function names and "%" to constants, so that they are
properly highlighted.
Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20211126081611.11001-17-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
* process_echoes doc was a misnomer
* isig and n_tty_receive_char docs were misplaced
* n_tty_read parameters were incorrect (from pre-cookie times)
So fix all the warnings at once:
624: warning: expecting prototype for process_echoes(). Prototype was for __process_echoes() instead
1110: warning: expecting prototype for isig(). Prototype was for __isig() instead
1264: warning: expecting prototype for n_tty_receive_char(). Prototype was for n_tty_receive_char_special() instead
2067: warning: Excess function parameter 'buf' description in 'n_tty_read'
624: warning: expecting prototype for process_echoes(). Prototype was for __process_echoes() instead
1110: warning: expecting prototype for isig(). Prototype was for __isig() instead
1264: warning: expecting prototype for n_tty_receive_char(). Prototype was for n_tty_receive_char_special() instead
2067: warning: Function parameter or member 'kbuf' not described in 'n_tty_read'
2067: warning: Function parameter or member 'cookie' not described in 'n_tty_read'
2067: warning: Function parameter or member 'offset' not described in 'n_tty_read'
2067: warning: Excess function parameter 'buf' description in 'n_tty_read'
Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20211126081611.11001-16-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Kernel-doc is a bit strict about some formatting. So fix these:
1) When there is a tab in comments, it thinks the line is a continuation
one. So the description of the functions end up as descriptions of
the last parameter described. Remove the tabs.
2) Remove newlines before parameters description and after the comments.
This was not wrong per se, only inconsistent with the rest of the
file.
3) Add periods to the end of sentences where appropriate.
4) Add "()" to function names and "%" to constants, so that they are
properly highlighted.
Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20211126081611.11001-15-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Kernel-doc is a bit strict about some formatting. So fix these:
1) When there is a tab in comments, it thinks the line is a continuation
one. So the description of the functions end up as descriptions of
the last parameter described. Remove the tabs.
2) Remove newlines before parameters description and after the comments.
This was not wrong per se, only inconsistent with the rest of the
file.
3) Add periods to the end of sentences where appropriate.
4) Add "()" to function names and "%" to constants, so that they are
properly highlighted.
Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20211126081611.11001-14-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Kernel-doc is a bit strict about some formatting. So fix these:
1) When there is a tab in comments, it thinks the line is a continuation
one. So the description of the functions end up as descriptions of
the last parameter described. Remove the tabs.
2) Remove newlines before parameters description and after the comments.
This was not wrong per se, only inconsistent with the rest of the
file.
3) Add periods to the end of sentences where appropriate.
4) Add "()" to function names and "%" to constants, so that they are
properly highlighted.
By the above, this patch also unifies these docs with the other
kernel-doc's in this file.
Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20211126081611.11001-13-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Kernel-doc is a bit strict about some formatting. So fix these:
1) When there is a tab in comments, it thinks the line is a continuation
one. So the description of the functions end up as descriptions of
the last parameter described. Remove the tabs.
2) Remove newlines before parameters description. This was not wrong per
se, only inconsistent with the rest of the file.
3) Add periods to the end of sentences where appropriate.
4) Use recognized "Note" instead of "NB" (nota bene).
5) Add "()" to function names and "%" to constants, so that they are
properly highlighted.
By the above, this patch also unifies these docs with the other
kernel-doc's in this file.
Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20211126081611.11001-12-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
We want to reference TTY_DRIVER_* flags in Documentation/ later in this
series. But the current documentation in the TTY_DRIVER_*'s header does
not allow that. Reformat it to kernel-doc using "DOC" directive and
line-feeds, so that we can include it as it is.
Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20211126081611.11001-11-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Move the partial tty_struct::flags documentation from tty_ldisc to the
tty.h header and combine it with the one-liners present there. Convert
all those to kernel-doc. This way, we can simply reference the
documentation in Documentation while the text is still along the
definitions.
Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20211126081611.11001-10-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
tty_ldisc_ops structure was already partially documented in a standalone
comment in the header beginning.
Move it right before the structure and reformat it so it complies to
kernel-doc. That way, we can include it in Documentation/ later in this
series.
And add the documentation for the members where missing too.
Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20211126081611.11001-7-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
tty_operations structure was already documented in a standalone comment
in the header beginning.
Move it right before the structure and reformat it so it complies to
kernel-doc. That way, we can include it in Documentation/ later in this
series.
Note that we named proc_show's parameters, so that we can reference
them in the text.
Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20211126081611.11001-5-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
tty_driver used to have only short comments along its members. Convert
them into proper kernel-doc comments in front of the structure. And add
some more explanation to them where needed.
The whole structure handling is documented at the end too.
Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20211126081611.11001-4-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
tty_port used to have only short comments along its members. Convert
them into proper kernel-doc comments in front of the structure. And add
some more explanation to them where needed.
The whole structure purpose and handling is documented at the end too --
some pieces of preexisting text moved to this place.
Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20211126081611.11001-3-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
There are already pieces of kernel-doc documentation for struct
tty_struct in tty.h. Finish the documentation for the members which were
undocumented yet.
It also includes tuning the already existing pieces like flow and ctrl,
especially adding highlights to them.
Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20211126081611.11001-2-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
The driver wrongly assummed that tx_submit() will start the transfer,
which is not the case, now that the at_xdmac driver is fixed. tx_submit
is supposed to push the current transaction descriptor to a pending queue,
waiting for issue_pending to be called. issue_pending must start the
transfer, not tx_submit.
Fixes: 34df42f59a ("serial: at91: add rx dma support")
Fixes: 08f738be88 ("serial: at91: add tx dma support")
Signed-off-by: Tudor Ambarus <tudor.ambarus@microchip.com>
Link: https://lore.kernel.org/r/20211125090028.786832-4-tudor.ambarus@microchip.com
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
The tx_submit() method of struct dma_async_tx_descriptor is entitled
to do sanity checks and return errors if encountered. It's not the
case for the DMA controller drivers that this client is using
(at_h/xdmac), because they currently don't do sanity checks and always
return a positive cookie at tx_submit() method. In case the controller
drivers will implement sanity checks and return errors, print a message
so that the client will be informed that something went wrong at
tx_submit() level.
Fixes: 08f738be88 ("serial: at91: add tx dma support")
Signed-off-by: Tudor Ambarus <tudor.ambarus@microchip.com>
Acked-by: Richard Genoud <richard.genoud@gmail.com>
Link: https://lore.kernel.org/r/20211125090028.786832-3-tudor.ambarus@microchip.com
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
The UCR4_OREN should be disabled before disabling the uart receiver in
.stop_rx() instead of in the .shutdown().
Otherwise, if we have the overrun error during the receiver disable
process, the overrun interrupt will keep trigging until we disable the
OREN interrupt in the .shutdown(), because the ORE status can only be
cleared when read the rx FIFO or reset the controller. Although the
called time between the receiver disable and OREN disable in .shutdown()
is very short, there is still the risk of endless interrupt during this
short period of time. So here change to disable OREN before the receiver
been disabled in .stop_rx().
Signed-off-by: Fugang Duan <fugang.duan@nxp.com>
Signed-off-by: Sherry Sun <sherry.sun@nxp.com>
Link: https://lore.kernel.org/r/20211125020349.4980-1-sherry.sun@nxp.com
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Since commit a9c3f68f3c (tty: Fix low_latency BUG) in 2014,
tty_flip_buffer_push() is only a wrapper to tty_schedule_flip(). All
users were converted in the previous patches, so remove
tty_schedule_flip() completely while inlining its body into
tty_flip_buffer_push().
One less exported function.
Reviewed-by: Johan Hovold <johan@kernel.org>
Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20211122111648.30379-4-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
On the StarFive JH7100 RISC-V SoC the UART core clocks can't be set to
exactly 16 * 115200Hz and many other common bitrates. Trying this will
only result in a higher input clock, but low enough that the UART's
internal divisor can't come close enough to the baud rate target.
So rather than try to set the input clock it's better to skip the
clk_set_rate call and rely solely on the UART's internal divisor.
Signed-off-by: Emil Renner Berthing <kernel@esmil.dk>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Reviewed-by: Geert Uytterhoeven <geert@linux-m68k.org>
Link: https://lore.kernel.org/r/20211116150119.2171-15-kernel@esmil.dk
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
First, checking tty->receive_room to signalize whether there is enough space
in the tty buffers does not make much sense. Provided the tty buffers
are in tty_port and those are not checked at all.
Second, if the rx path is throttled, with CRTSCTS, RTS is deasserted,
but is never asserted again. This leads to port "lockup", not accepting
any more input.
So:
1) stty -F /dev/ttyMI0 crtscts # the mxser port
2) stty -F /dev/ttyS6 crtscts # the connected port
3) cat /dev/ttyMI0
4) "write in a loop" to /dev/ttyS6
5) cat from 3) produces the bytes from 4)
6) killall -STOP cat (the 3)'s one)
7) wait for RTS to drop on /dev/ttyMI0
8) killall -CONT cat (again the 3)'s one)
cat erroneously produces no more output now (i.e. no data sent from
ttyS6 to ttyMI can be seen).
Note that the step 7) is performed twice: once from n_tty by
tty_throttle_safe(), once by mxser_stoprx() from the receive path. Then
after step 7), n_tty correctly unthrottles the input, but mxser calls
mxser_stoprx() again as there is still only a little space in n_tty
buffers (tty->receive_room mentioned at the beginning), but the device's
FIFO is/can be already filled.
After this patch, the output is correctly resumed, i.e. n_tty both
throttles and unthrottles without interfering with mxser's attempts.
This allows us to get rid of the non-standard ldisc_stop_rx flag from
struct mxser_port.
Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20211118073125.12283-15-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
I fail to see the point of calling mxser_flush_buffer() from
mxser_close():
1) The SW xmit buffer is freed in mxser_shutdown_port() right after the
call to mxser_flush_buffer(). And all 'cnt', 'head', and 'tail' are
properly initialized to 0 in mxser_activate().
2) The HW buffer is flushed in mxser_shutdown_port() via
mxser_disable_and_clear_FIFO() too.
So the effect of doing it by mxser_flush_buffer() in mxser_close() is
none. Hence remove it, so that when we use tty_port_close() later, the
code is 1:1 identical.
Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20211118073125.12283-10-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
mxser_stop_rx() should be called from mxser_shutdown_port() for several
reasons:
1) info->slock is held while manipulating IER (as on other places),
2) hangup now stops rx too,
3) mxser_close() will use tty_port_close() and there is no place except
tty_port_operations::shutdown() where this can be done,
4) this is the same sequence as serial_core does. So we can map this
code 1:1 when switching the driver to it.
Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20211118073125.12283-9-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
The port->icount.tx is handled in a too complicated manner. Instead of
remembering the original count and subtracting the new one from it,
simply increase tx for each character in the loop. No need for cnt
variable then.
Change also the "X = X & Y" assignment to simpler "X &= Y".
Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20211118073125.12283-6-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
The others are superfluous with tty refcounting in place now. And they
are racy in fact:
* tty_port_initialized() reports false for a small moment after
interrupts are enabled.
* closing is 1 while the port is still alive.
The queues are flushed later during close anyway. So there is no need
for this special handling. Actually, the ISR should not flush the
queues. It should behave as every other driver, just queue the chars
into tty buffer and go on. But this will be changed later. There is
still a lot code depending on having tty in ISR (and not only tty_port).
Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20211118073125.12283-4-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
mxser_close() behaves like this:
-> tty_port_close_start()
-> tty_wait_until_sent()
-> mxser_wait_until_sent()
-> mxser_close_port
-> wait for TEMT
So it is already waited for TEMT through mxser_wait_until_sent() and
there is another round of waiting in mxser_close_port(). The latter one
is superfluous as nothing could be filled into the output FIFO. Remove
the call.
This helps unification among drivers (so that all behave the same) and
future use of tty_port_close().
Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20211118073125.12283-2-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
