.. _eeprom_hal:

EEPROM HAL
==========================

概述
------

- EEPROM HAL(硬件抽象层)组件为 HPMicro SDK 中访问各种类型的 EEPROM 存储设备提供统一接口。它抽象了底层硬件差异,为应用程序提供一致的 API 来读写 EEPROM 数据

    - eeprom hal 特点

        - 支持三种驱动方式：
            - 基于 flash 模拟 eeprom
            - i2c eeprom
            - spi eeprom

        - 多实例支持
            - HAL 层通过注册的方式支持多个 eeprom 设备实例,通过注册名统一管理
            - 每个实例可以独立配置不同的硬件接口和参数

        - 统一接口调用
            - 提供统一的读写接口,屏蔽底层实现差异;可以通过 hal 层调用 API,同时也可以直接调用底层驱动 API(需要自己配置参数)

        - 页感知写入
            - 底层提供防回卷功能,自动处理页边界跨越

        - 状态轮询
            - 提供写入完成状态轮询接口,确保数据写入成功

架构描述
----------------------
- eeprom hal 层架构图

    .. _architecture_diagram:

    .. rst-class:: center-block

    .. raw:: html

        <pre>
        +----------------------------------------------------------+
        |                          应用层                          |
        |              (使用 EEPROM 存储的用户应用)                 |
        +----------------------------------------------------------+
                                |
                                | 统一 API
                                |
        +----------------------------------------------------------+
        |                    HAL 层 (eeprom_hal)                    |
        |      - 设备注册与管理                                      |
        |      - 设备发现(按名称查找)                                |
        |      - 统一接口(read/write/init/deinit)                   |
        +----------------------------------------------------------+
                                |
                +----------------+----------------+
                |                |                |
                |                |                |
        +------------------+ +--------------+ +------------------+
        |    I2C 设备      | |   SPI 设备   | |   Flash 模拟     |
        |      驱动层      | |    驱动层    | |     驱动层       |
        |                  | |              | |                  |
        | - I2C 协议       | | - SPI 协议   | | - XPI Flash API  |
        | - AT24Cxx 系列   | | - AT25xxx    | | - E2P 模拟库     |
        +------------------+ +--------------+ +------------------+
                |                |                |
                |                |                |
                |                |                |
        +----------------------------------------------------------+
        |                      硬件抽象层                          |
        |             (I2C 驱动、SPI 驱动、XPI 驱动)               |
        +----------------------------------------------------------+
                |                |                |
                |                |                |
                |                |                |
        +----------------------------------------------------------+
        |                        硬件层                            |
        |               (I2C EEPROM、SPI EEPROM、NOR Flash)          |
        +----------------------------------------------------------+

相关宏定义以及枚举和结构体介绍
------------------------------

- 宏定义

    - 定义了用于配置的 eeprom 类型和允许注册的最大实例数量(可扩展)

        .. code-block:: c

            /**
            * @brief eeprom 支持驱动类型
            * @note 用于注册时指定 eeprom 设备类型(可扩展)
            */
            #define EEPROM_FLAG_EMULATION_XPI 0x0
            #define EEPROM_FLAG_DEVICE_I2C    0x4
            #define EEPROM_FLAG_DEVICE_SPI    0x5

            /**
            * @brief eeprom 允许注册最大数量
            * @note 用于初始化注册 eeprom 的数组大小(可扩展)
            */
            #define EEPROM_MAX_DEVICE_CNT 32

            /**
            * @brief eeprom spi 指令
            */
            #define E2P_SPI_INSTRUCTION_WREN 0x06  /* 写使能 */
            #define E2P_SPI_INSTRUCTION_RDSR 0x05  /* 读状态寄存器 */
            #define E2P_SPI_INSTRUCTION_WRDI 0x04  /* 写禁止 */
            #define E2P_SPI_INSTRUCTION_READ 0x03  /* 读数据 */
            #define E2P_SPI_INSTRUCTION_WRITE 0x02  /* 写数据 */
            #define E2P_SPI_INSTRUCTION_WRSR 0x01  /* 写状态寄存器 */


