LPT26x-HSF-4MB-Hilink_14.2.0.308_20250411/ws63_check_json_analysis.md

# WS63 Check.json 文件分析完整文档

## 概述

本文档详细分析了 `ws63-liteos-hilink-check.json` 文件的生成机制、校验内容和对应关系。该文件是WS63项目独立升级功能的核心组件，用于验证HiLink固件与App-IoT固件之间的接口兼容性。

## 1. JSON文件基本信息

**文件路径**: `./output/ws63/acore/ws63-liteos-hilink/ws63-liteos-hilink-check.json`

**文件内容结构**:
```json
{
  "ver": 1,
  "app": "3A23309AAF0B692188B9C56755C084522354143382C5309A2D3258C3E6C834A500B53089C7A65C43392D51DFEF32BBC125B613C6B37656F59E142F0D713AD6115955749E72C53C3BA8CD96D2C69CB534231411DEAE5C4F1782DA2760BB04E0199813CAC4CBA339BEBF3D734FBF0955235DD160C0387CA4AD28BFC8766508F627D0B46BE48319EAC371921D27D806C9F3464BF4DFBAE09ADB95232386B021EEFBD3FAD2C6B405A1E9C13BB0420CAB5EF02D3D543090162EB8E51C2E1D10F3EE4EE5FE71A0BA8DF1E95E4A36694908DDB16E08F54B606E13CACB530F71320CC9DF6C3DCB70DC6E54BDA7B3C1720E7ECCB54E88950CFC3D4D700224AB40D9E568A89571387053E9BB3D77889DAA102DB1FC4CE38751F2E6A0BD27B0EC51B8EA015CE0E475ADF3E3CDB49580E84E228803A691F39D958D3F28B0E4D53C670A27B5AB436D11F83A8AAEB6538628D32F674C398B6CF1C295BAB9499E19EA993B11D07524E025EF6FF88F42331C3BE36689468DAF74C6B811187E2D7953251B9228B8A8C32422F97C0122332BB295C110F36291A845CD2FA2D6BC34E37B7CBE23083067AE8AF9346DEEEFCC168D2D4658A94AB5049858C11E8BE4672F492DE9B4046E4B0EEEA5E3D6FE8809743B2B6111718F2038742D7C48EE81BBD5D485373D34C70868622D3233179ADED3E8C5026A2217F6938E85AA7A6754CE869A8127656D364C00F05E95FE7738AD05E79CACA11368FAE6717C71C469FC934FF221953E9F7CA301D52266EA04E8184A6D5AF66621F90139D0642D0350FA3F28ED49CF23AC20D03710992FBE7E3DBCEBD737385AE906D8D885A6118F2416A45FFA93EC3483EDADE5864419C451689382274A6DEC6FD6734D3975199C9FFB561202FEAB34F195D595E791C43315669E430FB9E7288EF87BC4498A4DF1A93918FA7C7805F7131CCF092F762F28C0A502EC955661D19C624CD0B61E88F81F9D57108A971D268273CEABEE8013FF69661C1A29BBD995111C6A64314013FBA647F77B736AE8E330F3D7157E6C3774AFBCC38D643C7108363127CB03B902C6D32C202A73EE7099A65902A14959BA60D70D055A89A6C3E489489F355E418A02EF8A543D8DF826C59AD8FABD1564AF4FEE6224FCA67974F6F63E17D3036A50120E5449669A4D792E919F88C4BBEEC64E542216D35ED1DE5A21434FC521776D37F5C50257B639AA3F47D1CC1888A19961CD6F5D7C9BEF30D5EACE785DB24268E360581533F98458376DD1E770BF3612B6D1F9C62395F48BEDE23AE1514E24C79360CE44291140AFEC5576503E6EBBC1D453DC9ED772F6AA506112D26C5B806EC4E0EAEC6A98F6F1683AC86494FA565B7CE2A0540F45AC6A8A556CDEE96B315EF45ED456EF46F1E5C234ABF92B121CCE688D2163BDF57FB6098B4742FBC504AC5E03230ADF90428D53F024F9C20964CA8AEA8A9042D1CEF0A2BA9C88A011C1004A9B8F7F9EBEDA365056947E9426D868829904D70DA74B7276D93829D151333F3506E83032A8CF68630BD5D0A39237FDF0BADD131AB77B6092987F07139588081D140EB2A0CA25BF9267FBC809457528A7C5DFA1729552A8D76B3362B9915E84795CD770EB84A3AE73DE78F04D37E8FC2F53E2F72853D57F170FC2551F7CBBB9B63D119AC4775120418F3865792FEFAAFF69038BFD3AA3C2C476B26DFB2B48F3B3904203C394782FE1C40F718001C31504539827DDC80900966524DCE965006F86EBDA9C46226BC1DA2387E2AE9565DFEE621F0DA936298371D1AD83860B4E607BB473E4103ADF872D1A3CA9EB171CF73077B4AFC2D7FC3737FAE5337290D8116CE0826F347C621502BA313EEF20F1F67D00A7EB1BB555DE7B0FCDD05C747D7615136B35079DA4BF9A6EED5F0C5448B8364FB03476275BD823C8C7F3CBCC1D0BD41C5B49538D65C00C85F9C8D50201EDA6266D7A2A375141F7F5E69E1AD06932C3A6C044EAE908D43657EA22C5FA797FE8D04592541477B362753A05",
  "hilink": "BEC62B3A1B90717BABD8C9AD15D3BE1560977111A022C59CEF399A97E8B1D1D2D981EE972F4C881D0D3D30D8165FA46BEB1F07B4B8F1AECEA4335DFC7388E1234641EDD1AF31DFEDB616EBF0A9900778C03C4467D3CBCD6540F51D66CBE0FF998506BA06448D8BEB6CDA8E9E79BE4C8BF15449A4DEFEB22F342B09F03683E17D699DA475D08A2F079EDA59B99A96CD0E468B089224120EE96B86A8BB4B250B35E0E8B8A1E77FE8A13F50CF8B018FA5A91475DDA932141DAF1F5C4D9C5D7F8DC8E3CB582D0DB0EA8823396BF6BC0A30D68B968BEE77AB6014036385A68BB35701D274404A9BFA24348E7321F63FEA98B7"
}
```

