@@ -25,11 +25,12 @@ In the figure, the registers in different colors indicate different functions. T
The following table describes APIs available for the OpenHarmony LiteOS-M stack trace module. For more details about the APIs, see the API reference.
**Table 1** APIs of the stack trace module
**Table 1** APIs of the stack trace module
| Category| API|
| API| Description|
| -------- | -------- |
| Stack tracing| **LOS_BackTrace**: prints the call stack relationship at the calling point.<br>**LOS_RecordLR**: obtains the call stack relationship at the calling point when print is unavailable.|
| LOS_BackTrace | Prints the call stack relationship at the calling point.|
| LOS_RecordLR | Obtains the call stack relationship at the calling point when print is unavailable.|
## Development Guidelines
...
...
@@ -39,17 +40,18 @@ The following table describes APIs available for the OpenHarmony LiteOS-M stack
The typical process for enabling exception debugging is as follows:
1. Configure the macros related to exception handling
in the **target_config.h** file.
| Configuration Item| Description| Value|
1. Configure the macros related to exception handling in the **target_config.h** file.
| Configuration Item| Description| Value|
| -------- | -------- | -------- |
| LOSCFG_BACKTRACE_DEPTH | Depth of the function call stack. The default value is **15**.| 15 |
| LOSCFG_BACKTRACE_TYPE | Type of the stack tracing.<br>**0**: The stack tracing is disabled.<br>**1**: supports call stack analysis of the Cortex-M series hardware.<br>**2**: supports call stack analysis of the RISC-V series hardware.| Set this parameter to **1** or **2** based on the toolchain type.|
1. Use the error code in the example to build and run a project, and check the error information displayed on the serial port terminal. The sample code simulates error code. During actual product development, use the exception debugging mechanism to locate exceptions.
The following example demonstrates the exception output through a task. The task entry function simulates calling of multiple functions and finally calls a function that simulates an exception. The sample code is as follows:
The sample code can be compiled and verified in **./kernel/liteos_m/testsuites/src/osTest.c**. The **ExampleExcEntry** function is called in **TestTaskEntry**.
2. Use the error code in the example to build and run a project, and check the error information displayed on the serial port terminal. The sample code simulates error code. During actual product development, use the exception debugging mechanism to locate exceptions.
The following example demonstrates the exception output through a task. The task entry function simulates calling of multiple functions and finally calls a function that simulates an exception. The sample code is as follows:
The sample code is built and verified in **./kernel/liteos_m/testsuites/src/osTest.c**. Call **ExampleExcEntry** in **TestTaskEntry**.
```
#include <stdio.h>
...
...
@@ -210,10 +212,10 @@ The typical process for enabling exception debugging is as follows:
The procedure for locating the exception is as follows:
1.Ensure that the compiler optimization is disabled. Otherwise, the following problems may be optimized during the compilation process.
1.Check that the compiler optimization is disabled. Otherwise, the following problems may be optimized during the compilation process.
2. Open the image disassembly file (.asm) generated. If the file is not generated, use the objdump tool to generate it. The command is as follows:
```
arm-none-eabi-objdump -S -l XXX.elf
```
...
...
@@ -221,7 +223,7 @@ The procedure for locating the exception is as follows:
3. Search for the PC (pointing to the instruction being executed) in the .asm file to locate the abnormal function.
The PC address directs to the instruction being executed when the exception occurs. In the .asm file corresponding to the currently executed binary file, search for the PC value **0x2101c61a** and locate the instruction being executed by the CPU. Disassemble the code as follows:
```
2101c60c <GetResultException0>:
2101c60c: b580 push {r7, lr}
...
...
@@ -242,13 +244,13 @@ The procedure for locating the exception is as follows:
2101c62e: bd80 pop {r7, pc}
2101c630: 21025f90 .word 0x21025f90
```
As indicated by the information displayed:
- The CPU is executing **ldr r3, [r3, #0]** when an exception occurs. The value of **r3** is **0xffffffff**, which causes an invalid address.
- When the exception occurs, the CPU is executing the **ldr r3, [r3, #0]** instruction. The value of **r3** is **0xffffffff**, which causes an invalid address.
- The exception occurs in the **GetResultException0** function.
4. Search for the parent function of the abnormal function based on the LR value.
5. Search for the parent function of the abnormal function based on the LR value.
The code disassembly of the LR value **0x2101c64d** is as follows:
```
...
...
@@ -271,7 +273,7 @@ The procedure for locating the exception is as follows:
2101c656: bf00 nop
2101c658: 21025fb0 .word 0x21025fb0
```
The previous line of LR **2101c648** is **bl2101c60c <GetResultException0>**, which calls the abnormal function. The parent function is **GetResultException1**.
5. Parse the LR value between **backtrace start** and **backtrace end** in the exception information to obtain the call stack relationship where the exception occurs and find the cause of the exception.
\ No newline at end of file
The previous line of LR **2101c648** is **bl 2101c60c \<GetResultException0\>**, which calls the abnormal function. The parent function is **GetResultException1**.
7. Repeat step 3 to parse the LR value between **backtrace start** and **backtrace end** in the exception information to obtain the call stack relationship where the exception occurs and find the cause of the exception.
@@ -10,9 +10,9 @@ The interface through which you interact with an operating system (OS) is the ou
An OS is a system software located between applications and hardware. It provides program interfaces and running environments for upper-layer applications and manages underlying hardware resources. Located at a lower layer of the OS, the kernel provides concurrent management of hardware resources for the upper-layer program framework.
**Figure 1** OS architecture
**Figure 1** OS architecture
### Multi-Kernel Architecture
...
...
@@ -31,10 +31,10 @@ OpenHarmony supports Linux and LiteOS. You can select OpenHarmony based on produ
The kernel subsystem is located at the lower layer of OpenHarmony. Since OpenHarmony is oriented to devices with different CPUs and storage space, the kernel subsystem supports use of the optimal OS kernel for devices of different resource levels. The KAL shields differences between kernels and provides basic kernel capabilities for the upper layer.
**Figure 2** OpenHarmony architecture
**Figure 2** OpenHarmony architecture
### OpenHarmony Types
...
...
@@ -43,19 +43,17 @@ OpenHarmony can be classified into the following types based on the supported de
- Mini system
The mini system fits into the devices that come with MCU processors, such as Arm Cortex-M and 32-bit RISC-V, and memory greater than or equal to 128 KiB. This system provides a variety of lightweight network protocols, a lightweight graphics framework, and a wide range of read/write components with the Internet of Things (IoT) bus. The mini system applies to smart home products such as LinkIoT module devices and sensors.
The mini system fits into the devices that come with MCU processors, such as Arm Cortex-M and 32-bit RISC-V, and memory greater than or equal to 128 KiB. This system provides a variety of lightweight network protocols, a lightweight graphics framework, and a wide range of read/write components with the Internet of Things (IoT) bus. The mini system applies to smart home products such as LinkIoT module devices and sensors.
- Small system
The small system fits into the devices that come with application processors, such as Arm Cortex-A, and memory greater than or equal to 1 MiB. This system provides higher security capabilities, a standard graphics framework, and video encoding and decoding capabilities. The small system applies to smart home products such as IP cameras, peephole cameras, and routers as well as smart travel products such as event data recorders (EDRs).
The small system fits into the devices that come with application processors, such as Arm Cortex-A, and memory greater than or equal to 1 MiB. This system provides higher security capabilities, a standard graphics framework, and video encoding and decoding capabilities. The small system applies to smart home products such as IP cameras, peephole cameras, and routers as well as smart travel products such as event data recorders (EDRs).
- Standard system
The standard system fits into the devices that come with application processors, such as Arm Cortex-A, and memory greater than or equal to 128 MiB. This system provides a complete application framework supporting enhanced interaction, 3D GPU, hardware composer, diverse components, and rich animations. The standard system applies to high-end refrigerator displays.
Different OpenHarmony systems use kernels of different forms. LiteOS applies to mini and small systems. Linux applies to small and standard systems. The table below lists the kernels and applicable systems.
**Table 1** Kernels and applicable systems
**Table 1** Kernels and applicable systems
| Level| Mini System| Small System| Standard System|
| -------- | -------- | -------- | -------- |
...
...
@@ -69,11 +67,13 @@ Different OpenHarmony systems use kernels of different forms. LiteOS applies to
### Kernel Architecture
OpenHarmony LiteOS-M is a lightweight OS kernel designed for the IoT field. It features small footprint, low power consumption, and high performance. It has a simple code structure, including the minimum kernel function set, kernel abstraction layer, optional components, and project directory. The LiteOS-M kernel is divided into the hardware layer and hardware-irrelevant layers. The hardware layer provides a unified HAL interface for easier hardware adaptation. A range of compilation toolchains can be used with different chip architectures to meet the expansion of diversified hardware and compilation toolchains in the Artificial Intelligence of Things (AIoT) field.
OpenHarmony LiteOS-M is a lightweight OS kernel designed for the IoT field. It features small footprint, low power consumption, and high performance. It has a simple code structure, including the minimum kernel function set, kernel abstraction layer, optional components, and project directory.
The LiteOS-M kernel is divided into the hardware layer and hardware-irrelevant layers. The hardware layer provides a unified HAL interface for easier hardware adaptation. A range of compilation toolchains can be used with different chip architectures to meet the expansion of diversified hardware and compilation toolchains in the Artificial Intelligence of Things (AIoT) field.
@@ -86,7 +86,7 @@ For details about how to use LiteOS-M, see "Usage" in LiteOS-M [Kernel Overview]
### Kernel Architecture
The LiteOS-A kernel mainly applies to small-sized systems. It is oriented to devices with M-level memory and supports memory management unit (MMU) isolation. Similar kernels in the industry include Zircon and Darwin.
The LiteOS-A kernel applies to the small system. It fits into devices with memory greater than or equal to 1 MiB and supporting memory management unit (MMU) isolation. Similar kernels in the industry include Zircon and Darwin.
To keep pace with the rapid development of the IoT industry, the OpenHarmony lightweight kernel is continuously optimized and expanded to provide application developers with friendly development experience and unified and open ecosystem capabilities. LiteOS-A has the following new features:
...
...
@@ -134,7 +134,7 @@ During the build process, you can merge the driver code based on the chip platfo
OpenHarmony provides the enhanced swap (ESwap), related thread group (RTG), and lightweight CPU isolation features for the Linux kernel.
ESwap
**ESwap**
Enhanced Swap (ESwap) allows a custom partition to serve as a swap partition and uses a resident process zswapd to encrypt and swap the anonymous pages compressed by [zram](https://gitee.com/link?target=https%3A%2F%2Fwww.kernel.org%2Fdoc%2Fhtml%2Flatest%2Fadmin-guide%2Fblockdev%2Fzram.html) to the ESwap partition. In this way, a block of memory can be completely released to ensure the available memory (Memavailable) waterline. In addition to this reclaiming mechanism, the entire memory framework is enhanced to improve the reclaiming efficiency of anonymous pages and file pages and streamline the reclaiming ratio of these two types of pages to prevent refaults caused by excessive reclamation.
...
...
@@ -150,16 +150,18 @@ Lightweight CPU isolation enables dynamic CPU isolation based on the system load
### How to Use
1. Apply HDF patches.
Apply the HDF kernel patches matching your kernel version. For details, see the method in **kernel.mk** in the **kernel/linux/build** repository.
Place the patches for the chip component in the corresponding path based on the path and naming rules for the patches of the chip component in **kernel.mk** in the **kernel/linux/build** repository.
Place the patches for the chip component in the corresponding directory based on the path and naming rules for the patches of the chip component in **kernel.mk** in the **kernel/linux/build** repository.
@@ -167,13 +169,16 @@ Lightweight CPU isolation enables dynamic CPU isolation based on the system load
```
3. Modify the **config** file to build.
Place the **config** file for the chip component in the corresponding path based on the path and naming rules of the chip component in **kernel.mk** in the **kernel/linux/build** repository.
Place the **config** file for the chip component in the corresponding directory based on the path and naming rules of the chip component in **kernel.mk** in the **kernel/linux/build** repository.
> In the OpenHarmony project build process, patches are installed after "kernel/linux/linux-\*.\*" is copied. Before using the version-level build command of OpenHarmony, ensure that the "kernel/linux/linux-\*.\*" source code is available.
>
> After the build is complete, the kernel is generated in the kernel directory in the **out** directory. Modify the **config** file based on the kernel generated, and copy the generated **.config** file to the corresponding path in the **config** repository. Then, the configuration takes effect.
@@ -17,7 +17,7 @@ The HAP provides HAP build functions and supports FA and stage models.
## How to Develop
### Templates
### OpenHarmony Templates
#### ohos_hap
This template declares a HAP target, which generates a HAP that will be packaged into the system image.
...
...
@@ -27,8 +27,8 @@ This template declares a HAP target, which generates a HAP that will be packaged
| hap_profile | Configuration file of the HAP. It is **config.json** for the FA model and **module.json** for the stage model.|
| raw_assets | Raw assets, which are directly copied to the **assets** directory of the HAP.|
| resources | Resource files, which are stored in the **assets/entry/resources** directory after build.|
| js_assets | JS resources, which are stored in the **assets/js/default** directory after built with Ace.|
| ets_assets | eTS resources, which are stored in the **assets/js/default** directory after built with Ace.|
| js_assets | JS resources, which are stored in the **assets/js/default** directory after built.|
| ets_assets | eTS resources, which are stored in the **assets/js/default** directory after built.|
| deps | Dependencies of the target.|
| shared_libraries | Native libraries on which the target depends.|
| hap_name | HAP name, which is optional. By default, it is the target name.|
...
...
@@ -55,7 +55,7 @@ Declares the AppScope module of the HAP. The **app_profile** and **sources** var
| sources | Resources in the AppScope module of the HAP. This variable is used only in the stage model.|
#### ohos_js_assets
Provides JS or eTS code, which is stored in the **assets/js/default** directory after built with Ace. In the stage model, this template is stored in the **assets/js** or **assets/ets** directory, depending on the programming language.
Provides JS or eTS code, which is stored in the **assets/js/default** directory after built. In the stage model, this template is stored in the **assets/js** or **assets/ets** directory, depending on the programming language.
| Variable| Description|
| --------- | ---- |
...
...
@@ -84,7 +84,7 @@ Resource files, which are stored in the **assets/entry/resources** directory for
1. Save the developed application example to the **applications/standard/** directory.
2. Configure the GN script **applications/standard/example/BUILD.gn**.<br>The following is an example of the FA model. For details about more **BUILD.gn** configurations, see [GN Script Configuration Example](#gn-script-configuration-example).
2. Configure the GN script **applications/standard/example/BUILD.gn**.<br>The following is an example of the FA model. For details about more **BUILD.gn** configurations, see [GN Script Configuration Example](#gn-script-configuration-example).
```
import("//build/ohos.gni") # Import ohos.gni.
...
...
@@ -103,7 +103,7 @@ Resource files, which are stored in the **assets/entry/resources** directory for
}
```
3. Modify the **applications/standard/hap/ohos.build** file.<br>The following is an example:
3. Modify the **applications/standard/hap/ohos.build** file.<br>The following is an example:
