.. _flash-api-lib:

flash api库
======================

简介
-------------------------

SPV1x的flash api库，提供擦写程序flash的相关功能。该库对内置flash和外挂程序flash的场景都能适用。

相关的数据结构说明
-------------------------

.. c:enum:: spi_baud_t

  操作flash时，spi的时钟频率配置。

  - *Spi_Baud_1M*: 配置spi的SCK频率为1MHz。
  - *Spi_Baud_2M*: 配置spi的SCK频率为2MHz。
  - *Spi_Baud_4M*: 配置spi的SCK频率为4MHz。
  - *Spi_Baud_8M*: 配置spi的SCK频率为8MHz。
  - *Spi_Baud_12M*: 配置spi的SCK频率为12MHz。
  - *Spi_Baud_16M*: 配置spi的SCK频率为16MHz。
  - *Spi_Baud_24M*: 配置spi的SCK频率为24MHz。
  - *Spi_Baud_48M*: 配置spi的SCK频率为48MHz。

.. c:enum:: spi_chx_t

  操作flash时，spi的通道选择。

  - *Spi_Ch0*: 选择SPI0。
  - *Spi_Ch1*: 选择SPI1。

API说明
-------------------------

.. c:function:: int32_t flash_op_init(spi_chx_t chx,spi_baud_t spi_baud)

  flash操作初始化。

  :param chx: 选择用于操作flash的spi通道。
  :param spi_baud: 选择spi的SCK信号频率。
  :returns: 返回0表示成功；其他值表示错误。

.. c:function:: int32_t flash_op_erase(uint32_t addr,uint32_t size)

  对flash进行擦除。

  :param addr: 擦除地址，需要4K对齐。
  :param size: 擦除的区域大小，需要是4K的整数倍。
  :returns: 返回0表示成功；其他值表示错误。

.. c:function:: int32_t flash_op_write(uint32_t addr,uint8_t *pbuf,uint32_t len)

  对flash进行写入。

  :param addr: 写入地址，无对齐要求。
  :param pbuf: 指向写入的数据，数据必须在SRAM中。
  :param len: 要写入的数据长度，最小为1byte。
  :returns: 返回0表示成功；其他值表示错误。

.. c:function:: int32_t flash_op_read_id(uint32_t *id_out)

  读取flash ID。ID格式如下：
   * 最高字节：固定为0x00；
   * 次高字节：Manufacturer ID；
   * 次低字节：Memory Type ID；
   * 最低字节：Capacity ID。

  :param id_out: 指向用于容纳ID的变量。
  :returns: 返回0表示成功；其他值表示错误。

.. c:function:: void flash_op_deinit(void)

  flash操作去初始化。

  :param : 无。
  :returns: 无。

flash api库使用方法
-------------------------

 1. 包含头文件： `#include "flash_api.h"` 。
 2. 调用 `flash_op_init(chx，spi_baud)` ，初始化flash api库。chx选择spi通道，spi_baud选择spi速率。
 3. 调用 `flash_op_erase(addr,size)` ，擦除flash区域，如果后续要写入的区域已经是擦除过的，则不用再擦除。flash以4K扇区为擦除单位，所以addr需要对齐到4096，size需要是4096的整数倍。
 4. 调用 `flash_op_write(addr,pbuf,len)` ，写入数据到flash。写入时没有地址对齐要求，len最小可以是1个byte。
 5. 调用 `flash_op_deinit()` ，去初始化flash api库。

 .. note::

  建议程序对flash api的返回值进行检查。常见的错误码列表如下：
   * 0：操作成功。
   * -1：初始化SPI时，等待NORC空闲过程超时。
   * -2：SPI发送数据超时。
   * -3：SPI接收数据超时。
   * -4：等待flash空闲过程超时。
   * -5：SPI通道参数错误，参数不在 `spi_chx_t` 中。
   * -6：SPI速度参数错误，参数不在 `spi_baud_t` 中。
   * -7：SPI通道参数不支持，flash接线不支持当前请求的SPI通道。

注意事项
-------------------------

 1. flash api库和其他场景库（播放库/录音库/识别库）存在资源重叠。在使用flash api库的时候，需要先将其他场景库去初始化。待flash api库使用完成并去初始化后，再重新初始化其他场景库。
 2. 如果程序flash接在GPIO00~GPIO03上，则只能选 `Spi_Ch0` 。如果程序flash接在GPIO10~GPIO13上，则 `Spi_Ch0` 和 `Spi_Ch1` 都可选。
 3. flash在擦写过程中，CPU会停止其他代码的执行，直到擦写过程完成。
 4. 如果要从flash读取数据，直接使用NORC的地址空间访问即可。比如要访问flash地址0x1234处存储的int型数据，则按如下代码访问：

  .. code-block:: c

   int data = *((int *)(NORC_DATA_UNCACHE_SINGLE_ADDR(0x1234)));

 5. flash擦写寿命有限，软件可以做磨损均衡，以减少扇区的擦写频率。