Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
From:   =?UTF-8?q?Pali=20Roh=C3=A1r?= <pali@kernel.org>
To:     Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
        Jiri Slaby <jirislaby@kernel.org>,
        Johan Hovold <johan@kernel.org>,
        =?UTF-8?q?Marek=20Beh=C3=BAn?= <kabel@kernel.org>
Cc:     linux-serial@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: [PATCH 1/3] serial: core: Document why UPF_SPD_CUST is not handled in uart_get_baud_rate()
Date:   Mon, 21 Mar 2022 17:30:53 +0100
Message-Id: <20220321163055.4058-2-pali@kernel.org>
In-Reply-To: <20220321163055.4058-1-pali@kernel.org>
References: <20220321163055.4058-1-pali@kernel.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Precedence: bulk

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@kernel.org>
---
 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