SPI API
################################################################################

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

SPI API は、同期転送と DMA 転送の両方を提供します。
複数タスクから利用する場合は `lock()` / `unlock()` でトランザクションを保護します。

xmc::spi::getPreferredFrequency
================================================================================

.. code-block:: cpp

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

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

`device` には接続先デバイス種別を指定します。
戻り値は、そのデバイスでの使用を想定した推奨 SPI クロックです。

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

xmc::spi::init
--------------------------------------------------------------------------------

.. code-block:: cpp

	XmcStatus xmc::spi::init();

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

SPI API を利用する前に呼び出します。
戻り値は `XmcStatus` で、成功時は `XMC_OK` です。

xmc::spi::deinit
--------------------------------------------------------------------------------

.. code-block:: cpp

	void xmc::spi::deinit();

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

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

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

xmc::spi::tryLock
--------------------------------------------------------------------------------

.. code-block:: cpp

	bool xmc::spi::tryLock();

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

取得成功時は `true`、取得失敗時は `false` を返します。

xmc::spi::lock
--------------------------------------------------------------------------------

.. code-block:: cpp

	XmcStatus xmc::spi::lock();

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

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

xmc::spi::unlock
--------------------------------------------------------------------------------

.. code-block:: cpp

	XmcStatus xmc::spi::unlock();

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

戻り値は `XmcStatus` です。

通信設定
================================================================================

xmc::spi::setBaudrate
--------------------------------------------------------------------------------

.. code-block:: cpp

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

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

`baudrate` には希望するクロック周波数を指定します。
戻り値は `XmcStatus` です。

同期転送
================================================================================

xmc::spi::writeBlocking
--------------------------------------------------------------------------------

.. code-block:: cpp

	XmcStatus xmc::spi::writeBlocking(const uint8_t *data, uint32_t size);

SPI へブロッキング書き込みを行います。

`data` は送信バッファ先頭、`size` は送信バイト数です。
戻り値は `XmcStatus` です。

xmc::spi::readBlocking
--------------------------------------------------------------------------------

.. code-block:: cpp

	XmcStatus xmc::spi::readBlocking(uint8_t repeated_byte, uint8_t *data, uint32_t size);

読み出し中に `repeated_byte` を送信しながら、`size` バイト受信します。

`data` は受信バッファ先頭、`size` は受信バイト数です。
戻り値は `XmcStatus` です。

DMA 転送
================================================================================

xmc::spi::dmaWriteStart
--------------------------------------------------------------------------------

.. code-block:: cpp

	XmcStatus xmc::spi::dmaWriteStart(const xmc::dma::Config *cfg, int csPin);

DMA 書き込みを開始します。関数は転送完了を待たずに返ります。

`cfg` の主なメンバー:

- `ptr`: 転送元バッファ
- `elementSize`: 要素サイズ [byte]
- `length`: 要素数

`csPin` に 0 以上を指定すると、転送中のみ CS を自動制御します。

戻り値は `XmcStatus` です。転送開始に成功した時点で返るため、完了確認には `dmaComplete()` または `dmaIsBusy()` を使用します。

xmc::spi::dmaComplete
--------------------------------------------------------------------------------

.. code-block:: cpp

	XmcStatus xmc::spi::dmaComplete();

進行中 DMA 転送の完了を待機します。

戻り値は `XmcStatus` です。DMA 転送と必要な CS 解放処理が完了した時点で返ります。

xmc::spi::dmaIsBusy
--------------------------------------------------------------------------------

.. code-block:: cpp

	bool xmc::spi::dmaIsBusy();

DMA 転送中かどうかを返します。

転送中は `true`、アイドル状態では `false` を返します。