# SD卡存储监控功能说明

## 概述

本文档说明系统监控模块中新增的SD卡存储监控功能。该功能用于实时跟踪SD卡的写入操作、错误情况和性能指标。

## 监控指标

### 1. SD卡写入次数 (`sd_write_count`)
- **描述**: 记录成功写入SD卡的次数
- **用途**: 评估SD卡使用频率和系统活跃度
- **更新时机**: 每次成功刷新缓冲区到SD卡后

### 2. SD卡写入错误次数 (`sd_write_error_count`)
- **描述**: 记录SD卡写入失败的次数
- **用途**: 监控SD卡健康状态和可靠性
- **更新时机**: 
  - 缓冲区刷新失败时
  - 文件创建失败时
- **注意**: 该值持续增加可能表示SD卡故障或文件系统问题

### 3. 缓冲区满次数 (`sd_buffer_full_count`)
- **描述**: 记录双缓冲区都处于忙碌状态的次数
- **用途**: 评估数据写入速度是否跟得上数据产生速度
- **更新时机**: 切换缓冲区时发现目标缓冲区仍在刷新中
- **注意**: 该值频繁增加表示需要优化写入性能或增大缓冲区

### 4. SD卡总写入字节数 (`sd_total_bytes_written`)
- **描述**: 累计写入SD卡的总字节数
- **用途**: 
  - 评估SD卡使用量
  - 计算平均写入速度
  - 预估SD卡寿命
- **更新时机**: 每次成功写入后累加

### 5. 创建的文件数量 (`sd_file_count`)
- **描述**: 记录创建的数据文件总数
- **用途**: 跟踪数据分段情况
- **更新时机**: 每次成功创建新文件后

## API函数

### 初始化
```c
void SystemMonitor_Init(void);
```
初始化系统监控模块，清零所有统计信息。

### SD卡监控函数

#### 报告SD卡写入
```c
void SystemMonitor_ReportSDWrite(uint32_t bytes_written);
```
- **参数**: `bytes_written` - 本次写入的字节数
- **功能**: 增加写入次数计数，累加总写入字节数

#### 报告SD卡写入错误
```c
void SystemMonitor_ReportSDWriteError(void);
```
- **功能**: 增加写入错误计数

#### 报告缓冲区满
```c
void SystemMonitor_ReportSDBufferFull(void);
```
- **功能**: 增加缓冲区满计数

#### 报告文件创建
```c
void SystemMonitor_ReportSDFileCreated(void);
```
- **功能**: 增加文件创建计数

### 获取统计信息
```c
void SystemMonitor_GetStats(SystemMonitorStats_t *stats);
```
- **参数**: `stats` - 指向统计信息结构体的指针
- **功能**: 获取当前所有监控统计信息

## 集成说明

### 在data_storage.c中的集成点

1. **文件头部**: 添加 `#include "system_monitor.h"`

2. **DataStorage_FlushBuffer()函数**:
   - 写入成功时调用 `SystemMonitor_ReportSDWrite(bytes_written)`
   - 写入失败时调用 `SystemMonitor_ReportSDWriteError()`

3. **DataStorage_CreateNewFile()函数**:
   - 文件创建成功时调用 `SystemMonitor_ReportSDFileCreated()`
   - 文件创建失败时调用 `SystemMonitor_ReportSDWriteError()`

4. **DataStorage_SwitchBuffer()函数**:
   - 目标缓冲区忙碌时调用 `SystemMonitor_ReportSDBufferFull()`

## 使用示例

```c
// 初始化系统监控
SystemMonitor_Init();

// ... 系统运行 ...

// 获取统计信息
SystemMonitorStats_t stats;
SystemMonitor_GetStats(&stats);

// 打印SD卡监控信息
printf("SD卡写入次数: %lu\n", stats.sd_write_count);
printf("SD卡写入错误: %lu\n", stats.sd_write_error_count);
printf("缓冲区满次数: %lu\n", stats.sd_buffer_full_count);
printf("总写入字节数: %lu\n", stats.sd_total_bytes_written);
printf("创建文件数量: %lu\n", stats.sd_file_count);

// 计算平均写入大小
if (stats.sd_write_count > 0) {
    uint32_t avg_write_size = stats.sd_total_bytes_written / stats.sd_write_count;
    printf("平均写入大小: %lu 字节\n", avg_write_size);
}

// 计算错误率
if (stats.sd_write_count > 0) {
    float error_rate = (float)stats.sd_write_error_count / 
                       (stats.sd_write_count + stats.sd_write_error_count) * 100.0f;
    printf("写入错误率: %.2f%%\n", error_rate);
}
```

## 性能考虑

1. **低开销**: 所有监控函数都是简单的计数器操作，对系统性能影响极小
2. **线程安全**: 当前实现未考虑多线程，如需在中断中使用需添加保护机制
3. **溢出处理**: 使用32位计数器，在高频写入场景下可能溢出，需定期重置或使用64位计数器

## 故障诊断

### 高错误率
- **现象**: `sd_write_error_count` 持续增加
- **可能原因**: 
  - SD卡故障或接触不良
  - 文件系统损坏
  - SD卡写保护
- **建议**: 检查SD卡硬件连接，尝试格式化SD卡

### 频繁缓冲区满
- **现象**: `sd_buffer_full_count` 快速增加
- **可能原因**:
  - 数据产生速度超过SD卡写入速度
  - SD卡性能不足（低速卡）
  - 缓冲区大小不足
- **建议**: 
  - 使用更高速的SD卡（Class 10或UHS-I）
  - 增大缓冲区大小
  - 优化数据采集频率

### 写入速度异常
- **现象**: 平均写入大小异常小或写入频率异常高
- **可能原因**: 缓冲区切换策略不当
- **建议**: 调整缓冲区大小或刷新策略

## 版本历史

- **v1.0** (2026-02-06): 初始版本，添加SD卡存储监控功能