## 2. 文件生成机制

### 2.1 生成触发条件

**触发时机**: 在构建过程的 `build_post` 阶段（构建完成后）

**配置条件**: 编译配置中必须包含 `CONFIG_SUPPORT_HILINK_INDIE_UPGRADE`
- 当前项目状态：该配置**已被注释**（config.py:334行）
- 因此只有HiLink固件生成了check.json，App-IoT固件未生成

### 2.2 生成调用链

```
构建系统 (build.py) 
  ↓
build_post 钩子
  ↓  
entry.py:153 → dump_indie_upg_check_file()
  ↓
indie_upgrade_utils.py:324 → 生成JSON文件
```

### 2.3 核心生成文件

**主要脚本文件**:
- `build/config/target_config/ws63/script/entry.py:153` - 构建钩子调用点
- `build/script/utils/indie_upgrade_utils.py:324` - JSON文件生成函数
- `build/script/utils/indie_upgrade_utils.py:292-320` - 接口校验码生成核心逻辑

## 3. 校验内容详解

### 3.1 JSON字段含义

| 字段 | 含义 | 数据格式 |
|------|------|----------|
| `ver` | 校验文件版本号 | 整数，当前为1 |
| `app` | App侧接口校验码串联 | CRC32十六进制字符串 |
| `hilink` | HiLink侧接口校验码串联 | CRC32十六进制字符串 |

### 3.2 校验码生成原理

1. **接口函数扫描**: 通过正则表达式扫描源文件中的函数原型
   ```python
   rgl = r"((?:const )?(?:unsigned )?(?:struct )?(?:enum )?\w+[ \*]*)" + \
         r"(\w+)[\s\n]*" + \
         r"(\()" + \
         r"([\s\*,\w\[\]]*?)" + \
         r"(\))" + \
         r"\s*\{"
   ```

2. **原型标准化**: 去除参数名，保留参数类型，生成标准化函数原型字符串

