Skip to contentSkip to conversation

serial: RS485 kerneldoc/documentation improvements

PATCH In review Ilpo Järvinen 2 participants 7 messages Oct 19, 2022 – Oct 20, 2022

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

v5 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 in this series.

v5:
- Make formatting of names more consistent
- serial_rs485::flags bits are: -> The flag bits are:

v4:
- Remove wrong private: markers
- Fix grammar problems

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 (5):
serial: Convert serial_rs485 to kernel doc
Documentation: rs485: Link reference properly
Documentation: rs485: Mention uart_get_rs485_mode()
Documentation: rs485: Fix struct referencing
Documentation: Make formatting consistent for rs485 docs

 .../driver-api/serial/serial-rs485.rst        | 56 ++++++++++---------
 include/uapi/linux/serial.h                   | 55 +++++++++++-------
 2 files changed, 66 insertions(+), 45 deletions(-)
Signature · 1 line
2.30.2
#1 lore raw

PATCH v5 1/5 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                   | 55 ++++++++++++-------
 2 files changed, 43 insertions(+), 25 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 +36 -19

69 lines not on this page · raw message

Signature · 1 line
2.30.2
#2 lore raw

PATCH v5 2/5 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
#3 lore raw

PATCH v5 3/5 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 the driver must fill it by itself.

---
 Documentation/driver-api/serial/serial-rs485.rst | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)
Documentation/driver-api/serial/serial-rs485.rst +4 -3
index 513758a702a6..ee34c8e1e56e 100644
@@ -34,8 +34,9 @@ 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 the 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 +49,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
#4 lore raw

PATCH v5 4/5 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 ee34c8e1e56e..e53aa291bcd7 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.
 
@@ -40,13 +40,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
@@ -108,8 +109,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
#5 lore raw

PATCH v5 5/5 Documentation: Make formatting consistent for rs485 docs

In reply to Ilpo Järvinen

Tweak styling of names that come directly from the code.

---
 .../driver-api/serial/serial-rs485.rst        | 37 ++++++++++---------
 1 file changed, 19 insertions(+), 18 deletions(-)
Documentation/driver-api/serial/serial-rs485.rst +19 -18
index e53aa291bcd7..dce061ef7647 100644
@@ -39,15 +39,15 @@ RS485 Serial Communications
    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
-   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
+   implement the ``rs485_config`` callback and provide ``rs485_supported``
+   in the ``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.
+   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
@@ -108,23 +108,24 @@ 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 struct serial_rs485. The struct serial_rs485 has two additional
-   flags and fields for enabling receive and destination addresses.
+   communications line. The addressing mode is enabled with
+   ``SER_RS485_ADDRB`` 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).
-	- SER_RS485_ADDR_RECV: Receive (filter) address enabled.
-	- SER_RS485_ADDR_DEST: Set destination address.
+	- ``SER_RS485_ADDRB``: Enabled addressing mode (sets also ADDRB in termios).
+	- ``SER_RS485_ADDR_RECV``: Receive (filter) address enabled.
+	- ``SER_RS485_ADDR_DEST``: Set destination address.
 
-   Address fields (enabled with corresponding SER_RS485_ADDR_* flag):
-	- addr_recv: Receive address.
-	- addr_dest: Destination address.
+   Address fields (enabled with corresponding ``SER_RS485_ADDR_*`` flag):
+	- ``addr_recv``: Receive address.
+	- ``addr_dest``: Destination address.
 
    Once a receive address is set, the communication can occur only with the
    particular device and other peers are filtered out. It is left up to the
    receiver side to enforce the filtering. Receive address will be cleared
-   if SER_RS485_ADDR_RECV is not set.
+   if ``SER_RS485_ADDR_RECV`` is not set.
 
    Note: not all devices supporting RS485 support multipoint addressing.
 
Signature · 1 line
2.30.2
Reviewed-by on the v5 series
#6 lore raw
In reply to Ilpo Järvinen
Quoted 26 lines · Ilpo Järvinen

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

v5:
- Make formatting of names more consistent
- serial_rs485::flags bits are: -> The flag bits are:

v4:
- Remove wrong private: markers
- Fix grammar problems

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 (5):
serial: Convert serial_rs485 to kernel doc
Documentation: rs485: Link reference properly
Documentation: rs485: Mention uart_get_rs485_mode()
Documentation: rs485: Fix struct referencing
Documentation: Make formatting consistent for rs485 docs

Quoted 4 lines
 .../driver-api/serial/serial-rs485.rst        | 56 ++++++++++---------
 include/uapi/linux/serial.h                   | 55 +++++++++++-------
 2 files changed, 66 insertions(+), 45 deletions(-)

The doc LGTM, thanks.

For the series,

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