Heap API
################################################################################

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

Heap API は、プラットフォーム依存の RAM 特性を考慮した動的メモリ確保を行うための API です。

この API は C リンケージで提供されるため、C/C++ のどちらからでも利用できます。

型
================================================================================

XmcHeapCap
--------------------------------------------------------------------------------

RAM の特性を指定するビットフラグ列挙型です。

.. csv-table:: XmcHeapCap の値
	 :header: "値", "説明"

	 "XMC_HEAP_CAP_NONE", "特別な特性を要求しない。"
	 "XMC_HEAP_CAP_DMA", "DMA 可能な RAM を要求する。"
	 "XMC_HEAP_CAP_SPIRAM", "SPIRAM を要求する。"

複数の特性を要求する場合は OR (`|`) で組み合わせます。
割り当て可否と選択されるメモリ領域はプラットフォーム実装に依存します。

グローバル関数
================================================================================

xmcHasSpiRam
--------------------------------------------------------------------------------

.. code-block:: cpp

	bool xmcHasSpiRam();

システムに SPIRAM (PSRAM) が搭載されているかどうかを返します。

SPIRAM が利用可能であれば `true` を、利用不可であれば `false` を返します。

xmcMalloc
--------------------------------------------------------------------------------

.. code-block:: cpp

	void *xmcMalloc(size_t size, XmcHeapCap caps);

指定サイズのメモリ領域を確保します。

`size` には確保バイト数、`caps` には要求する RAM 特性を指定します。
確保に成功した場合は確保領域へのポインタを返し、失敗した場合は `NULL` を返します。

ESP32S3 版では、第二引数に XMC_HEAP_CAP_SPIRAM を指定すると PSRAM に確保されます。
これは SRAM の不足を回避するのに有効です。

RP2350 版では第二引数は無視され、常に SRAM に確保されます。

xmcFree
--------------------------------------------------------------------------------

.. code-block:: cpp

	void xmcFree(void *ptr);

`xmcMalloc()` で確保したメモリ領域を解放します。

`ptr` には解放対象のポインタを指定します。