serial: Convert serial_rs485 to kernel doc

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

Ilpo Järvinen committed 4 years ago

Commit 6dd07781 parent 109a9512 files · +43 −25Browse files

Unified · Split

2 files

Documentation/driver-api/serial/serial-rs485.rst +7 −6
include/uapi/linux/serial.h +36 −19

Documentation/driver-api/serial/serial-rs485.rst+7−6

@@ -29,11 +29,11 @@ RS485 Serial Communications · 28 unmodified lines
29	29	3. Data Structures Already Available in the Kernel
30	30	==================================================
31	31
32		− The Linux kernel provides the serial_rs485 structure (see [1]) to handle
33		− RS485 communications. This data structure is used to set and configure RS485
	32	+ The Linux kernel provides the serial_rs485 structure to handle RS485
	33	+ communications. This data structure is used to set and configure RS485
34	34	parameters in the platform data and in ioctls.
35	35
36		− The device tree can also provide RS485 boot time parameters (see [2]
	36	+ The device tree can also provide RS485 boot time parameters (see [1]
37	37	for bindings). The driver is in charge of filling this data structure from
38	38	the values given by the device tree.
39	39
@@ -47,6 +47,9 @@ RS485 Serial Communications · 7 unmodified lines
47	47	for the uart_port. TIOCGRS485 ioctl can be used to read back the
48	48	serial_rs485 structure matching to the current configuration.
49	49
	50	+.. kernel-doc:: include/uapi/linux/serial.h
	51	+ :identifiers: serial_rs485
	52	+
50	53	4. Usage from user-level
51	54	========================
52	55
@@ -126,6 +129,4 @@ RS485 Serial Communications · 73 unmodified lines
126	129	6. References
127	130	=============
128	131
129		− [1] include/uapi/linux/serial.h
130		−
131		− [2] Documentation/devicetree/bindings/serial/rs485.txt
	132	+ [1] Documentation/devicetree/bindings/serial/rs485.txt

include/uapi/linux/serial.h+36−19

@@ -107,33 +107,50 @@ struct serial_icounter_struct { · 106 unmodified lines
107	107	int reserved[9];
108	108	};
109	109
110		−/*
	110	+/**
	111	+ * struct serial_rs485 - serial interface for controlling RS485 settings.
	112	+ * @flags: RS485 feature flags.
	113	+ * @delay_rts_before_send: Delay before send (milliseconds).
	114	+ * @delay_rts_after_send: Delay after send (milliseconds).
	115	+ * @addr_recv: Receive filter for RS485 addressing mode
	116	+ * (used only when %SER_RS485_ADDR_RECV is set).
	117	+ * @addr_dest: Destination address for RS485 addressing mode
	118	+ * (used only when %SER_RS485_ADDR_DEST is set).
	119	+ * @padding0: Padding (set to zero).
	120	+ * @padding1: Padding (set to zero).
	121	+ * @padding: Deprecated, use @padding0 and @padding1 instead.
	122	+ * Do not use with @addr_recv and @addr_dest (due to
	123	+ * overlap).
	124	+ *
111	125	* Serial interface for controlling RS485 settings on chips with suitable
112	126	* support. Set with TIOCSRS485 and get with TIOCGRS485 if supported by your
113	127	* platform. The set function returns the new state, with any unsupported bits
114	128	* reverted appropriately.
	129	+ *
	130	+ * The flag bits are:
	131	+ *
	132	+ * * %SER_RS485_ENABLED - RS485 enabled.
	133	+ * * %SER_RS485_RTS_ON_SEND - Logical level for RTS pin when sending.
	134	+ * * %SER_RS485_RTS_AFTER_SEND - Logical level for RTS pin after sent.
	135	+ * * %SER_RS485_RX_DURING_TX - Full-duplex RS485 line.
	136	+ * * %SER_RS485_TERMINATE_BUS - Enable bus termination (if supported).
	137	+ * * %SER_RS485_ADDRB - Enable RS485 addressing mode.
	138	+ * * %SER_RS485_ADDR_RECV - Receive address filter (enables @addr_recv). Requires %SER_RS485_ADDRB.
	139	+ * * %SER_RS485_ADDR_DEST - Destination address (enables @addr_dest). Requires %SER_RS485_ADDRB.
115	140	*/
116		−
117	141	struct serial_rs485 {
118		− __u32 flags; /* RS485 feature flags */
119		−#define SER_RS485_ENABLED (1 << 0) /* If enabled */
120		−#define SER_RS485_RTS_ON_SEND (1 << 1) /* Logical level for
121		− RTS pin when
122		− sending */
123		−#define SER_RS485_RTS_AFTER_SEND (1 << 2) /* Logical level for
124		− RTS pin after sent*/
	142	+ __u32 flags;
	143	+#define SER_RS485_ENABLED (1 << 0)
	144	+#define SER_RS485_RTS_ON_SEND (1 << 1)
	145	+#define SER_RS485_RTS_AFTER_SEND (1 << 2)
125	146	#define SER_RS485_RX_DURING_TX (1 << 4)
126		−#define SER_RS485_TERMINATE_BUS (1 << 5) /* Enable bus
127		− termination
128		− (if supported) */
129		−
130		−/* RS-485 addressing mode */
131		−#define SER_RS485_ADDRB (1 << 6) /* Enable addressing mode */
132		−#define SER_RS485_ADDR_RECV (1 << 7) /* Receive address filter */
133		−#define SER_RS485_ADDR_DEST (1 << 8) /* Destination address */
	147	+#define SER_RS485_TERMINATE_BUS (1 << 5)
	148	+#define SER_RS485_ADDRB (1 << 6)
	149	+#define SER_RS485_ADDR_RECV (1 << 7)
	150	+#define SER_RS485_ADDR_DEST (1 << 8)
134	151
135		− __u32 delay_rts_before_send; /* Delay before send (milliseconds) */
136		− __u32 delay_rts_after_send; /* Delay after send (milliseconds) */
	152	+ __u32 delay_rts_before_send;
	153	+ __u32 delay_rts_after_send;
137	154
138	155	/* The fields below are defined by flags */
139	156	union {