# CRB - Core Runtime Base

**Repository Path**: rachcham/crb

## Basic Information

- **Project Name**: CRB - Core Runtime Base
- **Description**: No description available
- **Primary Language**: C
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-12
- **Last Updated**: 2025-08-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CRB (Core Runtime Base) - 企业级嵌入式C语言框架

> **注意**: 本项目在 Gitee 和 GitHub 上进行同步维护。Gitee 仓库为 **中文版** (本文档、代码注释)，GitHub 仓库为对应的 **英文版**。

**CRB (Core Runtime Base)** 是一个为构建健壮、可靠、可移植的实时嵌入式系统而设计的企业级分层C语言框架。它以 **MISRA C** 标准为基石，通过严格的软件工程规范和分层架构，旨在为复杂的嵌入式应用提供一个坚实、可维护且高效的软件基础平台。

## 核心设计哲学

`CRB` 框架的设计遵循三大核心原则：

1. **确定性与可靠性 (Deterministic & Reliable)**: 系统的每一个核心机制，从错误处理到内存管理，都经过精心设计，以确保在严苛的实时环境下的行为可预测性和高度可靠性。
    
2. **分层与解耦 (Layered & Decoupled)**: 严格的四层架构设计，确保上层应用逻辑与底层硬件平台完全分离，极大地提升了代码的可移植性、可测试性和可重用性。
    
3. **规范驱动开发 (Specification-Driven)**: 项目的开发流程由一系列明确的规范文档驱动，涵盖命名、编码风格、版本控制到测试流程，确保团队协作的一致性和项目的长期健康。
    

## 核心特性

`CRB` 框架提供了一系列经过精心设计和单元测试的内置功能，旨在解决嵌入式开发中的常见痛点。

### 架构与可移植性

|   |   |   |
|---|---|---|
|**特性 (Feature)**|**状态 (Status)**|**备注 (Notes)**|
|**清晰的四层架构设计**|✅|应用、服务、驱动、平台完全解耦。|
|**统一的平台抽象层 (PAL)**|✅|已适配STM32 HAL，可轻松扩展至其他MCU。|
|**可裁剪的RTOS抽象层 (OSAL)**|✅|已适配FreeRTOS/RT-Thread，可完全禁用以支持裸机。|
|**裸机 (Bare-metal) 开发支持**|🟡|规划中，将允许在无RTOS环境下独立运行驱动和服务。|

### 安全与可靠性

|                            |                 |                             |
| -------------------------- | --------------- | --------------------------- |
| **特性 (Feature)**           | **状态 (Status)** | **备注 (Notes)**              |
| **核心原语 (Core Primitives)** | ✅               | 提供基础类型、错误码、断言、内存管理接口。       |
| **32位分层错误码体系**             | ✅               | 精确到模块的错误定位，便于快速诊断问题。        |
| **可配置的自定义断言**              | ✅               | 符合MISRA标准，开发时“快速失败”，发布时零开销。 |
| **混合内存管理策略**               | ☑️              | 支持纯静态分配与受控动态分配两种模式。         |

### 通用模块与数据结构

|                   |                 |                                    |
| ----------------- | --------------- | ---------------------------------- |
| **特性 (Feature)**  | **状态 (Status)** | **备注 (Notes)**                     |
| **线程安全的环形缓冲区**    | ✅               | `crb_ds_ringbuffer`，经过单元测试。        |
| **有限状态机 (FSM)**   | 🟡              | `crb_ds_fsm`，规划中。                  |
| **内存安全的字符串库**     | ✅               | `crb_util_safe_string`，替代标准库不安全函数。 |
| **自动化序列化/反序列化引擎** | ✅               | `crb_util_serdes`，基于描述符，高效安全。      |
| **通用数据包封包/解包。**   | ☑️              | `crb_util_packet_framing`，开发中         |



### 系统服务与驱动

|                         |                 |                                 |
| ----------------------- | --------------- | ------------------------------- |
| **特性 (Feature)**        | **状态 (Status)** | **备注 (Notes)**                  |
| **异步非阻塞日志服务**           | ✅               | `crb_svc_log`，中断安全，对实时性能影响极小。   |
| **CAN总线驱动**             | ✅               | `crb_hal_can`，已在STM32F4上验证。     |
| **IMU传感器驱动**            | ✅               | `crb_drivers/sensors/imu`，分层设计。 |
| **Bootloader (IAP) 服务** | 🟡              | `crb_services/bootloader`，规划中。  |
| **显示驱动**                | 🟡              | `crb_drivers/display/`，规划中。     |
| **Flash存储驱动**           | 🟡              | `crb_drivers/storage/`，规划中。     |

