serial: Convert serial_rs485 to kernel doc

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

Suggested-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
Signed-off-by: Ilpo Järvinen <ilpo.jarvinen@linux.intel.com>
Link: https://lore.kernel.org/r/20221019093343.9546-2-ilpo.jarvinen@linux.intel.com
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

diff --git a/Documentation/driver-api/serial/serial-rs485.rst b/Documentation/driver-api/serial/serial-rs485.rst
index 6ebad75..264e4b7 100644 (file)
--- a/Documentation/driver-api/serial/serial-rs485.rst
+++ b/Documentation/driver-api/serial/serial-rs485.rst
@@ -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

diff --git a/include/uapi/linux/serial.h b/include/uapi/linux/serial.h
index cea0692..53bc1af 100644 (file)
--- a/include/uapi/linux/serial.h
+++ b/include/uapi/linux/serial.h
@@ -107,33 +107,50 @@ 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).
+ * @padding1:                  Padding (set to zero).
+ * @padding:                   Deprecated, use @padding0 and @padding1 instead.
+ *                             Do not use with @addr_recv and @addr_dest (due to
+ *                             overlap).
+ *
  * 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.
+ *
+ * The flag bits are:
+ *
+ * * %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.
  */
-
 struct serial_rs485 {
-       __u32   flags;                  /* RS485 feature flags */
-#define SER_RS485_ENABLED              (1 << 0)        /* If enabled */
-#define SER_RS485_RTS_ON_SEND          (1 << 1)        /* Logical level for
-                                                          RTS pin when
-                                                          sending */
-#define SER_RS485_RTS_AFTER_SEND       (1 << 2)        /* Logical level for
-                                                          RTS pin after sent*/
+       __u32   flags;
+#define SER_RS485_ENABLED              (1 << 0)
+#define SER_RS485_RTS_ON_SEND          (1 << 1)
+#define SER_RS485_RTS_AFTER_SEND       (1 << 2)
 #define SER_RS485_RX_DURING_TX         (1 << 4)
-#define SER_RS485_TERMINATE_BUS                (1 << 5)        /* Enable bus
-                                                          termination
-                                                          (if supported) */
-
-/* RS-485 addressing mode */
-#define SER_RS485_ADDRB                        (1 << 6)        /* Enable addressing mode */
-#define SER_RS485_ADDR_RECV            (1 << 7)        /* Receive address filter */
-#define SER_RS485_ADDR_DEST            (1 << 8)        /* Destination address */
+#define SER_RS485_TERMINATE_BUS                (1 << 5)
+#define SER_RS485_ADDRB                        (1 << 6)
+#define SER_RS485_ADDR_RECV            (1 << 7)
+#define SER_RS485_ADDR_DEST            (1 << 8)
 
-       __u32   delay_rts_before_send;  /* Delay before send (milliseconds) */
-       __u32   delay_rts_after_send;   /* Delay after send (milliseconds) */
+       __u32   delay_rts_before_send;
+       __u32   delay_rts_after_send;
 
        /* The fields below are defined by flags */
        union {