One minute to take you through the Huawei LiteOS component development guide

Abstract: This article will be based on the Huawei LiteOS system, starting from the component definition and take you into the component development guide.

This article is shared from the Huawei Cloud Community " You to Know Huawei LiteOS Component Development Guide ", author: Lionlace.

In the development process, faced with the huge amount of code, are you worried about the situation that will affect your whole body and don't know where to start?

Today we bring you a tool for improving the efficiency of developers: components

This article will be based on the Huawei LiteOS system, starting with the component definition and take you into the component development guide.

Component definition

Components are part of the Huawei LiteOS system and belong to Huawei LiteOS applications. From a system perspective, except for the kernel, build scripts, auxiliary tools, and system function libraries, the other software packages that make up the functions of the Huawei LiteOS system can all be called components. This document will introduce the composition, specification and development process of components in detail to help component developers to develop components. The components of Huawei LiteOS are divided into online components and offline components. The component source code of the online component is not in the Huawei LiteOS code warehouse and needs to be downloaded from the Internet when used; while the source code of the offline component is stored in the Huawei LiteOS code warehouse. Offline components are generally basic components, such as networks, file systems, and so on.

Component composition

The following takes the online component curl as an example to describe the component composition and component management of Huawei LiteOS in detail.

Directory Structure

Adding a new component involves creating and modifying files/directories as shown below. Among them, curl under components, curl under demos and the files they contain are newly added directories and files, and the remaining files are common files of each component or demos, and generally need to be modified when adding new components.

Notice:

To add a new component or demo, you need to create its own Kconfig, Makefile, and .mk files. This document takes the new component as the theme. The method of adding a demo is similar to that of adding a new component. This document will not repeat it.

curl-7.54.1, curl-7.54.1.zip need to be deleted when submitting, no need to submit to LiteOS warehouse.

origin.patch, patch.sha256, src.sha256 are files generated during the development process and need to be submitted to the LiteOS_Components warehouse.

online_components

The source code of online components needs to be downloaded from the Internet, and the download information is recorded in the online_components file. The file has a specific format and saves the relevant information (or parameters) of each online component. As shown below, each component has four parameters, and each parameter is separated by &#&.

curl-7.54.1 &#& components/utility/curl &#& LOSCFG_COMPONENTS_CURL=y &#& https://github.com/curl/curl/archive/refs/tags/curl-7_54_1.zip

• Parameter 1: Component source code name (generally named: source code name-version number).

Note: This name is equivalent to renaming the source code, and may not be the same as the name obtained by clicking the download directly on the web page. For example, visit directly here https://github.com/curl/curl/archive/refs/tags/curl-7_54_1.zip, the downloaded file is named curl-curl-7_54_1.zip, and the file obtained by decompressing the file is curl-curl-7_54_1. However, when download.sh executes the download, the downloaded file will be named curl-7.54.1.zip according to parameter 1 and parameter 4 (naming method: parameter 1 + download type in parameter 4), and decompress The file obtained from this file is curl-7.54.1, which is parameter one. Therefore, in the development process, all operations performed by the developer on the source code must be based on the name written in the first parameter. If the downloaded source code name is inconsistent with the first written parameter, please follow the above instructions and rename it before proceeding. Development.

• Parameter 2: The path where the component is located (download the component source code to this directory).

• Parameter 3: The component enable flag (used to determine whether to download the component source code, this flag is the configuration item in the component Kconfig file).

• Parameter 4: The download address of the component source code or the command to obtain the component source code (because the source code verification is involved later, it is recommended to download the source code compression package first, which is more convenient and faster during verification).

Note: The online component currently supports the following download methods:

• Download compressed package: currently only supports .zip, .tar.gz type compressed packages, such as:

https://github.com/curl/curl/archive/refs/tags/curl-7_54_1.zip
https://github.com/curl/curl/archive/refs/tags/curl-7_54_1.tar.gz

