serial: RS485 kerneldoc/documentation improvements
Subsystems (2)
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
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
@@ -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
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@@ -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
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@@ -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.
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@@ -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
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@@ -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.
PATCH v3 2/4 Documentation: rs485: Link reference properly
In reply to Ilpo JärvinenLink 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
@@ -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
PATCH v3 3/4 Documentation: rs485: Mention uart_get_rs485_mode()
In reply to Ilpo JärvinenAdd 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
@@ -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
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_rs485whenuart_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
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.
PATCH v3 4/4 Documentation: rs485: Fix struct referencing
In reply to Ilpo JärvinenUse "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
@@ -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
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 improvementsv2:
- Includeserial_rs485into documentation
- Add * to multi-line flag descriptionsIlpo Järvinen (4):
serial: Convertserial_rs485to kernel doc
Documentation: rs485: Link reference properly
Documentation: rs485: Mentionuart_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