Merge remote-tracking branch 'origin/develop' into xap

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.

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);
+
+/** \} */