3. **CRC32计算**: 对每个函数原型字符串计算CRC32校验码
   ```python
   checksum = "{:08X}".format(zlib.crc32(prototype.encode("utf8")))
   ```

4. **校验码串联**: 将所有接口的8位十六进制CRC32码按顺序串联

### 3.3 校验码对应的编译文件

| JSON字段 | 编译目标 | 二进制文件 | 签名文件 |
|----------|----------|------------|----------|
| `"app"` | `ws63-liteos-app-iot` | `output/ws63/acore/ws63-liteos-app-iot/ws63-liteos-app-iot.bin` | `ws63-liteos-app-iot-sign.bin` |
| `"hilink"` | `ws63-liteos-hilink` | `output/ws63/acore/ws63-liteos-hilink/ws63-liteos-hilink.bin` | `ws63-liteos-hilink-sign.bin` |

## 4. 接口映射文件体系

### 4.1 App侧接口配置

**源文件路径**: `application/samples/wifi/hilink_indie_upgrade/address_mapping/hilinksdk/app_uapi/`

**主要接口文件**:
- `uapi_hilink_kv_adapter.c` - KV存储适配器接口
- `uapi_hilink_mem_adapter.c` - 内存管理适配器接口
- `uapi_hilink_socket_adapter.c` - Socket网络适配器接口
- `uapi_hilink_stdio_adapter.c` - 标准IO适配器接口
- `uapi_hilink_thread_adapter.c` - 线程管理适配器接口
- `uapi_hilink_time_adapter.c` - 时间管理适配器接口
- `uapi_hilink_network_adapter.c` - 网络适配器接口
- `uapi_hilink_device.c` - 设备管理接口
- `uapi_hichain.c` - 设备认证接口
- `uapi_hilink_ble_adapter.c` - BLE适配器接口
- 等共52个接口适配文件

**生成的映射表**: `application/samples/wifi/hilink_indie_upgrade/address_mapping/application/app_function_mapping.c`

### 4.2 HiLink侧接口配置

**源文件路径**: `application/samples/wifi/hilink_indie_upgrade/address_mapping/application/hilink_uapi/`

**主要接口文件**:
- `uapi_hilink.c` - HiLink核心接口
- `uapi_hilink_log_manage.c` - 日志管理接口
- `uapi_hilink_device_ext.c` - 设备扩展接口
- `uapi_ble_cfg_net_api.c` - BLE配网接口
- `uapi_hilink_bt_function.c` - 蓝牙功能接口
- `uapi_hilink_network_adapter.c` - 网络适配器接口
- `uapi_hilink_socket_adapter.c` - Socket适配器接口
- `uapi_hilink_custom.c` - 自定义功能接口
- `uapi_hilink_sle_api.c` - SLE接口
- `uapi_hilink_quick_netcfg_api.c` - 快速配网接口

**生成的映射表**: `application/samples/wifi/hilink_indie_upgrade/address_mapping/hilinksdk/hilink_function_mapping.c`

### 4.3 接口头文件映射

**App侧头文件路径**:
- `application/samples/wifi/ohos_connect/hilink_adapt/adapter/include/` - 适配器接口声明
- `application/samples/wifi/ohos_connect/hilink_adapt/product/` - 产品相关接口
- `application/samples/wifi/ohos_connect/hilink_adapt/include/` - 通用接口声明
- `open_source/deviceauth/interfaces/innerkits/deviceauth_lite/` - 设备认证接口
- `kernel/liteos/liteos_v208.5.0/Huawei_LiteOS/open_source/CMSIS/CMSIS/RTOS2/Include/` - RTOS接口
- `open_source/cjson/cjson/` - JSON库接口
- `open_source/mbedtls/mbedtls_v3.1.0/include/` - 加密库接口

**HiLink侧头文件路径**:
- `application/samples/wifi/ohos_connect/hilink_adapt/include/` - HiLink核心接口声明
- `application/samples/wifi/ohos_connect/hilink_adapt/product/` - 产品相关接口
- `application/samples/wifi/ohos_connect/hilink_adapt/adapter/include/` - 适配器接口声明

