UART
======
概述
-----
WQ7036 芯片中共有 4 个 UART（Universal Asynchronous Receiver/Transmitter，通用异步收发传输器），均位于应用子系统，可被 DMA 访问或 CPU 直接访问。

UART 的架构如下图所示。

.. image:: ../../../_static/UART_architecture.png
    :align: center

.. centered:: UART 架构图


UART 以字符为导向，不要求在发送数据的同时发送时钟，可实现设备间的异步通信。UART 通信要求发送端和接收端的速率、停止位宽度、奇偶校验位相同。

UART 接口信号包含：

- TXD：待发送的串行数据
- RXD：已接收的串行数据
- RTS（Request To Send）：请求发送的流控信号
- CTS（Clear To Send）：允许发送的流控信号

UART 发送数据的流程如下：

1.	UART 的待发送数据来自 UART 内部存储（UART MEM）。数据可通过 CPU 直接写入 UART MEM，或通过 DMA 从其他位置搬运至 UART MEM。
2.	UART 寄存器配置 UART 控制器（UART CTRL）的工作模式。UART CTRL 读取 UART MEM 获得待发送数据。
3.	控制器按 UART 相关协议将待发送数据转换成串行数据发送到 TXD 端。

UART 接收数据的流程如下：

1.	UART 收到串行数据 RXD。
2.	UART CTRL 按 UART 协议转换成并行的 byte 数据，并将数据存放于 UART MEM。
3.	CPU 直接读取数据或者通过 DMA 将数据搬运至其他 MEM。

功能特性
------------------
四个 UART 的 Tx/Rx 共享 2 KB x 8 bits UART MEM，且每个 UART 的 DMA 可选择。UART 的数据位宽度可配置成 5/6/7/8 bits，停止位宽度可以配置为 1/1.5/2/3/4 bits。

UART 支持：

- 全双工异步通信
- 收/发波特率可配
- 奇偶校验
- CTS/RTS 硬件流控
- XON/XOFF 软件流控
- RS232、RS485 和 IrDA 协议
- Loopback 回环测试

工作模式
------------
UART TXD/RXD 连接同一个 PAD，TXD 信号经过 GPIO matrix 为输出信号。

寄存器 **uart_share_io_en** 可以配置 UART 处于单线或双线模式：

- **uart_share_io_en** = **1** ：UART 处于单线模式（半双工）。
- **uart_share_io_en**  = **0** ：UART 处于双线模式（全双工）。

当 UART 处于单线模式时，电路产生输出使能 **uart_pad_share_oen** 用于控制数据传输方向。

- 配置寄存器 **force_share_oen_low** ：此时 **uart_pad_share_oen** 一直为 **0** ，接收数据。
- 配置寄存器 **force_share_oen_high** ：此时 **uart_pad_share_oen** 一直为 **1** ，发送数据。

在单线模式下，当 Rx 处于输入状态且有数据待发送时，则需等待 Rx 接收完当前字节的数据，再将传输方向由输入转为输出，由 Tx 完成数据发送。此时，RXD 信号被强制置为高电平，后续若需要继续接受数据，需要再次修改传输方向。

资源依赖
---------------
- UART
- DMA （DMA 传输模式）

用法流程
-------------


- 初始化 :cpp:func:`wq_uart_init`

.. code-block:: c
   :linenos:

    /** 选择要初始化的端口 1 */
    wq_uart_init(WQ_UART_PORT_1);

- 配置 :cpp:type:`wq_uart_configuration_t`  :cpp:type:`wq_uart_gpio_configuration_t`  :cpp:func:`wq_uart_register_rx_callback`

.. code-block:: c
   :linenos:

    /** 定义并初始化配置变量 */
    wq_uart_configuration_t uart_cfg;
    uart_cfg.baud_rate = 2000000;
    uart_cfg.data_bits = WQ_UART_DATA_BITS_8;
    uart_cfg.parity = WQ_UART_PARITY_NONE;
    uart_cfg.stop_bits = WQ_UART_STOP_BITS_1;

    wq_uart_gpio_configuration_t pin_cfg;
    pin_cfg.tx = 73;
    pin_cfg.rx = 74;

    /** 配置 rx callback func*/
    wq_uart_register_rx_callback(WQ_UART_PORT_1, rx_buf, BUF_SIZE,
                                 uart1_rx_callback);


- 打开串口  :cpp:func:`wq_uart_open`

.. code-block:: c
   :linenos:

    /** 打开串口 */
    wq_uart_open(WQ_UART_PORT_1, &uart_cfg, &pin_cfg);

- 读写内容 :cpp:func:`wq_uart_puts` :cpp:func:`wq_uart_write_buffer` :cpp:func:`wq_uart_read`

.. code-block:: c
   :linenos:

    /** 写字符串 */
    wq_uart_puts(WQ_UART_PORT_1, str_1);

    /** 写 buffer */
    wq_uart_write_buffer(WQ_UART_PORT_1,buffer,buf_len);

    /** 读 buffer */
    wq_uart_read(WQ_UART_PORT_1,buffer,buf_len);

- 关闭 :cpp:func:`wq_uart_close`

.. code-block:: c
   :linenos:

    /** 关闭串口 */
    wq_uart_close(WQ_UART_PORT_1);

- 注销 :cpp:func:`wq_uart_deinit`

.. code-block:: c
   :linenos:

    /** 注销串口 */
    wq_uart_deinit(WQ_UART_PORT_1);

参考示例
-----------

::

    /examples/uart_demo/

API 介绍
---------------

.. doxygenfile:: wq_uart.h