- 枚举介绍

    - eeprom 支持的实体设备,包括 i2c 和 spi(list 中参数由数据手册获得,list 可扩展)

        .. code-block:: text

            支持的 i2c eeprom 设备:

            +--------------------+-----------------------+------------+----------------+------------------------------------------+------------------------------------------+
            | 公司               | 型号 (Series)         | 存储容量    | 页大小 (Bytes)  | 宏定义 (Macro)                            | 备注 (Notes)                             |
            +====================+=======================+============+================+==========================================+==========================================+
            | Microchip (Atmel)  | AT24C01 / AT24C02     | 1Kbit/2Kbit| 8              | E2P_DEVICE_AT24C01, E2P_DEVICE_AT24C02    | 标准 8 位地址                            |
            |                    +-----------------------+------------+----------------+------------------------------------------+------------------------------------------+
            |                    | 24xx01 / 24xx02       | 1Kbit/2Kbit| 8              | E2P_DEVICE_24xx01, E2P_DEVICE_24xx02      | 标准 8 位地址                            |
            |                    +-----------------------+------------+----------------+------------------------------------------+------------------------------------------+
            |                    | AT24C04 / 24xx04      | 4Kbit      | 16             | E2P_DEVICE_AT24C04, E2P_DEVICE_24xx04     | 9位地址，A8 在设备地址中                 |
            |                    +-----------------------+------------+----------------+------------------------------------------+------------------------------------------+
            |                    | AT24C08 / 24xx08      | 8Kbit      | 16             | E2P_DEVICE_AT24C08, E2P_DEVICE_24xx08     | 10位地址，A9, A8 在设备地址中            |
            |                    +-----------------------+------------+----------------+------------------------------------------+------------------------------------------+
            |                    | AT24C16 / 24xx16      | 16Kbit     | 16             | E2P_DEVICE_AT24C16, E2P_DEVICE_24xx16     | 11位地址，A10, A9, A8 在设备地址中       |
            |                    +-----------------------+------------+----------------+------------------------------------------+------------------------------------------+
            |                    | AT24C32               | 32Kbit     | 32             | E2P_DEVICE_AT24C32                        | 2字节地址                                |
            |                    +-----------------------+------------+----------------+------------------------------------------+------------------------------------------+
            |                    | AT24C64 / 24xxC64     | 64Kbit     | 32             | E2P_DEVICE_AT24C64, E2P_DEVICE_24xxC64     | 2字节地址                                |
            |                    +-----------------------+------------+----------------+------------------------------------------+------------------------------------------+
            |                    | AT24C128 / 24xx128    | 128Kbit    | 64             | E2P_DEVICE_AT24C128, E2P_DEVICE_24xx128    | 2字节地址                                |
            |                    +-----------------------+------------+----------------+------------------------------------------+------------------------------------------+
            |                    | AT24C256 / 24xx256    | 256Kbit    | 64             | E2P_DEVICE_AT24C256, E2P_DEVICE_24xx256    | 2字节地址                                |
            |                    +-----------------------+------------+----------------+------------------------------------------+------------------------------------------+
            |                    | AT24C512 / 24xx512    | 512Kbit    | 128            | E2P_DEVICE_AT24C512, E2P_DEVICE_24xx512    | 2字节地址                                |
            |                    +-----------------------+------------+----------------+------------------------------------------+------------------------------------------+
            |                    | AT24CM01              | 1Mbit      | 256            | E2P_DEVICE_AT24CM01                      | 17位地址，A16 在设备地址中               |
            |                    +-----------------------+------------+----------------+------------------------------------------+------------------------------------------+
            |                    | AT24CM02              | 2Mbit      | 256            | E2P_DEVICE_AT24CM02                      | 18位地址，A17, A16 在设备地址中          |
            +--------------------+-----------------------+------------+----------------+------------------------------------------+------------------------------------------+
            | ON Semi            | NV24C02               | 2Kbit      | 16              | E2P_DEVICE_NV24C02                       | 标准 8 位地址                            |
            |                    +-----------------------+------------+----------------+------------------------------------------+------------------------------------------+
            |                    | NV24C04               | 4Kbit      | 16             | E2P_DEVICE_NV24C04                       | 9位地址，A8 在设备地址中                 |
            |                    +-----------------------+------------+----------------+------------------------------------------+------------------------------------------+
            |                    | NV24C08               | 8Kbit      | 16             | E2P_DEVICE_NV24C08                       | 10位地址，A9, A8 在设备地址中            |
            |                    +-----------------------+------------+----------------+------------------------------------------+------------------------------------------+
            |                    | NV24C16               | 16Kbit     | 16             | E2P_DEVICE_NV24C16                       | 11位地址，A10, A9, A8 在设备地址中       |
            |                    +-----------------------+------------+----------------+------------------------------------------+------------------------------------------+
            |                    | NV24C32               | 32Kbit     | 32             | E2P_DEVICE_NV24C32                       | 2字节地址                                |
            |                    +-----------------------+------------+----------------+------------------------------------------+------------------------------------------+
            |                    | NV24C64               | 64Kbit     | 32             | E2P_DEVICE_NV24C64                       | 2字节地址                                |
            |                    +-----------------------+------------+----------------+------------------------------------------+------------------------------------------+
            |                    | NV24C128              | 128Kbit    | 64             | E2P_DEVICE_NV24C128                      | 2字节地址                                |
            |                    +-----------------------+------------+----------------+------------------------------------------+------------------------------------------+
            |                    | NV24C256              | 256Kbit    | 64             | E2P_DEVICE_NV24C256                      | 2字节地址                                |
            +--------------------+-----------------------+------------+----------------+------------------------------------------+------------------------------------------+
            | STMicroelectronics | M24C01 / M24C02       | 1Kbit/2Kbit| 16             | E2P_DEVICE_M24C01, E2P_DEVICE_M24C02    | 标准 8 位地址                            |
            |                    +-----------------------+------------+----------------+------------------------------------------+------------------------------------------+
            |                    | M24C04                | 4Kbit      | 16             | E2P_DEVICE_M24C04                        | 9位地址，A8 在设备地址中                 |
            |                    +-----------------------+------------+----------------+------------------------------------------+------------------------------------------+
            |                    | M24C08                | 8Kbit      | 16             | E2P_DEVICE_M24C08                        | 10位地址，A9, A8 在设备地址中            |
            |                    +-----------------------+------------+----------------+------------------------------------------+------------------------------------------+
            |                    | M24C16                | 16Kbit     | 16             | E2P_DEVICE_M24C16                        | 11位地址，A10, A9, A8 在设备地址中       |
            |                    +-----------------------+------------+----------------+------------------------------------------+------------------------------------------+
            |                    | M24C32                | 32Kbit     | 32             | E2P_DEVICE_M24C32                        | 2字节地址                                |
            |                    +-----------------------+------------+----------------+------------------------------------------+------------------------------------------+
            |                    | M24128                | 128Kbit    | 64             | E2P_DEVICE_M24128                        | 2字节地址                                |
            |                    +-----------------------+------------+----------------+------------------------------------------+------------------------------------------+
            |                    | M24256                | 256Kbit    | 64             | E2P_DEVICE_M24256                        | 2字节地址                                |
            |                    +-----------------------+------------+----------------+------------------------------------------+------------------------------------------+
            |                    | M24512                | 512Kbit    | 128            | E2P_DEVICE_M24512                        | 2字节地址                                |
            |                    +-----------------------+------------+----------------+------------------------------------------+------------------------------------------+
            |                    | M24M01                | 1Mbit      | 256            | E2P_DEVICE_M24M01                        | 17位地址，A16 在设备地址中               |
            |                    +-----------------------+------------+----------------+------------------------------------------+------------------------------------------+
            |                    | M24M02                | 2Mbit      | 256            | E2P_DEVICE_M24M02                        | 18位地址，A17, A16 在设备地址中          |
            +--------------------+-----------------------+------------+----------------+------------------------------------------+------------------------------------------+

            支持的 spi eeprom 设备:
            +--------------------+------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            | 公司/品牌          | 型号 (Series)    | 存储容量  | 页大小 (Bytes) | 宏定义 (Macro)                      | 备注 (Notes)                                               |
            +====================+==================+===========+================+=====================================+=========================================================+
            | Microchip (Atmel)  | AT25010B         | 1Kbit     | 8              | E2P_DEVICE_AT25010B                 |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | AT25020B         | 2Kbit     | 8              | E2P_DEVICE_AT25020B                 |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | AT25040B         | 4Kbit     | 8              | E2P_DEVICE_AT25040B                 | 9位地址，MSB 在指令序列中传输                             |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | AT25080B         | 8Kbit     | 32             | E2P_DEVICE_AT25080B                 |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | AT25160B         | 16Kbit    | 32             | E2P_DEVICE_AT25160B                 |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | AT25320B         | 32Kbit    | 32             | E2P_DEVICE_AT25320B                 |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | AT25640B         | 64Kbit    | 32             | E2P_DEVICE_AT25640B                 |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | AT25128B         | 128Kbit   | 64             | E2P_DEVICE_AT25128B                 |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | AT25256B         | 256Kbit   | 64             | E2P_DEVICE_AT25256B                 |                                                         |
            +--------------------+------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            | STMicroelectronics | M95010           | 1Kbit     | 16             | E2P_DEVICE_M95010                   |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | M95020           | 2Kbit     | 16             | E2P_DEVICE_M95020                   |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | M95040           | 4Kbit     | 16             | E2P_DEVICE_M95040                   | 9位地址，MSB 在指令序列中传输                             |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | M95080           | 8Kbit     | 32             | E2P_DEVICE_M95080                   |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | M95160           | 16Kbit    | 32             | E2P_DEVICE_M95160                   |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | M95320           | 32Kbit    | 32             | E2P_DEVICE_M95320                   |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | M95640           | 64Kbit    | 32             | E2P_DEVICE_M95640                   |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | M95128           | 128Kbit   | 64             | E2P_DEVICE_M95128                   |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | M95256           | 256Kbit   | 64             | E2P_DEVICE_M95256                   |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | M95512           | 512Kbit   | 128            | E2P_DEVICE_M95512                   |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | M95M01           | 1Mbit     | 256            | E2P_DEVICE_M95M01                   |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | M95M02           | 2Mbit     | 256            | E2P_DEVICE_M95M02                   |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | M95M04           | 4Mbit     | 256            | E2P_DEVICE_M95M04                   |                                                         |
            +--------------------+------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            | ABLIC (Seiko)      | S-25C010A        | 1Kbit     | 16             | E2P_DEVICE_S_25C010A                |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | S-25C020A        | 2Kbit     | 16             | E2P_DEVICE_S_25C020A                |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | S-25C040A        | 4Kbit     | 16             | E2P_DEVICE_S_25C040A                | 9位地址，MSB 在指令序列中传输                             |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | S-25C080A        | 8Kbit     | 32             | E2P_DEVICE_S_25C080A                |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | S-25C160A        | 16Kbit    | 32             | E2P_DEVICE_S_25C160A                |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | S-25C320A        | 32Kbit    | 32             | E2P_DEVICE_S_25C320A                |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | S-25C640A        | 64Kbit    | 32             | E2P_DEVICE_S_25C640A                |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | S-25C128A        | 128Kbit   | 64             | E2P_DEVICE_S_25C128A                |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | S-25C256A        | 256Kbit   | 64             | E2P_DEVICE_S_25C256A                |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | S-25C512A        | 512Kbit   | 128            | E2P_DEVICE_S_25C512A                |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | S-25CM01A        | 1Mbit     | 256            | E2P_DEVICE_S_25CM01A                |                                                         |
            +--------------------+------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            | Generic/Other      | 25xx010A         | 1Kbit     | 16             | E2P_DEVICE_25xx010A                 | (通常兼容 S-25C 系列)                                    |
            | (Microchip, etc.)  +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | 25xx020A         | 2Kbit     | 16             | E2P_DEVICE_25xx020A                 |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | 25xx040A         | 4Kbit     | 16             | E2P_DEVICE_25xx040A                 | 9位地址，MSB 在指令序列中传输                             |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | 25xx080A         | 8Kbit     | 16             | E2P_DEVICE_25xx080A                 |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | 25xx160A         | 16Kbit    | 16             | E2P_DEVICE_25xx160A                 |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | 25xx080B         | 8Kbit     | 32             | E2P_DEVICE_25xx080B                 | (通常兼容 AT25 系列)                                     |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | 25xx160B         | 16Kbit    | 32             | E2P_DEVICE_25xx160B                 |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | 25xx320A         | 32Kbit    | 32             | E2P_DEVICE_25xx320A                 |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | 25xx640A         | 64Kbit    | 32             | E2P_DEVICE_25xx640A                 |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | 25xx128          | 128Kbit   | 64             | E2P_DEVICE_25xx128                  |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | 25xx256          | 256Kbit   | 64             | E2P_DEVICE_25xx256                  |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | 25x512           | 512Kbit   | 128            | E2P_DEVICE_25x512                   |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | 25xx1024         | 1Mbit     | 256            | E2P_DEVICE_25xx1024                 |                                                         |
            +--------------------+------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            | ON Semi            | NV25010A         | 1Kbit     | 16             | E2P_DEVICE_NV25010A                 |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | NV25020A         | 2Kbit     | 16             | E2P_DEVICE_NV25020A                 |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | NV25040A         | 4Kbit     | 16             | E2P_DEVICE_NV25040A                 | 9位地址，MSB 在指令序列中传输                             |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | NV25080          | 8Kbit     | 32             | E2P_DEVICE_NV25080                  |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | NV25160          | 16Kbit    | 32             | E2P_DEVICE_NV25160                  |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | NV25320          | 32Kbit    | 32             | E2P_DEVICE_NV25320                  |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | NV25640          | 64Kbit    | 32             | E2P_DEVICE_NV25640                  |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | NV25128          | 128Kbit   | 64             | E2P_DEVICE_NV25128                  |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | NV25256          | 256Kbit   | 64             | E2P_DEVICE_NV25256                  |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | NV25512          | 512Kbit   | 128            | E2P_DEVICE_NV25512                  |                                                         |
            |                    +------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+
            |                    | NV25M01          | 1Mbit     | 256            | E2P_DEVICE_NV25M01                  |                                                         |
            +--------------------+------------------+-----------+----------------+-------------------------------------+---------------------------------------------------------+