• Use git clone, such as:

git clone -b curl-7.54.1 https://github.com/curl/curl.git

• If you cannot obtain the source code using the above method, you can write a shell script to complete the source download and return the download result (success/failure). Parameter four fills in the method of calling the script.

download.sh

Download the online component source code and patch file, perform sha256sum verification, and enter the patch file into the source code after the verification is successful.

components/utility/curl

The curl directory is the directory where the source code of the curl component and its related files are located. When adding a new component, please create a new component directory under the corresponding location of the components directory according to the function of the component (divided into language component language, media component media, tool component utility, security component security, etc.. Curl is a tool component, so it is Located in the utility directory).

Naming convention: generally the same name as the component source code (not abbreviated, such as libpng cannot be written as png) or refer to the industry's general naming.

curl/curl-7.54.1

Component source code, the directory name needs to be consistent with the parameters in the online_components file. The online components are downloaded from the Internet by download.sh. There is no need to upload the component source code to the Huawei LiteOS code warehouse. Only the source code of the offline component needs to be uploaded.

src.sha256

The content of the file is the sha256 check code of the component source code. In order to ensure the normal use of the component, it is necessary to ensure that the source code downloaded from the Internet is the same as the source code used when developing the component. LiteOS guarantees the same source code by performing sha256 verification on the downloaded source code. Therefore, when developing components, you need to calculate the sha256 checksum of the source file and copy it to the src.sha256 file. The content of the src.sha256 file of the curl component is as follows:

7eec2c7f863c17d8586e94255cd0c2934822f1ae3cb40283a892b46e44f93bdf curl-7.54.1.zip

For the method of generating sha256 checksum, please refer to the following command:

• If the downloaded source code package is a compressed package:

sha256sum 参数一.zip > src.sha256 # sha256sum curl-7.54.1.zip > src.sha256

• If the source code package is not a compressed package:

find 参数一 -type f -print0 | xargs -0 sha256sum > src.sha256 # find curl-7.54.1 -type f -print0 | xargs -0 sha256sum > src.sha256

Note: If you need to execute the above commands in Windows, you can install the Git tool and use the terminal that comes with Git to execute. Note that you need to set Git to prohibit newline conversion in advance, refer to the command git config --global core.autocrlf input.

Notice:

The checksum file is named src.sha256 uniformly, and the file name cannot be modified.

When developing components, please use the parameter four in the online_components file to download the source file.

src.sha256

The patch file of the source code. The file is named origin.patch uniformly and cannot be modified. When developing components on Huawei LiteOS, it is recommended to avoid direct modification of the open source source code. If it is unavoidable (for example: the source code cannot be compiled successfully without modifying the source code, or the source code cannot be directly run on Huawei LiteOS, adaptation is required), then the modification content should be generated. Become the patch file origin.patch, and in subsequent use, modify the source code by patching. The patch -p1 method is used when patching, please pay attention when generating the patch file.

The origin.patch patch file can be generated as follows:

• Create a and b directories, copy the unmodified component source code to the a directory, and copy the modified component source code to the b directory. The directory structure is as follows:

• Execute the following command

diff -Nur a/curl-7.54.1 b/curl-7.54.1 > orinig.patch

Note: Please make sure that the origin.patch file is in unix format before local verification. Because the file is automatically converted to unix format when uploaded to the LiteOS_Components warehouse, if it is not in unix format during local verification, it will cause the online component to fail to execute download.sh.

patch.sha256

The verification code file of the source patch file origin.patch. The file is named patch.sha256 uniformly and cannot be modified. Its function is to ensure that the downloaded patch file is correct, and the file format is consistent with the requirements of src.patch.

Kconfig

components/utility/curl/Kconfig

Component configuration file. Through this file, the components are included in the menu item interface of LiteOS for management. When writing, you can refer to the Kconfig file of the existing components to modify. The basic syntax of Kconfig can be searched by yourself or refer to the official document "kconfig-language.txt".

