linux.git/Documentation/driver-api/serial/driver.rst, branch master Clone of https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git Documentation: driver-api: correct spelling 2023-02-02T18:05:16+00:00 Randy Dunlap rdunlap@infradead.org 2023-01-29T23:10:46+00:00 7852fe3a092721794f92c4d04fb33184501a3c9a Correct spelling problems for Documentation/driver-api/ as reported by codespell. Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Cc: Mauro Carvalho Chehab <mchehab@kernel.org> Cc: linux-media@vger.kernel.org Cc: Vishal Verma <vishal.l.verma@intel.com> Cc: Dave Jiang <dave.jiang@intel.com> Cc: nvdimm@lists.linux.dev Cc: Vinod Koul <vkoul@kernel.org> Cc: dmaengine@vger.kernel.org Cc: linux-raid@vger.kernel.org Cc: linux-usb@vger.kernel.org Acked-by: Dan Williams <dan.j.williams@intel.com> Acked-by: Song Liu <song@kernel.org> Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Link: https://lore.kernel.org/r/20230129231053.20863-3-rdunlap@infradead.org Signed-off-by: Jonathan Corbet <corbet@lwn.net> 
Correct spelling problems for Documentation/driver-api/ as reported
by codespell.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: linux-media@vger.kernel.org
Cc: Vishal Verma <vishal.l.verma@intel.com>
Cc: Dave Jiang <dave.jiang@intel.com>
Cc: nvdimm@lists.linux.dev
Cc: Vinod Koul <vkoul@kernel.org>
Cc: dmaengine@vger.kernel.org
Cc: linux-raid@vger.kernel.org
Cc: linux-usb@vger.kernel.org
Acked-by: Dan Williams <dan.j.williams@intel.com>
Acked-by: Song Liu <song@kernel.org>
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Link: https://lore.kernel.org/r/20230129231053.20863-3-rdunlap@infradead.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
tty: serial: introduce transmit helpers 2022-11-03T02:32:40+00:00 Jiri Slaby (SUSE) jirislaby@kernel.org 2022-10-04T10:49:25+00:00 8275b48b278096edc1e3ea5aa9cf946a10022f79 Many serial drivers do the same thing: * send x_char if set * keep sending from the xmit circular buffer until either - the loop reaches the end of the xmit buffer - TX is stopped - HW fifo is full * check for pending characters and: - wake up tty writers to fill for more data into xmit buffer - stop TX if there is nothing in the xmit buffer The only differences are: * how to write the character to the HW fifo * the check of the end condition: - is the HW fifo full? - is limit of the written characters reached? So unify the above into two helpers: * uart_port_tx_limited() -- it performs the above taking the written characters limit into account, and * uart_port_tx() -- the same as above, except it only checks the HW readiness, not the characters limit. The HW specific operations (as stated as "differences" above) are passed as arguments to the macros. They are: * tx_ready -- returns true if HW can accept more data. * put_char -- write a character to the device. * tx_done -- when the write loop is done, perform arbitrary action before potential invocation of ops->stop_tx() happens. Note that the above are macros. This means the code is generated in place and the above 3 arguments are "inlined". I.e. no added penalty by generating call instructions for every single character. Nor any indirect calls. (As in some previous versions of this patchset.) Reviewed-by: Ilpo Järvinen <ilpo.jarvinen@linux.intel.com> Signed-off-by: Jiri Slaby (SUSE) <jirislaby@kernel.org> Link: https://lore.kernel.org/r/20221004104927.14361-2-jirislaby@kernel.org Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> 
Many serial drivers do the same thing:
* send x_char if set
* keep sending from the xmit circular buffer until either
  - the loop reaches the end of the xmit buffer
  - TX is stopped
  - HW fifo is full
* check for pending characters and:
  - wake up tty writers to fill for more data into xmit buffer
  - stop TX if there is nothing in the xmit buffer

The only differences are:
* how to write the character to the HW fifo
* the check of the end condition:
  - is the HW fifo full?
  - is limit of the written characters reached?

So unify the above into two helpers:
* uart_port_tx_limited() -- it performs the above taking the written
  characters limit into account, and
* uart_port_tx() -- the same as above, except it only checks the HW
  readiness, not the characters limit.

The HW specific operations (as stated as "differences" above) are passed
as arguments to the macros. They are:
* tx_ready -- returns true if HW can accept more data.
* put_char -- write a character to the device.
* tx_done -- when the write loop is done, perform arbitrary action
  before potential invocation of ops->stop_tx() happens.

