Unify UART headers (#24855)

* Remove deprecated defines

* Move default config to .c files

* Unify UART headers

* Clean up docs

* Reorganise PAL mode defaults

6 files changed, 225 insertions, 252 deletions

diff --git a/docs/drivers/uart.md b/docs/drivers/uart.md
index 7cc68727ee..b895266cab 100644
--- a/docs/drivers/uart.md
+++ b/docs/drivers/uart.md
@@ -45,17 +45,17 @@ To enable UART, modify your board's `mcuconf.h` to enable the peripheral you've
 
 Configuration-wise, you'll need to set up the peripheral as per your MCU's datasheet -- the defaults match the pins for a Proton-C, i.e. STM32F303.
 
-|     `config.h` override     |                           Description                           | Default Value |
-| --------------------------- | --------------------------------------------------------------- | ------------- |
-| `#define UART_DRIVER`       | USART peripheral to use - USART1 -> `SD1`, USART2 -> `SD2` etc. | `SD1`         |
-| `#define UART_TX_PIN`       | The pin to use for TX                                           | `A9`          |
-| `#define UART_TX_PAL_MODE`  | The alternate function mode for TX                              | `7`           |
-| `#define UART_RX_PIN`       | The pin to use for RX                                           | `A10`         |
-| `#define UART_RX_PAL_MODE`  | The alternate function mode for RX                              | `7`           |
-| `#define UART_CTS_PIN`      | The pin to use for CTS                                          | `A11`         |
-| `#define UART_CTS_PAL_MODE` | The alternate function mode for CTS                             | `7`           |
-| `#define UART_RTS_PIN`      | The pin to use for RTS                                          | `A12`         |
-| `#define UART_RTS_PAL_MODE` | The alternate function mode for RTS                             | `7`           |
+|`config.h` Override|Description                                                    |Default|
+|-------------------|---------------------------------------------------------------|-------|
+|`UART_DRIVER`      |USART peripheral to use - USART1 -> `SD1`, USART2 -> `SD2` etc.|`SD1`  |
+|`UART_TX_PIN`      |The pin to use for TX                                          |`A9`   |
+|`UART_TX_PAL_MODE` |The alternate function mode for TX                             |`7`    |
+|`UART_RX_PIN`      |The pin to use for RX                                          |`A10`  |
+|`UART_RX_PAL_MODE` |The alternate function mode for RX                             |`7`    |
+|`UART_CTS_PIN`     |The pin to use for CTS                                         |`A11`  |
+|`UART_CTS_PAL_MODE`|The alternate function mode for CTS                            |`7`    |
+|`UART_RTS_PIN`     |The pin to use for RTS                                         |`A12`  |
+|`UART_RTS_PAL_MODE`|The alternate function mode for RTS                            |`7`    |
 
 ## API {#api}
 
@@ -111,7 +111,7 @@ Receive multiple bytes.
 #### Arguments {#api-uart-receive-arguments}
 
  - `uint8_t *data`  
-   A pointer to the buffer to read into.
+   A pointer to a buffer to read into.
  - `uint16_t length`  
    The number of bytes to read. Take care not to overrun the length of `data`.
 
@@ -123,4 +123,4 @@ Return whether the receive buffer contains data. Call this function to determine
 
 #### Return Value {#api-uart-available-return}
 
-`true` if the receive buffer length is non-zero.
+`true` if there is data available to read.
diff --git a/drivers/uart.h b/drivers/uart.h
new file mode 100644
index 0000000000..c5068c86e1
--- /dev/null
+++ b/drivers/uart.h
@@ -0,0 +1,62 @@
+// Copyright 2025 QMK
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+#pragma once
+
+#include <stdint.h>
+#include <stdbool.h>
+
+/**
+ * \file
+ *
+ * \defgroup uart UART API
+ *
+ * \brief API to communicate with UART devices.
+ * \{
+ */
+
+/**
+ * \brief Initialize the UART driver. This function must be called only once, before any of the below functions can be called.
+ *
+ * \param baud The baud rate to transmit and receive at. This may depend on the device you are communicating with. Common values are 1200, 2400, 4800, 9600, 19200, 38400, 57600, and 115200.
+ */
+void uart_init(uint32_t baud);
+
+/**
+ * \brief Transmit a single byte.
+ *
+ * \param data The byte to write.
+ */
+void uart_write(uint8_t data);
+
+/**
+ * \brief Receive a single byte.
+ *
+ * \return The byte read from the receive buffer. This function will block if the buffer is empty (ie. no data to read).
+ */
+uint8_t uart_read(void);
+
+/**
+ * \brief Transmit multiple bytes.
+ *
+ * \param data A pointer to the data to write from.
+ * \param length The number of bytes to write. Take care not to overrun the length of `data`.
+ */
+void uart_transmit(const uint8_t *data, uint16_t length);
+
+/**
+ * \brief Receive multiple bytes.
+ *
+ * \param data A pointer to a buffer to read into.
+ * \param length The number of bytes to read. Take care not to overrun the length of `data`.
+ */
+void uart_receive(uint8_t *data, uint16_t length);
+
+/**
+ * \brief Return whether the receive buffer contains data. Call this function to determine if `uart_read()` will return data immediately.
+ *
+ * \return true if there is data available to read.
+ */
+bool uart_available(void);
+
+/** \} */
diff --git a/platforms/avr/drivers/uart.h b/platforms/avr/drivers/uart.h
deleted file mode 100644
index e2dc664eda..0000000000
--- a/platforms/avr/drivers/uart.h
+++ /dev/null
@@ -1,39 +0,0 @@
-/* UART Example for Teensy USB Development Board
- * http://www.pjrc.com/teensy/
- * Copyright (c) 2009 PJRC.COM, LLC
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in
- * all copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
- * THE SOFTWARE.
- */
-
-#pragma once
-
-#include <stdint.h>
-#include <stdbool.h>
-
-void uart_init(uint32_t baud);
-
-void uart_write(uint8_t data);
-
-uint8_t uart_read(void);
-
-void uart_transmit(const uint8_t *data, uint16_t length);
-
-void uart_receive(uint8_t *data, uint16_t length);
-
-bool uart_available(void);
diff --git a/platforms/chibios/drivers/uart.h b/platforms/chibios/drivers/uart.h
deleted file mode 100644
index c1945575f1..0000000000
--- a/platforms/chibios/drivers/uart.h
+++ /dev/null
@@ -1,200 +0,0 @@
-// Copyright 2024 Stefan Kerkmann
-// Copyright 2021 QMK
-// Copyright 2024 Stefan Kerkmann
-// SPDX-License-Identifier: GPL-2.0-or-later
-
-#pragma once
-
-#include <stdint.h>
-#include <stdbool.h>
-
-#include <hal.h>
-
-#include "gpio.h"
-#include "chibios_config.h"
-
-// ======== DEPRECATED DEFINES - DO NOT USE ========
-#ifdef SERIAL_DRIVER
-#    define UART_DRIVER SERIAL_DRIVER
-#endif
-#ifdef SD1_TX_PIN
-#    define UART_TX_PIN SD1_TX_PIN
-#endif
-#ifdef SD1_RX_PIN
-#    define UART_RX_PIN SD1_RX_PIN
-#endif
-#ifdef SD1_CTS_PIN
-#    define UART_CTS_PIN SD1_CTS_PIN
-#endif
-#ifdef SD1_RTS_PIN
-#    define UART_RTS_PIN SD1_RTS_PIN
-#endif
-#ifdef SD1_TX_PAL_MODE
-#    define UART_TX_PAL_MODE SD1_TX_PAL_MODE
-#endif
-#ifdef SD1_RX_PAL_MODE
-#    define UART_RX_PAL_MODE SD1_RX_PAL_MODE
-#endif
-#ifdef SD1_CTS_PAL_MODE
-#    define UART_RTS_PAL_MODE SD1_CTS_PAL_MODE
-#endif
-#ifdef SD1_RTS_PAL_MODE
-#    define UART_TX_PAL_MODE SD1_RTS_PAL_MODE
-#endif
-#ifdef SD1_CR1
-#    define UART_CR1 SD1_CR1
-#endif
-#ifdef SD1_CR2
-#    define UART_CR2 SD1_CR2
-#endif
-#ifdef SD1_CR3
-#    define UART_CR3 SD1_CR3
-#endif
-#ifdef SD1_WRDLEN
-#    define UART_WRDLEN SD1_WRDLEN
-#endif
-#ifdef SD1_STPBIT
-#    define UART_STPBIT SD1_STPBIT
-#endif
-#ifdef SD1_PARITY
-#    define UART_PARITY SD1_PARITY
-#endif
-#ifdef SD1_ATFLCT
-#    define UART_ATFLCT SD1_ATFLCT
-#endif
-// ========
-
-#ifndef UART_DRIVER
-#    if (HAL_USE_SERIAL == TRUE)
-#        define UART_DRIVER SD1
-#    elif (HAL_USE_SIO == TRUE)
-#        define UART_DRIVER SIOD1
-#    endif
-#endif
-
-#ifndef UART_TX_PIN
-#    define UART_TX_PIN A9
-#endif
-
-#ifndef UART_RX_PIN
-#    define UART_RX_PIN A10
-#endif
-
-#ifndef UART_CTS_PIN
-#    define UART_CTS_PIN A11
-#endif
-
-#ifndef UART_RTS_PIN
-#    define UART_RTS_PIN A12
-#endif
-
-#ifdef USE_GPIOV1
-#    ifndef UART_TX_PAL_MODE
-#        define UART_TX_PAL_MODE PAL_MODE_ALTERNATE_PUSHPULL
-#    endif
-#    ifndef UART_RX_PAL_MODE
-#        define UART_RX_PAL_MODE PAL_MODE_INPUT
-#    endif
-#    ifndef UART_CTS_PAL_MODE
-#        define UART_CTS_PAL_MODE PAL_MODE_INPUT
-#    endif
-#    ifndef UART_RTS_PAL_MODE
-#        define UART_RTS_PAL_MODE PAL_MODE_ALTERNATE_PUSHPULL
-#    endif
-#else
-#    ifndef UART_TX_PAL_MODE
-#        define UART_TX_PAL_MODE 7
-#    endif
-
-#    ifndef UART_RX_PAL_MODE
-#        define UART_RX_PAL_MODE 7
-#    endif
-
-#    ifndef UART_CTS_PAL_MODE
-#        define UART_CTS_PAL_MODE 7
-#    endif
-
-#    ifndef UART_RTS_PAL_MODE
-#        define UART_RTS_PAL_MODE 7
-#    endif
-#endif
-
-#ifndef UART_CR1
-#    define UART_CR1 0
-#endif
-
-#ifndef UART_CR2
-#    define UART_CR2 0
-#endif
-
-#ifndef UART_CR3
-#    define UART_CR3 0
-#endif
-
-#ifndef UART_WRDLEN
-#    define UART_WRDLEN 3
-#endif
-
-#ifndef UART_STPBIT
-#    define UART_STPBIT 0
-#endif
-
-#ifndef UART_PARITY
-#    define UART_PARITY 0
-#endif
-
-#ifndef UART_ATFLCT
-#    define UART_ATFLCT 0
-#endif
-
-/**
- * @brief Initialize the UART driver. This function must be called only once,
- * before any of the below functions can be called.
- *
- * @param baud The baud rate to transmit and receive at. This may depend on the
- * device you are communicating with. Common values are 1200, 2400, 4800, 9600,
- * 19200, 38400, 57600, and 115200.
- */
-void uart_init(uint32_t baud);
-
-/**
- * @brief Transmit a single byte.
- *
- * @param data The byte to transmit.
- */
-void uart_write(uint8_t data);
-
-/**
- * @brief Receive a single byte.
- *
- * @return uint8_t The byte read from the receive buffer. This function will
- * block if the buffer is empty (ie. no data to read).
- */
-uint8_t uart_read(void);
-
-/**
- * @brief Transmit multiple bytes.
- *
- * @param data A pointer to the data to write from.
- * @param length The number of bytes to write. Take care not to overrun the
- * length of `data`.
- */
-void uart_transmit(const uint8_t *data, uint16_t length);
-
-/**
- * @brief Receive multiple bytes.
- *
- * @param data A pointer to the buffer to read into.
- * @param length The number of bytes to read. Take care not to overrun the
- * length of `data`.
- */
-void uart_receive(uint8_t *data, uint16_t length);
-
-/**
- * @brief Return whether the receive buffer contains data. Call this function
- * to determine if `uart_read()` will return data immediately.
- *
- * @return true If there is data available to read.
- * @return false If there is no data available to read.
- */
-bool uart_available(void);
diff --git a/platforms/chibios/drivers/uart_serial.c b/platforms/chibios/drivers/uart_serial.c
index 6aff4eae47..e0afb9768a 100644
--- a/platforms/chibios/drivers/uart_serial.c
+++ b/platforms/chibios/drivers/uart_serial.c
@@ -3,6 +3,89 @@
 // SPDX-License-Identifier: GPL-2.0-or-later
 
 #include "uart.h"
+#include "gpio.h"
+#include "chibios_config.h"
+#include <hal.h>
+
+#ifndef UART_DRIVER
+#    define UART_DRIVER SD1
+#endif
+
+#ifndef UART_TX_PIN
+#    define UART_TX_PIN A9
+#endif
+
+#ifndef UART_TX_PAL_MODE
+#    ifdef USE_GPIOV1
+#        define UART_TX_PAL_MODE PAL_MODE_ALTERNATE_PUSHPULL
+#    else
+#        define UART_TX_PAL_MODE 7
+#    endif
+#endif
+
+#ifndef UART_RX_PIN
+#    define UART_RX_PIN A10
+#endif
+
+#ifndef UART_RX_PAL_MODE
+#    ifdef USE_GPIOV1
+#        define UART_RX_PAL_MODE PAL_MODE_INPUT
+#    else
+#        define UART_RX_PAL_MODE 7
+#    endif
+#endif
+
+#ifndef UART_CTS_PIN
+#    define UART_CTS_PIN A11
+#endif
+
+#ifndef UART_CTS_PAL_MODE
+#    ifdef USE_GPIOV1
+#        define UART_CTS_PAL_MODE PAL_MODE_INPUT
+#    else
+#        define UART_CTS_PAL_MODE 7
+#    endif
+#endif
+
+#ifndef UART_RTS_PIN
+#    define UART_RTS_PIN A12
+#endif
+
+#ifndef UART_RTS_PAL_MODE
+#    ifdef USE_GPIOV1
+#        define UART_RTS_PAL_MODE PAL_MODE_ALTERNATE_PUSHPULL
+#    else
+#        define UART_RTS_PAL_MODE 7
+#    endif
+#endif
+
+#ifndef UART_CR1
+#    define UART_CR1 0
+#endif
+
+#ifndef UART_CR2
+#    define UART_CR2 0
+#endif
+
+#ifndef UART_CR3
+#    define UART_CR3 0
+#endif
+
+#ifndef UART_WRDLEN
+#    define UART_WRDLEN 3
+#endif
+
+#ifndef UART_STPBIT
+#    define UART_STPBIT 0
+#endif
+
+#ifndef UART_PARITY
+#    define UART_PARITY 0
+#endif
+
+#ifndef UART_ATFLCT
+#    define UART_ATFLCT 0
+#endif
 
 #if defined(MCU_KINETIS)
 static SerialConfig serialConfig = {SERIAL_DEFAULT_BITRATE};
diff --git a/platforms/chibios/drivers/uart_sio.c b/platforms/chibios/drivers/uart_sio.c
index 442df1c54d..fc12f0abed 100644
--- a/platforms/chibios/drivers/uart_sio.c
+++ b/platforms/chibios/drivers/uart_sio.c
@@ -3,6 +3,73 @@
 // SPDX-License-Identifier: GPL-2.0-or-later
 
 #include "uart.h"
+#include "gpio.h"
+#include "chibios_config.h"
+#include <hal.h>
+
+#ifndef UART_DRIVER
+#    define UART_DRIVER SIOD1
+#endif
+
+#ifndef UART_TX_PIN
+#    define UART_TX_PIN A9
+#endif
+
+#ifndef UART_TX_PAL_MODE
+#    ifdef USE_GPIOV1
+#        define UART_TX_PAL_MODE PAL_MODE_ALTERNATE_PUSHPULL
+#    else
+#        define UART_TX_PAL_MODE 7
+#    endif
+#endif
+
+#ifndef UART_RX_PIN
+#    define UART_RX_PIN A10
+#endif
+
+#ifndef UART_RX_PAL_MODE
+#    ifdef USE_GPIOV1
+#        define UART_RX_PAL_MODE PAL_MODE_INPUT
+#    else
+#        define UART_RX_PAL_MODE 7
+#    endif
+#endif
+
+#ifndef UART_CTS_PIN
+#    define UART_CTS_PIN A11
+#endif
+
+#ifndef UART_CTS_PAL_MODE
+#    ifdef USE_GPIOV1
+#        define UART_CTS_PAL_MODE PAL_MODE_INPUT
+#    else
+#        define UART_CTS_PAL_MODE 7
+#    endif
+#endif
+
+#ifndef UART_RTS_PIN
+#    define UART_RTS_PIN A12
+#endif
+
+#ifndef UART_RTS_PAL_MODE
+#    ifdef USE_GPIOV1
+#        define UART_RTS_PAL_MODE PAL_MODE_ALTERNATE_PUSHPULL
+#    else
+#        define UART_RTS_PAL_MODE 7
+#    endif
+#endif
+
+#ifndef UART_CR1
+#    define UART_CR1 0
+#endif
+
+#ifndef UART_CR2
+#    define UART_CR2 0
+#endif
+
+#ifndef UART_CR3
+#    define UART_CR3 0
+#endif
 
 #if defined(MCU_RP)
 // 38400 baud, 8 data bits, 1 stop bit, no parity, no flow control