The content and description of the components/utility/curl/Kconfig file are as follows:

config LOSCFG_COMPONENTS_CURL           # 配置项：一般固定为"LOSCFG_COMPONENTS_目录名"
    bool "Enable Curl"                  # bool: 配置项类型; Enable Curl: 配置项提示
    select LOSCFG_COMPONENTS_NET_LWIP   # 依赖关系：如依赖其他组件，请指明依赖关系
    select LOSCFG_COMPONENTS_FS_FATFS
    default n                           # 组件默认是否使能：一般默认不使能
    help
      Answer y to enable curl.          # 帮助信息：该配置项的说明

• If there are multiple other components under the component, the configuration items can be named flexibly. Such as LOSCFG_COMPONENTS_directory name_XXX, but it should not be too long.

• The configuration item prompt is the display information in the menuconfig menu item, which can be understood as the alias of the configuration item. The first letter of each word should be capitalized, and the rest should be lowercase (except for proper nouns).

• The first letter of the help information is capitalized, the remaining letters are lowercase (except for proper nouns), and there must be a terminator.

• Please use spaces for indentation, not the tab key.

Kconfig in the parent directory

When adding new components, in addition to creating a new Kconfig file for this component in the component directory at this level, you also need to modify the Kconfig file in the parent directory. This file is used to call Kconfig in the next subdirectory, and can be modified by referring to other components in this file. The content of the components/utility/Kconfig file is as follows, which contains the Kconfig files of all components in the utility directory.

menu "Utility" # 菜单项

source "components/utility/bidireference/Kconfig"

source "components/utility/curl/Kconfig" # 本次新增的内容

source "components/utility/freetype/Kconfig"

source "components/utility/iconv/Kconfig"

source "components/utility/iniparser/Kconfig"

source "components/utility/json-c/Kconfig"

source "components/utility/libxml2/Kconfig"

endmenu

.mk file

.mk is used to export the external header file of the component for other components or modules to call the API in this component. To avoid confusion among header files, Huawei LiteOS uses .mk files to manage and restrict the external header files of components, and export the external interfaces of components layer by layer through the .mk files in each directory. Finally, the header files of all components are exported through components.mk supply.

The .mk files generally involved when adding new components are:

• Create a new .mk file of this component in the new component directory, you can refer to the .mk file of an existing component.

• Modify the .mk file in the upper-level directory. You can refer to other components in the file for modification.

Such as curl.mk and utility.mk:

####################### curl.mk的内容如下 ########################
CURL_VERSION=curl-7.54.1   # 组件版本
COMPONENTS_CURL_INCLUDE := \
    -I $(LITEOSTOPDIR)/components/utility/curl/$(CURL_VERSION)/include \
    -I $(LITEOSTOPDIR)/components/utility/curl/$(CURL_VERSION)/src
##################### utility.mk的内容如下 #######################
ifeq ($(LOSCFG_COMPONENTS_CURL), y)                       # 只有组件已使能，才执行以下操作
include $(LITEOSTOPDIR)/components/utility/curl/curl.mk   # 调用子目录下其他组件的.mk文件
COMPONENTS_UTILITY_INCLUDE += $(COMPONENTS_CURL_INCLUDE)  # 导出该组件对外开放的头文件
endif

Document specifications and instructions:

• CURL_VERSION: component version macro definition, generally named as the source code name _VERSION.

• COMPONENTS_CURL_INCLUDE: Header file macro definition, generally named COMPONENTS_source name_INCLUDE.

• Generally, in the .mk file of the upper-level directory of the component, there must be conditions when calling the .mk file of a specific component, and the .mk file of the component is allowed to be called only when the component is enabled.

• If you need to indent, indent four spaces uniformly, and be careful not to use the tab key.

Makefile