- 结构体介绍

    - eeprom hal 层设备结构体定义

        .. code-block:: c

            typedef struct {
                uint32_t flag; /* eeprom 设备类型标志 */
                char device_name[E2P_DEVICE_NAME_MAX_LEN]; /* 设备实例名称 */
                void *host; /* eeprom 设备所使用的硬件接口句柄 */
                void *private; /* 用户私有数据 */
                void *config; /* eeprom 设备配置参数 */
                void *ops; /* eeprom 设备操作函数集 */
            } hpm_eeprom_device_t;

    - eeprom 调用函数集定义

        .. code-block:: c

            typedef struct {
                hpm_stat_t (*init)(hpm_eeprom_device_t *device);
                hpm_stat_t (*deinit)(hpm_eeprom_device_t *device);
                hpm_stat_t (*write)(hpm_eeprom_device_t *device, uint32_t data_addr, uint32_t len, uint8_t *data);
                hpm_stat_t (*read)(hpm_eeprom_device_t *device, uint32_t data_addr, uint32_t len, uint8_t *data);
            } e2p_device_ops_t;

    - eeprom 设备实例注册数组

        .. code-block:: c

            typedef struct {
                hpm_eeprom_device_t device[EEPROM_MAX_DEVICE_CNT]; /* eeprom 设备实例数组 */
                uint8_t device_count; /* 已注册设备数量 */
                uint32_t device_bit; /* 已注册设备标志位 */
            } eeprom_context_t;

    - eeprom emulation 配置参数

        .. code-block:: c

            typedef struct {
                uint32_t flash_base_addr; /* 模拟 eeprom 使用的 flash 基地址 */
                uint32_t version; /* 模拟 eeprom 版本号 */
                uint32_t opt_header; /* 模拟 eeprom 配置头 */
                uint32_t opt0; /* 模拟 eeprom 配置选项0 */
                uint32_t opt1; /* 模拟 eeprom 配置选项1 */
                uint32_t start_addr; /* 模拟 eeprom 数据区起始地址 */
                uint32_t erase_size; /* 模拟 eeprom 擦除单元大小 */
                uint32_t sector_cnt; /* 模拟 eeprom 擦除单元数量 */
            } e2p_emu_xpi_config_t;

    - eeprom device spi 配置参数

        .. code-block:: c

            typedef struct {
                SPI_Type *base; /* SPI 外设基地址 */
                uint32_t cs_pin; /* SPI 片选引脚 */
                uint32_t (*clock_init)(SPI_Type *ptr); /* SPI 时钟初始化函数指针 */
                void (*pin_init)(void); /* SPI 引脚初始化函数指针 */
                void (*cs_control)(uint32_t pin, uint8_t state); /* SPI 片选引脚控制函数指针 */
            } e2p_device_spi_host_config_t;

    - eeprom device i2c 配置参数

        .. code-block:: c

            typedef struct {
                I2C_Type *base; /* I2C 外设基地址 */
                uint32_t (*clock_init)(I2C_Type *ptr); /* I2C 时钟初始化函数指针 */
                void (*pin_init)(void); /* I2C 引脚初始化函数指针 */
            } e2p_device_i2c_host_config_t;

            typedef struct {
                uint32_t dev_addr; /* eeprom 设备地址 */
                uint32_t addr_bytes; /* 地址字节数 */
                uint32_t page_size; /* 页大小 */
                uint32_t timeout; /* I2C 操作超时时间 */
            } e2p_device_i2c_attribute_t;