## 5. 校验机制详解

### 5.1 接口兼容性检查函数

**函数位置**: `build/script/utils/indie_upgrade_utils.py:353-370`

**检查逻辑**:
```python
def check_indie_upg_match(hilink_check_file, app_check_file):
    # 读取两个check.json文件
    f = open(hilink_check_file, "r", encoding="utf-8")
    hilink_check = json.loads(f.read())
    f.close()
    f = open(app_check_file, "r", encoding="utf-8")
    app_check = json.loads(f.read())
    f.close()

    # 版本号检查
    if hilink_check["ver"] != 1 or app_check["ver"] != 1:
        print("check file ver[h:%d,a:%d] not match" % (hilink_check["ver"], app_check["ver"]))
        return False
        
    # HiLink侧接口向后兼容检查
    if not hilink_check["hilink"].startswith(app_check["hilink"]):
        prt_not_match_info("hilink", hilink_check["hilink"], app_check["hilink"], True)
        return False
        
    # App侧接口向后兼容检查
    if not app_check["app"].startswith(hilink_check["app"]):
        prt_not_match_info("app", app_check["app"], hilink_check["app"], True)
        return False
        
    return True
```

### 5.2 校验失败信息输出

**函数位置**: `indie_upgrade_utils.py:330-350`

校验失败时会输出具体的不匹配接口信息：
- 显示接口序号和对应的CRC32校验码
- 帮助定位具体是哪个接口发生了变更
- 每个CRC32码长度为8个十六进制字符

### 5.3 升级包构建时的校验

**调用位置**: `build/config/target_config/ws63/build_ws63_update.py:74`

```python
if not check_indie_upg_match(info.hilink_check, info.app_iot_check):
    print("indie upg hilink and app not match")
    return False
```

在生成升级包时会自动进行兼容性检查，如果接口不兼容，构建过程会失败。

## 6. 独立升级工作流程

### 6.1 独立升级概述

独立升级允许在不更新App-IoT固件的情况下，单独升级HiLink SDK固件。这种机制可以：
- 快速修复HiLink SDK的bug
- 更新云端协议和功能
- 减少升级包大小和升级时间
- 降低升级风险

### 6.2 配置开启流程

根据 `indie_upg.md` 文档，开启独立升级需要：

1. **修改配置** (`build/config/target_config/ws63/config.py`):
   - 删除 `'liteos_kconfig': 'ws63_iot'`
   - 在 `'defines'` 中增加 `CONFIG_SUPPORT_HILINK_INDIE_UPGRADE`
   - 在 `'ram_component'` 中增加 `'app_addr_map'`
   - 在 `'ram_component'` 中删除 `'hilinkdevicesdk'`、`'hilinkota'`、`'hilinkbtsdk'`、`'hilinkquickcfg'`

2. **分别编译两个固件**:
   ```bash
   # 先编译HiLink固件
   python3 build.py -c ws63-liteos-hilink
   
   # 再编译App-IoT固件
   python3 build.py -c ws63-liteos-app-iot
   
   # 生成升级包
   python3 build/config/target_config/ws63/build_ws63_update.py --pkt=app_iot
   ```

3. **使用简化编译工具**:
   ```bash
   # 完整编译
   python3 indie_build.py all
   
   # 仅编译SDK（用于独立升级）
   python3 indie_build.py sdk
   ```

### 6.3 独立升级流程

1. **准备已认证的App-IoT固件**:
   - `ws63-liteos-app-iot-sign.bin`
   - `ws63-liteos-app-iot-check.json`

2. **更新HiLink SDK库文件**:
   - 替换 `application/samples/wifi/libhilink/` 中的库文件

3. **执行独立编译**:
   ```bash
   python3 indie_build.py sdk
   ```

4. **接口兼容性校验**:
   - 自动比较新HiLink固件与已认证App-IoT固件的接口
   - 如果接口不匹配，构建失败
   - 校验通过后生成完整升级包

### 6.4 约束条件

