# UART Hal interface documentation

## Hardware introduction

K230 integrates five UART (Universal Asynchronous Receiver and Transmitter) hardware modules. The rtsmart system occupies one serial port (serial port 0 is occupied by default), and other serial ports can be used by users.

---

## Data structure description

### `struct uart_configure`

UART configuration structure, including the following members:

* `baud_rate`: baud rate
* `data_bits`: number of data digits (5-9)
* `stop_bits`: Stop bits (0-3 corresponds to 1-4 stop bits)
* `parity`: Check digit (0: no check, 1: odd check, 2: even check)
* `bit_order`: Bit order (0: LSB first, 1: MSB first)
* `invert`: Signal inversion (0: normal mode, 1: inversion mode)
* `bufsz`: buffer size
* `reserved`: reserved field

---

## Function interface description

### `int drv_uart_inst_create(int id, drv_uart_inst_t** inst);`

**Function**: Create UART driver instance.

**parameter**:

* `id`: UART interface ID, range `[0, KD_HARD_UART_MAX_NUM-1]`
* `inst`: double pointer to store the created instance

**Return Value**:

* `0`: Created successfully
* `-1`: Invalid parameter
* `-2`: Invalid UART ID
* `-3`: Memory allocation failed

---

### `void drv_uart_inst_destroy(drv_uart_inst_t** inst);`

**Function**: Destroy the UART driver instance.

**parameter**:

* `inst`: double pointer, pointing to the instance to be destroyed

---

### `size_t drv_uart_read(drv_uart_inst_t* inst, const uint8_t* buffer, size_t size);`

**Function**: Read data from UART.

**parameter**:

* `inst`: UART instance
* `buffer`: Buffer to store read data
* `size`: Number of bytes to read

**Return Value**:

* On success: number of bytes actually read
* `-1`: Invalid parameter
* `-2`: read error

---

### `size_t drv_uart_write(drv_uart_inst_t* inst, uint8_t* buffer, size_t size);`

**Function**: Write data to UART.

**parameter**:

* `inst`: UART instance
* `buffer`: Data to be written
* `size`: Number of bytes to write

**Return Value**:

* On success: number of bytes actually written
* `-1`: Invalid parameter
* `-2`: Write error

---

### `int drv_uart_poll(drv_uart_inst_t* inst, int timeout_ms);`

**Function**: Poll UART read availability.

**parameter**:

* `inst`: UART instance
* `timeout_ms`: timeout (milliseconds), `-1` means infinite waiting, `0` means non-blocking

**Return Value**:

* `>0`: There is data to read
* `0`: timeout
* `-1`: Invalid parameter
* `-errno`: Polling error (negative errno value)
* `-EIO`: Device error

---

### `size_t drv_uart_recv_available(drv_uart_inst_t* inst);`

**Function**: Check the number of bytes that can be read.

**parameter**:

* `inst`: UART instance

**Return Value**:

* On success: Number of bytes that can be read
* `-1`: Invalid parameter
* `-2`: IOCTL error

---

### `int drv_uart_send_break(drv_uart_inst_t* inst);`

**Function**: Send an interrupt signal on the UART TX line. Force the TX line low for a period of time for special event signaling (such as LIN sync, attention request, soft reset, etc.).

**parameter**:

* `inst`: UART instance

**Return Value**:

* `0`: Success
* `-1`: The instance is invalid or not open
* `-2`: IOCTL call failed

---

### `int drv_uart_set_config(drv_uart_inst_t* inst, struct uart_configure* cfg);`

**Function**: Set UART configuration.

**parameter**:

* `inst`: UART instance
* `cfg`: configuration structure

**Return Value**:

* `0`: Success
* `-1`: Invalid parameter
* `-2`: IOCTL error

**Note**: This function cannot modify `bufsz`, please use `drv_uart_configure_buffer_size` to modify the buffer size.

---

### `int drv_uart_get_config(drv_uart_inst_t* inst, struct uart_configure* cfg);`

**Function**: Get the current UART configuration.

**parameter**:

* `inst`: UART instance
* `cfg`: Structure used to store configuration

**Return Value**:

* `0`: Success
* `-1`: Invalid parameter
* `-2`: IOCTL error

---

### `int drv_uart_configure_buffer_size(int id, uint16_t size);`

**Function**: Configure the buffer size of the specified UART device.

**parameter**:

* `id`: UART device ID (such as 0 means UART0, 1 means UART1, etc.)
* `size`: Buffer size to set

**Return Value**:

* `0`: Success
* `-1`: Invalid UART ID or wrong status
* `-2`: Device not found or configuration failed

**Note**: This function should be called before creating the instance.

---

### `int drv_uart_get_id(drv_uart_inst_t *inst);`

**Function**: Get the ID of the UART instance.

**parameter**:

* `inst`: UART instance

**Return Value**:

* When valid: UART ID
* When invalid: `-1`

---

### `int drv_uart_get_fd(drv_uart_inst_t *inst);`

**Function**: Get the file descriptor of the UART instance.

**parameter**:

* `inst`: UART instance

**Return Value**:

* When valid: file descriptor
* When invalid: `-1`

---

## Example

Please refer to `src/rtsmart/libs/testcases/rtsmart_hal/test_uart.c`

---

## Things to note

1. The `bufsz` field of `struct uart_configure` can only be modified through the `drv_uart_configure_buffer_size` interface, and `bufsz` cannot be modified using `drv_uart_set_config`. The general approach is to first call `drv_uart_get_config` to obtain the current configuration, modify other parameters except `bufsz`, and then call `drv_uart_set_config`.

1. `drv_uart_configure_buffer_size` must be called before creating the instance.

1. The invert field is not supported on K230.