Skip to contentSkip to conversation

serial: RS485 kerneldoc/documentation improvements

PATCH Superseded Ilpo Järvinen 3 participants 12 messages Sep 28, 2022 – Sep 29, 2022

Subsystems (2)

v3 of 5 Superseded Latest is v5 →

lore
Share & tools
lore
#0 lore raw

v3 cover serial: RS485 kerneldoc/documentation improvements

RS485 documentation improvements. While doing the kerneldoc conversion, a few other items came up so they're now included to this series.

v3:
- More fixes to kernel doc formatting (thanks to Jiri)
- Added a few other related improvements

v2:
- Include serial_rs485 into documentation
- Add * to multi-line flag descriptions

Ilpo Järvinen (4):
serial: Convert serial_rs485 to kernel doc
Documentation: rs485: Link reference properly
Documentation: rs485: Mention uart_get_rs485_mode()
Documentation: rs485: Fix struct referencing

 .../driver-api/serial/serial-rs485.rst        | 36 ++++++-----
 include/uapi/linux/serial.h                   | 62 ++++++++++++-------
 2 files changed, 60 insertions(+), 38 deletions(-)
Signature · 1 line
2.30.2
#1 lore raw

PATCH v3 1/4 serial: Convert serial_rs485 to kernel doc

Convert struct serial_rs485 comments to kernel doc format and include it into documentation.

---
 .../driver-api/serial/serial-rs485.rst        | 13 ++--
 include/uapi/linux/serial.h                   | 62 ++++++++++++-------
 2 files changed, 48 insertions(+), 27 deletions(-)
Documentation/driver-api/serial/serial-rs485.rst +7 -6
index 6ebad75c74ed..264e4b753713 100644
@@ -29,11 +29,11 @@ RS485 Serial Communications
 3. Data Structures Already Available in the Kernel
 ==================================================
 
-   The Linux kernel provides the serial_rs485 structure (see [1]) to handle
-   RS485 communications. This data structure is used to set and configure RS485
+   The Linux kernel provides the serial_rs485 structure to handle RS485
+   communications. This data structure is used to set and configure RS485
    parameters in the platform data and in ioctls.
 