components/utility/curl/Makefile is a componentized compilation file. Use this file to add components to the componentized compilation framework of Huawei LiteOS. When adding a new component, you need to create this file in the component directory to compile the component. You can refer to the Makefile of the existing component. The contents of the components/utility/curl/Makefile file are as follows:

include $(LITEOSTOPDIR)/config.mk
include $(LITEOSTOPDIR)/components/net/lwip/lwip.mk
include $(LITEOSTOPDIR)/components/utility/curl/curl.mk
MODULE_NAME := $(notdir $(CURDIR))      # $(notdir $(CURDIR)) 等价于 curl
LOCAL_SRCS_y :=
LOCAL_DIRS_y :=
LOCAL_DIRS_y += $(CURL_VERSION)/lib
LOCAL_DIRS_y += $(CURL_VERSION)/lib/vauth
LOCAL_DIRS_y += $(CURL_VERSION)/lib/vtls
LOCAL_DIRS_y += $(CURL_VERSION)/src
LOCAL_INCLUDE := $(LWIP_INCLUDE)
LOCAL_INCLUDE += \
    -I $(LITEOSTOPDIR)/components/utility/curl/$(CURL_VERSION)/lib \
    -I $(LITEOSTOPDIR)/components/utility/curl/$(CURL_VERSION)/include \
    -I $(LITEOSTOPDIR)/components/utility/curl/$(CURL_VERSION)/src
