Flash API
################################################################################

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

Flash API は、内蔵フラッシュメモリへのデータ書き込みおよびメモリマップアクセスを提供する低レベル API です。

`xmc::flash::init()` で初期化した後、`write()` でデータを書き込み、`mmap()` / `munmap()` でメモリマップ読み出しを行います。

情報取得
================================================================================

xmc::flash::getSectorSize
--------------------------------------------------------------------------------

.. code-block:: cpp

	size_t xmc::flash::getSectorSize();

フラッシュメモリのセクターサイズをバイト単位で返します。
書き込み・消去の最小単位として使用します。

xmc::flash::getRange
--------------------------------------------------------------------------------

.. code-block:: cpp

	void xmc::flash::getRange(size_t *base, size_t *size);

フラッシュメモリの読み可能な領域のベースオフセットとサイズを取得します。

`base` が `nullptr` でない場合はベースオフセット [バイト] を書き込み、
`size` が `nullptr` でない場合は領域全体のサイズ [バイト] を書き込みます。

RP2350 版ではプログラムデータを含む Flash 領域全体の空間を返します。
書き込みを行う場合、通常は使用されていない末尾から使用します。

ESP32S3 版では SPIFFS パーティションの領域を返します。
書き込みを行うと、既存のファイルシステムは破壊されます。

書き込み・マップ
================================================================================

xmc::flash::erase
--------------------------------------------------------------------------------

.. code-block:: cpp

	XmcStatus xmc::flash::erase(uint32_t offset, size_t size);

フラッシュメモリの指定領域を消去します。

`offset` には消去開始オフセット [バイト] を指定します。
`size` には消去するバイト数を指定します。実際にはセクターサイズに切り上げて消去されます。

戻り値は `XmcStatus` で、成功時は `XMC_OK` です。

xmc::flash::write
--------------------------------------------------------------------------------

.. code-block:: cpp

	XmcStatus xmc::flash::write(uint32_t offset, const void *data, size_t size);

フラッシュメモリにデータを書き込みます。

`offset` には書き込み先のオフセット [バイト] を指定します。
`data` には書き込むデータのポインタを指定します。
`size` には書き込むバイト数を指定します。

書き込み前に対象領域を消去する場合は `erase()` を別途呼び出してください。

戻り値は `XmcStatus` で、成功時は `XMC_OK` です。

xmc::flash::mmap
--------------------------------------------------------------------------------

.. code-block:: cpp

	XmcStatus xmc::flash::mmap(uint32_t offset, size_t size, void **handle, const uint8_t **outPtr);

フラッシュメモリの指定領域をメモリマップします。

`offset` にはマップ開始オフセット [バイト] を指定します。
`size` にはマップするサイズ [バイト] を指定します。
`handle` にはマップ解除時に `munmap()` へ渡すハンドルが書き込まれます。
`outPtr` にはマップ後のアドレスが書き込まれます。

戻り値は `XmcStatus` で、成功時は `XMC_OK` です。

xmc::flash::munmap
--------------------------------------------------------------------------------

.. code-block:: cpp

	void xmc::flash::munmap(void *handle);

`mmap()` でマップした領域を解除します。
`handle` には `mmap()` で取得したハンドルを指定します。