API调用流程介绍
---------------------

- 使用流程

    .. _process_diagram:

    .. rst-class:: center-block

    .. raw:: html

        <pre>
        应用程序启动
                │
                ▼
        ┌──────────────────────────┐
        │  1. 准备配置              │
        │     - 主机配置            │
        │     - 设备属性            │
        └──────────┬───────────────┘
                    │
                    ▼
        ┌──────────────────────────┐
        │  2. 注册参数              │
        │     hpm_eeprom_          │
        │       register_param()   │
        └──────────┬───────────────┘
                    │
                    ▼
        ┌──────────────────────────┐
        │  3. 注册设备              │
        │     hpm_eeprom_          │
        │       register()         │
        └──────────┬───────────────┘
                    │
                    ▼
        ┌──────────────────────────┐
        │  4. 查找设备              │
        │     hpm_eeprom_find()    │
        └──────────┬───────────────┘
                    │
                    ▼
        ┌──────────────────────────┐
        │  5. 初始化设备            │
        │     hpm_eeprom_init()    │
        └──────────┬───────────────┘
                    │
                    ▼
        ┌──────────────────────────┐
        │  6. 读写操作              │
        │     hpm_eeprom_read_     │
        │       block()            │
        │     hpm_eeprom_write_    │
        │       block()            │
        └──────────┬───────────────┘
                    │
                    ▼
        ┌──────────────────────────┐
        │  7. 清理 (可选)           │
        │     hpm_eeprom_          │
        │       unregister()       │
        └──────────────────────────┘

