目标机库集成指南

概述

emXCP 是一个面向嵌入式系统的 XCP Slave 库，支持高速数据采集和录制功能。本文档介绍如何将 emXCP 库集成到您的目标机项目中。

核心特性

特性	说明
运行时内存配置	缓冲区大小由用户在运行时传入，无需重新编译库
自动适配模式	库根据缓冲区大小自动选择最优采集模式
静态内存架构	无动态内存分配，适合裸机/RTOS环境
灵活集成	适应从资源受限到高端平台的各种目标系统

适用场景

无OS（裸机）/ 轻量级RTOS嵌入式平台
采用静态内存架构，无动态内存分配
程序通过交叉编译、链接生成ELF文件，转换为BIN文件后烧录至MCU运行

快速开始

1. 分配内存

根据MCU内存映射，分配一段连续物理内存：

// 根据MCU内存映射分配（示例）
#define EMXCP_BUFFER_ADDR    0x20002000   // 符合MCU RAM地址范围
#define EMXCP_BUFFER_SIZE    (16 * 1024)  // 16KB，可根据RAM余量调整

2. 初始化库

在程序初始化阶段调用 emeye_xcp_init：

#include "emXcp.h"

void user_init(void)
{
    // 传入缓冲区地址和大小
    emeye_xcp_init((char*)EMXCP_BUFFER_ADDR, EMXCP_BUFFER_SIZE);

    // 设置中断周期（1ms）
    emeye_xcp_set_irq(1, 0);
}

3. 周期调用

在定时器中断中周期调用 emeye_xcp_irq_handler：

// 在1ms定时器中断中调用
void timer_isr(void)
{
    emeye_xcp_irq_handler();
}

IRQ 内部模式优先级：

优先级	模式	独占条件
1（最高）	Recorder	启用时独占
2	Power-on Recorder	仅 RECORDING/UPLOAD 状态独占
3	Scope	Power-on Recorder 非活跃时自动接管

提示：使用预录制（emeye_set_poweron_prerec）时，预录制完成后 Power-on Recorder 进入 DONE 状态，IRQ 自动切换到 Scope 模式，无需手动干预。

缓冲区配置

缓冲区大小与模式

emXCP库根据缓冲区大小自动选择采集模式：

缓冲区大小	模式	批量发送帧数	适用场景
≥ 64KB	大容量模式	16	高频采集、多通道数据
8KB ~ 64KB	中等模式	8	平衡采集频率和数据量
< 8KB（最小512字节）	最小模式	4	低频率、小数据量采集

缓冲区大小估算

缓冲区大小 ≈ (预触发点数 + 后触发点数) × 单次采样字节数

其中：
- 单次采样字节数 = 所有变量大小之和
- 预触发点数 = 预触发时长(ms) × 采样率(Hz) / 1000
- 后触发点数 = 后触发时长(ms) × 采样率(Hz) / 1000

示例：8个uint32变量，1ms采样周期，录制200ms（前50ms + 后150ms）

单次采样 = 32字节
预触发 = 50 × 1000 / 1000 = 50点
后触发 = 150 × 1000 / 1000 = 150点
缓冲区 ≈ (50 + 150) × 32 = 6400字节 ≈ 6.4KB

内存要求

必须是物理连续内存
地址必须在MCU合法地址空间内
地址需按4字节对齐
缓冲区必须在整个程序运行期间保持有效
禁止使用malloc/free分配缓冲区

API参考

初始化API

API	说明
`emeye_xcp_init(pBuffer, size)`	初始化库，传入缓冲区
`emeye_xcp_set_irq(ms, us)`	设置中断周期
`emeye_xcp_irq_handler()`	中断处理函数，需周期调用

查询API

API	说明
`emeye_xcp_get_buffer_size()`	查询当前缓冲区大小
`emeye_xcp_get_required_mem_size(...)`	查询所需内存大小
`emeye_xcp_recorder_get_capability(...)`	获取Recorder能力信息

配置API

API	说明
`emeye_xcp_recorder_config(...)`	配置Recorder参数
`emeye_xcp_recorder_set_trigger(...)`	配置触发条件

运行控制API

API	说明
`emeye_xcp_recorder_start()`	启动录制
`emeye_xcp_recorder_stop()`	停止录制
`emeye_xcp_recorder_trigger()`	手动触发
`emeye_xcp_recorder_get_status(...)`	获取录制状态

完整示例

#include "emXcp.h"

// 1. 根据MCU内存映射分配缓冲区
#define EMXCP_BUFFER_ADDR    0x20002000
#define EMXCP_BUFFER_SIZE    (16 * 1024)  // 16KB

void user_init(void)
{
    // 2. 初始化emXCP，传入缓冲区
    emeye_xcp_init((char*)EMXCP_BUFFER_ADDR, EMXCP_BUFFER_SIZE);

    // 3. 设置中断周期（1ms）
    emeye_xcp_set_irq(1, 0);
}

// 在1ms定时器中断中调用
void timer_1ms_isr(void)
{
    emeye_xcp_irq_handler();
}

注意事项

重要：如果 emeye_xcp_init(NULL, 0) 不传入缓冲区，Recorder功能将不可用（Enable时会报错），但Scope/Watch等其他XCP功能仍正常工作。

注意：多线程/中断场景下，需保证Recorder相关接口的调用互斥，避免内存访问冲突。

提示：上位机解析ELF文件获取的变量地址，即为MCU真实物理地址，emXCP库可直接通过该地址访问变量。

故障排查

Recorder功能不可用

可能原因：
- 未传入缓冲区或缓冲区大小不足
- 缓冲区地址不在合法地址空间内

解决方案：
1. 确认调用了 emeye_xcp_init 并传入有效缓冲区
2. 检查缓冲区地址是否符合MCU内存映射
3. 确保缓冲区大小至少512字节

数据采集异常

可能原因：
- 中断周期未正确设置
- 中断处理函数未周期调用

解决方案：
1. 确认调用了 emeye_xcp_set_irq 设置正确的中断周期
2. 确认定时器中断正常触发
3. 检查 emeye_xcp_irq_handler 是否在中断中正确调用