1. **分区兼容性**: 非独立升级版本与独立升级版本不可交叉升级
2. **接口兼容性**: 模组App程序不变时，HiLink接口不能发生变更
3. **版本号格式**: 
   - 非独立升级：`1.0.0`
   - 独立升级：`1.0.0_14.2.0.304` (拼接SDK版本号)

## 7. 新增接口适配指南

### 7.1 接口调用机制

独立升级模式下，模组App和HiLink分别编译成两个固件：
- 各自维护接口地址表
- 通过查表机制获取对方接口函数指针
- 实现跨固件的函数调用

### 7.2 新增HiLink接口步骤

**示例接口原型**:
```c
retType TestFuncName(type1 param1, type2 param2, type3 param3);
```

1. **接口声明** (`application/samples/wifi/ohos_connect/hilink_adapt/include/hilink_test.h`):
   ```c
   retType TestFuncName(type1 param1, type2 param2, type3 param3);
   ```

2. **查表适配实现** (`application/samples/wifi/hilink_indie_upgrade/address_mapping/application/hilink_uapi/uapi_hilink_test.c`):
   ```c
   retType TestFuncName(type1 param1, type2 param2, type3 param3)
   {
       hilink_call3(HILINK_CALL_TEST_FUNC_NAME, TestFuncName, retType, type1, param1, type2, param2, type3, param3);
       return (retType)0;
   }
   ```

3. **添加到编译系统** (`application/samples/wifi/hilink_indie_upgrade/address_mapping/application/CMakeLists.txt`):
   ```cmake
   uapi_hilink_test.c
   ```

4. **配置脚本识别** (`build/script/utils/indie_upgrade_utils.py`):
   ```python
   default_config["hilink"]["src_file"] += ("uapi_hilink_test.c",)
   default_config["hilink"]["mapping_header"]["application/samples/wifi/ohos_connect/hilink_adapt/include/"] += ("hilink_test.h",)
   ```

5. **白名单配置**（可选）:
   ```python
   default_config["hilink"]["white_list"] += ("TestFuncName",)
   ```

### 7.3 宏说明

**查表宏定义**:
- `hilink_call0` / `hilink_call0_ret_void` - 无参数函数
- `hilink_call1` / `hilink_call1_ret_void` - 1个参数函数  
- `hilink_call2` / `hilink_call2_ret_void` - 2个参数函数
- `hilink_call3` / `hilink_call3_ret_void` - 3个参数函数
- `hilink_callx` / `hilink_callx_ret_void` - x个参数函数

**参数说明**:
1. 枚举值（如 `HILINK_CALL_TEST_FUNC_NAME`）
2. 函数名
3. 返回值类型  
4. 参数类型和参数名交替列出

## 8. 相关文件清单

### 8.1 核心脚本文件

| 文件路径 | 功能描述 |
|----------|----------|
| `build/script/utils/indie_upgrade_utils.py` | 独立升级工具核心逻辑 |
| `build/config/target_config/ws63/script/entry.py` | 构建钩子入口 |
| `build/config/target_config/ws63/build_ws63_update.py` | 升级包构建脚本 |
| `build/config/target_config/ws63/config.py` | 编译配置文件 |
| `indie_build.py` | 独立升级编译工具 |
| `package.py` | 升级包生成工具 |

### 8.2 接口映射相关文件

| 目录/文件 | 描述 |
|-----------|------|
| `application/samples/wifi/hilink_indie_upgrade/address_mapping/` | 接口映射根目录 |
| `application/samples/wifi/hilink_indie_upgrade/address_mapping/include/func_call_list.h` | 函数调用枚举定义（自动生成） |
| `application/samples/wifi/hilink_indie_upgrade/address_mapping/application/` | App侧接口适配 |
| `application/samples/wifi/hilink_indie_upgrade/address_mapping/hilinksdk/` | HiLink侧接口适配 |
| `application/samples/wifi/ohos_connect/hilink_adapt/` | 接口声明头文件目录 |

### 8.3 输出文件

