I2C API
################################################################################

概要
================================================================================

I2C API は、I2C デバイスへの同期アクセスを行うための低レベル API です。
複数タスクから安全に利用するため、アクセス時は `lock()` / `unlock()` でトランザクションを保護します。

初期化
================================================================================

xmc::i2c::getPreferredFrequency
--------------------------------------------------------------------------------

.. code-block:: cpp

	uint32_t xmc::i2c::getPreferredFrequency(Chipset device);

デバイス種別に応じた推奨 I2C クロック周波数 [Hz] を返します。

`device` には接続先デバイス種別を指定します。
戻り値は、そのデバイスで安全に使用できることを想定した推奨クロック周波数です。

xmc::i2c::init
--------------------------------------------------------------------------------

.. code-block:: cpp

	XmcStatus xmc::i2c::init();

I2C ペリフェラルを初期化します。

I2C API を使う前に一度だけ呼び出します。
戻り値は `XmcStatus` で、成功時は `XMC_OK` です。

xmc::i2c::deinit
--------------------------------------------------------------------------------

.. code-block:: cpp

	void xmc::i2c::deinit();

I2C ペリフェラルを終了します。

以後 I2C を使用しない場合に呼び出します。戻り値はありません。

トランザクション制御
================================================================================

xmc::i2c::tryLock
--------------------------------------------------------------------------------

.. code-block:: cpp

	bool xmc::i2c::tryLock();

非ブロッキングで I2C ロック取得を試みます。

ロック取得に成功した場合は `true`、他の処理が使用中で取得できなかった場合は `false` を返します。

xmc::i2c::lock
--------------------------------------------------------------------------------

.. code-block:: cpp

	XmcStatus xmc::i2c::lock();

ロックが取得できるまで待機してから I2C トランザクションを開始します。

戻り値は `XmcStatus` です。通常は `XMC_OK` が返ります。

xmc::i2c::unlock
--------------------------------------------------------------------------------

.. code-block:: cpp

	XmcStatus xmc::i2c::unlock();

I2C トランザクションを終了します。

`lock()` または `tryLock()` で開始したトランザクションの終端として呼び出します。
戻り値は `XmcStatus` です。

通信設定とバス復旧
================================================================================

xmc::i2c::setBaudrate
--------------------------------------------------------------------------------

.. code-block:: cpp

	XmcStatus xmc::i2c::setBaudrate(uint32_t baudrate);

I2C 通信速度 [Hz] を設定します。

`baudrate` には希望するクロック周波数を指定します。
戻り値は `XmcStatus` で、プラットフォームが設定に失敗した場合はエラーコードを返します。

xmc::i2c::resetBus
--------------------------------------------------------------------------------

.. code-block:: cpp

	XmcStatus xmc::i2c::resetBus();

SCL トグルによりスタックしたバスを復旧します。

スレーブが SDA を保持したままになった場合など、異常状態からの回復に使用します。
戻り値は `XmcStatus` です。

データ転送
================================================================================

xmc::i2c::writeBlocking
--------------------------------------------------------------------------------

.. code-block:: cpp

	XmcStatus xmc::i2c::writeBlocking(uint8_t devAddr, const uint8_t *data, uint32_t size, bool nostop);

I2C デバイスへデータを書き込みます。
`devAddr` は 7bit アドレスです。

`data` は送信するバッファ先頭アドレス、`size` は送信バイト数です。
`nostop` を `true` にすると STOP 条件を出さずに終了するため、続けて repeated start を伴う操作を行えます。

戻り値は `XmcStatus` です。

xmc::i2c::readBlocking
--------------------------------------------------------------------------------

.. code-block:: cpp

	XmcStatus xmc::i2c::readBlocking(uint8_t devAddr, uint8_t *data, uint32_t size, bool nostop);

I2C デバイスからデータを読み出します。

`nostop` を `true` にすると STOP 条件を出さないため、
レジスタアドレス書き込み後の連続読み出しなどに利用できます。

`data` は受信データの格納先、`size` は受信バイト数です。
戻り値は `XmcStatus` です。