## 架构设计

`CRB` 采用严格的分层架构，各层之间通过明确定义的API进行通信，实现了高度的模块化和可移植性。
![CRB_Architectture](images/CRB_Architectture.png)

- **应用层 (Application Layer)**: 系统的顶层业务逻辑。
    
- **服务层 (Services Layer)**: 提供与具体硬件无关的高级功能，如日志、低功耗管理等。
    
- **驱动层 (Drivers Layer)**: 提供与具体外部设备（传感器、存储器等）交互的接口。
    
- **平台抽象层 (Platform Abstraction Layer - PAL)**: 框架的核心，它将底层硬件（MCU片上外设）和RTOS内核的差异进行封装，为上层提供统一、标准的接口。
    

## 快速上手

### 1. 环境准备

本项目使用 `Ceedling` 进行单元测试，并通过 `bundler` 管理其版本。请确保您已安装 Ruby 和 bundler。

```
# (如果未安装)
gem install bundler
```

### 2. 克隆仓库

```
# 克隆 Gitee (中文版) 仓库
git clone git@gitee.com:rachcham/crb.git

# 克隆 GitHub (英文版) 仓库
git clone git@github.com:irontxZZZ/CoreRuntimeBase.git
```

### 3. 构建与运行示例

以 `stm32f4_can_imu_demo` 为例：

```
# 进入示例工程目录并构建
cd examples/stm32f4_can_imu_demo/build
cmake ..
make -j
```

> 详细的环境准备、项目配置和编译指南，请参阅 `docs/BUILD_GUIDE.md`。

## 项目文档

我们坚信完备的文档是项目成功的关键。`CRB` 框架提供两种形式的文档：

- **API参考手册**: 所有对外接口均遵循 **Doxygen** 规范编写了详细注释。您可以通过CI/CD流程自动生成HTML格式的API手册。
    
- **设计与规范文档**: 位于 `/docs` 目录下，使用 Markdown 编写，包含了框架的核心设计决策、架构图、命名规范、协作流程等关键信息。
    

## 贡献指南

我们欢迎任何形式的贡献！如果您希望为 `CRB` 框架贡献代码，请您务必仔细阅读我们的贡献指南，它详细说明了我们的开发流程、代码风格和提交规范。

核心协作规范摘要：

- **分支模型**: 采用 **GitHub Flow**。所有变更都应在独立的 `feature/...` 或 `fix/...` 分支上进行，并通过 **Pull Request** 合入 `master`。
    
- **代码风格**: 项目根目录下的 `.clang-format` 文件定义了唯一的代码风格，请在提交前使用它格式化您的代码。
    
- **提交信息**: 采用 [**约定式提交 (Conventional Commits)**](https://www.conventionalcommits.org/ "null") 规范，如 `feat(hal): add spi support`。
    
- **单元测试**: 核心的、平台无关的模块**必须**提供完整的单元测试用例。我们使用 `Ceedling` + `CMock` 进行测试驱动开发(TDD)。
    

## 发展路线图 (Roadmap)

- **v1.1**:
    
    - [ ] 完成Bootloader (IAP)服务的实现。
        
    - [ ] 增加对低功耗管理服务的支持。
        
    - [ ] 增加对RISC-V架构（如ESP32-C3）的平台适配。
        
- **v1.2**:
    
    - [ ] 引入对C++包管理器（如CMake FetchContent）的支持。
        
    - [ ] 增加对TCP/IP协议栈的抽象和集成。
        

## 致谢

本框架的设计和实现受到了以下优秀开源项目的深刻启发，在此表示诚挚的感谢：

- **FreeRTOS**: 提供了企业级的实时内核和卓越的编码风格典范。
    
- **Zephyr Project**: 在设备模型和驱动架构方面提供了宝贵的参考。
    
- **AUTOSAR**: 其分层、组件化的思想是本框架架构设计的核心灵感来源。
    

## 许可证

本项目采用 **MIT许可证**。详情请参阅 `LICENSE` 文件。

Copyright (c) 2025 Ironside Zhang