Note that the above are macros. This means the code is generated in
place and the above 3 arguments are "inlined". I.e. no added penalty by
generating call instructions for every single character. Nor any
indirect calls. (As in some previous versions of this patchset.)

Reviewed-by: Ilpo Järvinen <ilpo.jarvinen@linux.intel.com>
Signed-off-by: Jiri Slaby (SUSE) <jirislaby@kernel.org>
Link: https://lore.kernel.org/r/20221004104927.14361-2-jirislaby@kernel.org
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
tty: serial: document uart_get_console() 2022-07-28T08:37:42+00:00 Jiri Slaby jslaby@suse.cz 2022-07-28T06:10:56+00:00 9e5f399f5c9f62e537735f2f8e42bd2f7c255c1f This was the only function mentioned in the text, but was neither linked nor documented. So document and link it, so that hyperlinking works in the text. Signed-off-by: Jiri Slaby <jslaby@suse.cz> Link: https://lore.kernel.org/r/20220728061056.20799-6-jslaby@suse.cz Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> 
This was the only function mentioned in the text, but was neither linked
nor documented. So document and link it, so that hyperlinking works in
the text.

Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20220728061056.20799-6-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
tty: serial: serial_core, reformat kernel-doc for functions 2022-07-28T08:37:42+00:00 Jiri Slaby jslaby@suse.cz 2022-07-28T06:10:55+00:00 987233b342b950653d21c5e3e5b78689c995c869 There are many annotated functions in serial_core.c, but they do not completely conform to the kernel-doc style. So reformat them and link them from the Documentation. Signed-off-by: Jiri Slaby <jslaby@suse.cz> Link: https://lore.kernel.org/r/20220728061056.20799-5-jslaby@suse.cz Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> 
There are many annotated functions in serial_core.c, but they do not
completely conform to the kernel-doc style. So reformat them and link
them from the Documentation.

Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20220728061056.20799-5-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Documentation: serial: link uart_ops properly 2022-07-28T08:37:42+00:00 Jiri Slaby jslaby@suse.cz 2022-07-28T06:10:54+00:00 d34d7c4b774dac1d4be440207ab9e347f599dd30 The syntax to reference a struct in text is "struct XY". So reference uart_ops properly, so that hyperlinks work. Signed-off-by: Jiri Slaby <jslaby@suse.cz> Link: https://lore.kernel.org/r/20220728061056.20799-4-jslaby@suse.cz Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> 
The syntax to reference a struct in text is "struct XY". So reference
uart_ops properly, so that hyperlinks work.

Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20220728061056.20799-4-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Documentation: serial: move GPIO kernel-doc to the functions 2022-07-28T08:37:42+00:00 Jiri Slaby jslaby@suse.cz 2022-07-28T06:10:53+00:00 27940abd555228fdda39a40081ae02450c500f35 The GPIO uart functions are documented in Documentation. Move and transform this documentation into kernel-doc directly in the code and reference it in Documentation using kernel-doc:. This makes it easier to update, maintain and check by the build. Signed-off-by: Jiri Slaby <jslaby@suse.cz> Link: https://lore.kernel.org/r/20220728061056.20799-3-jslaby@suse.cz Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> 
The GPIO uart functions are documented in Documentation. Move and
transform this documentation into kernel-doc directly in the code and
reference it in Documentation using kernel-doc:.

This makes it easier to update, maintain and check by the build.

Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20220728061056.20799-3-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Documentation: serial: dedup kernel-doc for uart functions 2022-07-28T08:37:42+00:00 Jiri Slaby jslaby@suse.cz 2022-07-28T06:10:52+00:00 c4bd17a6ddf3b92bf9d7939ae251570ace14bb52 Some of the serial (uart_*) functions are documented twice. Once as kernel-doc along their sources and once in Documentation. So deduplicate these texts, merge them into kernel-doc in the sources, and link them using kernel-doc: from the Documentation. To be properly linked and rendered, tabulators had to be removed from the comments. Signed-off-by: Jiri Slaby <jslaby@suse.cz> Link: https://lore.kernel.org/r/20220728061056.20799-2-jslaby@suse.cz Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> 
Some of the serial (uart_*) functions are documented twice. Once as
kernel-doc along their sources and once in Documentation. So deduplicate
these texts, merge them into kernel-doc in the sources, and link them
using kernel-doc: from the Documentation.

