1# A Method for Rapidly Porting the OpenHarmony Linux Kernel 2 3## Overview 4 5This document describes how to quickly port OpenHarmony to a third-party chip platform by using the existing capabilities of the Linux kernel of the third-party chip platform. 6 7## Overall Porting Approach 8 9### Kernel Mode Layer and User Mode Layer 10 11For easy description, we divide the OpenHarmony architecture into two parts: 12 13OpenHarmony = Kernel mode layer + User mode layer 14 15 16 17The kernel mode layer is the OpenHarmony kernel layer \(purple part in the figure\). It consists of the kernel, such as Linux Kernel and LiteOS, and features, such as Hardware Driver Foundation \(HDF\), running in the kernel mode. 18 19The user mode layer includes other parts except the OpenHarmony kernel layer. It consists of the system service layer, framework layer, and application layer from the bottom to the top. 20 21The user mode layer of OpenHarmony is loosely coupled with the third-party chip platform and is easy to port. The kernel and HDF at the kernel mode layer are closely coupled with the third-party chip platform and are difficult to port. This document focus on the porting of the kernel mode layer. In addition, it describes only the quick porting of the Linux kernel. It does not include the porting of LiteOS. 22 23### Composition of the Kernel Mode Layer 24 25The OpenHarmony kernel mode layer can be further divided as follows: 26 27OpenHarmony kernel mode layer = OpenHarmony Linux kernel + OpenHarmony kernel-mode features \(mandatory features, such as HDF, and optional features, such as HMDFS\) 28 29OpenHarmony Linux kernel = Standard LTS Linux kernel + Third-party SoC platform code + OpenHarmony basic kernel-mode code \(most basic code required for running of the OpenHarmony user mode layer\) 30 31Therefore, the OpenHarmony kernel mode layer includes the following: 32 33- Standard LTS Linux kernel 34- Third-party SoC platform code 35- OpenHarmony basic kernel-mode code 36- OpenHarmony kernel-mode features, such as HDF 37 38 39 40The standard LTS Linux kernel and third-party SoC chip platform code constitute the basis of a third-party Linux kernel. The OpenHarmony kernel mode layer can be composed of either of the following: 41 42- OpenHarmony kernel mode layer = Third-party Linux kernel + OpenHarmony basic kernel-mode code + OpenHarmony kernel-mode features \(such as HDF and HMDFS\) 43 44 In this case, the OpenHarmony kernel mode layer consists of the third-party Linux kernel and OpenHarmony basic code and features for the kernel mode. 45 46 47- OpenHarmony kernel mode layer = OpenHarmony Linux kernel + OpenHarmony kernel-mode features \(such as HDF and HMDFS\) 48 49 In this case, the OpenHarmony kernel mode layer consists of OpenHarmony kernel and features. However, the OpenHarmony kernel supports few third-party chip platforms. 50 51 52In the following, we elaborate how to port OpenHarmony that uses with the third-party Linux kernel. 53 54### Overall Porting Process 55 56The porting process is as follows: 57 581. Prepare the build environment, including copying the existing kernel code of the third-party chip platform to the OpenHarmony build environment. 592. Port the OpenHarmony basic kernel-mode code. 603. Port OpenHarmony mandatory kernel-mode features \(such as HDF\). 61 62## Procedure 63 64The following uses Raspberry Pi 3b \(BCM2837\) as an example to describe how to port OpenHarmony to Raspberry Pi. 65 66### Setting Up the Environment 67 681. Copy the third-party kernel code to the OpenHarmony build environment. 69 70 Build the standard Hi3516D V300 kernel, clone the Raspberry Pi kernel source code, and copy it to the manifest output directory. 71 72 ``` 73 export PROJ_ROOT=[OpenHarmony manifest] 74 git clone https://gitee.com/xfan1024/oh-rpi3b-kernel.git 75 cp -r oh-rpi3b-kernel $PROJ_ROOT/out/KERNEL_OBJ/kernel/src_tmp/linux-rpi3b 76 ``` 77 782. Configure the Raspberry Pi kernel build environment. 79 80 ``` 81 # Go to the Raspberry Pi kernel directory. 82 cd out/KERNEL_OBJ/kernel/src_tmp/linux-rpi3b 83 84 # Configure the build environment, and use clang provided by the project to build the Raspberry Pi kernel source code. 85 export PATH=$PROJ_ROOT/prebuilts/clang/ohos/linux-x86_64/llvm/bin:$PROJ_ROOT/prebuilts/gcc/linux-x86/arm/gcc-linaro-7.5.0-arm-linux-gnueabi/bin/:$PATH 86 export MAKE_OPTIONS="ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- CC=clang HOSTCC=clang" 87 export PRODUCT_PATH=vendor/hisilicon/hispark_taurus_linux 88 ``` 89 903. Comment out the flags that cannot be recognized by **clang**. 91 92 In the **PROJ\_ROOT/out/KERNEL\_OBJ/kernel/src\_tmp/linux-rpi3b/arch/arm/Makefile** file, comment out the following line: 93 94 ``` 95 KBUILD_CFLAGS +=-fno-omit-frame-pointer -mapcs -mno-sched-prolog 96 ``` 97 98 99### Porting Basic Kernel-Mode Code 100 101Currently, the basic kernel-mode code of OpenHarmony is related to the log service. The lightweight kernel log service code includes the following: 102 103``` 104drivers/staging/hilog 105drivers/staging/hievent 106``` 107 108Copy the preceding code from the **kernel/linux/linux-4.19/drivers/staging** directory of OpenHarmony to **out/KERNEL\_OBJ/kernel/src\_tmp/linux-rpi3b/drivers/staging**. 109 110Add the following code to the third-party kernel file **Kconfig** in the **drivers/staging** directory: 111 112``` 113source "drivers/staging/hilog/Kconfig" 114source "drivers/staging/hievent/Kconfig" 115``` 116 117Add the following code to the third-party kernel file **Makefile** in the **drivers/staging** directory: 118 119``` 120obj-$(CONFIG_HILOG) += hilog/ 121obj-$(CONFIG_HIEVENT) += hievent/ 122``` 123 124Enable the CONFIG macros **CONFIG\_HILOG** and **CONFIG\_HIEVENT** in the kernel **config** section. 125 126For details about how to use the logs, see [Hilog\_lite](https://gitee.com/openharmony/hiviewdfx_hilog_lite/blob/master/README.md). 127 128### Porting the HDF Feature 129 1301. Install HDF patches. 131 132 Run the shell script to apply HDF patches. 133 134 1. Set the four variables in the **patch\_hdf.sh** script. 135 2. Obtain the **patch\_hdf.sh** script. 136 3. Run the **patch\_hdf.sh** script to pass the four variables in sequence. 137 138 Run the following command: 139 140 ``` 141 ./patch_hdf.sh [Project root directory path] [Kernel directory path] [Kernel patch path] [Device name] 142 ``` 143 144 The following uses Raspberry Pi 3b as an example: 145 146 ``` 147 # Go to the Raspberry Pi kernel directory. 148 PROJ_ROOT/drivers/adapter/khdf/linux/patch_hdf.sh \ 149 PROJ_ROOT # Specify the path of the project root directory.\ 150 PROJ_ROOT/out/KERNEL_OBJ/kernel/src_tmp/linux-rpi3b # Specify the kernel directory for applying the patch.\ 151 PROJ_ROOT/kernel/linux/patches/linux-4.19 # Kernel patch patch.\ 152 hi3516dv300 # Device name. 153 ``` 154 1552. Configure the **config** file. 156 157 Configure basic HDF settings. If other functions are required, enable the corresponding driver switch by using **menuconfig**. 158 159 After HDF patches are installed, the HDF function is disabled by default. To enable the HDF function, perform the following settings: 160 161 ``` 162 CONFIG_DRIVERS_HDF=y 163 CONFIG_HDF_SUPPORT_LEVEL=2 164 CONFIG_DRIVERS_HDF_PLATFORM=y 165 CONFIG_DRIVERS_HDF_PLATFORM_MIPI_DSI=y 166 CONFIG_DRIVERS_HDF_PLATFORM_GPIO=y 167 CONFIG_DRIVERS_HDF_PLATFORM_I2C=y 168 CONFIG_DRIVERS_HDF_PLATFORM_UART=y 169 CONFIG_DRIVERS_HDF_TEST=y 170 ``` 171 172 Alternatively, run the following command to enable the HDF configuration on the **menuconfig** page: 173 174 ``` 175 # Generate the .config file. 176 make ${MAKE_OPTIONS} rpi3b_oh_defconfig 177 178 # Modify the HDF kernel configuration. 179 make ${MAKE_OPTIONS} menuconfig 180 # [*] Device Drivers 181 # [*] HDF driver framework support ---> 182 ``` 183 184 The configuration \(in **Device Drivers** \> **HDF driver framework support**\) is as follows: 185 186  187 188 189### Building the Image 190 191``` 192# Run the following command: 193make ${MAKE_OPTIONS} -j33 zImage 194``` 195 196### \(Optional\) Building and Running HDF Test Cases 197 198**Overview** 199 200The HDF test cases are used to verify basic functions of the HDF framework and peripherals. This document describes the HDF kernel-mode test cases. 201 202**Prerequisites** 203 204- In **menuconfig**, **CONFIG\_DRIVERS\_HDF\_TEST** is set to **y**. 205- The standard Hi3516D V300 kernel is built completely. 206 207**Test Case Build and Test Method** 208 209Use the [hdc_std](../subsystems/subsys-toolchain-hdc-guide.md) tool to push the test case execution file to the device and execute the test cases. The procedure is as follows: 210 2111. Build the HDF test cases. 2122. Use the **hdc_std** tool to push the test case execution file to the device. 2133. Go to the **data/test** directory of the device and execute the test file. 214 215The procedure is as follows: 216 2171. Build the HDF test cases. 218 219 Run the following command: 220 221 ``` 222 ./build.sh --product-name hispark_taurus_standard --build-target hdf_test 223 ``` 224 225 Wait until the build is complete. 226 2272. Copy the test files to the target device \(Raspberry Pi in this example\). 228 229 Method 1: Use the [hdc_std](../subsystems/subsys-toolchain-hdc-guide.md) tool. 230 231 1. Create the **data/test** directory in Raspberry Pi. 232 233 ``` 234 mkdir -p data/test 235 ``` 236 237 2. Push the dependencies and test cases to Raspberry Pi. 238 239 ``` 240 hdc file send XXX\out\{device_name}\hdf\hdf\libhdf_test_common.z.so /system/lib 241 hdc file send XXX\out\{device_name}\tests\unittest\hdf\config\hdf_adapter_uhdf_test_config /data/test 242 hdc file send XXX\out\{device_name}\tests\unittest\hdf\devmgr\DevMgrTest /data/test 243 hdc file send XXX\out\{device_name}\tests\unittest\hdf\osal\OsalTest /data/test 244 hdc file send XXX\out\{device_name}\tests\unittest\hdf\sbuf\SbufTest /data/test 245 ``` 246 247 Method 2: Copy the test files to Raspberry Pi using its memory card. 248 249 1. Remove the serial port and USB cable of Raspberry Pi from the PC, and remove its memory card. The **zImage** file in the memory card will be replaced. Back it up in advance. 250 2. Insert the memory card into the port of the PC used for porting, download the **zImage** file and the **test/** folder to the PC, and then copy them to the root directory of the memory card. 251 3. Insert the memory card into Raspberry Pi. 252 253 ``` 254 # Enable the Raspberry Pi file system to read the root directory of the memory card. 255 mount -t vfat /dev/block/mmcblk0p1 /boot 256 cd /boot/[Test file directory] 257 # Enable system files to be modified. 258 mount -o remount,rw / 259 # Install the test library. 260 mv libhdf_test_common.z.so /system/lib 261 mkdir /data/test 262 mv * /data/test 263 ``` 264 2653. Perform the test. 266 1. Go to the **data/test** directory. 267 268 ``` 269 cd /data/test 270 ``` 271 272 2. Assign the execute permission on the test files. 273 274 ``` 275 chmod 777 hdf_adapter_uhdf_test_config DevMgrTest OsalTest SbufTest 276 ``` 277 278 3. Start the test. 279 280 ``` 281 ./hdf_adapter_uhdf_test_config 282 ./DevMgrTest 283 ./OsalTest 284 ./SbufTest 285 ``` 286 287 4. If **PASSED** is displayed for all test items, HDF is functioning. 288 289 Example: DevMgrTest case 290 291 ``` 292 ./DevMgrTest 293 Running main() from gmock_main.cc 294 [==========] Running 1 test from 1 test case. 295 [----------] Global test environment set-up. 296 [----------] 1 test from DevMgrTest 297 [ RUN ] DevMgrTest.DriverLoaderTest_001 298 [ OK ] DevMgrTest.DriverLoaderTest_001 (0 ms) 299 [----------] 1 test from DevMgrTest (0 ms total) 300 [----------] Global test environment tear-down 301 Gtest xml output finished 302 [==========] 1 test from 1 test case ran. (0 ms total) 303 [ PASSED ] 1 test. 304 ``` 305 306 307 308
