From f5f354dc4659f91ed4483cbf360cea4ec81f9733 Mon Sep 17 00:00:00 2001
From: Gatsby Van <gatsby_van@163.com>
Date: Sun, 27 Oct 2024 22:26:20 +0800
Subject: [PATCH] doc: add README

---
 README.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)

diff --git a/README.md b/README.md
index 00e3857..ea159ac 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,82 @@
 # CX9261API-C
 
+本项目实现了 `cx9261A_api` 的 C++ 到 C 的封装，使 C 程序能够直接链接并调用 `cx9261A_api`。
+
+## C 封装的转换说明
+
+在封装过程中，我们对原始 API 进行了如下调整：
+
+1. **命名转换**：  
+   原始 API 中的所有命名空间 `CX9261A::` 被转换为 C 语言风格的前缀 `CX9261A_`，对应的数据类型也进行了同样的转换。例如：
+   
+   - 原始 API：`CX9261A::Clock`
+   - C 封装：`CX9261A_Clock`
+
+2. **参数传递方式的修改**：  
+   - 原始 API 中使用的 `const` 结构体引用在 C 封装中统一改为 **`const` 指针传递**。
+   - 例如：  
+     原始 API：`void configAGC(const CX9261A::AGCDIG& agc)`  
+     C 封装：`void CX9261A_configAGC(const CX9261A_AGCDIG* agc)`
+
+3. **数据拷贝的使用**：  
+   为避免可能存在的 ABI 和数据布局不兼容问题，C 封装在部分接口中引入了数据的深拷贝操作。后续会进行优化以减少不必要的拷贝开销。
+
+## 目录结构
+
+```plaintext
+.
+├── Makefile              # 构建项目的Makefile
+├── cx9261A_api/          # 原始 API 目录
+│   ├── CX9261A API.pdf   # 原始 API 说明文档
+│   ├── cx9261adriver.cpp # C++ API 实现文件
+│   ├── cx9261adriver.h   # C++ API 头文件
+│   ├── defs.h            # C++ API 数据类型定义文件
+│   └── utils.h           # C++ API 辅助工具头文件
+├── cx9261adriver_c.cpp   # C 封装的实现文件
+├── cx9261adriver_c.h     # C 封装的头文件
+└── ld_test.c             # 测试编译链接文件
+```
+
+## 编译与使用
+
+### 环境要求
+
+- **工具链**：建议使用 `gcc-arm-embedded` 编译器，或使用 Xilinx SDK/Vitis 提供的交叉编译工具链。
+- **目标平台**：默认添加了 Cortex R5、Cortex A9 和 Cortex A53 三个目标平台。如需加入其他目标请确保所使用的工具链与目标平台兼容，编译配置中启用了硬件浮点请做出合适的修改以兼容目标平台。
+
+### 编译步骤
+
+1. 在项目目录下，运行以下命令生成静态库文件：
+
+    ```bash
+    make all
+    ```
+
+2. 编译完成后，生成的库文件会存放在 `build/<cpu>` 目录下，其中 `<cpu>` 为指定的目标 CPU 架构。不同架构的二进制文件分别存储在对应的子目录中。
+
+### 链接依赖
+
+将本项目的库文件链接至您的 C 项目时，需要附加以下库：
+
+- **`stdc++`**：支持 C++ STL 容器（如 `vector`、`map` 等）。
+- **`m`**：包含数学相关函数。
+
+## TODO
+
+- **优化数据拷贝**：  
+  目前的封装中，为了避免潜在的 ABI 和数据布局不兼容问题，在多个接口中引入了数据的深拷贝。后续会针对这些部分进行性能优化，以减少不必要的拷贝开销。
+
+## 常见问题
+
+1. **如何配置目标架构？**  
+   - 在 `Makefile` 中修改目标架构配置，或通过命令行参数指定目标 CPU。确保使用的工具链支持所选架构。
+
+2. **链接错误：`undefined reference to 'std::...'`**  
+   - 该错误通常由缺少 `stdc++` 库链接导致，请在编译时添加 `-lstdc++`。
+
+3. **链接错误：`undefined reference to 'round'`**  
+   - 该错误通常由缺少 `m` 库链接导致，请在编译时添加 `-lm`。
+
+## 贡献
+
+如果您发现问题或有新的功能需求，欢迎通过 `issue` 或 `pull request` 参与贡献。