LOCAL_SRCS_y += $(foreach dir, $(LOCAL_DIRS_y), $(wildcard $(dir)/*.c))
LOCAL_SRCS   = $(LOCAL_SRCS_y)
LOCAL_EXT_FLAG := -Wno-error -Wno-implicit-function-declaration -Wno-unused-variable
CURL_DEFS = \
    -D HAVE_CONFIG_H \
    -D BUILDING_LIBCURL
LOCAL_FLAGS := $(LOCAL_INCLUDE) $(CURL_DEFS) $(LOCAL_EXT_FLAG)
include $(MODULE)

A few important parameters are explained below (some parameters are not required for every Makefile, please choose to write/not write according to actual needs):

• include $(LITEOSTOPDIR)/config.mk: Introduce the macro definition of Huawei LiteOS system. All Makefiles need to quote this file.

• MODULE_NAME: Module name, the name of the static link library generated by compilation is the module name. For example, if the module is named curl, the static link library generated is libcurl.a. In the bsp.mk file, the link to the library file of the new component needs to be added. Please refer to the link of the existing component in the bsp.mk file to modify it.

Note: If the component name itself starts with lib, the module name does not need to reflect lib. For example, libpng should be written as MODULE_NAME := png instead of MODULE_NAME := libpng. Avoid the generated static library file name as liblibpng. a.

• LOCAL_INCLUDE: A collection of header files needed for compilation.

• LOCAL_SRCS: All source files except header files that this module needs to participate in compilation.

• LOCAL_EXT_FLAG: The compilation parameter set of this module (not required).

• CURL_DEFS: A collection of macro definitions (not required) needed for the compilation of this module.

• If you need to indent, indent four spaces uniformly, and be careful not to use the tab key.

Makefile in the parent directory

This file is used to call the Makefile in the next subdirectory. The contents of the components/utility/Makefile are as follows:

include $(LITEOSTOPDIR)/config.mk
MODULE_$(LOSCFG_COMPONENTS_BIDIREFERENCE) += bidireference
MODULE_$(LOSCFG_COMPONENTS_CURL) += curl                    # 本次新增的内容
MODULE_$(LOSCFG_COMPONENTS_FREETYPE) += freetype
MODULE_$(LOSCFG_COMPONENTS_ICONV) += iconv
MODULE_$(LOSCFG_COMPONENTS_INIPARSER) += iniparser
MODULE_$(LOSCFG_COMPONENTS_JSON_C) += json-c
MODULE_$(LOSCFG_COMPONENTS_LIBXML2) += libxml2
include $(MODULE)

LOSCFG_COMPONENTS_CURL is a configuration item in the component Kconfig file, and MODULE_$(LOSCFG_COMPONENTS_CURL) means that the curl component can only be compiled after the component is enabled.

Component demo

In principle, each component should provide a reference demo, the demo must be self-developed, and it is forbidden to directly copy the code on the network. Each demo is only allowed to provide one external interface, which is uniformly called in the demo_entry.c file.

bsp.mk

Huawei LiteOS uses a component-based compilation framework. After each component or demo is compiled, a corresponding static library file will be generated in the out directory. Because the Windows platform cannot automatically link static library files, you need to link manually in the bsp.mk file. For example, add static library files linking curl components and demo:

ifneq ($(OS), Linux)
    ifeq ($(LOSCFG_COMPONENTS_CURL), y)
        LITEOS_BASELIB += -lcurl        # curl是组件的模块名
    endif
    ifeq ($(LOSCFG_DEMOS_CURL), y)
        LITEOS_BASELIB += -lcurl_demo   # curl_demo是组件demo的模块名
    endif
endif

demo_entry.c

Entrance to all demos. After the demo is completed, it is uniformly called in the DemoEntry function of the file.

#ifdef LOSCFG_DEMOS_CURL
#include "curl_demo.h"
#endif
VOID DemoEntry(VOID)
{
#ifdef LOSCFG_DEMOS_CURL
    CurlDemoTask();
#endif
}

Note: The function must be called in the way of #include header file, and the use of extern is forbidden.

Online component download process

Linux platform

Download the LiteOS code warehouse. After executing the make menuconfig command in the root directory of the Huawei LiteOS source code, the download.sh script will be automatically invoked. The script reads the content of the online_components file to obtain component download information, and determines whether the component is enabled. If the component has been enabled, continue to determine whether the component source code exists. If it does not exist, download the component source code, origin.patch, src.sha256 and patch.sha256, and judge whether the downloaded component source code and origin.patch file are correct through the .sha256 file. If it is correct, enter the patch to complete the download process of the online component.

Note: If you want to re-download the component source code and patch, you need to delete the existing source code and patch file locally. At the same time, if the script is forcibly interrupted by external signals, such as ctrlz, ctrlc, etc., during the running of the script, the download process may fail. Please clean up the remaining files in this download in time.

Windows platform

In the HUAWEI LiteOS Studio development tool, after completing the project configuration -> component configuration, the download.sh file will be automatically called, and the rest of the logic is consistent with the Linux platform.

Test component

After completing all the work of the component development, the component needs to be tested to ensure that the online component download process is executed and passed.

Submit code

After the component tests are passed, the code can be submitted to each code warehouse of Huawei LiteOS. The requirements for code submission are as follows:

• Online components do not need to submit component source code.

• Origin.patch, src.sha256 and patch.sha256 are submitted to the corresponding directories under the LiteOS_Components warehouse (the directory structure must be consistent with the directory structure during development. For example, these files in curl should be placed in the components/utility/curl of the warehouse Under contents). For offline components, the src.sha256 file is not required.

• Submit the remaining files to the LiteOS warehouse.

Note: Please refer to the LiteOS Code & Documentation Contribution Guide for the code submission process.

https://gitee.com/LiteOS/LiteOS/blob/master/doc/LiteOS_Contribute_Guide.md

Concluding remarks

In the future, we will continue to add more components, development boards, architectures, features, etc.

Thank you for reading. If you have any questions or suggestions, you can leave a message to us and let us make progress together:

https://gitee.com/LiteOS/LiteOS/issues

In order to find the "LiteOS" code warehouse easier, it is recommended to visit https://gitee.com/LiteOS/LiteOS, follow " Watch", like "Star", and "Fork" to your account, as shown below.

Click to follow to learn about Huawei Cloud's fresh technology for the first time~