CHI Wrapper

CHI (Coherent Hub Interface) 协议 Wrapper 层实现 - 桥接两个不同的CHI协议实现模块。

项目概述

本项目提供了一个统一的C++11接口，用于访问和操作两个不同的CHI协议实现模块（Module A 和 Module B）。Wrapper层负责：

• API统一化：将不同的API风格转换为统一的接口
• 协议转换：处理不同模块间的协议差异
• 事务管理：提供同步/异步事务支持
• 错误处理：统一的错误处理和报告机制
• 性能监控：统计和追踪功能

目录结构

chi_wrapper/
├── include/                 # 头文件
│   ├── chi_common.h        # 通用类型和定义
│   ├── chi_module_a.h       # 模块A接口定义
│   ├── chi_module_b.h       # 模块B接口定义
│   ├── chi_wrapper.h        # Wrapper公共接口
│   └── chi_wrapper_impl.h  # Wrapper实现
├── src/                     # 源文件
│   ├── chi_wrapper.cpp     # Wrapper实现
│   ├── chi_module_a_impl.cpp  # 模块A模拟实现
│   └── chi_module_b_impl.cpp  # 模块B模拟实现
├── test/                   # 测试文件
│   └── chi_wrapper_test.cpp
├── CMakeLists.txt         # CMake构建配置
└── README.md              # 本文件

快速开始

构建项目

mkdir build
cd build
cmake ..
make

运行测试

./chi_wrapper_test

API参考

初始化

#include "chi_wrapper.h"

// 创建Wrapper实例
chi_wrapper::WrapperConfig config;
config.primary_module = chi_wrapper::CHIModuleType::MODULE_A;
config.enable_fallback = true;

auto wrapper = chi_wrapper::create_wrapper(config);

// 初始化
if (!wrapper->initialize()) {
    std::cerr << "初始化失败" << std::endl;
    return;
}

读取操作

// 同步读取
chi::TransactionResult result = wrapper->read_no_snp(0x1000, 64);

if (result.is_success()) {
    std::vector<uint8_t>& data = result.data;
    std::cout << "读取成功，数据大小: " << data.size() << " bytes" << std::endl;
}

写入操作

std::vector<uint8_t> write_data(64, 0xAA);
chi::TransactionResult result = wrapper->write_unique(0x2000, write_data);

if (result.is_success()) {
    std::cout << "写入成功" << std::endl;
}

原子操作

// 原子加法
chi::TransactionResult result = wrapper->atomic_add(0x3000, 100);

// 比较并交换
chi::TransactionResult result = wrapper->atomic_cas(0x3000, old_value, new_value);

异步操作

chi::TransactionConfig config;
config.type = chi::TransactionType::READ_NO_SNP;
config.address = 0x4000;
config.size = 64;
config.qos = 15;  // 高优先级

// 设置回调
wrapper->set_completion_callback([](const chi::TransactionResult& result) {
    if (result.is_success()) {
        std::cout << "异步读取完成" << std::endl;
    }
});

// 发起异步请求
chi::TransactionID txn_id = wrapper->read_async(config, nullptr);

// 等待结果
chi::TransactionResult result = wrapper->wait_for_completion(txn_id, 1000);

模块切换

// 切换到备用模块
if (wrapper->switch_active_module(chi_wrapper::CHIModuleType::MODULE_B)) {
    std::cout << "模块切换成功" << std::endl;
}

// 查询当前模块
chi_wrapper::CHIModuleType current = wrapper->get_active_module();

统计和诊断

// 获取统计信息
chi_wrapper::WrapperStatistics stats = wrapper->get_statistics();

std::cout << "总事务数: " << stats.total_transactions << std::endl;
std::cout << "成功事务: " << stats.successful_transactions << std::endl;
std::cout << "失败事务: " << stats.failed_transactions << std::endl;

// 导出追踪日志
wrapper->export_traces("traces.csv");

支持的事务类型

读取事务

• ReadNoSnp - 无探查读取
• ReadShared - 读取共享数据
• ReadUnique - 读取独占数据
• ReadOnce - 读取一次
• ReadClean - 读取干净数据

写入事务

• WriteNoSnp - 无探查写入
• WriteUnique - 独占写入
• WriteBack - 回写
• CopyBack - 拷贝回写

原子事务

• AtomicAdd - 原子加法
• AtomicCAS - 比较并交换
• AtomicLoadClr - 原子加载清除
• AtomicXor - 原子异或

数据less事务

• CleanUnique - 清理并唯一化
• MakeUnique - 使缓存行唯一
• Evict - 驱逐缓存行
• CleanShared - 清理共享
• CleanInvalid - 清理并无效化

其他事务

• StashOnceUnique - Stash一次独占
• StashOnceShared - Stash一次共享
• DVMOp - 分布式虚拟内存操作

错误处理

Wrapper提供了统一的错误处理机制：

try {
    wrapper->read_no_snp(invalid_addr, 64);
} catch (const chi_wrapper::ProtocolException& e) {
    std::cerr << "协议错误: " << e.what() << std::endl;
} catch (const chi_wrapper::TimeoutException& e) {
    std::cerr << "事务超时: " << e.what() << std::endl;
} catch (const std::exception& e) {
    std::cerr << "通用错误: " << e.what() << std::endl;
}

配置选项

chi_wrapper::WrapperConfig config;

// 主模块和备份模块
config.primary_module = CHIModuleType::MODULE_A;
config.backup_module = CHIModuleType::MODULE_B;
config.enable_fallback = true;

// 超时和资源限制
config.default_timeout_ms = 1000;
config.max_pending_transactions = 256;

// 诊断选项
config.enable_logging = true;
config.strict_protocol_checking = true;

性能考虑

1. 异步操作：对于高吞吐量场景，优先使用异步API
2. 事务批处理：Module B支持批量读取操作
3. 优先级：通过QoS字段设置事务优先级
4. 模块选择：根据负载选择合适的底层模块

扩展指南

添加新的事务类型

1. 在 chi_common.h 的 TransactionType 枚举中添加新类型
2. 在 chi_wrapper_impl.h 中实现转换逻辑
3. 更新相应的转换函数

添加新的底层模块

1. 在 chi_wrapper.h 中添加新的模块类型枚举值
2. 创建新的模块接口头文件
3. 实现模块的具体API
4. 在 chi_wrapper_impl.h 中添加模块切换和转换逻辑

测试

项目包含完整的单元测试套件，涵盖：

• 所有事务类型的基本功能测试
• 异步操作测试
• 模块切换测试
• 错误处理测试
• 统计和追踪功能测试

运行测试：

cd build
./chi_wrapper_test

依赖项

• C++11 兼容的编译器
• CMake 3.10 或更高版本
• 标准库（<thread>, <mutex>, <future>等）

许可证

本项目仅供演示和学习使用。

联系方式

如有问题或建议，请提交Issue。

参考资料

• ARM IHI 0050: AMBA CHI Architecture Specification
• CHI协议规范文档（位于项目根目录）