1# Porting Preparation 2 3 4The OpenHarmony project must be built in the Linux environment. This topic describes how to set up the build environment, obtain the OpenHarmony source code, and create a vendor working directory to adapt the compilation framework of the vendor chip. 5 6 7## Setting Up the Build Environment 8 9Before porting, set up the build environment as instructed in [Setting Up the Windows Environment](../quick-start/quickstart-ide-env-win.md). 10 11 12## Obtaining Source Code 13 14 15### Procedure 16 17Download and compile the source code by following instructions in [Obtaining Source Code](https://gitee.com/openharmony/docs/blob/master/en/device-dev/get-code/sourcecode-acquire.md). 18 19>  **NOTE** 20> 21> This document applies only to OpenHarmony LTS 3.0.1 and earlier versions. Make sure you obtain the source code for one of these versions. 22 23 24### Directory Structure 25 26Table 1 describes the main directories of the OpenHarmony source code. The **device** and **vendor** directories are the working areas of chip and device module vendors. For details, see [Setting Up the Compilation Framework](#setting-up-the-compilation-framework). 27 28**Table 1** Main directories of OpenHarmony source code 29 30| Directory| Description| 31| -------- | -------- | 32| build | Directory where the compilation framework is located.| 33| kernel/liteos_m | Directory where the kernel is located. The **arch** directory describes the supported kernel architecture.| 34| device | Directory for adaptation by the chip vendor, where the **config.gni** file describes the architecture, toolchain, and linking options used by the current chip.| 35| vendor | Directory for adaptation by the device module vendor, where the **config.json** file describes the list of OpenHarmony subsystems to be integrated.| 36| utils | Adaptation related to files and KVs.| 37 38 39## Setting Up the Compilation Framework 40 41During porting, the vendor must create a working directory in the project based on your company name, chip model, and development board model, and add the created directory to the OpenHarmony compilation framework so that the working directory can participate in compilation. You can perform the following steps: 42 431. Add the chip vendor. 44 45 To adapt to OpenHarmony based on a chip, create a chip vendor directory in the **device** directory. The files in the directory describe the kernel type, compiler toolchain, linking options, and kernel configuration options. 46 47 Directory format: device/{*Chip vendor*}/{*Chip development board*} 48 49 Example: **device/MyDeviceCompany/MyBoard** 50 51 ``` 52 device 53 ├── hisilicon # HiSilicon chip-related directory, which can be used as a reference during directory creation. 54 ├── MyDeviceCompany # Chip vendor 55 │ └── MyBoard # Chip model 56 │ ├── BUILD.gn 57 │ ├── liteos_m 58 │ │ └── config.gni # Chip toolchain and compilation linking options 59 │ └── target_config.h # Kernel configuration options 60 └── qemu # QEMU-related 61 ``` 62 63 Build script: Add the files in **device/MyDeviceCompany/MyBoard** to the OpenHarmony compilation framework. 64 65 Path: **device/MyDeviceCompany/MyBoard/BUILD.gn** 66 67 68 ``` 69 group("MyBoard") { # Add the BUILD.gn file for parsing. 70 print("MyDeviceCompany MyBoard is under developing.") 71 } 72 ``` 73 74 Compilation configuration of the development board: This includes the kernel type, toolchain type, and compilation parameters. For details, see Table 2. 75 76 Path: **device/MyDeviceCompany/MyBoard/liteos_m/config.gni** 77 78 79 ``` 80 # Kernel type, e.g. "linux", "liteos_a", "liteos_m". 81 kernel_type = "liteos_m" 82 83 # Kernel version. 84 kernel_version = "" 85 86 # Board CPU type, e.g. "cortex-a7", "riscv32". 87 board_cpu = "cortex-m4" 88 89 # Board arch, e.g. "armv7-a", "rv32imac". 90 board_arch = "" 91 92 # Toolchain name used for system compiling. 93 # E.g. gcc-arm-none-eabi, arm-linux-harmonyeabi-gcc, ohos-clang, riscv32-unknown-elf. 94 # Note: The default toolchain is "ohos-clang". It's not mandatory if you use the default toochain. 95 board_toolchain = "arm-none-eabi-gcc" 96 97 # The toolchain path instatlled, it's not mandatory if you have added toolchian path to your ~/.bashrc. 98 board_toolchain_path = "" 99 100 # Compiler prefix. 101 board_toolchain_prefix = "arm-none-eabi-" 102 103 # Compiler type, "gcc" or "clang". 104 board_toolchain_type = "gcc" 105 106 # Board related common compile flags. 107 board_cflags = [] 108 board_cxx_flags = board_cflags 109 board_ld_flags = [] 110 111 # Board related headfiles search path. 112 board_include_dirs = [] 113 114 # Board adapter dir for OHOS components. 115 board_adapter_dir ="" 116 ``` 117 118 **Table 2** Main configuration items in config.gni 119 120 | Configuration Item| Description| 121 | -------- | -------- | 122 | kernel_type | Kernel type of the development board, for example, **"liteos_a"**, **"liteos_m"**, or **"linux"**.| 123 | kernel_version | Kernel version of the development board.| 124 | board_cpu | CPU type of the development board, for example, **"cortex-m4"**, **"cortex-a7"**, or **"riscv32"**.| 125 | board_arch | Architecture instruction set of the development board, for example, **"armv7-a"**.| 126 | board_toolchain | Name of the customized compiler toolchain used by the development board, for example, **"gcc-arm-none-eabi"**. If this parameter is not specified, **ohos-clang** will be used by default.| 127 | board_toolchain_path | Path of the compiler toolchain. If this parameter is left empty, the toolchain in the environment variable is used.| 128 | board_toolchain_prefix | Prefix of the compiler toolchain, for example, **"arm-none-eabi-"**.| 129 | board_toolchain_type | Type of the compiler toolchain, which can be **gcc** or **clang**.| 130 | board_cflags | Build options of the .c file configured for the development board.| 131 | board_cxx_flags | Build options of the .cpp file configured for the development board.| 132 | board_ld_flags | Linking options configured for the development board.| 133 | board_include_dirs | List of system header files configured on the development board.| 134 | board_adapter_dir | Adaptation files of the development board.| 135 1362. Add the device module vendor. 137 138 To develop a device module based on a chip with the OpenHarmony capability, create a module vendor directory under **vendor** and configure the OpenHarmony subsystem capabilities. 139 140 Directory format: vendor/{Product module vendor}/{Product module name}. 141 142 Example: **vendor/MyVendorCompany/MyProduct** 143 144 ``` 145 vendor 146 ├── hisilicon # HiSilicon chip-related directory, which can be used as a reference during directory creation. 147 └── MyVendorCompany # Module vendor 148 └── MyProduct # Product 149 ├── BUILD.gn 150 └── config.json # Product subsystem list 151 ``` 152 153 Build script: Add the files in **vendor/MyVendorCompany/MyProduct/BUILD.gn** to the OpenHarmony compilation framework. 154 155 Path: **vendor/MyVendorCompany/MyProduct/BUILD.gn** 156 157 158 ``` 159 group("MyProduct") { 160 print("MyVendorCompany MyProduct is under developing.") 161 } 162 ``` 163 164 Product configuration information: Add the product name, device vendor, kernel type, and subsystem list. For details, see Table 3. 165 166 Path: **vendor/MyVendorCompany/MyProduct/config.json** 167 168 169 ``` 170 { 171 "product_name": "MyProduct", 172 "ohos_version": "OpenHarmony 1.0", 173 "device_company": "MyDeviceCompany", 174 "board": "MyBoard", 175 "kernel_type": "liteos_m", 176 "kernel_version": "", 177 "subsystems": [ 178 { 179 "subsystem": "startup", 180 "components": [ 181 { "component": "bootstrap", "features":[] }, 182 { "component": "syspara_lite", "features": 183 [ 184 "enable_ohos_startup_syspara_lite_use_thirdparty_mbedtls = false" 185 ] 186 } 187 ] 188 } 189 ], 190 "vendor_adapter_dir": "", 191 "third_party_dir": "", 192 "product_adapter_dir": "//vendor/MyVendorCompany/MyProduct/hals", 193 } 194 ``` 195 196 **Table 3** Configuration items in the config.json file 197 198 | Configuration Item| Description| 199 | -------- | -------- | 200 | product_name | Product name, which is displayed during **hb set**.| 201 | ohos_version | OpenHarmony version number, which must be the same as the actual version number.| 202 | device_company | Chip vendor name, which is the same as the level-2 directory name under **device**.| 203 | board | Name of the development board, which is the same as the level-3 directory name under **device**.| 204 | kernel_type | Kernel type, which must match the kernel type of the OpenHarmony system ported to the development board.| 205 | kernel_version | Kernel version number, which matches the value of **kernel_version** in **config.gni**.| 206 | subsystem | Subsystem, which must be one supported by the OS. For details about the subsystem definition, see the description file of each subsystem in **build/lite/components**.| 207 | components | Components of the subsystem. For details about the components supported by a specific subsystem, see the **build/lite/components/{*Subsystem*}.json** file.| 208 | features | Features of the component configured for the product. For details, see the **BUILD.gn** file corresponding to the subsystem source code directory.| 209 | vendor_adapter_dir | Directory used for adaptation to IoT peripherals and UtilsFile file read and write capabilities. Generally, the value points to a directory under **device**. For details, see Step 2 in [Porting the File Subsystem] (porting-minichip-subsys-filesystem.md#example).| 210 | third_party_dir | Third-party software directory of the chip vendor, such as **mbedtls** and **lwip**. If the third-party software provided by OpenHarmony is used, leave this parameter empty or refer to the configuration for **hispark_pegasus**.| 211 | product_adapter_dir | Directory used for adaptation to hal_token and system parameters. Generally, the value points to a directory under **vendor**. For details, see Step 1 in [Porting the Startup Subsystem] (porting-minichip-subsys-startup.md#example).| 212 213 >  **NOTE** 214 > 215 > The compilation and build system checks the validity of fields. 216 > 217 > - The values of **device_company**, **board**, **kernel_type**, and **kernel_version** must match those configured by the chip vendor. 218 > 219 > - The values of **subsystem** and **component** must match the component description under **build/lite/components**. 220