- 根据实际的 eeprom 资源注册实例

    举例：
    - 注册一个模拟 eeprom 实例,使用 xpi 接口的 flash,具体可参考 unit_test/drivers/eeprom/e2p_emu/e2p_emu_test.c

        - 准备工作: 需清楚使用的 flash 基地址,模拟 eeprom 版本号,配置头和选项,模拟 eeprom 数据区起始地址,擦除单元大小和数量等参数。

        .. code-block:: c

            e2p_emu_xpi_config_t emu_config = {
                .flash_base_addr = BOARD_FLASH_BASE_ADDRESS,
                .version = 0x4553,
                .opt_header = BOARD_APP_XPI_NOR_CFG_OPT_HDR,
                .opt0 = BOARD_APP_XPI_NOR_CFG_OPT_OPT0,
                .opt1 = BOARD_APP_XPI_NOR_CFG_OPT_OPT1,
                .start_addr = BOARD_APP_EEPROM_EMU_START_ADDR,
                .erase_size = BOARD_APP_EEPROM_EMU_ERASE_SIZE,
                .sector_cnt = BOARD_APP_EEPROM_EMU_SECTOR_COUNT,
            };

            hpm_eeprom_device_t e2p_emu_temp = {
                .ptr = BOARD_APP_XPI_NOR_XPI_BASE,
                .flag = EEPROM_FLAG_EMULATION_XPI,
                .config = &emu_config,
            };  /* 配置模拟 eeprom 的参数 */

            hpm_eeprom_register_emulation_xpi_param(&e2p_emu_temp); /* 获取模拟 eeprom 参数(主要获取 ops 接口) */
            hpm_eeprom_register(&e2p_emu_temp, "e2p_emu"); /* 注册模拟 eeprom 实例 */

    - 注册一个 spi 驱动的 eeprom 实例,以 AT25128 为例,获取相关参数,具体可参考 unit_test/drivers/eeprom/e2p_spi/e2p_spi_test.c
        eeprom hal 层提供了一个全局 list hpm_support_e2p_spi_device_list[] 用于存放支持的 spi eeprom 设备参数,用户需要根据具体设备选择对应的索引。
        同时指定使用的片选引脚,硬件 spi 接口即可注册。

        - 准备工作: 需配置 spi 硬件接口的基地址,片选引脚,时钟初始化函数,引脚初始化函数,片选引脚控制函数等参数; 同时确认使用的 eeprom 型号, 如果在上述列表中, 需对 id 赋值; 如果不在, 需要自行填充 dev_attr 参数, 并对 id 赋值 0xff。

        .. code-block:: c

            uint32_t dev_type = E2P_DEVICE_AT25128; /* 选择 spi eeprom 设备类型 */
            e2p_device_spi_attribute_t dev_attr;
            e2p_device_spi_host_config_t host_info = {
                .base = BOARD_APP_SPI_BASE,
                .cs_pin = BOARD_SPI_CS_PIN,
                .clock_init = board_init_spi_eeprom_clock,
                .pin_init = board_init_spi_eeprom_pin,
                .cs_control = board_write_spi_cs,
            };  /* 配置 spi 硬件接口 */

            hpm_eeprom_device_t e2p_dev_temp = {
                .host = &host_info,
                .flag = EEPROM_FLAG_DEVICE_SPI,
                .config = &dev_attr,
            };  /* 配置已知的 spi eeprom 设备参数 */

            hpm_eeprom_register_spi_param(&e2p_dev_temp, &host_info, dev_id); /* 获取 spi eeprom 参数 */
            hpm_eeprom_register(&e2p_dev_temp, "e2p_dev_spi"); /* 注册 spi eeprom 实例 */

    - 注册一个 i2c 驱动的 eeprom 实例,以 AT24C02 为例,获取相关参数,具体可参考 unit_test/drivers/eeprom/e2p_i2c/e2p_i2c_test.c
        eeprom hal 层提供了一个全局 list hpm_support_e2p_i2c_device_list[] 用于存放支持的 i2c eeprom 设备参数,用户需要根据具体设备选择对应的索引。
        同时指定使用的硬件 i2c 接口即可注册。

        - 准备工作: 需配置 i2c 硬件接口的基地址,时钟初始化函数,引脚初始化函数等参数; 同时确认使用的 eeprom 型号, 如果在上述列表中, 需对 id 赋值; 如果不在, 需要自行填充 dev_attr 参数, 并对 id 赋值 0xff。

        .. code-block:: c

            uint8_t custom_id = 0;
            uint32_t e2p_device_index = HPM_E2P_I2C_ADD_CUSTOM_ID_TO_DEV_ID(custom_id, E2P_DEVICE_AT24C02);
            e2p_device_i2c_attribute_t dev_attr;
            e2p_device_i2c_host_config_t host_info = {
                .base = HPM_I2C1,
                .clock_init = board_init_i2c_eeprom_clock,
                .pin_init = board_init_i2c_eeprom_pin,
            }; /* 配置 i2c 硬件接口 */

            hpm_eeprom_device_t e2p_dev_temp = {
                .host = &host_info,
                .flag = EEPROM_FLAG_DEVICE_I2C,
                .config = &dev_attr,
            }; /* 配置已知的 i2c eeprom 设备参数 */

            hpm_eeprom_register_i2c_param(&e2p_dev_temp, &host_info, e2p_device_id); /* 获取 i2c eeprom 参数 */
            hpm_eeprom_register(&e2p_dev_temp, "e2p_dev_i2c"); /* 注册 i2c eeprom 实例 */

    - 注意：
        - 每个实例注册时需要指定唯一的名称,用于后续调用时区分不同实例
        - 使用 I2C eeprom 时，用户需要注意区分不同的设备 ID,根据板级的实际情况指定 custom_id 值，避免冲突。
        - 注册时需要先进性参数注册,再进行实例注册;如果没有参数注册,实例注册时,ops 接口将为空,无法进行后续操作(删除列表时可能会造成异常)
        - 如果 hal 层中没有用户需要的 eeprom 设备(比如用户使用的 spi eeprom 型号,不在 list 中定义),可以参考 list 表中的定义,自行填充配置进行注册;同时,需要确认 pinmux 引脚配置正确。
        - 如果用户不想通过 hal 层,想要直接使用底层驱动 API,也可以直接查看对应驱动代码,调用底层驱动 API 进行读写操作,但需要自行配置参数。

    - 通过名称获取对应的 eeprom 实例句柄并初始化

        举例： 以 spi 驱动的 eeprom 实例为例

            .. code-block:: c

                hpm_eeprom_device_t *e2p_dev = hpm_eeprom_find("e2p_dev_spi"); /* 通过名称查找 eeprom 实例句柄 */
                hpm_eeprom_init(e2p_dev); /* 初始化 eeprom 实例 */

    - 通过实例句柄进行读写操作

        .. code-block:: c

            hpm_eeprom_write_block(device, addr, len, (uint8_t *)&write_val); /* 写数据 */

            hpm_eeprom_read_block(device, addr, len, (uint8_t *)&read_val); /* 读数据 */

    当注册结束后,用户不需要关心底层驱动的实现细节,只需通过实例句柄调用统一的读写接口即可完成对 eeprom 的操作。