-   The device tree can also provide RS485 boot time parameters (see [2]
+   The device tree can also provide RS485 boot time parameters (see [1]
    for bindings). The driver is in charge of filling this data structure from
    the values given by the device tree.
 
@@ -47,6 +47,9 @@ RS485 Serial Communications
    for the uart_port. TIOCGRS485 ioctl can be used to read back the
    serial_rs485 structure matching to the current configuration.
 
+.. kernel-doc:: include/uapi/linux/serial.h
+   :identifiers: serial_rs485
+
 4. Usage from user-level
 ========================
 
@@ -126,6 +129,4 @@ RS485 Serial Communications
 6. References
 =============
 
- [1]	include/uapi/linux/serial.h
-
- [2]	Documentation/devicetree/bindings/serial/rs485.txt
+ [1]	Documentation/devicetree/bindings/serial/rs485.txt
include/uapi/linux/serial.h +41 -21

78 lines not on this page · raw message

Signature · 1 line
2.30.2
#2 lore raw

Re: [PATCH v3 1/4] serial: Convert serial_rs485 to kernel doc

Quoted 14 lines · Ilpo Järvinen
include/uapi/linux/serial.h +5 -1
index cea06924b295..6e347eb10b1f 100644
@@ -107,37 +107,57 @@ struct serial_icounter_struct {
 	int reserved[9];
 };
 
-/*
+/**
+ * struct serial_rs485 - serial interface for controlling RS485 settings.
+ * @flags:			RS485 feature flags.
+ * @delay_rts_before_send:	Delay before send (milliseconds).
+ * @delay_rts_after_send:	Delay after send (milliseconds).

include/uapi/linux/serial.h struct serial_icounter_struct { · line 124

Quoted 10 lines
include/uapi/linux/serial.h +10 -0
+ * @addr_recv:			Receive filter for RS485 addressing mode
+ *				(used only when %SER_RS485_ADDR_RECV is set).
+ * @addr_dest:			Destination address for RS485 addressing mode
+ *				(used only when %SER_RS485_ADDR_DEST is set).
+ * @padding0:			Padding (set to zero).
+ * @padding1:			Padding (set to zero).
+ * @padding:			Deprecated, use @padding0 and @padding1 instead.
+ *				Do not use with @addr_recv and @addr_dest (due to
+ *				overlap).
+ *

I don't see definition of fields after @delay_rts_after_send in the htmldocs output.

Quoted 7 lines
include/uapi/linux/serial.h +3 -0
  * Serial interface for controlling RS485 settings on chips with suitable
  * support. Set with TIOCSRS485 and get with TIOCGRS485 if supported by your
  * platform. The set function returns the new state, with any unsupported bits
  * reverted appropriately.
+ *
+ * serial_rs485::flags bits are:
+ *

include/uapi/linux/serial.h struct serial_icounter_struct { · line 141

Quoted 10 lines
include/uapi/linux/serial.h +10 -0
+ * * %SER_RS485_ENABLED		- RS485 enabled.
+ * * %SER_RS485_RTS_ON_SEND	- Logical level for RTS pin when sending.
+ * * %SER_RS485_RTS_AFTER_SEND	- Logical level for RTS pin after sent.
+ * * %SER_RS485_RX_DURING_TX	- Full-duplex RS485 line.
+ * * %SER_RS485_TERMINATE_BUS	- Enable bus termination (if supported).
+ * * %SER_RS485_ADDRB		- Enable RS485 addressing mode.
+ * * %SER_RS485_ADDR_RECV	- Receive address filter (enables @addr_recv).
+ *				  Requires %SER_RS485_ADDRB.
+ * * %SER_RS485_ADDR_DEST	- Destination address (enables @addr_dest).
+ *				  Requires %SER_RS485_ADDRB.

The last two items are rendered as bold text instead (maybe due to missing fields rendering above?)

Thanks.

Signature · 1 line
An old man doll... just what I always wanted! - Clara
#3 lore raw

Re: [PATCH v3 1/4] serial: Convert serial_rs485 to kernel doc

Quoted 20 lines · Bagas Sanjaya
Quoted 19 lines · Ilpo Järvinen
include/uapi/linux/serial.h +10 -1
index cea06924b295..6e347eb10b1f 100644
@@ -107,37 +107,57 @@ struct serial_icounter_struct {
 	int reserved[9];
 };
 
-/*
+/**
+ * struct serial_rs485 - serial interface for controlling RS485 settings.
+ * @flags:			RS485 feature flags.
+ * @delay_rts_before_send:	Delay before send (milliseconds).
+ * @delay_rts_after_send:	Delay after send (milliseconds).
+ * @addr_recv:			Receive filter for RS485 addressing mode
+ *				(used only when %SER_RS485_ADDR_RECV is set).
+ * @addr_dest:			Destination address for RS485 addressing mode
+ *				(used only when %SER_RS485_ADDR_DEST is set).
+ * @padding0:			Padding (set to zero).
Quoted 8 lines

include/uapi/linux/serial.h struct serial_icounter_struct { · line 124

Quoted 5 lines
include/uapi/linux/serial.h +5 -0
+ * @padding1:			Padding (set to zero).
+ * @padding:			Deprecated, use @padding0 and @padding1 instead.
+ *				Do not use with @addr_recv and @addr_dest (due to
+ *				overlap).
+ *

I don't see definition of fields after @delay_rts_after_send in the htmldocs output.

So it seems, this one I had missed. I guess the reason is that those members are inside anonymous unions. But the formatting follows what is documented here AFAICT:

https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#nested-structs-unions

Kerneldoc doesn't seem to live up to what is documented about it. It's a bit ironic that documentation system fails to document even itself to sufficient level, and what's worse, seems to be full of faulty examples.

Any suggestions how to make it work?

Quoted 18 lines
Quoted 7 lines
include/uapi/linux/serial.h +3 -0
  * Serial interface for controlling RS485 settings on chips with suitable
  * support. Set with TIOCSRS485 and get with TIOCGRS485 if supported by your
  * platform. The set function returns the new state, with any unsupported bits
  * reverted appropriately.
+ *
+ * serial_rs485::flags bits are:
+ *

include/uapi/linux/serial.h struct serial_icounter_struct { · line 141

Quoted 10 lines
include/uapi/linux/serial.h +10 -0
+ * * %SER_RS485_ENABLED		- RS485 enabled.
+ * * %SER_RS485_RTS_ON_SEND	- Logical level for RTS pin when sending.
+ * * %SER_RS485_RTS_AFTER_SEND	- Logical level for RTS pin after sent.
+ * * %SER_RS485_RX_DURING_TX	- Full-duplex RS485 line.
+ * * %SER_RS485_TERMINATE_BUS	- Enable bus termination (if supported).
+ * * %SER_RS485_ADDRB		- Enable RS485 addressing mode.
+ * * %SER_RS485_ADDR_RECV	- Receive address filter (enables @addr_recv).
+ *				  Requires %SER_RS485_ADDRB.
+ * * %SER_RS485_ADDR_DEST	- Destination address (enables @addr_dest).
+ *				  Requires %SER_RS485_ADDRB.
Quoted 2 lines

The last two items are rendered as bold text instead (maybe due to missing fields rendering above?)

It just goes into some random formatting mode here. Even if I remove those field markers (@) it doesn't do formatting differently so your guesss is wrong.

I found now a way to make it work though. It works when I put the whole description on a single line but it comes at the cost of removing the alignment of those "-". The other way to make it work would be like this:

* * %SER_RS485_ADDR_RECV - Receive address filter (enables @addr_recv).

    Requires %SER_RS485_ADDRB.

...And that's no good. I guess the single-line approach is an acceptable compromise for this case.

Signature · 1 line
 i.
#4 lore raw

Re: [PATCH v3 1/4] serial: Convert serial_rs485 to kernel doc

Quoted 35 lines · Ilpo Järvinen
Quoted 20 lines · Bagas Sanjaya
Quoted 19 lines · Ilpo Järvinen
include/uapi/linux/serial.h +10 -1
index cea06924b295..6e347eb10b1f 100644
@@ -107,37 +107,57 @@ struct serial_icounter_struct {
 	int reserved[9];
 };
 
-/*
+/**
+ * struct serial_rs485 - serial interface for controlling RS485 settings.
+ * @flags:			RS485 feature flags.
+ * @delay_rts_before_send:	Delay before send (milliseconds).
+ * @delay_rts_after_send:	Delay after send (milliseconds).
+ * @addr_recv:			Receive filter for RS485 addressing mode
+ *				(used only when %SER_RS485_ADDR_RECV is set).
+ * @addr_dest:			Destination address for RS485 addressing mode
+ *				(used only when %SER_RS485_ADDR_DEST is set).
+ * @padding0:			Padding (set to zero).
Quoted 8 lines

include/uapi/linux/serial.h struct serial_icounter_struct { · line 124

Quoted 5 lines
include/uapi/linux/serial.h +5 -0
+ * @padding1:			Padding (set to zero).
+ * @padding:			Deprecated, use @padding0 and @padding1 instead.
+ *				Do not use with @addr_recv and @addr_dest (due to
+ *				overlap).
+ *

I don't see definition of fields after @delay_rts_after_send in the htmldocs output.

So it seems, this one I had missed. I guess the reason is that those members are inside anonymous unions. But the formatting follows what is documented here AFAICT:

Quoted 8 lines

https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#nested-structs-unions

Kerneldoc doesn't seem to live up to what is documented about it. It's a bit ironic that documentation system fails to document even itself to sufficient level, and what's worse, seems to be full of faulty examples.

Any suggestions how to make it work?

CC'ing Akira.

Quoted 29 lines
Quoted 18 lines
Quoted 7 lines
include/uapi/linux/serial.h +3 -0
  * Serial interface for controlling RS485 settings on chips with suitable
  * support. Set with TIOCSRS485 and get with TIOCGRS485 if supported by your
  * platform. The set function returns the new state, with any unsupported bits
  * reverted appropriately.
+ *
+ * serial_rs485::flags bits are:
+ *

include/uapi/linux/serial.h struct serial_icounter_struct { · line 141

Quoted 10 lines
include/uapi/linux/serial.h +10 -0
+ * * %SER_RS485_ENABLED		- RS485 enabled.
+ * * %SER_RS485_RTS_ON_SEND	- Logical level for RTS pin when sending.
+ * * %SER_RS485_RTS_AFTER_SEND	- Logical level for RTS pin after sent.
+ * * %SER_RS485_RX_DURING_TX	- Full-duplex RS485 line.
+ * * %SER_RS485_TERMINATE_BUS	- Enable bus termination (if supported).
+ * * %SER_RS485_ADDRB		- Enable RS485 addressing mode.
+ * * %SER_RS485_ADDR_RECV	- Receive address filter (enables @addr_recv).
+ *				  Requires %SER_RS485_ADDRB.
+ * * %SER_RS485_ADDR_DEST	- Destination address (enables @addr_dest).
+ *				  Requires %SER_RS485_ADDRB.
Quoted 2 lines

The last two items are rendered as bold text instead (maybe due to missing fields rendering above?)

It just goes into some random formatting mode here. Even if I remove those field markers (@) it doesn't do formatting differently so your guesss is wrong.

I found now a way to make it work though. It works when I put the whole description on a single line but it comes at the cost of removing the alignment of those "-". The other way to make it work would be like this:

Quoted 6 lines

* * %SER_RS485_ADDR_RECV - Receive address filter (enables @addr_recv).

    Requires %SER_RS485_ADDRB.

...And that's no good. I guess the single-line approach is an acceptable compromise for this case.

OK, thanks for explaining.

Signature · 1 line
An old man doll... just what I always wanted! - Clara
#5 lore raw

Re: [PATCH v3 1/4] serial: Convert serial_rs485 to kernel doc

Quoted 38 lines · Bagas Sanjaya
Quoted 37 lines · Ilpo Järvinen
Quoted 20 lines · Bagas Sanjaya
Quoted 19 lines · Ilpo Järvinen
include/uapi/linux/serial.h +10 -1
index cea06924b295..6e347eb10b1f 100644
@@ -107,37 +107,57 @@ struct serial_icounter_struct {
 	int reserved[9];
 };
 
-/*
+/**
+ * struct serial_rs485 - serial interface for controlling RS485 settings.
+ * @flags:			RS485 feature flags.
+ * @delay_rts_before_send:	Delay before send (milliseconds).
+ * @delay_rts_after_send:	Delay after send (milliseconds).
+ * @addr_recv:			Receive filter for RS485 addressing mode
+ *				(used only when %SER_RS485_ADDR_RECV is set).
+ * @addr_dest:			Destination address for RS485 addressing mode
+ *				(used only when %SER_RS485_ADDR_DEST is set).
+ * @padding0:			Padding (set to zero).
Quoted 8 lines

include/uapi/linux/serial.h struct serial_icounter_struct { · line 124

Quoted 5 lines
include/uapi/linux/serial.h +5 -0
+ * @padding1:			Padding (set to zero).
+ * @padding:			Deprecated, use @padding0 and @padding1 instead.
+ *				Do not use with @addr_recv and @addr_dest (due to
+ *				overlap).
+ *

I don't see definition of fields after @delay_rts_after_send in the htmldocs output.

So it seems, this one I had missed. I guess the reason is that those members are inside anonymous unions. But the formatting follows what is documented here AFAICT:

https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#nested-structs-unions

Quoted 8 lines
Quoted 6 lines

Kerneldoc doesn't seem to live up to what is documented about it. It's a bit ironic that documentation system fails to document even itself to sufficient level, and what's worse, seems to be full of faulty examples.

Any suggestions how to make it work?

CC'ing Akira.

Nevermind, I figured out where the problem is (my incorrect use of
private: markers).

Signature · 1 line
 i.
#6 lore raw

PATCH v3 2/4 Documentation: rs485: Link reference properly

In reply to Ilpo Järvinen

Link DT bindings reference properly.

---
 Documentation/driver-api/serial/serial-rs485.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/driver-api/serial/serial-rs485.rst +4 -4
index 264e4b753713..513758a702a6 100644
@@ -33,9 +33,9 @@ RS485 Serial Communications
    communications. This data structure is used to set and configure RS485
    parameters in the platform data and in ioctls.
 
-   The device tree can also provide RS485 boot time parameters (see [1]
-   for bindings). The driver is in charge of filling this data structure from
-   the values given by the device tree.
+   The device tree can also provide RS485 boot time parameters
+   [#DT-bindings]_. The driver is in charge of filling this data structure
+   from the values given by the device tree.
 
    Any driver for devices capable of working both as RS232 and RS485 should
    implement the rs485_config callback and provide rs485_supported in the
@@ -129,4 +129,4 @@ RS485 Serial Communications
 6. References
 =============
 
- [1]	Documentation/devicetree/bindings/serial/rs485.txt
+.. [#DT-bindings]	Documentation/devicetree/bindings/serial/rs485.txt
Signature · 1 line
2.30.2
#7 lore raw

PATCH v3 3/4 Documentation: rs485: Mention uart_get_rs485_mode()

In reply to Ilpo Järvinen

Add to rs485 documentation that serial core prepares the struct serial_rs485 when uart_get_rs485_mode() is called. Remove the wrong claim that driver must fill it by itself.

---
 Documentation/driver-api/serial/serial-rs485.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
Documentation/driver-api/serial/serial-rs485.rst +3 -3
index 513758a702a6..2951dacfb9eb 100644
@@ -34,8 +34,8 @@ RS485 Serial Communications
    parameters in the platform data and in ioctls.
 
    The device tree can also provide RS485 boot time parameters
-   [#DT-bindings]_. The driver is in charge of filling this data structure
-   from the values given by the device tree.
+   [#DT-bindings]_. The serial core fills the struct serial_rs485 from the
+   values given by the device tree when driver calls uart_get_rs485_mode().
 
    Any driver for devices capable of working both as RS232 and RS485 should
    implement the rs485_config callback and provide rs485_supported in the
@@ -48,7 +48,7 @@ RS485 Serial Communications
    serial_rs485 structure matching to the current configuration.
 
 .. kernel-doc:: include/uapi/linux/serial.h
-   :identifiers: serial_rs485
+   :identifiers: serial_rs485 uart_get_rs485_mode
 
 4. Usage from user-level
 ========================
Signature · 1 line
2.30.2
#8 lore raw

Re: [PATCH v3 3/4] Documentation: rs485: Mention uart_get_rs485_mode()

Quoted 4 lines · Ilpo Järvinen

Add to rs485 documentation that serial core prepares the struct serial_rs485 when uart_get_rs485_mode() is called. Remove the wrong claim that driver must fill it by itself.

the driver

...

Documentation/driver-api/serial/serial-rs485.rst RS485 Serial Communications · line 38

Quoted 5 lines

The device tree can also provide RS485 boot time parameters

Documentation/driver-api/serial/serial-rs485.rst +2 -2
-   [#DT-bindings]_. The driver is in charge of filling this data structure
-   from the values given by the device tree.
+   [#DT-bindings]_. The serial core fills the struct serial_rs485 from the
+   values given by the device tree when driver calls uart_get_rs485_mode().

the driver

Feels like this should be before the previous patch and actually have a Fixes tag.

Signature · 2 lines
With Best Regards,
Andy Shevchenko
#9 lore raw

Re: [PATCH v3 3/4] Documentation: rs485: Mention uart_get_rs485_mode()

Quoted 9 lines · Andy Shevchenko

Documentation/driver-api/serial/serial-rs485.rst RS485 Serial Communications · line 38

Quoted 5 lines · Ilpo Järvinen

The device tree can also provide RS485 boot time parameters

Documentation/driver-api/serial/serial-rs485.rst +2 -2
-   [#DT-bindings]_. The driver is in charge of filling this data structure
-   from the values given by the device tree.
+   [#DT-bindings]_. The serial core fills the struct serial_rs485 from the
+   values given by the device tree when driver calls uart_get_rs485_mode().
Quoted 4 lines

the driver

Feels like this should be before the previous patch and actually have a Fixes tag.

I don't feel it would be an appropriate tag for this kind of cases where documentation is simply lacking behind what the core code now offers.

Signature · 1 line
 i.
#10 lore raw

PATCH v3 4/4 Documentation: rs485: Fix struct referencing

In reply to Ilpo Järvinen

Use "struct serial_rs485" to get the references properly recognized.

---
 .../driver-api/serial/serial-rs485.rst        | 21 ++++++++++---------
 1 file changed, 11 insertions(+), 10 deletions(-)
Documentation/driver-api/serial/serial-rs485.rst +11 -10
index 2951dacfb9eb..d902f9de0b0f 100644
@@ -29,7 +29,7 @@ RS485 Serial Communications
 3. Data Structures Already Available in the Kernel
 ==================================================
 
-   The Linux kernel provides the serial_rs485 structure to handle RS485
+   The Linux kernel provides the struct serial_rs485 to handle RS485
    communications. This data structure is used to set and configure RS485
    parameters in the platform data and in ioctls.
 
@@ -39,13 +39,14 @@ RS485 Serial Communications
 
    Any driver for devices capable of working both as RS232 and RS485 should
    implement the rs485_config callback and provide rs485_supported in the
-   uart_port structure. The serial core calls rs485_config to do the device
-   specific part in response to TIOCSRS485 ioctl (see below). The rs485_config
-   callback receives a pointer to a sanitizated serial_rs485 structure. The
-   serial_rs485 userspace provides is sanitized before calling rs485_config
-   using rs485_supported that indicates what RS485 features the driver supports
-   for the uart_port. TIOCGRS485 ioctl can be used to read back the
-   serial_rs485 structure matching to the current configuration.
+   struct uart_port. The serial core calls rs485_config to do the device
+   specific part in response to TIOCSRS485 ioctl (see below). The
+   rs485_config callback receives a pointer to a sanitizated struct
+   serial_rs485. The struct serial_rs485 userspace provides is sanitized
+   before calling rs485_config using rs485_supported that indicates what
+   RS485 features the driver supports for the struct uart_port. TIOCGRS485
+   ioctl can be used to read back the struct serial_rs485 matching to the
+   current configuration.
 
 .. kernel-doc:: include/uapi/linux/serial.h
    :identifiers: serial_rs485 uart_get_rs485_mode
@@ -107,8 +108,8 @@ RS485 Serial Communications
 
    The Linux kernel provides addressing mode for multipoint RS-485 serial
    communications line. The addressing mode is enabled with SER_RS485_ADDRB
-   flag in serial_rs485. Struct serial_rs485 has two additional flags and
-   fields for enabling receive and destination addresses.
+   flag in struct serial_rs485. The struct serial_rs485 has two additional
+   flags and fields for enabling receive and destination addresses.
 
    Address mode flags:
 	- SER_RS485_ADDRB: Enabled addressing mode (sets also ADDRB in termios).
Signature · 1 line
2.30.2
Reviewed-by on the v3 series
#11 lore raw
In reply to Ilpo Järvinen
Quoted 3 lines · Ilpo Järvinen

RS485 documentation improvements. While doing the kerneldoc conversion, a few other items came up so they're now included to this series.

in this

LGTM, thanks!

Quoted 22 lines

v3:
- More fixes to kernel doc formatting (thanks to Jiri)
- Added a few other related improvements

v2:
- Include serial_rs485 into documentation
- Add * to multi-line flag descriptions

Ilpo Järvinen (4):
serial: Convert serial_rs485 to kernel doc
Documentation: rs485: Link reference properly
Documentation: rs485: Mention uart_get_rs485_mode()
Documentation: rs485: Fix struct referencing

 .../driver-api/serial/serial-rs485.rst        | 36 ++++++-----
 include/uapi/linux/serial.h                   | 62 ++++++++++++-------
 2 files changed, 60 insertions(+), 38 deletions(-)

--
2.30.2

Signature · 2 lines
With Best Regards,
Andy Shevchenko