diff --git a/zh-cn/device-dev/kernel/Readme-CN.md b/zh-cn/device-dev/kernel/Readme-CN.md index 4334e426a66c53801fb1b9f044eaad0426f5a57c..f43d4bf95505be7c75abf8748ecad4698d8ce9a0 100755 --- a/zh-cn/device-dev/kernel/Readme-CN.md +++ b/zh-cn/device-dev/kernel/Readme-CN.md @@ -158,6 +158,7 @@ - [标准系统内核概述](kernel-standard-overview.md) - [OpenHarmony开发板Patch使用指导](kernel-standard-patch.md) - [标准系统内核编译与构建指导](kernel-standard-build.md) + - [HCK内核解耦框架指导](kernel-standard-hck.md) - 内核增强特性 - [Enhanced SWAP特性介绍](kernel-standard-mm-eswap.md) - [NewIP内核协议栈介绍](kernel-standard-newip.md) diff --git a/zh-cn/device-dev/kernel/figures/zh-cn_image-20230611130037045.png b/zh-cn/device-dev/kernel/figures/zh-cn_image-20230611130037045.png new file mode 100644 index 0000000000000000000000000000000000000000..75e59f5088fc2e951dae0800f29b0194c646f10a Binary files /dev/null and b/zh-cn/device-dev/kernel/figures/zh-cn_image-20230611130037045.png differ diff --git a/zh-cn/device-dev/kernel/kernel-standard-hck.md b/zh-cn/device-dev/kernel/kernel-standard-hck.md new file mode 100644 index 0000000000000000000000000000000000000000..5d9ef98b459137dcd5d4749810fe0aa1a103ff78 --- /dev/null +++ b/zh-cn/device-dev/kernel/kernel-standard-hck.md @@ -0,0 +1,144 @@ +# HCK内核解耦框架指导 + + +## 背景 + +随着更多的平台适配OpenHarmony，各厂商针对内核的需求功能也不尽相同，都有特性化的方案。 + +直接合入内核仓或适用patch方法，会导致后期构建开发效率低、日常维护复杂、特性移植性差等问题，阻碍内核的良性发展。 + +为使三方内核特性在不侵入或少侵入内核仓的情况下合入社区，社区开发设计HCK（OpenHarmony Common Kernel）内核解耦框架，该方案为开发者提供了整套插桩、注册、调用接口，减少对内核的侵入修改，统一解耦框架，插桩接口可在多平台间通用。 + +本文主要对基于源生hook方式的HCK框架进行使用指导说明，并对使用规范进行说明。 + +## 使用范围 + +涉及Linux内核patch、特性、模块侵入源生内核的整改。 + +## 接口说明 + +DECLARE_HCK_LITE_HOOK：接口定义使用的接口宏，用于插桩接口定义声明用，同时会生成注册和调用接口。 + +REGISTER_HCK_LITE_HOOK：插桩接口实例注册宏，HCK方案仅支持单接口注册单实例，且不可注销已注册接口。 + +REGISTER_HCK_LITE_DATA_HOOK：带参数的接口注册宏，同样仅单实例注册，且接口不可注销。 + +CALL_HCK_LITE_HOOK：插桩接口调用接口宏，在原侵入内核代码处进行替换，使用方法下详。 + +**图 1** HCK定义、注册、调用接口及流程图 + +![zh-cn_image-20230611130037045](figures/zh-cn_image-20230611130037045.png) + +## 使用指导 + +### 配置说明 + +使用HCK方案请先在kernel_linux_config仓下对应平台config配置文件中打开以下配置： + +```c +CONFIG_HCK=y +CONFIG_HCK_VENDOR_HOOKS=y +``` + +### 接口定义 + +在kernel-x.x/include/linux/hck/lite_hck_xxx.h中用以下宏定义hook接口： + +```c +#include // 包含hck必要头文件 + +// 可自定义数据类型，供注册传参用 +struct hck_data { + int stat; + char* name; +}; + +// 插桩接口声明，声明宏中包含EXPORT接口，无需单独调用 +DECLARE_HCK_LITE_HOOK(boot_config_info0_lhck, TP_PROTO(类型 参数, ...), TP_ARGS(参数, ...)); +``` + +### 接口声明 + +在统一新增的vendor hck模块下添加声明接口头文件，文件路径：drivers/hck/vendor_hooks.c + +```c +#define CREATE_LITE_VENDOR_HOOK +#include // 在宏定义后添加接口声明头文件 +``` + +### 接口注册 + +在自研hook模块中定义插桩函数以及注册hook函数 + +```c +// 包含接口声明头文件 +#include + +// 接口实现： +boot_config_info0([void* data], ...) +{ + // 调用注册入参 + ((struct hck_data*)data)->stat ... ; +} + +// 接口注册：一般在模块init函数中进行注册，确保注册要在调用之前完成 +xxx_init() +{ + REGISTER_HCK_LITE_HOOK(boot_config_info0_lhck, boot_config_info0); + // 带参数的接口注册，代入的参数可在接口实例中获取使用 + REGISTER_HCK_LITE_DATA_HOOK(boot_config_info1_lhck, boot_config_info1, data); +} +``` + +### 接口调用 + +在其他内核模块中，插入hook函数，完成接口调用。 + +如：在linux-x.y/drivers/xxx/xxx.c中添加之前定义的接口 + +```c +#include +... +int foo(...) +{ + CALL_HCK_LITE_HOOK(boot_config_info0_lhck, 参数...); +} +``` + +### 示例模块参考 + +示例代码位置：kernel/linux/linux-5.10/samples/hck + +启用示例代码，请打开以下config配置（请勿在正式版本中开启）： + +```c +CONFIG_SAMPLES=y +CONFIG_SAMPLE_HCK=y +CONFIG_SAMPLE_HCK_CALL=y +CONFIG_SAMPLE_HCK_REGISTER=y +``` + +## 使用规范 + +### 命名规范 + +1. 遵守内核接口命名格式即可，尽量做到自解释。 + +2. 当前使用的是lite hck接口，请在接口命名后加”_lhck”后缀。如： +```c +DECLARE_HCK_LITE_HOOK(boot_config_info0_lhck, TP_PROTO(int* s ), TP_ARGS(s)); +``` + +3. 使用英文单词和语法，不要用拼音。 + +4. 使用领域内公用的缩写，不自创缩写。 + +5. 尽量不要用否定句式。 + +如：获取启动配置接口： get_boot_config_lhck + +### 文件目录规范 + +1. 接口定义头文件放置位置：kernel-x.x/include/linux/hck/ + +2. 头文件命名规范：lite_hck_模块简述.h，如lite_hck_mmc.h \ No newline at end of file diff --git "a/zh-cn/readme/\345\206\205\346\240\270\345\255\220\347\263\273\347\273\237.md" "b/zh-cn/readme/\345\206\205\346\240\270\345\255\220\347\263\273\347\273\237.md" index f8ce7de1145bfd293d218a1546675ef1114b54e7..7ae779c5ae0dd96a5483da5984a39eb559dcd882 100644 --- "a/zh-cn/readme/\345\206\205\346\240\270\345\255\220\347\263\273\347\273\237.md" +++ "b/zh-cn/readme/\345\206\205\346\240\270\345\255\220\347\263\273\347\273\237.md" @@ -72,87 +72,92 @@ Linux社区LTS 5.10.y分支信息请查看[kernel官网](https://git.kernel.org/ ``` kernel/ ├── linux -│ ├── linux-4.19 # OpenHarmony linux-4.19 Common kernel -│ ├── linux-5.10 # OpenHarmony linux-5.10 Common kernel -│ ├── build -│ │ ├── BUILD.gn # 编译框架GN文件 -│ │ ├── kernel.mk # 内核编译文件 -│ │ └── ohos.build # 内核编译组件文件 -│ ├── patches -│ │ ├── linux-4.19 # linux-4.19 相关patch -│ │ │   ├── common_patch -│ │ │   │ └── hdf.patch # linux-4.19 HDF patches -│ │ │   └── hi3516dv300_patch -│ │ │   └── hi3516dv300.patch # linux-4.19 Hi3516D V300 SOC patches -│ │ └── linux-5.10 -│ │    ├── common_patch -│ │    │ └── hdf.patch # linux-5.10 HDF patches -│ │    └── hi3516dv300_patch -│ │    │ └── hi3516dv300.patch # linux-5.10 Hi3516D V300 SOC patches -│ │    └── rkrk3568_patch -│ │    ├── kernel.patch # linux-5.10 rk3568 SOC patches -│ │    └── hdf.patch # linux-5.10 rk3568 定制 HDF patches -│ └── config -│ ├── linux-4.19 -│ │   └── arch -│ │   └── arm -│ │   └── configs -│ │   ├── hi3516dv300_small_defconfig # 厂商Hisilicon对应的开源开发板Hi3516dv300小型系统的defconfig -│ │   ├── hi3516dv300_standard_defconfig # 厂商Hisilicon对应的开源开发板Hi3516dv300标准系统的defconfig -│ │   ├── small_common_defconfig # 小型系统的内核的common defconfig -│ │   └── standard_common_defconfig # 标准系统的内核的common defconfig -│ └── linux-5.10 -│ └── arch -│ └── arm -│ └── configs -│    ├── hi3516dv300_small_defconfig # 厂商Hisilicon对应的开源开发板Hi3516dv300小型系统的defconfig -│    ├── hi3516dv300_standard_defconfig # 厂商Hisilicon对应的开源开发板Hi3516dv300标准系统的defconfig -│    ├── small_common_defconfig # 小型系统的内核的common defconfig -│    └── standard_common_defconfig # 标准系统的内核的common defconfig -└── liteos_a # liteos内核基线代码 - ├── apps # 用户态的init和shell应用程序 - ├── arch # 体系架构的目录，如arm等 - │ └── arm # arm架构代码 - ├── bsd # freebsd相关的驱动和适配层模块代码引入，例如USB等 - ├── compat # 内核接口兼容性目录 - │ └── posix # posix相关接口 - ├── drivers # 内核驱动 - │ └── char # 字符设备 - │ ├── mem # 访问物理IO设备驱动 - │ ├── quickstart # 系统快速启动接口目录 - │ ├── random # 随机数设备驱动 - │ └── video # framebuffer驱动框架 - ├── fs # 文件系统模块，主要来源于NuttX开源项目 - │ ├── fat # fat文件系统 - │ ├── jffs2 # jffs2文件系统 - │ ├── include # 对外暴露头文件存放目录 - │ ├── nfs # nfs文件系统 - │ ├── proc # proc文件系统 - │ ├── ramfs # ramfs文件系统 - │ └── vfs # vfs层 - ├── kernel # 进程、内存、IPC等模块 - │ ├── base # 基础内核，包括调度、内存等模块 - │ ├── common # 内核通用组件 - │ ├── extended # 扩展内核，包括动态加载、vdso、liteipc等模块 - │ ├── include # 对外暴露头文件存放目录 - │ └── user # 加载init进程 - ├── lib # 内核的lib库 - ├── net # 网络模块，主要来源于lwip开源项目 - ├── platform # 支持不同的芯片平台代码，如Hi3516DV300等 - │ ├── hw # 时钟与中断相关逻辑代码 - │ ├── include # 对外暴露头文件存放目录 - │ └── uart # 串口相关逻辑代码 - ├── platform # 支持不同的芯片平台代码，如Hi3516DV300等 - ├── security # 安全特性相关的代码，包括进程权限管理和虚拟id映射管理 - ├── syscall # 系统调用 - └── tools # 构建工具及相关配置和代码 +│ ├── common_modules # linux内核通用模块仓 +│ ├── linux-4.19 # OpenHarmony linux-4.19 Common kernel +│ ├── linux-5.10 # OpenHarmony linux-5.10 Common kernel +│ ├── build +│ │ ├── BUILD.gn # 编译框架GN文件 +│ │ ├── kernel.mk # 内核编译文件 +│ │ └── ohos.build # 内核编译组件文件 +│ ├── patches +│ │ ├── linux-4.19 # linux-4.19 相关patch +│ │ │ ├── common_patch +│ │ │ │ └── hdf.patch # linux-4.19 HDF patches +│ │ │ └── hispark_taurus_patch +│ │ │ └── hispark_taurus.patch # linux-4.19 hispark_taurus SOC patches +│ │ └── linux-5.10 +│ │ ├── common_patch +│ │ │ └── hdf.patch # linux-5.10 HDF patches +│ │ └── hispark_taurus_patch +│ │ │ └── hispark_taurus.patch # linux-5.10 hispark_taurus SOC patches +│ │ └── rk3568_patch +│ │ ├── kernel.patch # linux-5.10 rk3568 SOC patches +│ │ └── hdf.patch # linux-5.10 rk3568 定制 HDF patches +│ └── config +│ ├── linux-4.19 +│ │ └── arch +│ │ └── arm +│ │ └── configs +│ │ ├── hispark_taurus_small_defconfig # 厂商Hisilicon对应的开源开发板hispark_taurus小型系统的defconfig +│ │ ├── hispark_taurus_standard_defconfig # 厂商Hisilicon对应的开源开发板hispark_taurus标准系统的defconfig +│ │ ├── small_common_defconfig # 小型系统的内核的common defconfig +│ │ └── standard_common_defconfig # 标准系统的内核的common defconfig +│ └── linux-5.10 +│ ├── base_defconfig # 内核必选或安全红线模块基础配置 +│ ├── type # 形态配置目录 +│ │ ├── small_defconfig # 小型系统常用配置文件 +│ │ └── standard_defconfig # 标准系统常用配置文件 +│ ├── form # 版本配置目录 +│ │ └── debug_defconfig # 调试版本配置文件（示例目前无配置需求） +│ ├── rk3568 # 厂商平台配置目录 +│ │ └── arch +│ │ └── arm64_defconfig # 芯片单板64位版本相关配置文件 +│ └── product # 相关产品类型配置目录 +│ └── phone_defconfig # 手机类型产品相关配置文件 +└── liteos_a # liteos内核基线代码 + ├── apps # 用户态的init和shell应用程序 + ├── arch # 体系架构的目录，如arm等 + │ └── arm # arm架构代码 + ├── bsd # freebsd相关的驱动和适配层模块代码引入，例如USB等 + ├── compat # 内核接口兼容性目录 + │ └── posix # posix相关接口 + ├── drivers # 内核驱动 + │ └── char # 字符设备 + │ ├── mem # 访问物理IO设备驱动 + │ ├── quickstart # 系统快速启动接口目录 + │ ├── random # 随机数设备驱动 + │ └── video # framebuffer驱动框架 + ├── fs # 文件系统模块，主要来源于NuttX开源项目 + │ ├── fat # fat文件系统 + │ ├── jffs2 # jffs2文件系统 + │ ├── include # 对外暴露头文件存放目录 + │ ├── nfs # nfs文件系统 + │ ├── proc # proc文件系统 + │ ├── ramfs # ramfs文件系统 + │ └── vfs # vfs层 + ├── kernel # 进程、内存、IPC等模块 + │ ├── base # 基础内核，包括调度、内存等模块 + │ ├── common # 内核通用组件 + │ ├── extended # 扩展内核，包括动态加载、vdso、liteipc等模块 + │ ├── include # 对外暴露头文件存放目录 + │ └── user # 加载init进程 + ├── lib # 内核的lib库 + ├── net # 网络模块，主要来源于lwip开源项目 + ├── platform # 支持不同的芯片平台代码，如hispark_taurus等 + │ ├── hw # 时钟与中断相关逻辑代码 + │ ├── include # 对外暴露头文件存放目录 + │ └── uart # 串口相关逻辑代码 + ├── platform # 支持不同的芯片平台代码，如hispark_taurus等 + ├── security # 安全特性相关的代码，包括进程权限管理和虚拟id映射管理 + ├── syscall # 系统调用 + └── tools # 构建工具及相关配置和代码 ``` ## 约束 LiteOS： -Hi3518EV300默认使用jffs2文件系统，Hi3516DV300默认使用FAT文件系统。若要使用其他文件系统，需要新增适配。 +Hi3518EV300默认使用jffs2文件系统，hispark_taurus默认使用FAT文件系统。若要使用其他文件系统，需要新增适配。 ## 使用 @@ -172,7 +177,7 @@ Hi3518EV300默认使用jffs2文件系统，Hi3516DV300默认使用FAT文件系 2. 合入芯片平台驱动补丁 - 以Hi3516DV300为例： + 以hispark_taurus为例： 在kernel/linux/build仓中，按照kernel.mk中的芯片组件所对应的patch路径规则及命名规则，将对应的芯片组件patch放到对应路径下： @@ -198,13 +203,13 @@ Hi3518EV300默认使用jffs2文件系统，Hi3516DV300默认使用FAT文件系 ## 构建说明 -以hi3516dv300开源开发板+ubuntu x86主机开发环境为例 +以hispark_taurus开源开发板+ubuntu x86主机开发环境为例 使用工程的全量编译命令，编译生成uImage内核镜像 ``` -./build.sh --product-name hispark_taurus_standard # 编译hi3516dv300镜像 - --build-target build_kernel # 编译hi3516dv300的uImage内核镜像 +./build.sh --product-name hispark_taurus_standard # 编译hispark_taurus镜像 + --build-target build_kernel # 编译hispark_taurus的uImage内核镜像 --gn-args linux_kernel_version=\"linux-5.10\" # 编译指定内核版本 ```