# FlashDB 使用说明

## 1. 概述

本项目使用 [FlashDB](https://github.com/armink/FlashDB) 嵌入式数据库，提供两种数据库：

- **KVDB**（键值数据库）：存储键值对，类似 Redis 简化版
- **TSDB**（时序数据库）：存储带时间戳的日志记录，支持按时间范围查询

底层存储介质为 GD5F2GQ5UE SPI NAND Flash（256MB），通过 FAL（Flash Abstraction Layer）抽象层访问。

## 2. 软件架构

```
┌─────────────────────────────────────────┐
│           用户应用（main.c）              │
├──────────────┬──────────────────────────┤
│   fdb_kvdb   │      fdb_tsdb            │
│  （键值数据库） │    （时序数据库）          │
├──────────────┴──────────────────────────┤
│              FlashDB 核心                │
│    Lib/FlashDB/src/                     │
├─────────────────────────────────────────┤
│    FAL 抽象层                           │
│    Lib/FlashDB/port/fal/src/            │
├─────────────────────────────────────────┤
│    FAL 设备适配层                        │
│    fal_flash_gd5f2gq5ue.c              │
├─────────────────────────────────────────┤
│    GD5F2GQ5UE SPI NAND 驱动             │
│    gd5f2gq5ue.c                         │
├─────────────────────────────────────────┤
│    SPI1 硬件外设 + HAL 驱动              │
└─────────────────────────────────────────┘
```

## 3. 文件清单

| 文件 | 说明 | 是否自编 |
|------|------|----------|
| `Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.h` | NAND 驱动头文件 | 是 |
| `Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c` | NAND 驱动实现 | 是 |
| `Drivers/BSP/GD5F2GQ5UE/fal_flash_gd5f2gq5ue.c` | FAL 设备适配 | 是 |
| `Drivers/BSP/GD5F2GQ5UE/fal_cfg.h` | FAL 设备表 + 分区表 | 是 |
| `Drivers/BSP/GD5F2GQ5UE/fdb_cfg.h` | FlashDB 功能配置 | 是 |
| `Lib/FlashDB/src/` | FlashDB 核心源码 | 否 |
| `Lib/FlashDB/port/fal/src/` | FAL 硬件抽象框架源码 | 否 |

## 4. 硬件配置

### 4.1 Flash 芯片参数

| 参数 | 值 |
|------|-----|
| 型号 | GD5F2GQ5UE（GigaDevice） |
| 总容量 | 2Gbit = 256MB |
| 页大小 | 2048 字节 |
| Spare 区 | 64 字节 |
| 每块页数 | 64 页 |
| 块大小 | 128KB（64 × 2048） |
| 总块数 | 2048 |
| SPI 模式 | Mode 0（CPOL=0, CPHA=0） |
| SPI 时钟 | 42MHz（APB2=84MHz, 分频=2） |
| MID | 0xC8 |
| DID | 0x52 |

### 4.2 引脚连接

| 信号 | STM32 引脚 | 方向 | 说明 |
|------|-----------|------|------|
| CS# | PE0 | OUT | 片选，低有效 |
| SCLK | PB3 | OUT | SPI1 时钟 |
| MOSI | PB5 | OUT | SPI1 主出从入 |
| MISO | PB4 | IN | SPI1 主入从出 |
| WP# | PB8 | OUT | 写保护，低有效（拉高禁用） |
| HOLD# | PE1 | OUT | 保持，低有效（拉高禁用） |

### 4.3 GPIO 初始化

CubeMX 中需确保以下 GPIO 上电默认电平：

- **CS#** (PE0)：上电输出 **高电平**（未选中）
- **HOLD#** (PE1)：上电输出 **高电平**（不保持）
- **WP#** (PB8)：上电输出 **高电平**（不禁用写保护）

> 若 GPIO 初始电平错误，SPI 通信将完全无响应。

## 5. 分区规划

| 分区名 | 设备 | 偏移 | 大小 | 用途 |
|--------|------|------|------|------|
| fdb_kvdb1 | gd5f2gq5ue | 0 | 64MB | KVDB 键值数据库 |
| fdb_tsdb1 | gd5f2gq5ue | 64MB | 64MB | TSDB 时序数据库 |
| （未分配） | - | 128MB | 128MB | 剩余空间 |

共使用 128MB / 256MB，剩余 128MB 可扩展。

## 6. 初始化流程

```
1. HAL_Init()
2. SystemClock_Config()
3. MX_GPIO_Init()          ← CS#/HOLD#/WP# 初始电平
4. MX_USART1_UART_Init()   ← 调试串口
5. MX_SPI2_Init()          ← CH395F 以太网
6. MX_SPI1_Init()          ← GD5F2GQ5UE NAND
7. gd5f2gq5ue_init()       ← NAND 初始化
8. fdb_kvdb_init()         ← FlashDB KVDB 初始化
```

### 6.1 gd5f2gq5ue_init() 内部步骤

```
1. CS#/WP#/HOLD# 拉高
2. 发送复位命令（FFh），等待 5ms
3. 读取芯片 ID（9Fh），校验 MID=0xC8, DID=0x52
4. 使能内部 ECC：SET_FEATURE(B0h, 10h)
5. 解除块保护：SET_FEATURE(A0h, 00h)
```

> **关键点**：SET_FEATURE 命令前必须先发写使能（06h），否则设置不生效。

## 7. KVDB 使用方法

### 7.1 初始化

```c
#include "flashdb.h"

static struct fdb_kvdb kvdb;

/* path 参数对应分区表中的分区名 "fdb_kvdb1" */
/* default_kv 传 NULL 表示不使用默认键值 */
int ret = fdb_kvdb_init(&kvdb, "db", "fdb_kvdb1", NULL, NULL);
if (ret != FDB_NO_ERR) {
    /* 初始化失败处理 */
}
```

### 7.2 字符串读写

```c
/* 写入字符串 */
fdb_kv_set(&kvdb, "device_name", "STM32F407-DTU");

/* 读取字符串（返回内部缓存指针，下次写入同一 key 后失效） */
char *val = fdb_kv_get(&kvdb, "device_name");
if (val) {
    printf("device_name = %s\n", val);
}
```

### 7.3 二进制数据读写（Blob）

```c
#include <string.h>

/* 写入二进制数据 */
uint32_t temp = 2560;
fdb_kv_set_blob(&kvdb, "temperature",
                fdb_blob_make(NULL, &temp, sizeof(temp)));

/* 读取二进制数据 */
uint32_t read_temp = 0;
fdb_kv_get_blob(&kvdb, "temperature",
                fdb_blob_make(NULL, &read_temp, sizeof(read_temp)));
printf("temperature = %u\n", read_temp);
```

### 7.4 删除键

```c
fdb_kv_del(&kvdb, "device_name");
```

### 7.5 遍历所有键

```c
struct fdb_kv kv;
struct fdb_kv_iterator itr;

fdb_kv_iterator_init(&kvdb, &itr);
while (fdb_kv_iterate(&kvdb, &itr)) {
    kv = itr.curr;
    printf("key: %s\n", kv.name);
}
```

### 7.6 打印所有键值

```c
fdb_kv_print(&kvdb);
```

## 8. TSDB 使用方法

### 8.1 获取时间戳

FlashDB 需要用户提供时间戳获取函数。本项目使用 HAL_GetTick()（毫秒）：

```c
static fdb_time_t get_time(void)
{
    return (fdb_time_t)HAL_GetTick();
}
```

### 8.2 初始化

```c
static struct fdb_tsdb tsdb;

/* max_len 参数限制单条记录最大长度 */
int ret = fdb_tsdb_init(&tsdb, "tsdb", "fdb_tsdb1",
                        get_time, 256, NULL);
```

### 8.3 追加记录

```c
/* 写入二进制数据，自动附加当前时间戳 */
uint32_t sensor_val = 3200;
fdb_tsl_append(&tsdb,
               fdb_blob_make(NULL, &sensor_val, sizeof(sensor_val)));
```

### 8.4 遍历记录

```c
/* 正序遍历 */
fdb_tsl_iter(&tsdb, tsl_cb_func, NULL);

/* 逆序遍历 */
fdb_tsl_iter_reverse(&tsdb, tsl_cb_func, NULL);

/* 按时间范围遍历 */
fdb_tsl_iter_by_time(&tsdb, from_time, to_time, tsl_cb_func, NULL);
```

回调函数原型：

```c
static void tsl_cb_func(struct fdb_tsl *tsl, void *arg)
{
    struct fdb_blob blob;
    uint32_t val;

    /* 读取数据 */
    fdb_blob_read((fdb_db_t)&tsl,
                  fdb_tsl_to_blob(tsl, fdb_blob_make(&blob, &val, sizeof(val))));
    printf("ts=%lu, val=%lu\n", tsl->time, val);
}
```

### 8.5 查询记录数量

```c
size_t count = fdb_tsl_query_count(&tsdb, from_time, to_time,
                                   FDB_TSL_STATUS_APPEND);
```

### 8.6 清理所有记录

```c
fdb_tsl_clean(&tsdb);
```

## 9. 配置文件说明

### 9.1 fdb_cfg.h

| 宏 | 说明 |
|----|------|
| `FDB_USING_KVDB` | 启用 KVDB |
| `FDB_USING_TSDB` | 启用 TSDB |
| `FDB_USING_FAL_MODE` | 使用 FAL 模式（非文件系统） |
| `FDB_WRITE_GRAN` | 写入粒度 8（字节可编程） |
| `FDB_DEBUG_ENABLE` | 启用调试输出 |
| `FDB_KV_AUTO_UPDATE` | KVDB 版本变化时自动更新（默认关闭） |

### 9.2 fal_cfg.h

分区表定义，修改分区大小需同时调整偏移和大小：

```c
#define FAL_PART_TABLE                                                        \
{                                                                             \
    {FAL_PART_MAGIC_WORD, "fdb_kvdb1", "gd5f2gq5ue",           0, 64*1024*1024, 0}, \
    {FAL_PART_MAGIC_WORD, "fdb_tsdb1", "gd5f2gq5ue", 64*1024*1024, 64*1024*1024, 0}, \
}
```

字段顺序：`{魔数, 分区名, 设备名, 偏移, 大小, 标志}`

## 10. Keil 工程配置

### 10.1 头文件搜索路径

在 Keil 工程 Options → C/C++ → Include Paths 中添加：

```
../Drivers/BSP/GD5F2GQ5UE
../Lib/FlashDB/inc
../Lib/FlashDB/port/fal/inc
```

### 10.2 编译的源文件

需在 Keil 工程中添加以下源文件：

```
Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c
Drivers/BSP/GD5F2GQ5UE/fal_flash_gd5f2gq5ue.c
Lib/FlashDB/src/fdb.c
Lib/FlashDB/src/fdb_kvdb.c
Lib/FlashDB/src/fdb_tsdb.c
Lib/FlashDB/src/fdb_utils.c
Lib/FlashDB/port/fal/src/fal.c
Lib/FlashDB/port/fal/src/fal_flash.c
Lib/FlashDB/port/fal/src/fal_partition.c
```

### 10.3 全局宏定义

确保工程中定义了：

```
USE_HAL_DRIVER, STM32F407xx
```

## 11. 注意事项

### 11.1 NAND Flash 特性

1. **写前必须擦除**：NAND 只能将 1→0，不能 0→1。写入前目标块必须先擦除（全部变为 0xFF）
2. **擦除单位是块**：最小擦除单位 128KB，不能按页擦除
3. **写入单位是页**：单次写入不超过一页（2048 字节），跨页需驱动层拆分
4. **Spare 区不可直接访问**：驱动已使能内部 ECC，Spare 区由芯片硬件管理

### 11.2 驱动层注意事项

1. **每次 SPI 事务前**：必须 `CS_LOW()` 拉低片选
2. **每次 SPI 事务后**：必须 `CS_HIGH()` 拉高片选
3. **SET_FEATURE 前必须写使能**：先发 06h，再发 1Fh + 地址 + 数据
4. **块擦除地址是字节地址**：D8h 命令的参数 = 块编号 × 128KB（不是块编号本身）
5. **读取 ID 需跳过 dummy 字节**：9Fh 返回 3 字节，第 0 字节无意义，第 1 字节 MID，第 2 字节 DID

### 11.3 FlashDB 使用注意事项

1. **fdb_kv_get 返回值是内部缓存**：下次对同一 key 写入后，之前返回的指针失效
2. **TSDB 需要用户提供时间戳**：通过 `get_time` 回调，本项目使用 `HAL_GetTick()`
3. **fdb_kvdb_init 的 path 参数**：对应分区表中的分区名 `"fdb_kvdb1"`
4. **FlashDB 开启 FDB_DEBUG_ENABLE 后**：会通过 `fdb_print()` 输出调试信息，需确保有可用的输出（如 printf 重定向到串口）
5. **分区大小修改后**：需同步更新 `fal_cfg.h` 中的偏移和大小

### 11.4 常见问题

| 现象 | 可能原因 | 解决方法 |
|------|----------|----------|
| init 返回 -6 (ID_MISMATCH) | SPI 通信失败或芯片未上电 | 检查接线、GPIO 初始电平、虚焊 |
| KVDB init 失败 | 分区名不匹配 | 确认 `fdb_kvdb_init` 的 path 与 `fal_cfg.h` 一致 |
| 写入后读取为空 | 未擦除或写入失败 | 检查写入返回值，确认目标块已擦除 |
| 读取数据异常 | ECC 错误 | 检查 `gd5f2gq5ue_init` 是否成功使能 ECC |
| SET_FEATURE 未生效 | 缺少写使能命令 | 确认 `gd5f_set_feature` 中先调用 `gd5f_write_enable()` |

## 12. 调试方法

### 12.1 串口调试输出

FlashDB 调试输出通过 `fdb_print` 宏实现。在 `fdb_cfg.h` 中定义 `FDB_DEBUG_ENABLE` 后，FlashDB 内部操作会自动输出到标准输出。

确保 Keil 工程中 `printf` 已重定向到 USART1（PA9/PA10, 115200bps）。

### 12.2 NAND 驱动调试

可通过串口输出以下信息验证驱动工作正常：

```c
/* 读取芯片 ID */
uint8_t mid, did;
gd5f2gq5ue_read_id(&mid, &did);
printf("MID=0x%02X DID=0x%02X\n", mid, did);
/* 预期输出：MID=0xC8 DID=0x52 */

/* 初始化测试 */
int ret = gd5f2gq5ue_init();
printf("init ret=%d\n", ret);
/* 预期输出：init ret=0 */
```

### 12.3 FAL 设备注册验证

```c
#include "fal.h"

/* 检查 FAL 是否初始化成功 */
int ret = fal_init();
printf("fal_init ret=%d\n", ret);
/* 预期输出：fal_init ret=0 */
```