1# HCK
2
3
4## Background
5
6Vendors have different kernel requirements and feature solutions when adapting their platforms to OpenHarmony.
7
8If their code is directly integrated into the kernel repository or patches are applied, problems such as low build and development efficiency, complex routine maintenance, and poor feature portability will be caused.
9
10To incorporate third-party kernel features into OpenHarmony without or with little interference with the kernel repository, OpenHarmony provides the OpenHarmony Common Kernel (HCK) framework, which provides a complete set of instrumentation, registration, and invoking interfaces to reduce modification to the kernel. The HCK provides instrumentation interfaces applicable to multiple platforms, implementing decoupling of the kernel.
11
12This document describes how to implement the HCK based on the native hook mode.
13
14## Application Scope
15
16You can use the HCK framework when your Linux kernel patches, features, and modules require modification on the native kernel.
17
18## Available APIs
19
20**DECLARE_HCK_LITE_HOOK**: macro used to declare an instrumentation interface. It generates the registration and call interfaces.
21
22**REGISTER_HCK_LITE_HOOK**: macro used to register an instrumentation interface instance. The HCK supports only the registration of a singleton for a singleton, and the registered interfaces cannot be deregistered.
23
24**REGISTER_HCK_LITE_DATA_HOOK**: macro used to register an instrumentation interface instance with parameters. Only a singleton can be registered, and the registered interfaces cannot be deregistered.
25
26**CALL_HCK_LITE_HOOK**: macro used to call an instrumentation interface, which replaces the code that intrudes into the native kernel code.
27
28**Figure 1** HCK interface definition, registration, and invocation
29
30![](figures/hck.png)
31
32## Usage Guide
33
34### Configuration
35
36Before using the HCK, enable the following settings in the **config** file of your platform in the **kernel_linux_config** repository:
37
38```c
39CONFIG_HCK=y
40CONFIG_HCK_VENDOR_HOOKS=y
41```
42
43### Interface Definition
44
45Define the hook interface in **kernel-x.x/include/linux/hck/lite_hck_xxx.h** by using the following macro:
46
47```c
48#include <linux/hck/lite_vendor_hooks.h> // Include HCK header file.
49
50// You can customize data types for passing in parameters in interface registration.
51struct hck_data {
52   int   stat;
53   char* name;
54};
55
56// Declare the hook interface. The declaration macro contains the EXPORT interface, and you do not need to call EXPORT separately to declare the interface.
57DECLARE_HCK_LITE_HOOK(boot_config_info0_lhck, TP_PROTO(Type Parameter, ...), TP_ARGS(Parameter, ...));
58```
59
60### Interface Declaration
61
62Add the interface declaration header file to the new vendor hck module. The file path is **drivers/hck/vendor_hooks.c**.
63
64```c
65#define CREATE_LITE_VENDOR_HOOK
66#include <linux/hck/lite_hck_sample.h> // Add the interface declaration header file after the macro definition.
67```
68
69### Interface Registration
70
71Define the instrumentation function and register the hook functions in the hook module.
72
73```c
74// Include the interface declaration header file.
75#include <linux/hck/lite_hck_sample.h>
76
77// Implement the interfaces:
78boot_config_info0([void* data], ...)
79{
80    // Call the input parameters for the registration.
81    ((struct hck_data*)data)->stat ... ;
82}
83
84// Register the interface. Generally, register the interface in the init() function of the module. Ensure that the registration is completed before the interface is called.
85xxx_init()
86{
87    REGISTER_HCK_LITE_HOOK(boot_config_info0_lhck, boot_config_info0);
88    // Register the interface with parameters. The input parameters can be obtained and used in the interface instance.
89    REGISTER_HCK_LITE_DATA_HOOK(boot_config_info1_lhck, boot_config_info1, data);
90}
91```
92
93### Interface Calling
94
95Add the hook function in other kernel modules.
96
97For example, add the previously defined interface to **linux-x.y/drivers/xxx/xxx.c**.
98
99```c
100#include <linux/hck/lite_hck_sample.h>
101...
102int foo(...)
103{
104    CALL_HCK_LITE_HOOK(boot_config_info0_lhck, parameter...);
105}
106```
107
108### Example
109
110The sample code is located in **kernel/linux/linux-5.10 (ro linux-6.6)/samples/hck**.
111
112To enable the sample code, enable the following settings in **config** (do not enable the settings in the official version):
113
114```c
115CONFIG_SAMPLES=y
116CONFIG_SAMPLE_HCK=y
117CONFIG_SAMPLE_HCK_CALL=y
118CONFIG_SAMPLE_HCK_REGISTER=y
119```
120
121## Specifications
122
123### Naming Rules
124
1251. Comply with the kernel interface naming rules. The interface names should be descriptive.
126
1272. Add **suffix _lhck** to the end of the interface names of lite hck interfaces. For example:
128```c
129DECLARE_HCK_LITE_HOOK(boot_config_info0_lhck, TP_PROTO(int* s ), TP_ARGS(s));
130```
131
1323. Use English words and grammar, not Hanyu Pinyin.
133
1344. Use commonly accepted abbreviations. Do not create abbreviations.
135
1365. Avoid using negative expressions.
137
138For example, name the interface for obtaining the boot configuration as follows:get_boot_config_lhck
139
140### File Directory Specifications
141
1421. Place the interface definition header file in **kernel-x.x/include/linux/hck/**.
143
1442. Name header files in the **lite_hck_*module-description*.h** format, for example, **lite_hck_mmc.h**.
145