To be properly linked and rendered, tabulators had to be removed from
the comments.

Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20220728061056.20799-2-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Documentation: serial: move uart_ops documentation to the struct 2022-07-28T08:37:42+00:00 Jiri Slaby jslaby@suse.cz 2022-07-28T06:10:51+00:00 e60a7233684aa8bbe9090537720fe6a1e901d823 While it's a lot of text, it always helps to keep it up to date when it's by the source. (And not in a separate file.) The documentation tooling also makes sure that all members of the structure are documented. (If not, it complains loudly.) Finally, there needs to be no comments inlined in the structure, so they are dropped as they are superfluous now. The compilation time of this header (tested with serial_core.c) didn't change in my testing at all. Signed-off-by: Jiri Slaby <jslaby@suse.cz> Link: https://lore.kernel.org/r/20220728061056.20799-1-jslaby@suse.cz Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> 
While it's a lot of text, it always helps to keep it up to date when
it's by the source. (And not in a separate file.)

The documentation tooling also makes sure that all members of the
structure are documented. (If not, it complains loudly.)

Finally, there needs to be no comments inlined in the structure, so they
are dropped as they are superfluous now.

The compilation time of this header (tested with serial_core.c) didn't
change in my testing at all.

Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20220728061056.20799-1-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
serial: Support for RS-485 multipoint addresses 2022-06-27T12:44:20+00:00 Ilpo Järvinen ilpo.jarvinen@linux.intel.com 2022-06-24T20:42:09+00:00 4f768e94774c58c9f7f54ebd38dadf172970046a Add support for RS-485 multipoint addressing using 9th bit [*]. The addressing mode is configured through ->rs485_config(). ADDRB in termios indicates 9th bit addressing mode is enabled. In this mode, 9th bit is used to indicate an address (byte) within the communication line. ADDRB can only be enabled/disabled through ->rs485_config() that is also responsible for setting the destination and receiver (filter) addresses. Add traps to detect unwanted changes to struct serial_rs485 layout using static_assert(). [*] Technically, RS485 is just an electronic spec and does not itself specify the 9th bit addressing mode but 9th bit seems at least "semi-standard" way to do addressing with RS485. Signed-off-by: Ilpo Järvinen <ilpo.jarvinen@linux.intel.com> Link: https://lore.kernel.org/r/20220624204210.11112-6-ilpo.jarvinen@linux.intel.com Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> 
Add support for RS-485 multipoint addressing using 9th bit [*]. The
addressing mode is configured through ->rs485_config().

ADDRB in termios indicates 9th bit addressing mode is enabled. In this
mode, 9th bit is used to indicate an address (byte) within the
communication line. ADDRB can only be enabled/disabled through
->rs485_config() that is also responsible for setting the destination and
receiver (filter) addresses.

Add traps to detect unwanted changes to struct serial_rs485 layout using
static_assert().

[*] Technically, RS485 is just an electronic spec and does not itself
specify the 9th bit addressing mode but 9th bit seems at least
"semi-standard" way to do addressing with RS485.

Signed-off-by: Ilpo Järvinen <ilpo.jarvinen@linux.intel.com>
Link: https://lore.kernel.org/r/20220624204210.11112-6-ilpo.jarvinen@linux.intel.com
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
serial: Drop timeout from uart_port 2022-06-27T12:34:45+00:00 Ilpo Järvinen ilpo.jarvinen@linux.intel.com 2022-06-13T11:39:05+00:00 f9008285bb69e4713918a665250ab2d356b731ba Since commit 31f6bd7fad3b ("serial: Store character timing information to uart_port"), per frame timing information is available on uart_port. Uart port's timeout can be derived from frame_time by multiplying with fifosize. Most callers of uart_poll_timeout are not made under port's lock. To be on the safe side, make sure frame_time is only accessed once. As fifo_size is effectively a constant, it shouldn't cause any issues. Signed-off-by: Ilpo Järvinen <ilpo.jarvinen@linux.intel.com> Link: https://lore.kernel.org/r/20220613113905.22962-1-ilpo.jarvinen@linux.intel.com Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> 
Since commit 31f6bd7fad3b ("serial: Store character timing information
to uart_port"), per frame timing information is available on uart_port.
Uart port's timeout can be derived from frame_time by multiplying with
fifosize.

Most callers of uart_poll_timeout are not made under port's lock. To be
on the safe side, make sure frame_time is only accessed once. As
fifo_size is effectively a constant, it shouldn't cause any issues.

Signed-off-by: Ilpo Järvinen <ilpo.jarvinen@linux.intel.com>
Link: https://lore.kernel.org/r/20220613113905.22962-1-ilpo.jarvinen@linux.intel.com
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>