| About OpenHarmony| Getting familiar with OpenHarmony | - [About OpenHarmony](https://gitee.com/openharmony)<br>- [Glossary](../glossary.md)|
| Development resources | Preparing for your development | - [Obtaining Source Code](get-code/sourcecode-acquire.md)<br>- [Obtaining Tools](get-code/gettools-acquire.md) |
| Getting started | Getting started with setup, build, burning, debugging, and running of OpenHarmony | - [Mini and Small System Overview](quick-start/quickstart-ide-lite-overview.md)|
| Basic capabilities | Using basic capabilities of OpenHarmony | - [Kernel for Mini System](kernel/kernel-mini-overview.md)<br>- [Kernel for Small System](kernel/kernel-small-overview.md)<br>- [HDF](driver/driver-hdf-overview.md)<br>- [Subsystems](subsystems/subsys-build-all.md)<br>- [Security Guidelines](security/security-guidelines-overall.md)<br>- [Privacy Protection](security/security-privacy-protection.md)|
| Getting started | Getting started with setup, build, burning, debugging, and running of OpenHarmony | - [Getting Started](quick-start/Readme-EN.md)|
| Basic capabilities | Using basic capabilities of OpenHarmony | - [Kernel for Mini System](kernel/kernel-mini-overview.md)<br>- [Kernel for Small System](kernel/kernel-small-overview.md)<br>- [HDF](driver/driver-hdf-overview.md)<br>- [Compilation and Building Guide](subsystems/subsys-build-all.md)<br>- [Security Guidelines](security/security-guidelines-overall.md)<br>- [Privacy Protection](security/security-privacy-protection.md)|
| Advanced development | Developing smart devices based on system capabilities | - [WLAN-connected Products](guide/device-wlan-led-control.md)<br>- [Cameras with a Screen](guide/device-camera-control-overview.md) |
| Porting and adaptation | - Porting and adapting OpenHarmony to an SoC<br>- Porting and adapting OpenHarmony to a third-party library<br>- Third-party vendor porting cases<br>| - [Mini System SoC Porting Guide](porting/porting-minichip.md)<br>- [Small System SoC Porting Guide](porting/porting-smallchip-prepare-needs.md)<br>- [Third-Party Library Porting Guide for Mini and Small Systems](porting/porting-thirdparty-overview.md)<br> - [Mini-System Devices with Screens — Bestechnic SoC Porting Case](porting/porting-bes2600w-on-minisystem-display-demo.md)<br> - [Combo Solution – ASR Chip Porting Case](porting/porting-asr582x-combo-demo.md)<br> |
| Porting and adaptation | - Porting and adapting OpenHarmony to an SoC<br>- Porting and adapting OpenHarmony to a third-party library<br>- Third-party vendor porting cases<br>| - [Small System SoC Porting Guide](porting/porting-smallchip-prepare-needs.md)<br>- [Third-Party Library Porting Guide for Mini and Small Systems](porting/porting-thirdparty-overview.md)<br> - [Mini-System Devices with Screens — Bestechnic SoC Porting Case](porting/porting-bes2600w-on-minisystem-display-demo.md) |
| Contributing components | Contributing components to OpenHarmony | - [HPM Part Overview](hpm-part/hpm-part-about.md)<br>- [HPM Part Development](hpm-part/hpm-part-development.md)<br>- [HPM Part Reference](hpm-part/hpm-part-reference.md) |
| Reference | Referring to development specifications | [FAQs](faqs/faqs-overview.md) |
| Reference | Referring to development specifications | - [FAQs](faqs/faqs-overview.md) |
**Table 2** Standard system development guidelines (reference memory ≥ 128 MiB)
| Topic| Development Scenario| Related Documentation|
| -------- | -------- | -------- |
| About OpenHarmony| Getting familiar with OpenHarmony| - [About OpenHarmony](https://gitee.com/openharmony)<br>- [Glossary](../glossary.md)|
| Development resources| Preparing for your development| - [Obtaining Source Code](get-code/sourcecode-acquire.md)<br>- [Obtaining Tools](get-code/gettools-acquire.md)|
| Getting started| Getting started with setup, build, burning, debugging, and running of OpenHarmony| - [Standard System Overview](quick-start/quickstart-ide-standard-overview.md) |
| Basic capabilities| Using basic capabilities of OpenHarmony| - [Kernel Development](kernel/kernel-standard-overview.md)<br>- [HDF](driver/driver-hdf-overview.md)<br>- [Subsystems](subsystems/subsys-build-all.md)<br>- [Security Guidelines](security/security-guidelines-overall.md)<br>- [Privacy Protection](security/security-privacy-protection.md) |
| Development resources| Preparing for your development| - [Obtaining Source Code](get-code/sourcecode-acquire.md)<br>- [Obtaining Tools](get-code/gettools-acquire.md)|
| Getting started| Getting started with setup, build, burning, debugging, and running of OpenHarmony| - [Getting Started](quick-start/Readme-EN.md) |
| Basic capabilities| Using basic capabilities of OpenHarmony| - [Kernel Development](kernel/kernel-standard-overview.md)<br>- [HDF](driver/driver-hdf-overview.md)<br>- [Compilation and Building Guide](subsystems/subsys-build-all.md)<br>- [Security Guidelines](security/security-guidelines-overall.md)<br>- [Privacy Protection](security/security-privacy-protection.md) |
| Advanced development| Developing smart devices based on system capabilities| - [Development Guidelines on Clock Apps](guide/device-clock-guide.md)<br>- [Development Example for Platform Drivers](guide/device-driver-demo.md)<br>- [Development Example for Peripheral Drivers](guide/device-outerdriver-demo.md) |
| Porting and adaptation| - Porting and adapting OpenHarmony to an SoC<br>- Rapidly porting the OpenHarmony Linux kernel| - [Standard System Porting Guide](porting/standard-system-porting-guide.md)<br>- [A Method for Rapidly Porting the OpenHarmony Linux Kernel](porting/porting-linux-kernel.md)|
| Porting and adaptation| - Porting and adapting OpenHarmony to an SoC<br>- Rapidly porting the OpenHarmony Linux kernel| - [Standard System Porting Guide](porting/standard-system-porting-guide.md)<br>- [A Method for Rapidly Porting the OpenHarmony Linux Kernel](porting/porting-linux-kernel.md) |
| Contributing components| Contributing components to OpenHarmony| - [HPM Part Overview](hpm-part/hpm-part-about.md)<br>- [HPM Part Development](hpm-part/hpm-part-development.md)<br>- [HPM Part Reference](hpm-part/hpm-part-reference.md) |
| Reference| Referring to development specifications| [FAQs](faqs/faqs-overview.md)|
| Reference| Referring to development specifications | - [FAQs](faqs/faqs-overview.md)|
2. Burn the U-Boot file by following the procedures for burning a U-Boot file over USB.
Select the U-Boot files of the corresponding development board for burning by referring to [Burning to Hi3516D V300](../quick-start/quickstart-ide-lite-steps-hi3516-burn.md).
Select the U-Boot files of the corresponding development board for burning by referring to [Burning an Image](../quick-start/quickstart-ide-3516-burn.md).
3. Log in to the serial port after the burning is complete.
Download and install DevEco Studio. For details, see the [HUAWEI DevEco Studio User Guide](../../application-dev/quick-start/deveco-studio-user-guide-for-openharmony.md).
Download and install DevEco Studio. For details, see the [DevEco Studio User Guide](../../application-dev/quick-start/deveco-studio-user-guide-for-openharmony.md).
## How to Develop<a name="section19901741111312"></a>
...
...
@@ -251,7 +251,7 @@ After finishing writing the app code, you need to sign and package the app befor
## Running on the Real Device<a name="section092721731511"></a>
Before you install the app and run it on the development board, install the DevEco Device Tool by following operations provided in [HUAWEI DevEco Device Tool User Guide](https://device.harmonyos.com/en/docs/ide/user-guides/service_introduction-0000001050166905). Burn OpenHarmony into the development board and run it. For details about how to build, burn, and run an image, see [Standard System Overview](../quick-start/quickstart-standard-overview.md). After the image is running normally and the system is started properly, perform the following steps to install or uninstall the app:
Before you install the app and run it on the development board, install the DevEco Device Tool by following operations provided in [DevEco Device Tool User Guide](https://device.harmonyos.com/en/docs/ide/user-guides/service_introduction-0000001050166905). Burn OpenHarmony into the development board and run it. For details about how to build, burn, and run an image, see [Getting Started with the Standard System with Hi3516 (IDE Mode)](../quick-start/quickstart-appendix-hi3516-ide.md). After the image is running normally and the system is started properly, perform the following steps to install or uninstall the app:
>This development example applies to standard, small, and mini OpenHarmony systems. The following sections use the standard system as an example. You can refer to the specific guide for your system to set up the environment.
...
...
@@ -430,8 +430,8 @@ Initialize the controller hardware, call core-layer APIs to add or delete device
2. Build source code and burn images to the development board.
- For details about the operations using the installation package, see [Building](../quick-start/quickstart-ide-standard-running-hi3516-build.md) and [Burning](../quick-start/quickstart-ide-standard-running-hi3516-burning.md).
- For details about the operations using the installation package, see [Building Source Code](../quick-start/quickstart-appendix-hi3516-pkg.md#building-source-code) and [Burning an Image](../quick-start/quickstart-appendix-hi3516-pkg.md#burning-an-image).
- For details about the operations in IDE mode, see [Building](../quick-start/quickstart-standard-running-hi3516-build.md) and [Burning](../quick-start/quickstart-standard-running-hi3516-burning.md).
- For details about the operations in IDE mode, see [Building Source Code](../quick-start/quickstart-appendix-hi3516-ide.md#building-source-code) and [Burning an Image](../quick-start/quickstart-appendix-hi3516-ide.md#burning-an-image).
>This development example applies to standard, small, and mini OpenHarmony systems. The following sections use the standard system as an example. You can refer to the specific guide for your system to set up the environment.
...
...
@@ -315,7 +315,7 @@ The input driver model consists of three parts of drivers. To develop a brand-ne
**touch\_gt911.o** is the content added in this example.
2. Build source code and burn images. For details, see the related sections in [Standard System Overview](../quick-start/quickstart-standard-overview.md).
2. Build source code and burn images. For details, see the related sections in [Quick Start Overview](../quick-start/quickstart-overview.md).
## Debugging and Verification<a name="section62577313482"></a>
For details about the compilation and burning processes, see [Building](../quick-start/quickstart-lite-steps-hi3861-building.md) and [Burning](../quick-start/quickstart-lite-steps-hi3861-burn.md).
For details about the compilation and burning processes, see [Building Source Code](../quick-start/quickstart-ide-3861-build.md) and [Burning an Image](../quick-start/quickstart-ide-3861-burn.md).
After the preceding two steps are complete, press the **RST** button to reset the module. If the LED blinks periodically as expected, the verification is passed.
@@ -95,7 +95,7 @@ The OpenHarmony LiteOS-M kernel build system is a modular build system based on
### Setting Up the Environment
Before setting up the environment for a development board, you must set up the basic system environment for OpenHarmony first. The basic system environment includes the OpenHarmony build environment and development environment. For details, see [Setting Up Development Environment](../quick-start/quickstart-lite-env-setup.md).
Before setting up the environment for a development board, you must set up the basic system environment for OpenHarmony first. The basic system environment includes the OpenHarmony build environment and development environment. For details, see [Quick Start Overview](../quick-start/quickstart-overview.md).
### Obtaining the OpenHarmony Source Code
...
...
@@ -133,9 +133,9 @@ The LiteOS-M kernel porting projects for specific development boards are provide
How to contribute a chip based on Liteos-M kernel:
Before running the **clang** command, install the LLVM compiler. For details, see [Installing LLVM](../quick-start/quickstart-lite-steps-hi3861-setting.md).
**--target=arm-liteos**: specifies the compilation platform, which is arm-liteos.
**--sysroot=$\{YOUR\_ROOT\_OUT\_PATH\}/sysroot**: specifies the directory in which you can search for the header file and the dependent standard libraries.
A user-mode program can be started in either of the following ways:
OpenHarmony has organized a Special Interest Group (SIG) [SIG_DevBoard](https://gitee.com/openharmony/community/blob/master/sig/sig-devboard/sig_devboard.md) to provide support for third-party development boards.
...
...
@@ -10,7 +10,7 @@ Before learning about how to port the code of a development board, take a look a
| Small-system devices| Memory > 1 MB, with MMU| LiteOS-A and Linux|
| Standard-system devices| Memory > 128 MB| Linux |
# Code Preparation
## Code Preparation
OpenHarmony has created repositories for vendors in openharmony-sig. To participate in the repository development, you need to use the following method to initialize and download the code.
@@ -473,8 +473,6 @@ The compilation option entry of the subsystem is in the `config.json` file of th
The source code of the lwIP component is stored in `//third_party/lwip`. The kernel in OpenHarmony is customized in `//kernel/liteos_m/components/net/lwip-2.1`, including the redefinition of some interfaces and structures.
For details about the porting process, see [lwIP Module Adaptation](porting-chip-board-lwip.md).
In this example, the path for setting lwip in the `config.json` file is as follows:
To use third-party modules in the **third\_party** directory, you may need to adapt the modules. This section uses mbedTLS as an example to describe how to integrate the adaptation code with the OpenHarmony compilation framework. For the principles of mbedTLS and the specific logic of the adaptation code, see the adaptation guide on the mbedTLS official website.
1.<aname="li12446195633211"></a>Write the adaptation layer code.
Write the required adaptation layer code based on the mbedTLS adaptation guide. In this example, adaptation of the hardware random number is used for illustration, and the paths are relative to **third\_party/mbedtls**:
1. Copy the **include/mbedtls/config.h** file to the **ports** directory, and enable **MBEDTLS\_ENTROPY\_HARDWARE\_ALT** in the file.
2. In the **ports** directory, create the **entropy\_poll\_alt.c** file under **include** and implement the hardware random number API in **entropy\_poll.h**.
3. Add the path of the adapted **entropy\_poll\_alt.c** file to **mbedtls\_sources** in the **BUILD.gn** file.
4. Add the line **MBEDTLS\_CONFIG\_FILE** to **lite\_library\("mbedtls\_static"\)** in the **BUILD.gn** file to specify the path of the new configuration file.
You are advised to make the preceding modifications in a new **config.h** file or **_xxx_\_alt.c** file. Do not directly edit the code in the original file. Intrusive modifications may cause a large number of scattered conflicts during subsequent version updates, increasing the update maintenance costs.
2. Create a patch.
The preceding adaptation is hardware-specific. Therefore, when uploading code to the library, you cannot directly store the code in the **third\_party/mbedtls** directory. Instead, you need to integrate the preceding modifications into a patch and inject the patch into the code for a build.
1. Add the patch configuration file **device/<_company_\>/<_board_\>/patch.yml**.
2. In the **device/<_company_\>/<_board_\>/patch.yml** file, add the information about the patch to apply.
```
# Path of the patch to apply. This path is relative to the code root directory.
>The information about the product to which the patch is most recently applied will be recorded. Next time the build is performed, the previous patch is rolled back \(that is, **\`patch -p1 -R < xxx\`** is executed\). If the patch fails to be rolled back or a patch fails to be added, the build process is terminated. In this case, resolve the patch conflict and try again.
# System Modules<a name="EN-US_TOPIC_0000001199722621"></a>
System modules, such as the system ability manager \(SAMGR\) and DFX subsystem, provide basic capabilities for upper-layer applications. During board-level system porting, you can directly select the system modules as required without any adaptation.
## SAMGR<a name="section105874301910"></a>
**Introduction**
This service-oriented framework enables you to develop services, features, and external APIs, and implement multi-service process sharing and service invocation for inter-process communication \(IPC\).
>This module must be used during board-level system porting. Otherwise, other service modules cannot run properly.
For details about how to use SAMGR, see [samgr\_lite](https://gitee.com/openharmony/systemabilitymgr_samgr_lite/blob/master/README.md).
## DFX<a name="section20064420420"></a>
**Introduction**
The design for X \(DFX\) subsystem mainly includes design for reliability \(DFR\) and design for testability \(DFT\), providing code maintenance and testing.
For details about how to use the DFX subsystem, see [DFX](../subsystems/subsys-dfx-overview.md).
To implement board-level driver adaptation, perform the following steps:
1. Develop the SDK based on the CMSIS/POSIX APIs provided by OpenHarmony.
The board-level SDK can be adapted to OS interfaces via CMSIS and POSIX APIs. Currently, the LiteOS Cortex-M kernel is adapted to most CMSIS APIs \(including APIs used for basic kernel management, thread management, timer, event, mutex, semaphore, and queue\), which meets the requirements of porting. POSIX APIs provide basic capabilities for porting, and more POSIX APIs are to be implemented. If the SDK is implemented based on the CMSIS or POSIX APIs, it can directly adapt to the LiteOS Cortex-M kernel.
If the SDK is developed based on other embedded OSs such as FreeRTOS, or has an abstraction layer for OS interfaces, it is recommended that the OS-dependent APIs be directly adapted to the CMSIS APIs.
Here is an OS interface defined by a product for creating a queue:
2. Compile the SDK independently or modify the SDK based on the OpenHarmony building framework and integrate the SDK code into the **device** directory of OpenHarmony as required.
After completing the OS API adaptation, you can integrate the board-level driver to OpenHarmony by the following two methods:
- Compile the SDK independently and link it to the OpenHarmony project in the binary format.
- Modify the SDK building framework based on OpenHarmony. Considering the long-term evolution and subsequent joint debugging, you are advised to compile the SDK based on the GN building framework and link it to the OpenHarmony project in the form of source code.
# Implementation of APIs at the HAL<a name="EN-US_TOPIC_0000001199722623"></a>
The HAL mainly aims to decouple OpenHarmony from the SoC. The following modules describe the dependency of OpenHarmony on the SoC APIs.
## Utils<a name="section1394788286"></a>
**Introduction**
The Utils subsystem provides common basic components that can be used by other subsystems and upper-layer applications. These basic components are implemented based on the file system of the SoC. The SoC platform must implement file operations such as opening, closing, reading data from, and writing data to a file, as well as obtaining the file size.
**Description for HAL APIs of the Utils subsystem**
The SoC needs to implement related APIs. For details about the dependency of OpenHarmony on the SoC file system APIs, see [HAL header files of Utils](https://gitee.com/openharmony/utils_native_lite/tree/master/hals/file).
The IoT peripheral subsystem provides dedicated peripheral operation interfaces for OpenHarmony, including FLASH, GPIO, I2C, PWM, UART, and WATCHDOG APIs.
**Description for HAL APIs of the IoT peripheral subsystem**
The SoC needs to implement related APIs. For details about the dependency of OpenHarmony on the chip peripheral APIs, see [HAL header files of IoT peripherals](https://gitee.com/openharmony/iothardware_peripheral/tree/master/interfaces/inner_api).
## WLAN<a name="section1331917210911"></a>
**Introduction**
The WLAN service enables devices to access the WLAN in the following modes:
-**Station \(STA\) mode**: allows your device to connect to the WLAN access point enabled on other devices and routers.
-**Access point \(AP\) mode**: enables your device to function as a WLAN access point for other devices to connect to.
The WLAN service enables you to control the WLAN in the system, including enabling, disabling, scanning for, connecting to, and disconnecting from WLAN access points.
In addition, it supports event listening. You can listen to the WLAN status and immediately detect the status change.
**Description for HAL APIs of the WLAN subsystem**
The vendor needs to implement defined APIs in the **vendor/\*\*\*/\*\*\*/\*\*\*\_adapter** directory. The following example shows how to implement these APIs for the Hi3861 chip:
The SoC needs to implement related APIs. For details about the dependency of OpenHarmony on the chip peripheral APIs, see [header files of WLAN](https://gitee.com/openharmony/communication_wifi_lite/tree/master/interfaces/wifiservice).
Lightweight IP (lwIP) is an open-source TCP/IP stack designed for embedded systems. LiteOS-M has adapted to lwIP and provides enhanced lwIP features. The lwIP code consists of the following:
- lwIP source code in the **third_party/lwip** directory: Only a few intrusive modifications have been made for enhanced features.
- Code for lwIP adaptation and enhancement in the **kernel/liteos_m/components/net/lwip-2.1** directory: The default lwIP configuration file is provided.
If you want to use the lwIP module, perform the following steps to complete adaptation:
1. Create a directory, for example, **lwip_adapter**, in the device directory to store its adaptation files.
2. Create the **include** directory in the **lwip_adapter** directory to store the adaptation header files.
3. Create the **lwip** directory in the **include** directory and then create the header file **lwipopts.h** in the **lwip** directory. The code is as follows. If the default configuration cannot meet service requirements, modify the configuration, for example, disable the DHCP function.
```
#ifndef _LWIP_ADAPTER_LWIPOPTS_H_
#define _LWIP_ADAPTER_LWIPOPTS_H_
#include_next "lwip/lwipopts.h"
#undef LWIP_DHCP
#define LWIP_DHCP 0 // Disable the DHCP function.
#endif /* _LWIP_ADAPTER_LWIPOPTS_H_ */
```
4. Copy **BUILD.gn** in the **kernel/liteos_m/components/net/lwip-2.1/porting** directory to the **lwip_adapter** directory and modify the file as follows:
For details about board-level system building adaptation, see [Compilation and Building Subsystem](porting-chip-prepare-process.md). The board-related drivers, software development software kits \(SDKs\), directories, and HAL implementation are stored in the **device** directory. The directory structure and its description are as follows:
```
.
├── device --- Sample board
│ └── xxx --- <Vendor name of the board>
│ └── xxx --- <Board name>. This directory contains the demo of the LiteOS Cortex-M kernel, which can run properly.
│ ├── BUILD.gn --- Building configuration file of the board
│ ├── board --- Specific implementation of the board (Optional. If a product-level demo is provided, implementation at the application layer is stored in this directory.)
│ ├── liteos_m --- LiteOS Cortex-M kernel to use based on the kernel_type in the BUILD.gn file
│ │ └── config.gni --- Building options
│ ├── libraries --- Board-level SDK
│ │ └── include --- SDK-provided header files that are exposed externally
│ │ └── ... --- binary or source files
│ ├── main.c --- main function entry (Product level configuration is used if the same definition exists at the product level.)
X Test Suite \(XTS\) is a set of OpenHarmony certification test suites. Currently, the application compatibility test suite \(ACTS\) is supported. The **test/xts** repository contains the **acts** directory and **tools** software package.
- The **acts** directory stores the source code and configuration files of ACTS test cases. The ACTS helps device vendors detect the software incompatibility as early as possible and ensures that the software is compatible with OpenHarmony during the entire development process.
- The **tools** software package stores the test case development framework related to **acts**.
The LiteOS Cortex-M kernel provides the system initialization process and customized configuration options required for system running. During kernel porting, you must pay attention to the functions related to hardware configuration in the initialization process and understand the kernel configuration options so that the minimum kernel that matches the board can be tailored.
In the **startup.S** file, you must ensure that the entry function \(for example, **reset\_vector**\) of the interrupt vector table is stored in the RAM start address specified by the link configuration files. The link configuration files of IAR, Keil, and GCC projects are **xxx.icf**, **xxx.sct**, and **xxx.ld**, respectively. The startup file provided by the vendor does not need to be modified if the **startup.S** file has initialized the system clock and returned to the **main** function. Otherwise, the preceding functions need to be implemented.
In the **main.c** file, you need to register the UartInit function used for initializing the serial port and the handler function used for the system tick.
- The UartInit function initializes the board serial port, and the function name can be defined based on the board. This function is optional. You can determine whether to call it based on whether the board supports the serial port. If the board supports the serial port, this function must enable TX and RX channels of the serial port and set the baud rate.
- You can call **HalTickStart** to set the **OsTickHandler** function for the tick interrupt response.
For the chip whose interrupt vector table cannot be redirected, you need to disable the **LOSCFG\_PLATFORM\_HWI** macro, and add the **OsTickHandler** function for the tick interrupt response in the **startup.S** file.
The **los\_config.h** file defines both complete configuration and default configuration of **liteos\_m**. All configuration items in this file can be customized for different boards as required.
You can define configuration items in the **device/xxxx/target\_config.h** file of the corresponding board. For other undefined configuration items, default values in the **los\_config.h** file will be used.
The following table shows some typical configuration items:
<tdclass="cellrowborder"valign="top"width="65.19%"headers="mcps1.2.3.1.2 "><pid="p84408426194"><aname="p84408426194"></a><aname="p84408426194"></a>Switch of the software timer. The values <strongid="b10860112593720"><aname="b10860112593720"></a><aname="b10860112593720"></a>1</strong> and <strongid="b297273113393"><aname="b297273113393"></a><aname="b297273113393"></a>0</strong> indicate that the switch is turned on and turned off, respectively.</p>
<tdclass="cellrowborder"valign="top"width="65.19%"headers="mcps1.2.3.1.2 "><pid="p62502611378"><aname="p62502611378"></a><aname="p62502611378"></a>Switch of the time alignment feature, which depends on the switch status of the software timer. The values <strongid="b10462312174018"><aname="b10462312174018"></a><aname="b10462312174018"></a>1</strong> and <strongid="b3462151215403"><aname="b3462151215403"></a><aname="b3462151215403"></a>0</strong> indicate that the switch is turned on and turned off, respectively.</p>
<tdclass="cellrowborder"valign="top"width="65.19%"headers="mcps1.2.3.1.2 "><pid="p1144017426191"><aname="p1144017426191"></a><aname="p1144017426191"></a>Switch of the mux feature. The values <strongid="b12108629184012"><aname="b12108629184012"></a><aname="b12108629184012"></a>1</strong> and <strongid="b510882954014"><aname="b510882954014"></a><aname="b510882954014"></a>0</strong> indicate that the switch is turned on and turned off, respectively.</p>
<tdclass="cellrowborder"valign="top"width="65.19%"headers="mcps1.2.3.1.2 "><pid="p1644094201917"><aname="p1644094201917"></a><aname="p1644094201917"></a>Switch of the queue feature. The values <strongid="b1514814454405"><aname="b1514814454405"></a><aname="b1514814454405"></a>1</strong> and <strongid="b114824504011"><aname="b114824504011"></a><aname="b114824504011"></a>0</strong> indicate that the switch is turned on and turned off, respectively.</p>
<tdclass="cellrowborder"valign="top"width="65.19%"headers="mcps1.2.3.1.2 "><pid="p529503704116"><aname="p529503704116"></a><aname="p529503704116"></a>Maximum number of available tasks, excluding idle tasks. You can set this item based on your actual service requirements, or you can initially set it to a large value and adjust the value at a later time.</p>
<tdclass="cellrowborder"valign="top"width="65.19%"headers="mcps1.2.3.1.2 "><pid="p1044024261912"><aname="p1044024261912"></a><aname="p1044024261912"></a>Switch of the semaphore feature. The values <strongid="b0766102114312"><aname="b0766102114312"></a><aname="b0766102114312"></a>1</strong> and <strongid="b1876612254312"><aname="b1876612254312"></a><aname="b1876612254312"></a>0</strong> indicate that the switch is turned on and turned off, respectively.</p>
<tdclass="cellrowborder"valign="top"width="65.19%"headers="mcps1.2.3.1.2 "><pid="p13441154216198"><aname="p13441154216198"></a><aname="p13441154216198"></a>Switch of the exception feature. The values <strongid="b15509164154316"><aname="b15509164154316"></a><aname="b15509164154316"></a>1</strong> and <strongid="b1651024115436"><aname="b1651024115436"></a><aname="b1651024115436"></a>0</strong> indicate that the switch is turned on and turned off, respectively.</p>
<tdclass="cellrowborder"valign="top"width="65.19%"headers="mcps1.2.3.1.2 "><pid="p1744115424197"><aname="p1744115424197"></a><aname="p1744115424197"></a>Switch of the print feature. The values <strongid="b71401245104416"><aname="b71401245104416"></a><aname="b71401245104416"></a>1</strong> and <strongid="b141401545194417"><aname="b141401545194417"></a><aname="b141401545194417"></a>0</strong> indicate that the switch is turned on and turned off, respectively.</p>
The chip architecture adaptation process is optional. If the particular chip architecture is supported in the **liteos\_m/arch** directory, you can directly implement the board adaptation. Otherwise, chip architecture porting is required.
The kernel used by module chips is LiteOS Cortex-M, which consists of four modules, namely kernel abstraction layer \(KAL\), components, kernel, and utils.
-**KAL**: provides APIs exposed externally and depends on the components and kernel modules.
-**Components**: is pluggable and relies on the kernel module.
-**Kernel**: stores hardware-related code in the **arch** directory and other code. The implementation of kernel function sets \(such as task and sem\), for example, task context switching and atomic operations, depends on the hardware-related code in the **arch** directory.
-**Utils**: functions as a basic code block where other modules rely.
**Figure 1** Architecture of the LiteOS Cortex-M kernel<aname="fig10838105524917"></a>
As shown in the [Directory Specifications](#section18127744153119), the **arch/include** directory defines the functions that need to be implemented on the common chip architecture. The code related to the chip architecture contains assembly code, which varies based on building toolchains. Therefore, the code for adapting to different toolchains \(for example, IAR, Keil, GCC, etc.\) must be implemented in a specific chip architecture.
The **arch/include** directory defines common files and functions. All functions in this directory need to be implemented to adapt to a newly added architecture. For details, refer to the following header files.
```
los_arch.h --- Defines the functions required for initializing the chip architecture.
los_atomic.h --- Defines the atomic operation functions required by the chip architecture.
los_context.h --- Defines the context functions required by the chip architecture.
los_interrupt.h --- Defines the interrupt and exception functions required by the chip architecture.
los_timer.h --- Defines the timer functions required by the chip architecture.
Add the sample program file **main.c** to the **device** directory of the project and compile the file. After LOS\_KernelInit is complete, this sample program will create two tasks that loop the **LOS\_TaskDelay** function and print the log information cyclically. In this way, you can check whether system scheduling and the clock work properly.
```
VOID TaskSampleEntry2(VOID) // Entry function of task 2
{
while(1) {
LOS_TaskDelay(10000);
printf("taskSampleEntry2 running...\n");
}
}
VOID TaskSampleEntry1(VOID) // Entry function of task 1
UartInit(); // Configure the hardware serial port and output the debug log over this serial port. The actual function name varies with the board.
printf("\n\rhello world!!\n\r");
ret = LOS_KernelInit();
TaskSample();
if (ret == LOS_OK) {
LOS_Start(); // Start system scheduling, execute stTask1/stTask2 cyclically, and output task logs over the serial port.
}
while (1) {
__asm volatile("wfi");
}
}
```
If the first task is executed properly, the core process of the minimum system is valid. Due to the XTS framework's dependency on the link scripts of Utils and Bootstrap as well as the building framework, testing the kernel by executing the XTS is not supported. You can test whether the minimum system is completely ported in [XTS](porting-chip-board-xts.md).
This document provides basic guidance for OpenHarmony developers and system on a chip (SoC) or module vendors to port OpenHarmony to typical chip architectures, such as the Cortex-M and RISC-V series. Currently, the Bluetooth service is not supported. Due to the complexity of the OpenHarmony project, this document is subject to update as the version and APIs change.
This guide is intended for readers who have experience in developing embedded systems. Therefore, it mainly describes operations and key points during platform porting instead of basic introduction to the OS.
## Porting Directory
The implementation of the OpenHarmony project directories and functions relies on the OS itself. If no enhancement for a complex feature is involved, you only need to focus on the directories described in the following table.
**Table 1** Key directories in the porting process
| Directory| Description|
| -------- | -------- |
| /build/lite | OpenHarmony basic compilation and building framework.|
| /kernel/liteos_m | Basic kernel. The implementation related to the chip architecture is in the **arch** directory.|
| /device | Board-level implementation, which complies with the OpenHarmony specifications. For details about the directory structure and porting process, see [Overview](../porting/porting-chip-board-overview.md).|
| /vendor | Product-level implementation, which is contributed by product vendors. |
The **device** directory is in the internal structure of **device/{Chip solution vendor}/{Development board}**. The following uses HiSilicon **hispark_taurus** as an example:
```
device
└── hisilicon # Name of the chip solution vendor
├── common # Common part of the chip solution development board
└── hispark_taurus # Name of the development board
├── BUILD.gn # Entry to building the development board
├── hals # OS hardware adaptation of the chip solution vendor
├── linux # Linux version
│ └── config.gni # Configurations of the building toolchain and building options for the Linux version
└── liteos_a # LiteOS Cortex-A version
└── config.gni # Configurations of the building toolchain and building options for the LiteOS Cortex-A version
```
The **vendor** directory is in the internal structure of **vendor/{Product solution vendor}/{Product name}**. The following uses the Wi-Fi IoT product as an example:
```
vendor # Product solution vendor
└── example # Name of the product solution vendor
└── wifiiot # Product name
├── hals # OS adaptation of the product solution vendor
├── BUILD.gn # Product building script
└── config.json # Product configuration file
```
## Porting Process
The **device** directory of OpenHarmony is the adaptation directory for the basic SoC. You can skip the porting process and directly develop system applications if complete SoC adaptation code is already available in the directory. If there is no corresponding SoC porting implementation in the directory, complete the porting process by following the instructions provided in this document. The following figure shows the process of porting OpenHarmony to a third-party SoC.
- The porting must comply with the basic principles described in [How to Contribute](../../contribute/how-to-contribute.md).
- The code required for third-party SoC adaptation is stored in the **device**, **vendor**, and **arch** directories. Naming and usage of these directories must comply with specified naming and usage specifications. For details, see [Overview](../porting/porting-chip-kernel-overview.md) and [Board-Level Directory Specifications](../porting/porting-chip-board-overview.md#section6204129143013).
For details about compilation and building, see [Compilation and Building Guide](../subsystems/subsys-build-all.md). When adding third-party chips, perform the following steps to complete building adaptation:
## Building Adaptation Process
You need to create a directory for the development board. For example, for the RTL8720 development board from SoC provider Realtek, the **device/realtek/rtl8720** directory must be created. To complete the building adaptation, perform the following steps:
1. Configure the toolchain and building options.
The **ohos-clang** toolchain is used by default. SoC providers can also customize the configuration based on their development boards. The building-related variables in the building configuration file of the development board are described as follows:
-**kernel_type**: kernel used by the development board, for example, **"liteos_a"**, **"liteos_m"**, or **"linux"**.
-**kernel_version**: kernel version of the development board, for example, **"4.19"**.
-**board_cpu**: CPU of the development board, for example, **"cortex-a7"** or **"riscv32"**.
-**board_arch**: chipset architecture of the development board, for example, **"armv7-a"** or **"rv32imac"**.
-**board_toolchain**: name of the customized build toolchain used by the development board, for example, **"gcc-arm-none-eabi"**. If this field is not specified, **ohos-clang** will be used.
-**board_toolchain_prefix**: prefix of the build toolchain, for example, **"gcc-arm-none-eabi"**.
-**board_toolchain_type**: build toolchain type. Currently, only GCC (**"gcc"**) and clang (**"clang"**) are supported.
-**board_cflags**: build options of the .c file configured for the development board.
-**board_cxx_flags**: build options of the **.cpp** file configured for the development board.
-**board_ld_flags**: linking options configured for the development board.
The corresponding **config.gni** file will be loaded based on the development board selected by the product. The variables in this file are globally visible to system modules.
The following is an example of the **device/realtek/rtl8720/liteos_m/config.gni** file for the RTL8720 development board:
```
# Kernel type, e.g. "linux", "liteos_a", "liteos_m".
kernel_type = "liteos_m"
# Kernel version.
kernel_version = "3.0.0"
# Board CPU type, e.g. "cortex-a7", "riscv32".
board_cpu = "real-m300"
# Board arch, e.g. "armv7-a", "rv32imac".
board_arch = ""
# Toolchain name used for system compiling.
# E.g. gcc-arm-none-eabi, arm-linux-harmonyeabi-gcc, ohos-clang, riscv32-unknown-elf.
# Note: The default toolchain is "ohos-clang". It's not mandatory if you use the default toochain.
board_toolchain = "gcc-arm-none-eabi"
# The toolchain path installed, it's not mandatory if you have added toolchain path to your ~/.bashrc.
2. Write the build script of the development board.
For a newly added development board, the **BUILD.gn** file that functions as the entry for building must be added to the board directory. The following is an example of the **device/realtek/rtl8720/BUILD.gn** file for the RTL8720 development board:
```
group("rtl8720") {
...
}
```
3. Build and debug the development board.
1. Run the **hb set** command in any directory to set the source code path and the product to build.
2. Run the **hb build** command in the development board directory to start the build.
4. Build and debug the product.
Write the development board and module information to the product configuration file. Fields in the configuration file are as follows:
-**product_name**: product name, which can be customized. It is recommended that the value be the same as the level-3 directory name under the **vendor** directory.
-**ohos_version**: OpenHarmony version number, which must be the same as the actual version number.
-**device_company**: name of the chip solution vendor. It is recommended that the value be the same as the level-2 directory name under the **device** directory.
-**board**: name of the development board. It is recommended that the value be the same as the level-3 directory name under the **device** directory.
-**kernel_type**: kernel type, which must match the kernel type supported by the development board.
-**kernel_version**: kernel version, which must match the kernel version supported by the development board.
-**subsystem**: subsystem selected for the product. For details about the supported subsystem, see the descriptions of the subsystems in the **build/lite/components** directory.
-**components**: subsystem-specific modules selected for the product. For details about the modules supported by the selected subsystem, see the **build/lite/components/*Specific subsystem*.json** file.
-**features**: module-specific features configured for the product. For details about the features supported by the selected module, see the **features** field of the module in **build/lite/components/*Specific subsystem*.json** file.
The following is an example of the **vendor/my_company/wifiiot/config.json** file for the Wi-Fi IoT module on the RTL8720 development board:
```
{
"product_name": "wifiiot", # Product name
"ohos_version": "OpenHarmony 1.0", # OS version
"device_company": "realtek", # Name of the chipset solution vendor
"board": "rtl8720", # Name of the development board
"kernel_type": "liteos_m", # Kernel type
"kernel_version": "3.0.0", # Kernel version
"subsystems": [
{
"subsystem": "kernel", # Subsystem
"components": [
{ "component": "liteos_m", "features":[] } # Module and its features
Chip architecture porting is the basis of kernel porting. It is required when the target chip architecture is not yet supported in OpenHarmony. You can check the supported architectures in the **liteos_m/arch** directory, as shown in Table 1.
**Table 1** Architectures supported by OpenHarmony
If the target chip architecture is not yet supported in OpenHarmony, it must be adapted by the chip vendor. The **arch/include** directory contains the functions that need to be implemented for common chip architecture adaptation. Some chip architecture code is implemented by assembly, and assembly code varies with compilers. Therefore, a specific chip architecture also includes architecture code compiled by using different compilers (such as IAR, Keil, and GCC).
```
kernel/liteos_m/arch # The path varies according to the version.
├── arm # Arm series
│ ├── arm9
│ ├── cortex-m3
│ ├── cortex-m33
│ │ ├── gcc # Architecture code compiled by the GCC compiler
│ │ └── iar # Architecture code compiled by the IAR compiler
│ ├── cortex-m4
│ ├── cortex-m7
├── csky # C-SKY series
├── include # Functions to be implemented for common chip architecture adaptation.
│ ├── los_arch.h # Definition of functions required for initializing the chip architecture.
│ ├── los_atomic.h # Definition of the atomic operation functions to be implemented by the chip architecture.
│ ├── los_context.h # Definition of the context-related functions to be implemented by the chip architecture.
│ ├── los_interrupt.h # Definition of the interrupt- and exception-related functions to be implemented by the chip architecture.
│ └── los_timer.h # Definition of the system clock–related functions to be implemented by the chip architecture.
├── risc-v # RISC-V series
│ ├── nuclei
│ └── riscv32
└── xtensa # Xtensa series
└── lx6
```
## Porting the Chip SDK
Add the chip SDK to the OpenHarmony compilation framework you have set up, so as to build the file with the SDK (which does not contain the system information), which can then be burnt so that interfaces in the SDK can be called in OpenHarmony. To add the chip SDK to the OpenHarmony compilation framework, perform the following steps:
1. Place the chip SDK in a proper position in the **device** directory, and integrate the SDK build script and image packaging script into the compilation framework.
Create the kernel configuration file **target_config.h** in a proper location in **device/MyDeviceCompany/MyBoard** and modify the parameter settings based on the hardware resources of the chip. For details about the parameters, see Table 2.
> 1. If the existing configuration items do not meet the requirements, modify the **kernel/liteos_m/kernel/include/los_config.h** file as needed, which contains the full configuration of the LiteOS_M kernel.
>
> 2. Configuration items in the **target_config.h** file will overwrite those in the **los_config.h** file.
**Table 2** Main configuration items in the target_config.h file
> The interrupt vector table **g_hwiForm** after redirection needs to be byte-aligned according to the requirements in the Arch manual. Generally, the interrupt vector table is 0x200 byte-aligned.
## Adding the Kernel Subsystem
After adding the kernel subsystem, you can compile a project with the system. To add a kernel subsystem, perform the following steps:
1. Add the kernel subsystem to the **vendor/MyVendorCompany/MyProduct/config.json** file.
The sample code is as follows:
```
{
"subsystem": "kernel", # Kernel subsystem to add
"components": [
{
"component": "liteos_m", "features":[""]
}
]
},
```
2. Enable or disable kernel features.
The mini-system kernel provides the following features. This step describes how to view, enable, and disable these features.
Features: switches for the file system, backtrace, and more
if (enable_ohos_kernel_liteos_m_cppsupport == true) {
deps += [ "components/cppsupport:cppsupport" ] # If a kernel feature is set to true, the code corresponding to this feature is included in the build process.
This document provides chip/module vendors with a complete walkthrough of OpenHarmony-based chip adaptation from an end-to-end perspective. It applies to typical chip architectures, such as the chip architectures in the Cortex-M and RISC-V series.
## Constraints
This document applies to the adaptation of the mini system in OpenHarmony LTS 3.0.1 and earlier versions.
> This document describes only the files and configuration items that you need to pay attention to during OpenHarmony porting and adaptation. Other files and configuration items are skipped.
## Adaptation Process
The adaptation process is divided into four steps: porting preparation, kernel porting, subsystem porting, and porting verification. For details, see Table 1.
**Table 1** Chip adaptation steps
| Step| Description|
| -------- | -------- |
| Porting preparation| Download code from the OpenHarmony community on Gitee and set up the build environment. You can familiarize yourself with the OpenHarmony compilation and building framework along the way.|
| Kernel porting| Port the chip SDK to the OpenHarmony platform and determine whether adaptation is required based on the chip architecture support.|
| Subsystem porting| Port the startup, file, security, communication, and driver subsystems.|
| Porting verification| After the adaptation is complete, conduct the compatibility test provided by OpenHarmony and the chip SDK function test of your own.|
| Subsystem| A subsystem, as a logical concept, consists of one or more components. OpenHarmony is designed with a layered architecture, which consists of the kernel layer, system service layer, framework layer, and application layer from the bottom up. System functions are built from components, subsystems, and then to the system. In a multi-device deployment, you can customize subsystems and components as required.|
| Component| A component is a reusable, configurable, and tailorable function unit. Each component has an independent directory, and can be built and tested independently and developed concurrently. |
| hb | hb is an OpenHarmony command line tool used to execute build commands.|
| HOBT | HOBT is short for HiLink SDK OHOS Basic Test. It is used to test the basic functions of the interfaces on which the HiLink SDK depends.|
| Kit Framework | Kit Framework is the basic framework of Kit. It contains the security components of OpenHarmony and cannot be tailored.|
| KV | A key-value pair (KV) is a format of data storage.|
The 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.
## Setting Up the Build Environment
Before porting, set up the build environment as instructed in [Setting Up the Windows Environment](../quick-start/quickstart-ide-env--win.md).
## Obtaining Source Code
### Procedure
Download 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).
> 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.
### Directory Structure
Table 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).
**Table 1** Main directories of OpenHarmony source code
| Directory| Description|
| -------- | -------- |
| build | Directory where the compilation framework is located.|
| kernel/liteos_m | Directory where the kernel is located. The **arch** directory describes the supported kernel architecture.|
| 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.|
| vendor | Directory for adaptation by the device module vendor, where the **config.json** file describes the list of OpenHarmony subsystems to be integrated.|
| utils | Adaptation related to files and KVs.|
## Setting Up the Compilation Framework
During 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:
1. Add the chip vendor.
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.
Directory format: device/{*Chip vendor*}/{*Chip development board*}
Example: **device/MyDeviceCompany/MyBoard**
```
device
├── hisilicon # HiSilicon chip-related directory, which can be used as a reference during directory creation.
Build script: Add the files in **device/MyDeviceCompany/MyBoard** to the OpenHarmony compilation framework.
Path: **device/MyDeviceCompany/MyBoard/BUILD.gn**
```
group("MyBoard") { # Add the BUILD.gn file for parsing.
print("MyDeviceCompany MyBoard is under developing.")
}
```
Compilation configuration of the development board: This includes the kernel type, toolchain type, and compilation parameters. For details, see Table 2.
# Kernel type, e.g. "linux", "liteos_a", "liteos_m".
kernel_type = "liteos_m"
# Kernel version.
kernel_version = ""
# Board CPU type, e.g. "cortex-a7", "riscv32".
board_cpu = "cortex-m4"
# Board arch, e.g. "armv7-a", "rv32imac".
board_arch = ""
# Toolchain name used for system compiling.
# E.g. gcc-arm-none-eabi, arm-linux-harmonyeabi-gcc, ohos-clang, riscv32-unknown-elf.
# Note: The default toolchain is "ohos-clang". It's not mandatory if you use the default toochain.
board_toolchain = "arm-none-eabi-gcc"
# The toolchain path instatlled, it's not mandatory if you have added toolchian path to your ~/.bashrc.
board_toolchain_path = ""
# Compiler prefix.
board_toolchain_prefix = "arm-none-eabi-"
# Compiler type, "gcc" or "clang".
board_toolchain_type = "gcc"
# Board related common compile flags.
board_cflags = []
board_cxx_flags = board_cflags
board_ld_flags = []
# Board related headfiles search path.
board_include_dirs = []
# Board adapter dir for OHOS components.
board_adapter_dir =""
```
**Table 2** Main configuration items in config.gni
| Configuration Item| Description|
| -------- | -------- |
| kernel_type | Kernel type of the development board, for example, **"liteos_a"**, **"liteos_m"**, or **"linux"**.|
| kernel_version | Kernel version of the development board.|
| board_cpu | CPU type of the development board, for example, **"cortex-m4"**, **"cortex-a7"**, or **"riscv32"**.|
| board_arch | Architecture instruction set of the development board, for example, **"armv7-a"**.|
| 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.|
| board_toolchain_path | Path of the compiler toolchain. If this parameter is left empty, the toolchain in the environment variable is used.|
| board_toolchain_prefix | Prefix of the compiler toolchain, for example, **"arm-none-eabi-"**.|
| board_toolchain_type | Type of the compiler toolchain, which can be **gcc** or **clang**.|
| board_cflags | Build options of the .c file configured for the development board.|
| board_cxx_flags | Build options of the .cpp file configured for the development board.|
| board_ld_flags | Linking options configured for the development board.|
| board_include_dirs | List of system header files configured on the development board.|
| board_adapter_dir | Adaptation files of the development board.|
2. Add the device module vendor.
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.
**Table 3** Configuration items in the config.json file
| Configuration Item| Description|
| -------- | -------- |
| product_name | Product name, which is displayed during **hb set**.|
| ohos_version | OpenHarmony version number, which must be the same as the actual version number.|
| device_company | Chip vendor name, which is the same as the level-2 directory name under **device**.|
| board | Name of the development board, which is the same as the level-3 directory name under **device**.|
| kernel_type | Kernel type, which must match the kernel type of the OpenHarmony system ported to the development board.|
| kernel_version | Kernel version number, which matches the value of **kernel_version** in **config.gni**.|
| 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**.|
| components | Components of the subsystem. For details about the components supported by a specific subsystem, see the **build/lite/components/{*Subsystem*}.json** file.|
| features | Features of the component configured for the product. For details, see the **BUILD.gn** file corresponding to the subsystem source code directory.|
| 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).|
| 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**.|
| 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).|
As shown above, the .c file of the vendor adaptation interfaces is stored in the **$ohos_board_adapter_dir/hals/communication/wifi_lite/wifiservice** directory, where the target in the **BUILD.gn** file is **wifiservice**. Table 1, Table 2, and Table 3 list the Wi-Fi interfaces that need to be adapted by vendors. Table 4 and Table 5 list the Bluetooth interfaces.
**Table 1** wifi_device.h
| API| Description|
| -------- | -------- |
| EnableWifi | Enables the Wi-Fi STA mode.|
| DisableWifi | Disables the Wi-Fi STA mode.|
| IsWifiActive | Check whether the Wi-Fi STA mode is enabled.|
| Scan | Scans for hotspots.|
| GetScanInfoList | Obtains the list of all found hotspots.|
| AddDeviceConfig | Adds the information about the hotspot to be connected.|
| GetDeviceConfigs | Obtains the information about the connected hotspot.|
| RemoveDevice | Deletes the information about a specified hotspot.|
The driver subsystem provides OpenHarmony-dedicated APIs for peripheral device operations, including FLASH, GPIO, I2C, PWM, UART, and WATCHDOG APIs.
OpenHarmony provides two driver adaptation modes: using the driver subsystem and using the HDF driver framework. Because the resources of the mini system are limited, the IoT subsystem mode is recommended.
## Procedure
Vendors need to implement their functions based on the interface definitions provided by OpenHarmony. The header files defined by the interfaces of the IoT subsystem are as follows:
```
base/iot_hardware/peripheral/
├── BUILD.gn
└── interfaces
└── kits
├── iot_errno.h
├── iot_flash.h
├── iot_gpio.h
├── iot_i2c.h
├── iot_pwm.h
├── iot_uart.h
├── iot_watchdog.h
├── lowpower.h
└── reset.h
```
The content of the **base/iot_hardware/peripheral/BUILD.gn** file is as follows:
As shown above, the directory for storing vendor adaptation interfaces is **$ohos_vendor_adapter_dir/hals/iot_hardware/wifiiot_lite**, where the target in the **BUILD.gn file** is **hal_iothardware**.
## Example
1. Add the iot_hardware subsystem to the **config.json** file.
The utils component can be used by service subsystems and upper-layer applications and depends on the chip file system. The chip platform needs to provide functions such as opening, closing, reading, writing, and obtaining the file size.
## Procedure
The OpenHarmony file system needs to adapt to the following HAL APIs:
**Table 1** Opening or closing a file
| API| Description|
| -------- | -------- |
| HalFileOpen | Opens or creates a file.|
| HalFileClose | Closes a file:|
**Table 2** File operations
| API| Description|
| -------- | -------- |
| HalFileRead | Reads a file.|
| HalFileWrite | Writes data to a file.|
| HalFileDelete | Deletes a file.|
| HalFileStat | Obtains file attributes.|
| HalFileSeek | Searches for files.|
For details about the implementation of vendor adaptation interfaces, see the definitions of the file interface and HAL adaptation interface in OpenHarmony.
As shown in the preceding example, the directory for storing vendor adaptation interfaces is **$ohos_vendor_adapter_dir/hals/utils/file**, where the target in the **BUILD.gn** file is **hal_file_static**.
Generally, vendors can use the following methods to adapt to HAL APIs:
1. Directly read and write the flash memory to simulate file operations.
2. Use the LittleFS or FatFs file system for adaptation. For the FatFs file system, you can refer to the **//thirdparty** directory of OpenHarmony.
3. Use the existing file system of the vendor for adaptation.
In addition to the preceding subsystems, there are some subsystems that are necessary but do not need to be ported, such as the distributed scheduler and DFX subsystems.
To add these subsystems, perform the following operations in the **vendor/MyVendorCompany/MyProduct/config.json** file:
```
{
"subsystem": "distributed_schedule",
"components": [
{ "component": "system_ability_manager", "features":[] } # The component name varies according to the version.
System functions are developed by levels, from system to subsystem and then to component. Customize subsystems and components as required. This topic uses certain subsystems and components as examples. To use the capabilities of the OpenHarmony system, the corresponding subsystems need to be adapted.
Table 1 lists the common subsystems involved in OpenHarmony chip adaptation. Add or delete subsystems based on the specific chip you use.
**Table 1** OpenHarmony subsystems
| Subsystem| Description|
| -------- | -------- |
| applications | Application demo. You can store the source code related to the application in this directory.|
| kernel | Kernel subsystem, which is responsible for common kernel functions such as task scheduling and memory management.|
| hiviewdfx | DFX subsystem, which provides log-related functions.|
| communication | Communication subsystem, which provides Wi-Fi and Bluetooth functions.|
| iothardware | IoT peripheral subsystem, which provides common peripheral interfaces, such as GPIO, I2C, and SPI.|
| startup | Startup subsystem, which is the first subsystem that runs after the kernel is started. It is responsible for the startup of key system processes and services after the kernel is started and before the application is started.|
| update | Update subsystem, which provides OTA update support for OpenHarmony devices.|
| utils | Utils subsystem, which provides some common enhanced APIs for development using C and C++.|
| distributed_schedule | Distributed scheduler subsystem, which manages cross-device components, provides the capabilities of accessing and controlling remote components, and supports application collaboration in distributed scenarios.|
| security | Security subsystem, which provides system, data, and application security capabilities to protect system and user data of OpenHarmony. It implements application integrity verification, application permission management, device authentication, OpenHarmony Universal KeyStore (HUKS) key management, and data transfer management.|
| test | Test subsystem. OpenHarmony provides a comprehensive auto-test framework for designing test cases. Detecting defects in the development process can improve code quality.|
The security subsystem provides functions such as network device connection, authentication, and authorization. It depends on mbedtls to implement hardware random numbers and network connection functions.
Because the chip hardware and the implementation for the hardware-based random number varies by vendor, the hardware-based random number interface needs to be adapted.
## Procedure
OpenHarmony provides an open-source library of Mbed TLS, which is stored in **//third_party/mbedtls**. This library provides several random number generation modes, such as **mbedtls_platform_entropy_poll**, **mbedtls_hardclock_poll**, **mbedtls_havege_poll**, and **mbedtls_hardware_poll**. For the hardware-based random number, adapt **mbedtls_hardware_poll** based on your chip.
**Table 1** Configuration items of the security subsystem
| Configuration Item| Description|
| -------- | -------- |
| disable_huks_binary | Whether to compile the HUKS source code.<br>(1) **false** (default): The HUKS source code is not compiled.<br>(2) **true**: The HUKS source code is not compiled.|
| disable_authenticate | Whether tailoring is required for the HiChain authentication function.<br>(1) **true** (default): Tailoring is not required.<br>(2) **false**: Tailoring is required.|
| huks_use_lite_storage | Whether the lightweight storage solution is used. The lightweight storage solution can be used for devices that come with flash storage and do not have file systems.<br>(1) **true** (default): The lightweight storage solution is used.<br>(2) **false**: The lightweight storage solution is not used.|
| huks_use_hardware_root_key | Whether the hardware root key is used. If a device has the hardware root key capability, the hardware root key solution needs to be adapted based on the device capability. The RKC solution provided by HUKS is only for simulation implementation.<br>(1) **false** (default): The hardware root key is not used.<br>(2) **true**: The hardware root key is used. This requires adaptation.|
| huks_config_file | Whether to use the default HUKS configuration file **hks_config.h**.<br>(1) **""**(default): The default HUKS configuration file is used.<br>(2) Other files: You can select the features to be supported from the HUKS support capability set.|
The startup subsystem is responsible for starting key system processes and services after the kernel is started and before applications are started.
## Procedure
For the mini system, the startup entry identifiers of services and functions are provided. When SAMGR is started, the entry function identified by bootstrap is called and system services are started.
After the adaptation is complete, call the **OHOS_SystemInit()** API to start the system.
Some components (such as syspara_lite) in the startup subsystem depend on the modules in **$ohos_product_adapter_dir/utils**. In the preceding information, **ohos_product_adapter_dir** is the value of **product_adapter_dir** configured in the **config.json** file. Generally, **ohos_product_adapter_dir** is set to **vendor/MyVendorCompany/MyProduct/hals**.
1. Add the **zinitcall** and **run** definitions.
Add the following code to the **.text** section in the vendor **.ld** linking script:
```
__zinitcall_bsp_start = .;
KEEP (*(.zinitcall.bsp0.init))
KEEP (*(.zinitcall.bsp1.init))
KEEP (*(.zinitcall.bsp2.init))
KEEP (*(.zinitcall.bsp3.init))
KEEP (*(.zinitcall.bsp4.init))
__zinitcall_bsp_end = .;
__zinitcall_device_start = .;
KEEP (*(.zinitcall.device0.init))
KEEP (*(.zinitcall.device1.init))
KEEP (*(.zinitcall.device2.init))
KEEP (*(.zinitcall.device3.init))
KEEP (*(.zinitcall.device4.init))
__zinitcall_device_end = .;
__zinitcall_core_start = .;
KEEP (*(.zinitcall.core0.init))
KEEP (*(.zinitcall.core1.init))
KEEP (*(.zinitcall.core2.init))
KEEP (*(.zinitcall.core3.init))
KEEP (*(.zinitcall.core4.init))
__zinitcall_core_end = .;
__zinitcall_sys_service_start = .;
KEEP (*(.zinitcall.sys.service0.init))
KEEP (*(.zinitcall.sys.service1.init))
KEEP (*(.zinitcall.sys.service2.init))
KEEP (*(.zinitcall.sys.service3.init))
KEEP (*(.zinitcall.sys.service4.init))
__zinitcall_sys_service_end = .;
__zinitcall_sys_feature_start = .;
KEEP (*(.zinitcall.sys.feature0.init))
KEEP (*(.zinitcall.sys.feature1.init))
KEEP (*(.zinitcall.sys.feature2.init))
KEEP (*(.zinitcall.sys.feature3.init))
KEEP (*(.zinitcall.sys.feature4.init))
__zinitcall_sys_feature_end = .;
__zinitcall_run_start = .;
KEEP (*(.zinitcall.run0.init))
KEEP (*(.zinitcall.run1.init))
KEEP (*(.zinitcall.run2.init))
KEEP (*(.zinitcall.run3.init))
KEEP (*(.zinitcall.run4.init))
__zinitcall_run_end = .;
__zinitcall_app_service_start = .; // SAMGR executes the function in the .zinitcall.app.featureX.init section.
KEEP (*(.zinitcall.app.service0.init))
KEEP (*(.zinitcall.app.service1.init))
KEEP (*(.zinitcall.app.service2.init))
KEEP (*(.zinitcall.app.service3.init))
KEEP (*(.zinitcall.app.service4.init))
__zinitcall_app_service_end = .;
__zinitcall_app_feature_start = .; // SAMGR executes the function in the .zinitcall.app.featureX.init section.
KEEP (*(.zinitcall.app.feature0.init))
KEEP (*(.zinitcall.app.feature1.init))
KEEP (*(.zinitcall.app.feature2.init))
KEEP (*(.zinitcall.app.feature3.init))
KEEP (*(.zinitcall.app.feature4.init))
__zinitcall_app_feature_end = .;
__zinitcall_test_start = .;
KEEP (*(.zinitcall.test0.init))
KEEP (*(.zinitcall.test1.init))
KEEP (*(.zinitcall.test2.init))
KEEP (*(.zinitcall.test3.init))
KEEP (*(.zinitcall.test4.init))
__zinitcall_test_end = .;
__zinitcall_exit_start = .;
KEEP (*(.zinitcall.exit0.init))
KEEP (*(.zinitcall.exit1.init))
KEEP (*(.zinitcall.exit2.init))
KEEP (*(.zinitcall.exit3.init))
KEEP (*(.zinitcall.exit4.init))
__zinitcall_exit_end = .;
```
1. The chip SDK creates a task.
Set task parameters. After the system is started, start the task. The following is an example:
```
void mainTask(void) {
// Vendor-defined function
OHOS_SystemInit(); // Initialize the startup subsystem.
printf("MainTask running...\n");
}
void main(VOID) {
// Initialize the hardware and redirect the printf output to the debug serial port.
if (LOS_KernelInit() == 0) { // Initialize the kernel.
After the OpenHarmony chip is ported, conduct the OpenHarmony compatibility test and chip SDK function test to obtain certification. Detecting defects in the development process can improve code quality.
## Conducting the OpenHarmony Compatibility Test
The OpenHarmony compatibility test is included in the X Test Suite (XTS), a set of OpenHarmony certification test suites. For details, see [DFX](https://gitee.com/openharmony/docs/blob/master/en/readme/dfx.md).
1. Add the test subsystem and the xts_acts component.
Add the following code to the **vendor/xxx/xxx/config.json** file:
```
{
"subsystem": "test",
"components": [
{ "component": "xts_acts", "features":[] },
{ "component": "xts_tools", "features":[] }
]
}
```
2. Link the .a library generated by the XTS.
In the linking options, link the **libmodule_ActsXxxTest.a** library in the **out/MyBoard/MyProduct/libs** directory in the mode of **-lmodule_ActsXxxTest**. The sample code is as follows:
```
"-Wl,--whole-archive",
......
"-lhctest",
"-lbootstrap",
"-lbroadcast",
"-lmodule_ActsBootstrapTest",
"-lmodule_ActsCMSISTest",
"-lmodule_ActsDfxFuncTest",
"-lmodule_ActsParameterTest",
"-lmodule_ActsSamgrTest",
"-lmodule_ActsSecurityDataTest",
......
"-Wl,--no-whole-archive",
```
3. Modify the code based on the test report.
Burn the files generated after compilation to the development board and use the serial port tool to view the XTS test report. If any test item fails, modify the code as needed.
During fault locating, you can comment out unnecessary test items in the **test/xts/acts/build_lite/BUILD.gn** file.
@@ -56,7 +56,7 @@ You can use the Bootloader provided by the chipset vendor or open-source U-Boot
## Verification
Debug the **init** process, start shell, and run a simple program in the user space to check whether the kernel porting is successful. Below is the OS image structure of the OpenHarmony [small system](../quick-start/quickstart-lite-overview.md) and the Linux user-space program startup process.
Debug the **init** process, start shell, and run a simple program in the user space to check whether the kernel porting is successful. Below is the OS image structure of the OpenHarmony small system and the Linux user-space program startup process.
**Figure 1** OS image structure and user-space program startup process based on the Linux kernel
Set up the basic environment by following instructions in [Setting Up the Hi3861 Development Board Environment](../quick-start/quickstart-lite-steps-hi3861-setting.md). Both the user space and LiteOS Cortex-A kernel space are compiled using the LLVM compiler. If you choose to port the Linux kernel, run the following command to install the gcc-arm-linux-gnueabi cross compiler for compiling the Linux kernel-space image:
Set up the basic environment by following instructions in [Quick Start Overview](../quick-start/quickstart-overview.md). Both the user space and LiteOS Cortex-A kernel space are compiled using the LLVM compiler. If you choose to port the Linux kernel, run the following command to install the gcc-arm-linux-gnueabi cross compiler for compiling the Linux kernel-space image:
# Before You Start<a name="EN-US_TOPIC_0000001154212510"></a>
This document provides guidance on how to port the Linux and LiteOS Cortex-A kernels on the OpenHarmony [small system](../quick-start/quickstart-lite-overview.md) to a development board. It is intended for developers with experience in developing embedded systems. Before following instructions in this document, it is recommended that you familiarize yourself with [OpenHarmony](../../OpenHarmony-Overview.md), including its technical architecture, directory structure, kernel subsystem, and driver subsystem. The following table lists the development boards that have been adapted to the small system.
This document provides guidance on how to port the Linux and LiteOS Cortex-A kernels on the OpenHarmony small system to a development board. It is intended for developers with experience in developing embedded systems. Before following instructions in this document, it is recommended that you familiarize yourself with [OpenHarmony](../../OpenHarmony-Overview.md), including its technical architecture, directory structure, kernel subsystem, and driver subsystem. The following table lists the development boards that have been adapted to the small system.
**Table 1** Development boards compatible with the OpenHarmony small system
@@ -5,7 +5,7 @@ The following shows how to port the double-conversion library.
## Source Code Acquisition
Acquire the source code of double-conversion from [https://github.com/google/double-conversion](https://github.com/google/double-conversion). The following table lists the directory structure.
Acquire the source code of double-conversion from [double-conversion](https://github.com/google/double-conversion). The following table lists the directory structure.
**Table 1** Directory structure of the source code
...
...
@@ -106,7 +106,7 @@ The following steps show how to configure and modify the toolchains for cross-co
1. Set up the OpenHarmony environment.
Using Hi3516D V300 as an example, compile the OpenHarmony image and burn it to the development board. For details, see [Developing the First Example Program Running on Hi3518](../quick-start/quickstart-lite-steps-hi3516-running.md).
Using Hi3516D V300 as an example, compile the OpenHarmony image and burn it to the development board. For details, see the content related to the small system in [Quick Start Overview](../quick-start/quickstart-overview.md).
The following screen is displayed after a successful login to the OS.
@@ -7,7 +7,7 @@ Burning is the process of downloading compiled program files to a development bo
The images of Hi3516DV300 are burnt in the Windows environment. After burning is initiated, DevEco Device Tool copies the target program files generated in the Ubuntu environment to the specified Windows directory in remote mode, and then burns the program files to Hi3516DV300 using the Windows burning tool.
Hi3516D V300 supports burning for the small system through the USB port, network port, and serial port. This document describes how to burn source code through the USB port.
Hi3516DV300 supports burning for the small system through the USB port, network port, and serial port. This topic describes how to burn source code through the USB port.
## Prerequisites
...
...
@@ -40,15 +40,16 @@ Hi3516D V300 supports burning for the small system through the USB port, network
5. On the **hi3516dv300** tab page, set the burning options. The settings are automatically saved.
-**upload_partitions**: Select the file to be burnt. By default, the **fastboot**, **kernel**, **rootfs**, and **userfs** files are burnt at the same time. Check the preset information of the files to be burnt and modify them when necessary. To modify the burning settings for a specific file, click  next to the file.
> Set the start address and length of the partition based on the size of the files to be burnt. Make sure the size of the partition is greater than that of the files to be burnt and the partition addresses of the files to be burnt do not overlap.
> The preceding command is applicable to Ubuntu 18.04. For other Ubuntu versions, modify the preceding installation command based on the installation package name. The details are as follows:
>
> - Python 3.8 or a later version is required. This section uses Python 3.8 as an example.
> - Java 8 or later is required. This section uses Java 8 as an example.
>
> - Java 8 or later is required. This section uses Java 8 as an example.
@@ -30,7 +30,7 @@ Kconfig visual configuration has the following advantages:
2. Set up the environment.
The Kconfiglib required for environment configuration has been embedded in the OpenHarmony hb tool. For details about how to install the hb tool, see "Installing hb" in [Setting Up Environments for the Mini and Small Systems](../quick-start/quickstart-lite-env-setup.md).
The Kconfiglib required for environment configuration has been embedded in the OpenHarmony hb tool. For details about how to install the hb tool, see [hb Installation](../quick-start/quickstart-pkg-install_tool.md#hb-installation).
