[PATCH 1/3] serial: core: Document why UPF_SPD_CUST is not handled in uart_get_baud_rate()

[Pali Rohár]

Switch in uart_get_baud_rate() function is missing case for UPF_SPD_CUST
flag. It is not obvious why it is missing here, so add comments explaining
how deprecated UPF_SPD_CUST flag is handled and how drivers should call
uart_get_baud_rate() and uart_get_divisor() functions.

Signed-off-by: Pali Rohár <pali@xxxxxxxxxx>
---
 drivers/tty/serial/serial_core.c | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/drivers/tty/serial/serial_core.c b/drivers/tty/serial/serial_core.c
index 1e738f265eea..d8fc2616d62b 100644
--- a/drivers/tty/serial/serial_core.c
+++ b/drivers/tty/serial/serial_core.c
@@ -364,7 +364,17 @@ EXPORT_SYMBOL(uart_update_timeout);
  *
  *	Decode the termios structure into a numeric baud rate,
  *	taking account of the magic 38400 baud rate (with spd_*
- *	flags), and mapping the %B0 rate to 9600 baud.
+ *	flags, except cust), and mapping the %B0 rate to 9600 baud.
+ *
+ *	UPF_SPD_CUST flag is not handled in this function as it applies
+ *	to the custom divisor. When UPF_SPD_CUST flag is active and in
+ *	use then this function returns value 38400 and not the correct
+ *	baud rate.
+ *
+ *	Drivers should call uart_get_divisor() function with baud rate
+ *	returned from this function to calculate clock divisor. Function
+ *	uart_get_divisor() then handles UPF_SPD_CUST flag with magic
+ *	baud rate value 38400 and returns the correct custom divisor.
  *
  *	If the new baud rate is invalid, try the old termios setting.
  *	If it's still invalid, we try 9600 baud.
@@ -396,6 +406,7 @@ uart_get_baud_rate(struct uart_port *port, struct ktermios *termios,
 	case UPF_SPD_WARP:
 		altbaud = 460800;
 		break;
+	/* Flag UPF_SPD_CUST is not handed here, see description why. */
 	default:
 		altbaud = 38400;
 		break;
@@ -462,6 +473,8 @@ EXPORT_SYMBOL(uart_get_baud_rate);
  *	@baud: desired baud rate
  *
  *	Calculate the uart clock divisor for the port.
+ *
+ *	Handles also special case when UPF_SPD_CUST flag is in use.
  */
 unsigned int
 uart_get_divisor(struct uart_port *port, unsigned int baud)
-- 
2.20.1