1# Chipset SDK白名单规则说明 2 3 4 5## 1. Chipset SDK的定义 6 7系统组件模块：安装到system.img中的模块，与芯片和硬件无关。 8 9芯片组件模块：安装到chipset.img中的模块，与芯片或硬件强相关。 10 11 12 13如上图所示：Chipset SDK是指允许被芯片组件进程加载的系统组件动态库模块集合。 14 15Chipset SDK集合中的单个模块称之为Chipset SDK模块。Chipset SDK模块分为两类，在BUILD.gn中通过innerapi_tags字段来标识，可选值为： 16 17- chipsetsdk: 芯片组件直接依赖的模块 18- chipsetsdk_indirect: chipsetsdk模块间接依赖的模块 19 20在BUILD.gn中的使用样例如下： 21 22```go 23ohos_shared_library(sample_chipsetsdk_module) { 24 ... 25 innerapi_tags = [ "chipsetsdk|chipsetsdk_indirect" ] 26 ... 27} 28``` 29 30chipsetsdk和chipsetsdk_indirect类型的模块都需要被芯片组件进程加载，这两个类型的模块都会安装到/chipset/lib{64}/chipset-sdk或/chipset/lib{64}/chipset-pub-sdk目录下，都可以被芯片组件沙盒访问。 31 32相比较于/chipset/lib{64}/chipset-sdk目录，/chipset/lib{64}/chipset-pub-sdk目录下的模块既能被芯片组件沙盒访问，也能被应用进程沙盒访问。 33 34## 2. 规则解释 35 36Chipset SDK白名单规则有几个方面的含义： 37 38### 2.1 芯片组件模块编译时能且仅能依赖系统组件中的chipsetsdk类型的ChipsetSDK模块 39 40违反此规则时，编译过程会产生如下格式的NOT ALLOWED错误： 41 42``` 43[NOT ALLOWED]: chipset module libNNN.z.so depends on non Chipset SDK module libsystemMMM.z.so in //NNNpath:libNNN 44``` 45 46该错误的含义是：芯片组件的libNNN.z.so模块依赖了libsystemMMM.z.so，而libsystemMMM.z.so并不是Chipset SDK的模块。 47 48处理方法： 49 501）检查libNNN.z.so是否需要安装到芯片组件中？如果是系统组件的产物，就不受此规则约束。一般是在BUILD.gn中的install_images字段决定安装到哪个组件中。 51 522）如果libNNN.z.so确实需要安装到芯片组件中，则分析对libsystemMMM.z.so的依赖是否是必须的。经常会出现libNNN.z.so是一个巨型库，对libsystemMMM.z.so的依赖部分并不会被芯片组件实际使用，此时可以考虑把libNNN.z.so进行拆分，把芯片组件确实需要使用的部分保留在芯片组件中；不需要的部分放在系统组件其它的库里。 53 543）如果以上都不满足，需要联系libsystemMMM.z.so的提供者，把此模块整改为Chipset SDK模块。参考第3章Chipset SDK模块基本要求。 55 56### 2.2 Chipset SDK模块能且仅能依赖其它的Chipset SDK模块 57 58违反此规则时，编译过程会产生如下格式的NOT ALLOWED错误： 59 60``` 61[NOT ALLOWED]: Chipset SDK module libNNN.z.so depends on non Chipset SDK module libsystemMMM.z.so in //NNNpath:libNNN 62``` 63 64该错误的含义是：系统组件中的libNNN.z.so模块是Chipset SDK模块，其依赖的libsystemMMM.z.so并不是Chipset SDK模块。 65 66处理方法： 67 681）分析新增对libsystemMMM.z.so的依赖是否合理。 69 702）如果以上都不满足，可以有两种处理方法： 71 72a）为libsystemMMM.z.so增加chipsetsdk_indirect类型的innerapi_tags，表示此模块为间接依赖模块。 73 74b）联系libsystemMMM.z.so的提供者，把此模块整改为Chipset SDK模块，增加chipsetsdk类型的innerapi_tags。参考第3章Chipset SDK模块基本要求。 75 76### 2.3 Chipset SDK模块白名单管理 77 78- Chipset SDK模块没有标记类型 79 80 每个Chipset SDK模块都需要在innerapi_tags中加上chipsetsdk或chipsetsdk_indirect标记；否则会报以下类型的错误： 81 82 ```shell 83 [ERROR]: Chipset SDK module libxxx.so has no innerapi_tags with "chipsetsdk", add it in //base/startup/init/interfaces/innerkits/init_module_engine:libinit_stub_empty 84 ``` 85 86 处理方法：按照提示在对应的BUILD.gn中添加innerapi_tags标记。 87 88- 非Chipset SDK模块添加了Chipset SDK模块标记 89 90 非Chipset SDK模块不要添加chipsetsdk或chipsetsdk_indirect标记；否则会报以下类型的错误： 91 92 ```shell 93 [ERROR]: non chipsetsdk_indirect module libdfx_dumpcatcher.z.so with innerapi_tags="chipsetsdk_indirect", //base/hiviewdfx/faultloggerd/interfaces/innerkits/dump_catcher:libdfx_dumpcatcher 94 ``` 95 96 处理方法：按照提示在对应的BUILD.gn中去掉innerapi_tags中的标记。 97 98 99 100## 3. Chipset SDK模块基本要求 101 102### 3.1 Chipset SDK模块所属部件必须加入最小系统部件集 103 104为了支持芯片组件独立编译，每个Chipset SDK模块所属的部件必须是[最小系统部件集合](https://gitee.com/openharmony/productdefine_common/base/standard_system.json)中的部件，确保最小系统可以正常编译；防止芯片组件编译时需要引入其他过多的系统组件部件。 105 106--- 107 108三方库模块不需要加入最小系统部件集合。 109 110---- 111 112### 3.2 Chipset SDK模块对外API需稳定 113 114Chipset SDK模块提供了跨组件的接口，需要维护稳定的对外API。基本要求如下： 115 1161）对外头文件需要在所属部件bundle.json中标注 117 1182）对外头文件需要清晰的文档注释 119 1203）对外API变更时需要向前兼容 121 122### 3.3 Chipset SDK模块需加入到白名单列表 123 124chipsetsdk_indirect类型的Chipset SDK模块需加入到[chipsetsdk_indirect.json](chipsetsdk_indirect.json)文件中 125 126~~chipsetsdk类型的Chipset SDK模块需加入到[whitelist.json](whitelist.json)文件中，同时需要更新模块描述信息文件[chipsetsdk_info.json](chipsetsdk_info.json)。~~ 127 128**chipsetsdk类型的Chipset SDK模块需加入到[chipsetsdk_info.json](chipsetsdk_info.json)文件中(原whistlist.json文件中原so信息已变更格式后迁移到 chipsetsdk_info.json文件中 ，后续请更新chipsetsdk_info.json文件，不再使用whitelist.json文件)** 129 130**白名单json格式变更如下** 131 132变更前： 133``` 134[ 135 "libc.so", 136 "so名称" 137] 138``` 139变更后： 140``` 141[ 142 { 143 "name": "hilog:libhilog", 144 "so_file_name": "libhilog.so", 145 "path": "//base/hiviewdfx/hilog/interfaces/native/innerkits:libhilog", 146 "headers": [ 147 "//base/hiviewdfx/hilog/interfaces/native/innerkits/include/" 148 ] 149 }, 150 { 151 "name": "归属部件:模块名", 152 "so_file_name": "so名称", 153 "path": "编译路径", 154 "headers": [] 155 } 156] 157``` 158----
