HIC 接口分类与维护原则

本文档详细说明了HIC系统的接口分类、维护原则和向后兼容性保证。

一、接口分类

1.1 官方接口（Official API）

定义: 由HIC官方团队维护和发布的接口，属于核心系统的一部分。

范围: - 系统调用（0-255） - Core-0提供的核心服务端点（0x0000-0x0FFF） - Privileged-1层的官方服务（0x1000-0x8FFF）

端点分配详情:

0x0000-0x0FFF  Core-0系统调用和服务
0x1000-0x1FFF  能力管理器
0x2000-0x2FFF  调度器
0x3000-0x3FFF  内存管理器
0x4000-0x4FFF  中断控制器
0x5000-0x5FFF  系统调用分发
0x6000-0x6FFF  模块管理器
0x7000-0x7FFF  官方扩展服务（文件系统、网络栈、块设备等）
0x8000-0x8FFF  官方高级服务（图形、音频、AI等）

总数: 34816个端点

第三方接口升级机制: - 优秀的第三方接口可以申请升级为官方接口 - 升级后接口从第三方范围移动到官方扩展服务范围 - 官方接口保持向后兼容，永不删除

1.2 第三方接口（Third-party API）

定义: 由第三方开发者创建和管理的服务接口，通过模块系统加载。

范围: - 用户自定义的服务（0x9000-0xAFFF） - 社区贡献的扩展服务

端点分配详情:

0x9000-0x9FFF  第三方基础服务（数据库、缓存、消息队列等）
0xA000-0xAFFF  第三方高级服务（自定义服务、实验性功能等）

总数: 10240个端点

接口升级流程: 1. 第三方开发者提交接口升级申请 2. 官方团队审核接口质量和兼容性 3. 通过审核后分配官方接口端点 4. 保留原第三方接口一段时间用于迁移

1.3 保留范围

范围: 0xB000-0xFFFF 用途: 保留给未来官方扩展和特殊用途

总数: 20480个端点

二、官方接口维护原则

2.1 核心原则

HIC官方接口遵循以下不可违背的核心原则：

原则1: 向后兼容

定义: 新版本必须完全兼容旧版本

实施: - 所有现有API继续正常工作 - 所有现有代码无需修改即可运行 - 二进制兼容性得到保证 - 现有行为永不改变

原则2: 不减少功能

定义: 永不删除或废弃任何现有功能

实施: - 永不删除任何公开API - 永不删除任何公开函数 - 永不删除任何公开结构体字段 - 永不删除任何公开枚举值

原则3: 只增加，不删除

定义: 新版本只能添加，不能删除或修改

实施: - 新版本只能添加新API - 新版本只能添加新函数 - 新版本只能在结构体末尾添加新字段 - 新版本只能添加新枚举值 - 现有API的签名、参数、返回值永不改变

原则4: 稳定保证

定义: API签名、参数、返回值在ABI版本内永不改变

实施: - 函数签名永不改变 - 参数类型和顺序永不改变 - 返回值类型永不改变 - 结构体布局永不改变

2.2 绝对禁止的操作

以下操作在官方接口中绝对禁止：

❌ 禁止删除任何公开API ❌ 禁止修改任何公开API的签名 ❌ 禁止改变任何公开结构体的字段布局 ❌ 禁止废弃任何现有功能 ❌ 禁止重用已删除的API编号或端点ID

2.3 允许的操作

以下操作在官方接口中是允许的：

✅ 添加新的公开API ✅ 添加新的枚举值 ✅ 在结构体末尾添加新字段 ✅ 添加新的系统调用 ✅ 添加新的服务端点 ✅ 改进内部实现（不影响API） ✅ 修复bug（不影响API）

三、官方接口版本演进

3.1 版本号规则

HIC API使用语义化版本号（Semantic Versioning）：

MAJOR.MINOR.PATCH

示例: 1.0.0, 1.1.0, 1.1.1, 2.0.0

3.2 主版本（Major）

触发条件: 仅当必须进行破坏性变更

破坏性变更包括： - 删除公开API - 修改公开API签名 - 改变公开结构体布局 - 改变系统调用约定

保证: - 主版本更新极少发生 - 必须有重大技术理由 - 必须提供完整的迁移路径 - 必须维护旧版本至少1个发布周期 - 必须发布详细的迁移指南

示例:

1.0.0 → 2.0.0  （删除了过时的API，提供迁移路径）

3.3 次版本（Minor）

触发条件: 添加新功能，保持向后兼容

允许的操作: - 添加新的公开API - 添加新的枚举值 - 在结构体末尾添加新字段 - 添加新的系统调用 - 添加新的服务端点

保证: - 所有现有API保持不变 - 二进制兼容性得到保证 - 现有代码无需修改

示例:

1.0.0 → 1.1.0  （添加了新的共享内存API）
1.1.0 → 1.2.0  （添加了新的文件系统服务）

3.4 补丁版本（Patch）

触发条件: Bug修复和优化

允许的操作: - 修复bug - 性能优化 - 安全修复 - 文档更新

保证: - 完全的二进制兼容性 - 不改变任何公开接口 - 不影响现有行为

示例:

1.1.0 → 1.1.1  （修复了IPC调用的bug）
1.1.1 → 1.1.2  （优化了系统调用性能）

3.5 版本兼容性矩阵

四、第三方接口规范

4.1 基本要求

第三方接口必须满足以下基本要求：

1. 版本号: 必须使用语义化版本号（MAJOR.MINOR.PATCH）
2. 文档: 必须提供完整的API文档
3. 兼容性声明: 必须明确说明版本兼容性规则
4. 安全规范: 必须遵循HIC能力系统规范

