!19503 Linux内核HCK使用指导文档更新

Merge pull request !19503 from 朱佳鑫/master

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)

zh-cn/device-dev/kernel/kernel-standard-hck.md

+# 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 <linux/hck/lite_vendor_hooks.h> // 包含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 <linux/hck/lite_hck_sample.h> // 在宏定义后添加接口声明头文件
+```
+
+### 接口注册
+
+在自研hook模块中定义插桩函数以及注册hook函数
+
+```c
+// 包含接口声明头文件
+#include <linux/hck/lite_hck_sample.h>
+
+// 接口实现：
+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 <linux/hck/lite_hck_sample.h>
+...
+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

zh-cn/readme/内核子系统.md

@@ -72,6 +72,7 @@ Linux社区LTS 5.10.y分支信息请查看[kernel官网](https://git.kernel.org/
 ```
 kernel/
 ├── linux
+│   ├── common_modules                     # linux内核通用模块仓
 │   ├── linux-4.19                         # OpenHarmony linux-4.19 Common kernel
 │   ├── linux-5.10                         # OpenHarmony linux-5.10 Common kernel
 │   ├── build
@@ -80,35 +81,39 @@ kernel/
 │   │   └── 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
+│   │   │   ├── 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
-│	│	    └── 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
+│   │       ├── 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
-│		│               ├── hi3516dv300_small_defconfig       # 厂商Hisilicon对应的开源开发板Hi3516dv300小型系统的defconfig
-│		│               ├── hi3516dv300_standard_defconfig    # 厂商Hisilicon对应的开源开发板Hi3516dv300标准系统的defconfig
-│		│               ├── small_common_defconfig            # 小型系统的内核的common defconfig
-│		│               └── standard_common_defconfig         # 标准系统的内核的common defconfig
+│       │   └── 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
-│		    └── 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
+│           ├── 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等
@@ -138,11 +143,11 @@ kernel/
     │   └── user           # 加载init进程
     ├── lib                # 内核的lib库
     ├── net                # 网络模块，主要来源于lwip开源项目
-     ├── platform               # 支持不同的芯片平台代码，如Hi3516DV300等
+    ├── platform           # 支持不同的芯片平台代码，如hispark_taurus等
     │   ├── hw             # 时钟与中断相关逻辑代码
     │   ├── include        # 对外暴露头文件存放目录
     │   └── uart           # 串口相关逻辑代码
-     ├── platform               # 支持不同的芯片平台代码，如Hi3516DV300等
+    ├── platform           # 支持不同的芯片平台代码，如hispark_taurus等
     ├── security           # 安全特性相关的代码，包括进程权限管理和虚拟id映射管理
     ├── syscall            # 系统调用
     └── tools              # 构建工具及相关配置和代码
@@ -152,7 +157,7 @@ kernel/
 
 LiteOS：
 
-Hi3518EV300默认使用jffs2文件系统，Hi3516DV300默认使用FAT文件系统。若要使用其他文件系统，需要新增适配。
+Hi3518EV300默认使用jffs2文件系统，hispark_taurus默认使用FAT文件系统。若要使用其他文件系统，需要新增适配。
 
 ## 使用<a name="section1393789267"></a>
 
@@ -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文件系
 
 ## 构建说明<a name="section19369206113115"></a>
 
-以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\"      # 编译指定内核版本
 ```