From 69352e92cf2ae0a425794d02c3efc8e7bf9db8de Mon Sep 17 00:00:00 2001 From: Nova Date: Tue, 28 Jul 2026 00:45:49 +0800 Subject: [PATCH] refactor: sync from template - ENABLE/DISABLE macro pattern - board_config.h: replace #define/#undef with ENABLE/DISABLE constants - All debug switches use ENABLE/DISABLE instead of define/undef - Replace #ifdef with #if MACRO == ENABLE across all sources - Sync updated README documentation --- Inc/board_config.h | 25 ++++---- Inc/i2c.h | 4 +- README.md | 141 ++++++++++++++++++++++++++++++++++++++++----- Src/command.c | 4 +- Src/gd32e23x_it.c | 2 +- Src/i2c.c | 44 +++++++------- Src/main.c | 6 +- 7 files changed, 171 insertions(+), 55 deletions(-) diff --git a/Inc/board_config.h b/Inc/board_config.h index dda76b5..415a9cf 100644 --- a/Inc/board_config.h +++ b/Inc/board_config.h @@ -1,6 +1,14 @@ #ifndef BOARD_CONFIG_H #define BOARD_CONFIG_H +#ifndef DISABLE +#define DISABLE 0 +#endif + +#ifndef ENABLE +#define ENABLE 1 +#endif + #define GD32E23XF4 0x10 #define GD32E23XF6 0x20 #define GD32E23XF8 0x40 @@ -11,30 +19,25 @@ /* >>>>>>>>>>>>>>>>>>>>[IIC TYPE DEFINE]<<<<<<<<<<<<<<<<<<<< */ -// #define SOFTWARE_IIC // IIC Type : Software IIC -#undef SOFTWARE_IIC // IIC Type : Hardware IIC +#define SOFTWARE_IIC DISABLE // DISABLE: Hardware IIC; ENABLE: Software IIC /* >>>>>>>>>>>>>>>>>>>>[DEBUG MODE]<<<<<<<<<<<<<<<<<<<< */ -// #define DEBUG_MODE // Operating Mode : Debug Mode -#undef DEBUG_MODE // Operating Mode : Release Mode +#define DEBUG_MODE DISABLE // DISABLE: Release Mode; ENABLE: Debug Mode /* >>>>>>>>>>>>>>>>>>>>[COMMAND DEBUG]<<<<<<<<<<<<<<<<<<<< */ -// #define COM_DEBUG // Enable Command Debug Information -#undef COM_DEBUG // Disable Command Debug Information +#define COM_DEBUG DISABLE // DISABLE: Command debug off; ENABLE: Command debug on /* >>>>>>>>>>>>>>>>>>>>[DEBUG ASSERTIONS DEFINE]<<<<<<<<<<<<<<<<<<<< */ -// #define DEBUG_VERBOSE // Debug Assertions Status : Debug Verbose Information -#undef DEBUG_VERBOSE // Debug Assertions Status : No Debug Verbose Information +#define DEBUG_VERBOSE DISABLE // DISABLE: Verbose debug off; ENABLE: Verbose debug on /* >>>>>>>>>>>>>>>>>>>>[SEGGER RTT DETECTION]<<<<<<<<<<<<<<<<<<<< */ -#define SEGGER_RTT_DETECTION // SEGGER RTT Detection : Enable -// #undef SEGGER_RTT_DETECTION // SEGGER RTT Detection : Disable +#define SEGGER_RTT_DETECTION ENABLE // DISABLE: SEGGER RTT off; ENABLE: SEGGER RTT on -#ifdef SEGGER_RTT_DETECTION +#if SEGGER_RTT_DETECTION == ENABLE #include "SEGGER_RTT.h" #define RTT_printf(ch, ...) SEGGER_RTT_printf(ch, __VA_ARGS__) #define RTT_WriteString(ch, s) SEGGER_RTT_WriteString(ch, s) diff --git a/Inc/i2c.h b/Inc/i2c.h index ab42e62..c3319d4 100644 --- a/Inc/i2c.h +++ b/Inc/i2c.h @@ -86,7 +86,9 @@ i2c_result_t i2c_bus_reset(void); \param[out] none \retval none */ +#if DEBUG_VERBOSE == ENABLE void i2c_scan(void); +#endif /*! \brief write 16-bit data to I2C device @@ -139,7 +141,7 @@ i2c_result_t i2c_read(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint8 */ i2c_result_t i2c_read_raw(uint8_t slave_addr, uint8_t *data, uint8_t length); -#ifdef DEBUG_VERBOSE +#if DEBUG_VERBOSE == ENABLE /*! \brief get status string for debugging \param[in] status: i2c_result_t value diff --git a/README.md b/README.md index f1ec269..1470ef5 100644 --- a/README.md +++ b/README.md @@ -108,39 +108,148 @@ --- -## 板级配置 +## 板级配置（`Inc/board_config.h`） -编辑 `Inc/board_config.h` 可切换以下功能： +所有功能开关和引脚定义集中在 `Inc/board_config.h`。功能开关均为单行数值宏：将右侧的 `ENABLE` 或 `DISABLE` 改为另一值即可；其中 `ENABLE` 为 `1`，`DISABLE` 为 `0`。以下为完整的宏开关说明和推荐使用方式。 + +### 功能开关速查表 + +| 宏 | 作用 | 默认值 | Release 建议 | +|---|------|:---:|:---:| +| `SOFTWARE_IIC` | I2C 实现方式 | `DISABLE`（硬件） | `DISABLE` | +| `DEBUG_MODE` | printf 串口输出 | `DISABLE` | `DISABLE` | +| `COM_DEBUG` | 命令帧调试打印 | `DISABLE` | `DISABLE` | +| `DEBUG_VERBOSE` | 详细调试信息 | `DISABLE` | `DISABLE` | +| `SEGGER_RTT_DETECTION` | SEGGER RTT 支持 | `ENABLE` | `DISABLE` | + +--- + +### `SOFTWARE_IIC` — I2C 实现方式 + +选择 I2C 使用硬件外设还是软件 GPIO 模拟。 + +> 当前工程尚未实现 `SOFTWARE_IIC` 的条件编译驱动选择；该宏已迁移为数值配置，但改值不会在此版本切换 I2C 实现。 ```c -/* I2C 类型：软件 I2C 或 硬件 I2C */ -// #define SOFTWARE_IIC -#undef SOFTWARE_IIC - -/* 调试模式：开启 printf 输出 */ -// #define DEBUG_MODE -#undef DEBUG_MODE - -/* 调试详细模式：I2C 扫描等额外信息 */ -// #define DEBUG_VERBOSE -#undef DEBUG_VERBOSE +#define SOFTWARE_IIC DISABLE // DISABLE: 硬件 I2C（默认）；ENABLE: 软件 I2C（GPIO 模拟） ``` -引脚定义集中在同一文件中，按需修改： +| 选项 | 优点 | 缺点 | +|------|------|------| +| 硬件 I2C | DMA 支持、CPU 占用低 | 仅限固定引脚、调试复杂 | +| 软件 I2C | 任意 GPIO、移植方便 | CPU 占用高、速率受限 | + +> 切换后需同步修改下方 I2C 引脚定义。 + +--- + +### `DEBUG_MODE` — 调试模式 + +开启后 USART0 输出 printf 调试信息。**Release 固件必须关闭。** ```c +#define DEBUG_MODE DISABLE // DISABLE: 关闭（默认）；ENABLE: 开启调试输出 +``` + +**影响范围：** +- 使能 `USART0` 初始化和 `printf` 重定向到串口 +- 会占用 PA2/PA3 引脚和 USART0 硬件资源 +- 增加 ROM 约 2~4KB（取决于 printf 调用量） + +--- + +### `COM_DEBUG` — 命令帧调试打印 + +开启后串口命令解析过程打印每帧的详细内容（地址、长度、数据、校验）。**仅调试通信协议时开启。** + +```c +#define COM_DEBUG DISABLE // DISABLE: 关闭（默认）；ENABLE: 开启命令帧调试 +``` + +**依赖：** 需要先开启 `DEBUG_MODE`，否则输出无法外发。 + +**输出示例：** +```text +[CMD] ADDR=01 LEN=05 DATA: AA BB CC DD EE CHK=OK +``` + +> ⚠️ Release 必须关闭，否则大量串口输出会严重拖慢主循环。 + +--- + +### `DEBUG_VERBOSE` — 详细调试信息 + +在 `DEBUG_MODE` 基础上输出更底层的信息，如 I2C 总线扫描结果、MCU 型号识别等。 + +```c +#define DEBUG_VERBOSE DISABLE // DISABLE: 关闭（默认）；ENABLE: 开启详细调试 +``` + +**额外输出：** +- 启动时打印 MCU Flash 容量检测结果 +- I2C 初始化时扫描总线上的设备地址 +- 其他诊断信息 + +> 依赖 `DEBUG_MODE`，开启后 ROM 进一步增加约 1~2KB。 + +--- + +### `SEGGER_RTT_DETECTION` — SEGGER RTT 支持 + +RTT（Real-Time Transfer）是 SEGGER 的调试通道技术，通过 SWD 接口传输数据，不占用串口引脚，速度远超 UART。 + +```c +#define SEGGER_RTT_DETECTION ENABLE // DISABLE: 禁用 RTT；ENABLE: 启用 RTT（默认） +``` + +**启用时：** +- 自动包含 `SEGGER_RTT.h`，提供 `RTT_printf` / `RTT_WriteString` / `RTT_PutChar` 宏 +- `SDK/SEGGER_RTT/` 模块参与编译和链接 +- 可用 J-Link RTT Viewer 或 VSCode + cortex-debug 查看实时日志 + +**禁用时：** +- 应用层 RTT 头文件引用与调用代码均在预处理阶段排除 +- RTT 宏展开为空操作；应用目标不生成 RTT 调用代码 +- 为保持现有 CMake SDK 加载方式，`SDK/SEGGER_RTT/` 仍会参与构建；静态库中未被引用的对象不会被链接器提取 + +> **Release 建议关闭** — RTT 依赖调试器连接，量产固件中无意义且占用 ROM。 + +**依赖关系总览：** +``` +COM_DEBUG ──── 依赖 ──→ DEBUG_MODE +DEBUG_VERBOSE ─ 依赖 ──→ DEBUG_MODE +SEGGER_RTT_DETECTION ─ 独立，与 DEBUG_MODE 并行 +``` + +--- + +### 引脚定义 + +所有引脚宏集中在 `board_config.h` 尾部，按需修改： + +```c +/* I2C */ #define I2C_SCL_PORT GPIOF #define I2C_SCL_PIN GPIO_PIN_1 #define I2C_SDA_PORT GPIOF #define I2C_SDA_PIN GPIO_PIN_0 -#define LED_PORT GPIOA -#define LED_PIN GPIO_PIN_7 +/* LED */ +#define LED_RCU RCU_GPIOB +#define LED_PORT GPIOB +#define LED_PIN GPIO_PIN_1 +/* UART */ +#define UART_GPIO_PORT GPIOA #define UART_TX_PIN GPIO_PIN_2 #define UART_RX_PIN GPIO_PIN_3 +#define UART_BAUDRATE 115200U ``` +### MCU 型号自动检测 + +`board_config.c` 中的 `mcu_detect_and_config()` 上电自动识别 GD32E230 的 Flash 容量（F4=16K / F6=32K / F8=64K），结果存入全局变量 `g_mcu_flash_size`，并自动选择对应的 UART 外设（USART0 或 USART1）。 + --- ## Flash 偏移配置（配合 Bootloader） diff --git a/Src/command.c b/Src/command.c index 1e7c72c..ab423cf 100644 --- a/Src/command.c +++ b/Src/command.c @@ -101,7 +101,7 @@ void system_software_reset(void) } /* Debug output control */ -#ifdef COM_DEBUG +#if COM_DEBUG == ENABLE #include #define COMMAND_DEBUG(fmt, ...) printf("[COMMAND] " fmt "\n", ##__VA_ARGS__) #else @@ -565,7 +565,7 @@ void command_process(void) { // 到帧尾，进行各项校验 bool verification_status = true; - #ifdef DEBUG_VERBOSE + #if DEBUG_VERBOSE == ENABLE if (cmd_buf[0] != PROTOCOL_PACKAGE_HEADER) { send_response(RESP_TYPE_HEADER_ERR, s_report_status_err, sizeof(s_report_status_err)); verification_status = false; diff --git a/Src/gd32e23x_it.c b/Src/gd32e23x_it.c index 6c67dbb..b7b49cc 100644 --- a/Src/gd32e23x_it.c +++ b/Src/gd32e23x_it.c @@ -108,7 +108,7 @@ void USART0_IRQHandler(void) { g_usart_config.irq_handler(); // 通过函数指针调用对应的处理函数 } // 作为调试口（第二串口）时也接收数据，便于模拟上位机命令 -#ifdef DEBUG_MODE +#if DEBUG_MODE == ENABLE else { usart0_irq_handler(); } diff --git a/Src/i2c.c b/Src/i2c.c index 66c9dcd..4dadd06 100644 --- a/Src/i2c.c +++ b/Src/i2c.c @@ -79,7 +79,7 @@ i2c_result_t i2c_bus_reset(void) { i2c_disable(I2C0); i2c_deinit(I2C0); -#ifdef DEBUG_VERBOSE +#if DEBUG_VERBOSE == ENABLE printf("I2C bus reset\r\n"); #endif @@ -145,6 +145,7 @@ i2c_result_t i2c_bus_reset(void) { * 如果在某个地址上发现了设备，则会打印出该设备的地址。 * 最后会打印出找到的设备总数。 */ +#if DEBUG_VERBOSE == ENABLE void i2c_scan(void) { uint32_t timeout; uint8_t address; @@ -249,6 +250,7 @@ void i2c_scan(void) { while (usart_flag_get(UART_PHY, USART_FLAG_TC) == RESET) {} } } +#endif /** * @brief 内部辅助函数：等待指定的I2C标志位被设置，带有超时。 @@ -260,7 +262,7 @@ static i2c_result_t _i2c_wait_flag_timeout(uint32_t flag) uint16_t timeout = 0; while(!i2c_flag_get(I2C0, flag)){ if(timeout++ > I2C_TIME_OUT){ -#ifdef DEBUG_VERBOSE +#if DEBUG_VERBOSE == ENABLE const char* fname = "UNKNOWN"; switch (flag) { case I2C_FLAG_SBSEND: fname = "SBSEND"; break; @@ -359,7 +361,7 @@ i2c_result_t i2c_write_16bits(uint8_t slave_addr, uint8_t reg_addr, uint8_t data } else { i2c_flag_clear(I2C0, I2C_FLAG_AERR); timeout =0; -#ifdef DEBUG_VERBOSE +#if DEBUG_VERBOSE == ENABLE printf("IIC write failed for Error Slave Address. \n"); #endif return I2C_RESULT_NACK; @@ -438,7 +440,7 @@ i2c_result_t i2c_write_16bits(uint8_t slave_addr, uint8_t reg_addr, uint8_t data retry_count ++; if (retry_count >= I2C_MAX_RETRY) { -#ifdef DEBUG_VERBOSE +#if DEBUG_VERBOSE == ENABLE printf("IIC write failed after %d retries\n", I2C_MAX_RETRY); #endif return I2C_RESULT_ERROR; @@ -612,7 +614,7 @@ i2c_result_t i2c_read_16bits(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data retry_count++; if (retry_count >= I2C_MAX_RETRY) { -#ifdef DEBUG_VERBOSE +#if DEBUG_VERBOSE == ENABLE printf("IIC read failed after %d retries\n", I2C_MAX_RETRY); #endif return I2C_RESULT_ERROR; @@ -652,7 +654,7 @@ i2c_result_t i2c_write(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint /* parameter validation */ if (data == NULL || slave_addr > 0x7F || length == 0) { -#ifdef DEBUG_VERBOSE +#if DEBUG_VERBOSE == ENABLE printf("I2C read invalid param: slave=0x%02X, len=%u, data=%p\r\n", slave_addr, length, data); #endif return I2C_RESULT_INVALID_PARAM; @@ -712,7 +714,7 @@ i2c_result_t i2c_write(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint i2c_flag_clear(I2C0, I2C_FLAG_AERR); i2c_stop_on_bus(I2C0); timeout = 0; -#ifdef DEBUG_VERBOSE +#if DEBUG_VERBOSE == ENABLE printf("I2C write failed for Error Slave Address. \n"); #endif return I2C_RESULT_NACK; @@ -787,7 +789,7 @@ i2c_result_t i2c_write(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint retry_count++; if (retry_count >= I2C_MAX_RETRY) { -#ifdef DEBUG_VERBOSE +#if DEBUG_VERBOSE == ENABLE printf("IIC write failed after %d retries\n", I2C_MAX_RETRY); #endif return I2C_RESULT_ERROR; @@ -832,7 +834,7 @@ i2c_result_t i2c_read(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint8 /* enable acknowledge */ i2c_ack_config(I2C0, I2C_ACK_ENABLE); -#ifdef DEBUG_VERBOSE +#if DEBUG_VERBOSE == ENABLE printf("I2C read start: slave=0x%02X reg=0x%02X len=%u\r\n", slave_addr, reg_addr, length); #endif @@ -884,7 +886,7 @@ i2c_result_t i2c_read(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint8 } /* debug: show address ack and error flags */ -#ifdef DEBUG_VERBOSE +#if DEBUG_VERBOSE == ENABLE printf("I2C CLEAR_ADDRESS: write_phase=%d ADDSEND=%d AERR=%d\r\n", (int)write_phase, (int)i2c_flag_get(I2C0, I2C_FLAG_ADDSEND), @@ -902,19 +904,19 @@ i2c_result_t i2c_read(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint8 - length > 2: keep ACK enabled and clear ADDR; we'll handle N-2/BTF sequence later */ if (length == 1) { i2c_ack_config(I2C0, I2C_ACK_DISABLE); -#ifdef DEBUG_VERBOSE +#if DEBUG_VERBOSE == ENABLE printf("I2C READ phase: length=1, disabling ACK before clearing ADDSEND\r\n"); #endif } else if (length == 2) { i2c_ackpos_config(I2C0, I2C_ACKPOS_NEXT); i2c_ack_config(I2C0, I2C_ACK_DISABLE); -#ifdef DEBUG_VERBOSE +#if DEBUG_VERBOSE == ENABLE printf("I2C READ phase: length=2, set ACKPOS_NEXT and disabling ACK before clearing ADDSEND\r\n"); #endif } else { /* length > 2: keep ACK enabled so slave will clock out data */ i2c_ack_config(I2C0, I2C_ACK_ENABLE); -#ifdef DEBUG_VERBOSE +#if DEBUG_VERBOSE == ENABLE printf("I2C READ phase: length=%u (>2), keeping ACK enabled\r\n", length); #endif } @@ -947,7 +949,7 @@ i2c_result_t i2c_read(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint8 break; } -#ifdef DEBUG_VERBOSE +#if DEBUG_VERBOSE == ENABLE printf("I2C RESTART: after BTC, delay 5ms and issuing repeated START\r\n"); #endif /* small delay to allow slave device to prepare multi-byte data before repeated start */ @@ -970,13 +972,13 @@ i2c_result_t i2c_read(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint8 write_phase = false; state = I2C_STATE_CLEAR_ADDRESS; timeout = 0; -#ifdef DEBUG_VERBOSE +#if DEBUG_VERBOSE == ENABLE printf("I2C addressing sent for read (slave=0x%02X)\r\n", slave_addr); #endif break; case I2C_STATE_RECEIVE_DATA: -#ifdef DEBUG_VERBOSE +#if DEBUG_VERBOSE == ENABLE printf("I2C RECEIVE_DATA: expecting %u bytes\r\n", length); #endif if (length == 1) { @@ -1058,7 +1060,7 @@ i2c_result_t i2c_read(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint8 case I2C_STATE_ERROR: /* I2C bus error, try to reset the bus and retry */ -#ifdef DEBUG_VERBOSE +#if DEBUG_VERBOSE == ENABLE printf("I2C_STATE_ERROR: resetting bus and retrying (retry_count=%u)\r\n", retry_count); #endif i2c_bus_reset(); @@ -1069,7 +1071,7 @@ i2c_result_t i2c_read(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint8 retry_count++; if (retry_count >= I2C_MAX_RETRY) { -#ifdef DEBUG_VERBOSE +#if DEBUG_VERBOSE == ENABLE /* Print diagnostic flags to help root-cause analysis */ printf("I2C read final failure after %d retries, last_state=%d\r\n", I2C_MAX_RETRY, state); printf(" FLAGS: AERR=%d BERR=%d LOSTARB=%d I2CBSY=%d\r\n", @@ -1078,7 +1080,7 @@ i2c_result_t i2c_read(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint8 (int)i2c_flag_get(I2C0, I2C_FLAG_LOSTARB), (int)i2c_flag_get(I2C0, I2C_FLAG_I2CBSY)); #endif -#ifdef DEBUG_VERBOSE +#if DEBUG_VERBOSE == ENABLE printf("I2C read failed after %d retries\n", I2C_MAX_RETRY); #endif return I2C_RESULT_ERROR; @@ -1099,7 +1101,7 @@ i2c_result_t i2c_read(uint8_t slave_addr, uint8_t reg_addr, uint8_t *data, uint8 } } /* timeout path: provide debug info */ -#ifdef DEBUG_VERBOSE +#if DEBUG_VERBOSE == ENABLE printf("I2C read timeout (end state). slave=0x%02X, len=%u\r\n", slave_addr, length); printf(" FLAGS: AERR=%d BERR=%d LOSTARB=%d I2CBSY=%d\r\n", (int)i2c_flag_get(I2C0, I2C_FLAG_AERR), @@ -1267,7 +1269,7 @@ i2c_result_t i2c_read_raw(uint8_t slave_addr, uint8_t *data, uint8_t length) return I2C_RESULT_TIMEOUT; } -#ifdef DEBUG_VERBOSE +#if DEBUG_VERBOSE == ENABLE /*! \brief get status string for debugging \param[in] status: i2c_status_t value diff --git a/Src/main.c b/Src/main.c index 8710b70..9bc9432 100644 --- a/Src/main.c +++ b/Src/main.c @@ -62,15 +62,15 @@ int main(void) i2c_config(); -#ifdef DEBUG_MODE +#if DEBUG_MODE == ENABLE printf("Hello World!\r\n"); #endif -#ifdef SEGGER_RTT_DETECTION +#if SEGGER_RTT_DETECTION == ENABLE RTT_printf(0, "Hello World!\r\n"); #endif -#ifdef DEBUG_VERBOSE +#if DEBUG_VERBOSE == ENABLE i2c_scan(); i2c_bus_reset();