4.2 端点分配

第三方接口使用以下端点范围：

4.3 命名规范

第三方接口建议使用以下命名规范：

{vendor}.{service}.v{major}.{minor}.{method}

示例: - community.custom_driver.v1.open - vendor.graphics.v2.render - experimental.ai.v1.inference

4.4 版本管理建议

第三方接口的版本管理建议：

1. 主版本: 破坏性变更时增加
2. 次版本: 添加新功能时增加
3. 补丁版本: Bug修复时增加
4. 迁移指南: 主版本更新时提供
5. 弃用通知: 提前通知API变更

五、向后兼容性保证

5.1 官方接口的兼容性承诺

HIC官方团队对官方接口做出以下严格承诺：

承诺1: 二进制兼容性

保证: 编译的应用程序可以在不同HIC版本间迁移而无需重新编译

实施: - ABI永不改变 - 调用约定永不改变 - 类型大小永不改变

承诺2: 源代码兼容性

保证: 使用官方API的源代码无需修改即可在新版本上编译

实施: - API签名永不改变 - 头文件兼容性得到保证

承诺3: 行为兼容性

保证: API的行为在新版本中保持一致

实施: - 函数的行为永不改变 - 错误码的含义永不改变 - 性能特性不会变差

5.2 兼容性验证

HIC官方提供以下机制验证兼容性：

1. 版本检查API: hic_api_check_compatibility()
2. 端点查询API: hic_endpoint_query()
3. 自动化测试: 完整的兼容性测试套件
4. 回归测试: 每个版本都进行回归测试

六、最佳实践

6.1 使用官方接口的最佳实践

1. 依赖稳定的API

/* ✅ 好的做法：使用官方接口 */
hic_error_t err = hic_domain_create(&config, &domain);
if (!hic_is_ok(err)) {
    /* 处理错误 */
}

/* ✅ 好的做法：使用版本化查询 */
hic_endpoint_info_t info;
hic_endpoint_query("filesystem", 1, 0, &info);

2. 检查版本兼容性

/* ✅ 好的做法：使用前检查版本 */
u32 req_major = 1, req_minor = 0;
u32 avail_major, avail_minor;
hic_api_get_version(&avail_major, &avail_minor, NULL);

if (hic_api_check_compatibility(req_major, req_minor, 
                                avail_major, avail_minor)) {
    /* 版本兼容，可以安全使用 */
} else {
    /* 版本不兼容，需要处理 */
}

3. 依赖官方接口而非第三方接口

/* ✅ 好的做法：优先使用官方接口 */
hic_shmem_alloc(size, 0, &shmem);

/* ⚠️ 谨慎使用：第三方接口 */
hic_endpoint_get_cap("third_party_service", 1, 0, &cap);

6.2 创建第三方接口的最佳实践

1. 使用版本化API

/* ✅ 好的做法：版本化API */
#define MY_SERVICE_V1  1
#define MY_SERVICE_V2  2

hic_endpoint_register("my_service.v1.open", 0x7500, handler_v1);
hic_endpoint_register("my_service.v2.open_with_flags", 0x7501, handler_v2);

2. 提供迁移指南

/* ✅ 好的做法：提供迁移指南 */
/*
 * v1.0 → v2.0 迁移指南
 * 
 * 变更：
 * - 'open' 参数增加了 'flags' 字段
 * 
 * 迁移：
 *   v1.0:  open(path, O_RDONLY)
 *   v2.0:  open(path, O_RDONLY | 0)
 * 
 * 兼容性：
 *   v2.0 支持所有 v1.0 的调用方式
 */

3. 明确兼容性声明

/* ✅ 好的做法：明确兼容性 */
/*
 * my_service v2.0 兼容性声明：
 * 
 * 向后兼容：
 *   - v2.0 完全兼容 v1.0
 *   - 所有 v1.0 的调用在 v2.0 中仍然有效
 * 
 * 不兼容：
 *   - 无
 * 
 * 迁移建议：
 *   - 无需迁移
 */

七、故障排查

7.1 官方接口问题

如果您使用官方接口遇到问题：

1. 检查版本: 确认您使用的HIC版本
2. 检查文档: 查看官方文档的最新版本
3. 报告问题: 向HIC官方报告bug
4. 获取支持: 使用官方支持渠道

7.2 第三方接口问题

如果您使用第三方接口遇到问题：

1. 联系开发者: 联系接口的维护者
2. 查看文档: 查看第三方接口的文档
3. 检查版本: 确认版本兼容性
4. 使用适配器: 考虑使用适配器服务

八、总结

8.1 官方接口的优势

✅ 长期稳定: 向后兼容，长期可用 ✅ 官方支持: 官方维护和支持 ✅ 完整文档: 完整的文档和示例 ✅ 安全可靠: 严格的安全验证 ✅ 性能优化: 持续的性能优化

8.2 第三方接口的优势

✅ 灵活性: 可以根据需求定制 ✅ 创新性: 社区可以快速创新 ✅ 多样性: 提供多样化的服务 ✅ 实验性: 可以尝试新想法

8.3 选择建议

使用官方接口当: - 需要长期稳定的应用 - 需要官方支持的服务 - 核心功能和性能关键路径 - 需要严格的安全保证

使用第三方接口当: - 有特定的定制需求 - 需要社区提供的扩展功能 - 进行实验性开发 - 需要快速原型

九、参考文献

• API接口列表
• 开发者指南
• ABI兼容性规范
• HIC架构文档

附录

A. 官方接口端点分配完整列表

B. 第三方接口端点分配完整列表

C. 端点ID使用历史

注意: 官方端点ID一旦分配，永不重用。