| 文件路径 | 描述 |
|----------|------|
| `output/ws63/acore/ws63-liteos-hilink/ws63-liteos-hilink-check.json` | HiLink固件接口校验文件 |
| `output/ws63/acore/ws63-liteos-app-iot/ws63-liteos-app-iot-check.json` | App-IoT固件接口校验文件（需开启独立升级） |
| `output/ws63/acore/ws63-liteos-hilink/ws63-liteos-hilink.bin` | HiLink固件二进制文件 |
| `output/ws63/acore/ws63-liteos-hilink/ws63-liteos-hilink-sign.bin` | HiLink固件签名文件 |
| `output/ws63/acore/ws63-liteos-app-iot/ws63-liteos-app-iot.bin` | App-IoT固件二进制文件 |
| `output/ws63/acore/ws63-liteos-app-iot/ws63-liteos-app-iot-sign.bin` | App-IoT固件签名文件 |
| `output/ws63/fwpkg/ws63-liteos-app-iot/ws63-liteos-app-iot_all.fwpkg` | 完整烧录包 |
| `output/ws63/upgrade/update.fwpkg` | 升级包 |
| `output/ws63/ws63-liteos_all.zip` | 完整产物压缩包 |

## 9. 当前项目状态

### 9.1 独立升级配置状态

**当前状态**: 独立升级功能**已关闭**

**证据**:
- `config.py:334` 行：`"CONFIG_SUPPORT_HILINK_INDIE_UPGRADE"` 被注释
- `config.py:291` 行：`'liteos_kconfig': 'ws63_iot'` 仍然存在
- 只有HiLink固件生成了check.json文件
- App-IoT固件目录下没有对应的check.json文件

### 9.2 编译产物状态

**已生成的文件**:
- ✅ `ws63-liteos-hilink.bin` (278K)
- ✅ `ws63-liteos-hilink-sign.bin` (279K)  
- ✅ `ws63-liteos-hilink-check.json` (3.4K)
- ✅ `ws63-liteos-app-iot.bin` (1.7M)
- ✅ `ws63-liteos-app-iot-sign.bin` (1.7M)
- ❌ `ws63-liteos-app-iot-check.json` (未生成，因为独立升级未开启)

## 10. 故障排查指南

### 10.1 check.json文件未生成

**可能原因**:
1. `CONFIG_SUPPORT_HILINK_INDIE_UPGRADE` 未在配置中启用
2. 构建过程中 `build_post` 钩子未执行
3. 接口映射文件生成失败

**排查步骤**:
1. 检查 `config.py` 中的配置项
2. 查看构建日志中是否有 "create indie upg mapping files succ" 消息
3. 检查接口源文件和头文件是否存在语法错误

### 10.2 接口兼容性校验失败

**错误信息示例**:
```
indie upg hilink and app not match
hilink checksum not match  
func 5 [A1B2C3D4:E5F6A7B8] not match
```

**排查步骤**:
1. 确定是哪个接口发生了变更（根据func序号）
2. 检查接口原型是否发生改变
3. 检查参数类型、顺序、返回值类型
4. 如果是合理的接口升级，需要重新生成App-IoT的check.json

### 10.3 接口映射表生成失败

**可能原因**:
1. 源文件中函数原型格式不规范
2. 头文件中接口声明与源文件实现不匹配
3. 正则表达式匹配失败

**排查步骤**:
1. 检查函数原型是否符合标准C语法
2. 确保头文件声明与源文件实现一致
3. 查看构建日志中的正则匹配错误信息

## 11. 总结

`ws63-liteos-hilink-check.json` 文件是WS63项目独立升级功能的核心组件，通过CRC32校验码机制确保固件间接口兼容性。虽然当前项目未启用独立升级功能，但完整的技术框架已经就绪，可以通过简单的配置修改来启用该功能。

该机制的核心价值在于：
- **风险控制**: 通过接口校验防止不兼容升级
- **灵活部署**: 支持HiLink SDK的独立快速升级  
- **开发效率**: 减少完整固件的编译和测试周期
- **维护便利**: 清晰的接口约定和自动化校验流程

---
**文档创建时间**: 2025-09-10  
**项目版本**: SR_Light_Hilink_14.2.1.312_20250714  
**分析对象**: output/ws63/acore/ws63-liteos-hilink/ws63-liteos-hilink-check.json