I2C
========

概述
--------
I2C 总线（Inter-Integrated Circuit）是半双工串行总线，只需 SDA（serial data line，串行数据）和 SCL（serial clock line，串行时钟线）两根线即可在总线上完成器件之间的数据传输。

I2C master 产生时钟 SCL，启动总线开始数据传输。既可以发送数据，也可以从 I2C slave 读取数据。各 I2C 设备在总线上的连接示例如下图所示，接口电路为开漏输出。

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

.. centered:: I2C 设备在总线上的连接示例

发送到 SDA 线上的每个字节必须为 8 位。每次传输可以发送的字节数不限，首先传输的是数据的最高有效位（MSB），每个字节后必须跟一个响应位（ACK）。

I2C 完整的数据传输协议如下图所示。

.. wavedrom::

    {
        signal: [
            {name: 'SDA', wave: '1.0...3...3.|.3...4...5...1..0.6...6.|.6...7...10..1', data: 'A6 . A0 R/W ACK D7 . D0 ACK', period: 0.5},
            {name: 'SCL', wave: '1...0..1.0.1|0.1.0.1.0.1.0......1.0.1|0.1.0.1.0..1..', period: 0.5}
        ],
        config: {skin: 'narrow'}
    }

.. centered:: I2C 完整的数据传输协议

I2C 主机写数据的流程如下：

1.	主机在检测到总线为“空闲状态”（即 SDA、SCL 线均为高电平）时，向从机发送启动信号 S，开始通信。
2.	主机发送一个命令字节。该字节由 7 位的待寻址的从机地址和 1 位读写控制位 R/W 组成（主机写数据时，R/W=0）。
3.	指定从机收到命令字节后向主机反馈应答信号 ACK。
4.	主机收到从机的应答信号后开始发送第一个字节的数据。
5.	从机收到数据后返回一个应答信号 ACK。
6.	主机收到应答信号后再发送下一个字节的数据。
7.	主机发送最后一个数据字节并收到从机的反馈后，向从机发送停止信号 P 结束本次通信并释放总线。


.. admonition:: 说明

   某些从机会把从机地址之后的第一个数据当作从机寄存器的起始地址。即，主机会从这个寄存器地址开始往后写待发送的数据。

   如果 I2C master 需要继续在总线上通讯，则会产生 Restart 条件，并寻址另一个 slave。最后等待所有数据传输完成后，I2C master 再产生 Stop condition。

I2C 主机读数据的流程如下：

1.	主机发送启动信号后，发送命令字节（主机读数据时，R/W=1）。
2.	对应的从机收到地址后，返回一个应答信号并向主机发送数据。
3.	主机收到数据后向从机发送 ACK 反馈。
4.	从机收到应答信号后再向主机发送下一个字节。
5.	主机完成接收数据后，向从机发送 NACK 信号，从机收到后停止发送数据。
6.	主机再发送一个停止信号 P，释放总线结束通信。

功能特性
-------------------
WQ7036 内部有两个 I2C master 控制器，均位于应用子系统。I2C master 遵循标准 I2C 协议。

I2C master 支持如下特性：

- 半双工传输模式。
- 100 kbps 标准模式、400 kbps 快速模式及其他模式。
- 16x8 bit Tx FIFO 和 16x8 bit Rx FIFO。
- 多从机 7 位寻址。
- 可配置的数据过滤器。
- 可配置字符字节序列（MSB、LSB）。
- 多数据传输。

工作模式
----------
I2C master 模块既可以作为 Tx 发送数据，又可以作为 Rx 接收数据，I2C master 收发数据流程如下图所示。

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

.. centered:: I2C 收发流程

I2C master 作 Tx 时，数据传输流程如下：

1.	APB 总线配置相关寄存器，将待发送数据写入 Tx FIFO。
2.	I2C master 主控制器将从 Tx FIFO 中读取的数据根据 I2C 协议发送到 I2C 总线，同时产生时钟信号 SCL。
3.	主控制器（I2C master main control）根据 Tx FIFO 的中断信息判断何时可以写 Tx FIFO。
4.	根据 i2c_trans_done 信号来判断所有数据传输是否完成。

I2C master 作 Rx 时，数据传输流程如下：

1.	APB 总线配置相关寄存器。
2.	I2C master 主控制器接收 I2C 总线上的 SDA 数据，写入 Rx FIFO，同时主控制器会产生 SCL 时钟信号送到 I2C 总线上。
3.	主控制器根据 Rx FIFO 的中断信息判断何时读取 Rx FIFO，将收到的数读到 APB 总线。


资源依赖
---------
- I2C
- GPIO
- IRQ

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

- 初始化 i2c :c:func:`wq_i2c_init`
- 配置并打开 i2c :c:func:`wq_i2c_open`
- poll 方式读写 :c:func:`wq_i2c_write_poll` :c:func:`wq_i2c_read_poll` :c:func:`wq_i2c_write_read_poll`
- 中断方式读写 :c:func:`wq_i2c_write` :c:func:`wq_i2c_read` :c:func:`wq_i2c_write_read`
- 关闭 i2c :c:func:`wq_i2c_close`
- 注销 i2c :c:func:`wq_i2c_deinit`


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

    examples/i2c_demo

示例说明
^^^^^^^^^^^
- 本示例使用 WQ 开发板和 EEPROM AT24CXX，通过 i2c 建立通信连接。

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

.. centered:: I2C Demo 流程图


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

.. doxygenfile:: wq_i2c.h