From 976a652d4b524bee8f245e208de2aa118619407b Mon Sep 17 00:00:00 2001
From: wwhaoww <15849883627@163.com>
Date: Fri, 27 Feb 2026 16:41:14 +0800
Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0README=EF=BC=9A=E8=A1=A5?=
 =?UTF-8?q?=E5=85=85=E9=80=82=E7=94=A8=E8=8C=83=E5=9B=B4=E4=B8=8E=E7=A7=BB?=
 =?UTF-8?q?=E6=A4=8D=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 116 ++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 86 insertions(+), 30 deletions(-)

diff --git a/README.md b/README.md
index 8caaa76..7076ab1 100644
--- a/README.md
+++ b/README.md
@@ -1,32 +1,69 @@
-# Driver_M24Cxx（可移植 EEPROM 驱动）
+# EEPROM24xx 通用驱动模块说明
 
-这是一个面向 M24Cxx / AT24Cxx 系列 EEPROM 的可移植驱动模块。
+本 README 对当前 EEPROM 模块代码做统一说明，包含：适用范围、文件职责、移植步骤。
 
-核心特性：
+## 1. 适用范围
 
-- 不依赖特定 MCU/SDK（不绑定 STM32 HAL）
-- 支持页写自动拆分
-- 用户传入 I2C 读、I2C 写、毫秒延时三个函数后即可直接使用
+该模块适用于 I2C 接口的 24xx 系列 EEPROM（如 M24Cxx / AT24Cxx），并支持：
 
-## 目录结构
+- 1 字节或 2 字节存储地址（`mem_addr_size = 1/2`）
+- 页写自动拆分（避免跨页写导致写入异常）
+- 平台无关移植（通过用户传入读/写/延时函数）
 
-- `module/Int_EEPROM24xx.h`：驱动接口
-- `module/Int_EEPROM24xx.c`：驱动实现
-- `examples/adapter_template.c`：移植模板
+不适用于：
 
-## 使用步骤
+- 非 I2C EEPROM
+- 需要 DMA/异步回调流程的复杂驱动（本模块为同步阻塞接口）
 
-1. 将 `module/Int_EEPROM24xx.h/.c` 加入你的工程。
-2. 在你的平台实现三个函数：
-   - `your_i2c_read(...)`
-   - `your_i2c_write(...)`
-   - `your_delay_ms(...)`
-3. 调用 `Int_EEPROM24xx_Init(...)` 完成初始化。
-4. 直接调用 `Int_EEPROM24xx_Read/Write` 进行访问。
+## 2. 文件说明
 
-## 示例
+### `interface/Int_EEPROM24xx.h`
+
+对外头文件，定义：
+
+- 返回码：
+  - `INT_EEPROM_OK`
+  - `INT_EEPROM_ERR_ARG`
+  - `INT_EEPROM_ERR_IO`
+- 用户需提供的函数指针类型：
+  - `IntEEPROM_I2CRead_t`
+  - `IntEEPROM_I2CWrite_t`
+  - `IntEEPROM_DelayMs_t`
+- 配置结构体 `IntEEPROM24xx_Config_t`
+- 对外 API：
+  - `Int_EEPROM24xx_Init()`
+  - `Int_EEPROM24xx_Read()`
+  - `Int_EEPROM24xx_Write()`
+
+### `interface/Int_EEPROM24xx.c`
+
+核心实现文件，主要逻辑：
+
+- `Init`：校验参数、保存配置和用户回调
+- `Read`：参数检查后调用用户读函数
+- `Write`：按页拆分写入 + 每页写后延时（写周期等待）
+
+## 3. API 使用流程
 
 ```c
+// 1) 实现底层 3 个函数
+static IntEEPROM_Result_t my_i2c_read(uint16_t dev_addr,
+                                      uint32_t mem_addr,
+                                      uint8_t mem_addr_size,
+                                      uint8_t *buf,
+                                      uint16_t len,
+                                      uint32_t timeout_ms);
+
+static IntEEPROM_Result_t my_i2c_write(uint16_t dev_addr,
+                                       uint32_t mem_addr,
+                                       uint8_t mem_addr_size,
+                                       const uint8_t *buf,
+                                       uint16_t len,
+                                       uint32_t timeout_ms);
+
+static void my_delay_ms(uint32_t ms);
+
+// 2) 填写配置并初始化
 IntEEPROM24xx_Config_t cfg = {
     .dev_addr = (0x50u << 1),
     .page_size = 8u,
@@ -35,22 +72,41 @@ IntEEPROM24xx_Config_t cfg = {
     .timeout_ms = 100u,
 };
 
-Int_EEPROM24xx_Init(&cfg, your_i2c_read, your_i2c_write, your_delay_ms);
+Int_EEPROM24xx_Init(&cfg, my_i2c_read, my_i2c_write, my_delay_ms);
 
+// 3) 读写
 Int_EEPROM24xx_Write(0x00, tx_buf, tx_len);
 Int_EEPROM24xx_Read(0x00, rx_buf, rx_len);
 ```
 
-## 参数说明
+## 4. 如何移植到新 MCU
 
-- `dev_addr`：设备地址（7bit 或左移后地址，取决于底层驱动规范）
-- `page_size`：页大小（必须与芯片手册一致）
-- `mem_addr_size`：地址字节数（1 或 2）
-- `write_cycle_ms`：每次页写后的写周期等待
-- `timeout_ms`：底层总线访问超时
+只需要做 4 步：
 
-## 注意事项
+1. 拷贝 `Int_EEPROM24xx.h/.c` 到你的工程。  
+2. 用目标平台 SDK 实现 3 个函数（读、写、毫秒延时）。  
+3. 按芯片手册填写配置参数：
+   - `dev_addr`
+   - `page_size`
+   - `mem_addr_size`
+   - `write_cycle_ms`
+4. 调用 `Int_EEPROM24xx_Init` 一次后，即可直接调用读写函数。
 
-- 驱动内部会自动按页拆分写入，避免跨页写异常。
-- 若你的器件使用 2 字节地址，请设置 `mem_addr_size = 2`。
-- 若写后立即读失败，请适当增大 `write_cycle_ms`。
+## 5. 关键参数建议
+
+- `page_size`：必须与 EEPROM 手册一致。
+- `mem_addr_size`：
+  - 小容量常见 1
+  - 大容量常见 2
+- `write_cycle_ms`：建议按 datasheet，通常 5~10ms。
+- `dev_addr`：根据你的 I2C 驱动要求使用 7bit 地址或左移地址。
+
+## 6. 常见问题排查
+
+- 写后读不一致：优先检查 `write_cycle_ms` 是否太小。  
+- 连续写入中间数据错位：优先检查 `page_size` 是否配置错误。  
+- 初始化失败：检查回调函数是否传空、`mem_addr_size` 是否为 1/2。
+
+## 7. 当前工程中的使用点
+
+本项目在 `interface/W5500/Int_NetCfg.c` 中调用该模块，用于网络参数 EEPROM 持久化。