# c-error-handler

**Repository Path**: MagicBude/c-error-handler

## Basic Information

- **Project Name**: c-error-handler
- **Description**: 轻量级、可移植的C语言错误处理库，专为嵌入式系统设计。提供分层错误码、错误追踪、日志记录等功能，支持ESP32/RT-Thread/STM32/FreeRTOS等20+平台，零依赖，开箱即用。
- **Primary Language**: C
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-22
- **Last Updated**: 2025-10-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# C Error Handler

[English](README.en.md) | 简体中文

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Language](https://img.shields.io/badge/language-C99-blue.svg)](https://en.wikipedia.org/wiki/C99)
[![Platform](https://img.shields.io/badge/platform-Embedded-green.svg)](https://en.wikipedia.org/wiki/Embedded_system)
[![Gitee](https://img.shields.io/badge/Gitee-c--error--handler-red.svg)](https://gitee.com/MagicBude/c-error-handler)

> 轻量级、可移植的C语言错误处理系统，专为嵌入式项目设计

一个统一的错误码定义、错误追踪和日志系统，提供清晰的错误处理路径，适用于资源受限的嵌入式C项目。

---

## ✨ 特性

- **🎯 分层错误码** - 通用错误 (0-99) + 模块专用错误 (100+)
- **📝 错误追踪** - 自动记录函数名、行号、时间戳
- **📊 错误日志** - 循环缓冲区，可配置大小
- **📈 错误统计** - 统计每种错误出现次数
- **⚙️ 可裁剪** - 通过宏控制功能，最小0字节RAM
- **🎯 易用性** - 便捷的宏 `CHECK_NULL_POINTER()` 等
- **🚀 轻量级** - 约2KB代码，1.3KB RAM（可配置）
- **🌐 多平台** - 支持ESP32/RT-Thread/STM32/FreeRTOS/裸机

---

## 📁 目录结构

```
error_handler/
├── include/                   # 公开接口
│   ├── error_handler.h       # 主接口文件（用户只需包含此文件）
│   ├── error_codes.h         # 错误码定义和工具函数
│   └── error_port.h          # 平台适配层接口
├── src/                      # 实现
│   └── error_codes.c         # 错误处理实现
├── port/                     # 平台适配层实现
│   ├── error_port.c          # 统一的平台适配（条件编译）
│   └── README.md             # Port层说明
├── examples/                 # 示例代码
│   └── basic_usage.c         # 基本使用示例
├── docs/                     # 文档
│   └── INTEGRATION.md        # 集成指南
├── LICENSE                   # MIT许可证
├── CHANGELOG.md              # 更新日志
└── README.md                 # 本文件
```

---

## 🚀 快速开始

### 1. 集成到项目

#### 方法A：直接复制

```bash
# 将整个 error_handler/ 目录复制到你的项目
cp -r error_handler/ your_project/
```

#### 方法B：作为子模块（推荐）

```bash
# 在你的项目根目录
git submodule add https://gitee.com/MagicBude/c-error-handler.git libs/error_handler
```

### 2. 配置平台

通过编译选项定义平台宏：

```bash
# ESP32 (ESP-IDF会自动定义，无需配置)
# 自动检测

# RT-Thread (通常自动定义RT_USING_RTTHREAD)
-DUSING_RTTHREAD

# STM32F1
-DSTM32F1

# STM32F4 + FreeRTOS
-DSTM32F4 -DUSING_FREERTOS

# 裸机
-DERROR_PORT_BAREMETAL
```

**支持平台：** ESP32、RT-Thread、STM32全系列、FreeRTOS、裸机

详见 `port/README.md`

### 3. 配置头文件路径

**Makefile:**
```makefile
INCLUDES += -I./error_handler/include
```

**CMake:**
```cmake
target_include_directories(your_target PRIVATE
    error_handler/include
)
```

**Keil/IAR:**
```
添加包含路径：./error_handler/include
```

### 4. 包含头文件

```c
#include "error_handler.h"  /* 简短路径 */
```

### 5. 基本使用

```c
/**
 * @brief 示例函数
 */
ErrorCode_t ProcessData(float *data, size_t size)
{
    /* 检查空指针 */
    CHECK_NULL_POINTER(data);
    
    /* 检查参数范围 */
    CHECK_PARAM(size > 0);
    CHECK_RANGE(*data, 0.0f, 100.0f);
    
    /* 调用其他函数并自动传播错误 */
    CHECK_ERROR(ValidateData(data, size));
    CHECK_ERROR(SaveData(data, size));
    
    return ERR_OK;
}
```

### 4. 错误处理

```c
ErrorCode_t result = ProcessData(data, size);

if (result != ERR_OK)
{
    /* 获取错误描述 */
    printf("Error: %s\n", Error_CodeToString(result));
    
    /* 获取错误严重级别 */
    if (Error_GetSeverity(result) == ERR_SEVERITY_CRITICAL)
    {
        /* 处理严重错误 */
        EnterSafeMode();
    }
}
```

---

## 📝 错误码分类

### 通用错误码 (0-99)

| 范围 | 类别 | 示例 |
|------|------|------|
| 0 | 成功 | `ERR_OK` |
| 1-19 | 参数错误 | `ERR_NULL_POINTER`, `ERR_INVALID_PARAM`, `ERR_OUT_OF_RANGE` |
| 20-39 | 资源错误 | `ERR_NO_MEMORY`, `ERR_BUSY`, `ERR_TIMEOUT` |
| 40-59 | 操作错误 | `ERR_NOT_INITIALIZED`, `ERR_OVERFLOW`, `ERR_NOT_SUPPORTED` |
| 60-79 | 硬件错误 | `ERR_HARDWARE_FAULT`, `ERR_IO_ERROR`, `ERR_CRC_ERROR` |
| 80-99 | 通信错误 | `ERR_COMM_ERROR`, `ERR_NO_RESPONSE`, `ERR_PROTOCOL_ERROR` |

### 模块专用错误码 (100+)

每个模块预留20个错误码，**按由浅入深、常用到不常用排序**：

#### 基础外设 (100-199)

| 范围 | 模块 | 示例 |
|------|------|------|
| 100-119 | **UART** | `ERR_UART_TIMEOUT`, `ERR_UART_OVERRUN`, `ERR_UART_FRAME_ERROR` |
| 120-139 | **I2C** | `ERR_I2C_TIMEOUT`, `ERR_I2C_NACK`, `ERR_I2C_BUS_ERROR` |
| 140-159 | **SPI** | `ERR_SPI_TIMEOUT`, `ERR_SPI_BUSY`, `ERR_SPI_CRC_ERROR` |
| 160-179 | **Timer** | `ERR_TIMER_NOT_STARTED`, `ERR_TIMER_OVERFLOW` |
| 180-199 | **DMA** | `ERR_DMA_TRANSFER_ERROR`, `ERR_DMA_TIMEOUT` |

#### 存储设备 (200-299)

| 范围 | 模块 | 示例 |
|------|------|------|
| 200-219 | **EEPROM** | `ERR_EEPROM_WRITE_FAIL`, `ERR_EEPROM_READ_FAIL` |
| 220-239 | **Flash** | `ERR_FLASH_WRITE_FAIL`, `ERR_FLASH_ERASE_FAIL` |
| 240-259 | **SD卡** | `ERR_SD_NOT_PRESENT`, `ERR_SD_INIT_FAIL` |
| 260-279 | **文件系统** | `ERR_FS_NOT_MOUNTED`, `ERR_FS_FILE_NOT_FOUND` |

#### 高级外设 (300-399)

| 范围 | 模块 | 示例 |
|------|------|------|
| 300-319 | **ADC** | `ERR_ADC_CONVERSION_FAIL`, `ERR_ADC_TIMEOUT` |
| 320-339 | **DAC** | `ERR_DAC_OUTPUT_FAIL`, `ERR_DAC_CALIBRATION_FAIL` |
| 340-359 | **RTC** | `ERR_RTC_NOT_INITIALIZED`, `ERR_RTC_INVALID_TIME` |
| 360-379 | **Display** | `ERR_DISPLAY_INIT_FAIL`, `ERR_DISPLAY_TIMEOUT` |

#### 通信协议 (400-459)

| 范围 | 模块 | 示例 |
|------|------|------|
| 400-419 | **CAN** | `ERR_CAN_TIMEOUT`, `ERR_CAN_BUS_OFF` |
| 420-439 | **USB** | `ERR_USB_NOT_CONNECTED`, `ERR_USB_TIMEOUT` |
| 440-459 | **Network** | `ERR_NET_NOT_CONNECTED`, `ERR_NET_TIMEOUT` |

#### 应用模块 (460+)

| 范围 | 模块 | 示例 |
|------|------|------|
| 460-479 | **传感器** | `ERR_SENSOR_FAULT`, `ERR_SENSOR_OUT_OF_RANGE` |
| 480+ | 用户自定义 | 根据项目需要添加 |

**粗体模块**为嵌入式常用模块。

---

## ⚙️ 配置选项

在 `error_codes.h` 中配置：

```c
/* 启用错误日志（占用约1.3KB RAM） */
#define ERROR_LOG_ENABLED           1

/* 错误日志缓冲区大小 */
#define ERROR_LOG_MAX_ENTRIES       16

/* 启用错误追踪（记录函数名和行号） */
#define ERROR_TRACE_ENABLED         1
```

### 配置方案

| 场景 | LOG_ENABLED | TRACE_ENABLED | RAM | Flash |
|------|-------------|---------------|-----|-------|
| 完整调试 | 1 | 1 | 1.3KB | 2KB |
| 精简调试 | 1 | 0 | 1.3KB | 1.5KB |
| 发布版本 | 0 | 0 | 0B | 1KB |

---

## 📚 API 参考

### 错误码工具

```c
/* 错误码转字符串 */
const char* Error_CodeToString(ErrorCode_t code);

/* 获取错误严重级别 */
ErrorSeverity_e Error_GetSeverity(ErrorCode_t code);
```

### 错误日志

```c
/* 记录错误（通常通过宏调用） */
void Error_Log(ErrorCode_t code, const char *function, uint32_t line);

/* 获取最后一次错误 */
const ErrorInfo_t* Error_GetLastError(void);

/* 清除错误日志 */
void Error_ClearLog(void);

/* 打印错误日志 */
void Error_PrintLog(void);
```

### 错误统计

```c
/* 获取特定错误次数 */
uint32_t Error_GetCount(ErrorCode_t code);

/* 获取总错误次数 */
uint32_t Error_GetTotalCount(void);
```

### 便捷宏

```c
/* 返回错误并记录 */
RETURN_ERROR(code);

/* 检查错误并传播 */
CHECK_ERROR(expr);

/* 检查空指针 */
CHECK_NULL_POINTER(ptr);

/* 检查参数 */
CHECK_PARAM(condition);

/* 检查范围 */
CHECK_RANGE(value, min, max);
```

---

## 📖 示例代码

### 基本错误检查

```c
ErrorCode_t MyFunction(uint8_t *buffer, size_t size)
{
    CHECK_NULL_POINTER(buffer);
    CHECK_PARAM(size > 0 && size <= 256);
    
    /* 处理数据... */
    
    return ERR_OK;
}
```

### 错误传播

```c
ErrorCode_t HighLevelFunction(void)
{
    CHECK_ERROR(InitHardware());
    CHECK_ERROR(LoadConfig());
    CHECK_ERROR(StartTask());
    
    return ERR_OK;
}
```

### 带重试机制的操作

```c
ErrorCode_t WriteEEPROM(uint16_t addr, uint8_t *data, size_t size)
{
    uint8_t retry;
    
    CHECK_NULL_POINTER(data);
    
    for (retry = 0; retry < 3; retry++)
    {
        if (HAL_I2C_Write(...) == HAL_OK)
        {
            return ERR_OK;
        }
        HAL_Delay(10);
    }
    
    RETURN_ERROR(ERR_EEPROM_WRITE_FAIL);
}
```

更多示例见 `examples/` 目录。

---

## 🔧 集成指南

详细的集成指南请参见 [`docs/INTEGRATION.md`](docs/INTEGRATION.md)，包括：
- 不同构建系统的集成方法（CMake、Makefile、Keil等）
- 现有项目迁移步骤
- 最佳实践
- 常见问题

---

## 🧪 测试

```c
/* 在调试模式下测试错误处理 */
void TestErrorHandling(void)
{
    Error_ClearLog();
    
    /* 触发一些错误 */
    MyFunction(NULL, 0);
    
    /* 打印错误日志 */
    Error_PrintLog();
    
    /* 查看统计 */
    printf("NULL pointer errors: %lu\n", Error_GetCount(ERR_NULL_POINTER));
}
```

---

## 📊 性能数据

基于 STM32F1 (72MHz Cortex-M3) 测试：

| 操作 | 耗时 | 说明 |
|------|------|------|
| `CHECK_NULL_POINTER` | < 1µs | 宏展开，无函数调用 |
| `Error_Log` | ~5µs | 记录到循环缓冲区 |
| `Error_CodeToString` | ~1µs | 查表操作 |

---

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

---

## 📄 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件

---

## 🙏 致谢

- 参考了 Linux Kernel errno 设计
- 借鉴了 STM32 HAL 错误处理机制
- 感谢所有贡献者

---

## 📮 反馈与贡献

- **提交Issue**: [Gitee Issues](https://gitee.com/MagicBude/c-error-handler/issues)
- **功能建议**: 欢迎在Issues中提出
- **Bug报告**: 请提供复现步骤和环境信息
- **Pull Request**: 遵循现有代码风格

---

## ⭐ 如果觉得有用，请给个Star！

---

**版本：** v1.0.1  
**最后更新：** 2025-10-22  
**作者：** MagicBude  
**许可证：** MIT