diff --git a/en/readme/ai.md b/en/readme/ai.md new file mode 100755 index 0000000000000000000000000000000000000000..6657e7d12b67dfe797386bc7eb95283d746db4e3 --- /dev/null +++ b/en/readme/ai.md @@ -0,0 +1,433 @@ +# AI + +- [Introduction](#section187321516154516) +- [Directory Structure](#section571610913453) +- [Constraints](#section5748426453) +- [Usage](#section6370123616447) +- [Repositories Involved](#section10492183517430) +- [Reference](#section6808423133718) + +## Introduction + +The AI subsystem is the part of OpenHarmony that provides native distributed AI capabilities. At the heart of the subsystem is a unified AI engine framework, which implements quick integration of AI algorithm plug-ins. The framework consists of the plug-in management, module management, and communication management modules, fulfilling lifecycle management and on-demand deployment of AI algorithms. Under this framework, AI algorithm APIs will be standardized to facilitate distributed calling of AI capabilities. In addition, unified inference APIs will be provided to adapt to different inference framework hierarchies. + +**Figure 1** AI engine framework +![](figures/ai-engine-framework.png "ai-engine-framework") + +## Directory Structure + +``` +/foundation/ai/engine # Home directory of the AI subsystem +├── interfaces +│ └── kits # External APIs of the AI subsystem +└── services +│ ├── client # Client module of the AI subsystem +│ │ ├── client_executor # Executor of the client module +│ │ └── communication_adapter # Communication adaptation layer for the client module, with extension supported +│ ├── common # Common tools and protocol modules of the AI subsystem +│ │ ├── platform +│ │ ├── protocol +│ │ └── utils +│ └── server # Server module of the AI subsystem +│ │ ├── communication_adapter # Communication adaptation layer for the server module, with extension supported +│ │ ├── plugin +│ │ ├── asr +│ │ └── keyword_spotting # ASR algorithm plug-in reference: keyword spotting +│ │ └── cv +│ │ └── image_classification # CV algorithm plug-in reference: image classification +│ │ ├── plugin_manager +│ │ └── server_executor # Executor of the server module +``` + +## Constraints + +**Programming language**: C/C++ + +**Operating system**: OpenHarmony + +**Others**: The System Ability Manager \(Samgr\) has been started and is running properly. + +## Usage + +1. Compile the AI subsystem. + + The source code for lightweight AI framework is available at **//foundation/ai/engine/services**. + + The compilation procedure is as follows: + + 1. Set the compilation path. + + ``` + hb set -root dir (root dir is the root directory of the project code.) + ``` + + 2. Specify the product for compilation. \(After the product list is displayed using the following command, move to the desired product with arrow keys and press **Enter**.\) + + ``` + hb set -p + ``` + + 3. Start compilation. + + ``` + hb build -f (Use this command if you want to compile the entire repository.) + hb build ai_engine (Use this command if you want to compile only the ai_engine module.) + ``` + + **Note**: For details about the hb configuration, see the readme of the build\_lite subsystem. + +2. Develop the plug-in, with keyword spotting as an example. + + Directory: //foundation/ai/engine/services/server/plugin/asr/keyword\_spotting + + **Note**: The plug-in must implement the **IPlugin** and **IPluginCallback** APIs provided by the server. + + ``` + #include "plugin/i_plugin.h + class KWSPlugin : public IPlugin { # Inherits the public base class of the IPlugin API for Keywords Spotting Plugin (KWSPlugin). + KWSPlugin(); + ~KWSPlugin(); + + const long long GetVersion() const override; + const char* GetName() const override; + const char* GetInferMode() const override; + + int32_t Prepare(long long transactionId, const DataInfo &amp;inputInfo, DataInfo &amp;outputInfo) override; + int32_t SetOption(int optionType, const DataInfo &amp;inputInfo) override; + int32_t GetOption(int optionType, const DataInfo &amp;inputInfo, DataInfo &amp;outputInfo) override; + int32_t SyncProcess(IRequest *request, IResponse *&amp;response) override; + int32_t AsyncProcess(IRequest *request, IPluginCallback*callback) override; + int32_t Release(bool isFullUnload, long long transactionId, const DataInfo &amp;inputInfo) override; + . + . + . + }; + ``` + + **Note**: Depending on the algorithm in use, you only need to implement the **SyncProcess** or **AsyncProcess** API. Use an empty function as a placeholder for the other API. In this example, the KWS plug-in uses the synchronous algorithm. Therefore, you need to implement **SyncProcess** API and use an empty function as a placeholder for the **SyncProcess** API. + + ``` + #include "aie_log.h" + #include "aie_retcode_inner.h" + . + . + . + + const long long KWSPlugin::GetVersion() const + { + return ALGOTYPE_VERSION_KWS; + } + + const char *KWSPlugin::GetName() const + { + return ALGORITHM_NAME_KWS.c_str(); + } + + const char *KWSPlugin::GetInferMode() const + { + return DEFAULT_INFER_MODE.c_str(); + } + . + . + . + int32_t KWSPlugin::AsyncProcess(IRequest *request, IPluginCallback *callback) + { + return RETCODE_SUCCESS; + } + ``` + +3. Develop the SDK, with keyword spotting as an example. + + Directory: //foundation/ai/engine/services/client/algorithm\_sdk/asr/keyword\_spotting + + Keyword spotting SDK: + + ``` + class KWSSdk { + public: + KWSSdk(); + virtual ~KWSSdk(); + + /** + * @brief Create a new session with KWS Plugin + * + * @return Returns KWS_RETCODE_SUCCESS(0) if the operation is successful, + * returns a non-zero value otherwise. + */ + int32_t Create(); + + /** + * @brief Synchronously execute keyword spotting once + * + * @param audioInput pcm data. + * @return Returns KWS_RETCODE_SUCCESS(0) if the operation is successful, + * returns a non-zero value otherwise. + */ + int32_t SyncExecute(const Array &audioInput); + + /** + * @brief Asynchronously execute keyword spotting once + * + * @param audioInput pcm data. + * @return Returns KWS_RETCODE_SUCCESS(0) if the operation is successful, + * returns a non-zero value otherwise. + */ + int32_t AsyncExecute(const Array &audioInput); + + /** + * @brief Set callback + * + * @param callback Callback function that will be called during the process. + * @return Returns KWS_RETCODE_SUCCESS(0) if the operation is successful, + * returns a non-zero value otherwise. + */ + int32_t SetCallback(const std::shared_ptr &callback); + + /** + * @brief Destroy the created session with KWS Plugin + * + * @return Returns KWS_RETCODE_SUCCESS(0) if the operation is successful, + * returns a non-zero value otherwise. + */ + int32_t Destroy(); + ``` + + **Note**: The sequence for the SDK to call client APIs of the AI engine is as follows: AieClientInit -\> AieClientPrepare -\> AieClientSyncProcess/AieClientAsyncProcess -\> AieClientRelease -\> AieClientDestroy. An exception will be thrown if the call sequence is violated. In addition, all these APIs must be called. Otherwise, a memory leakage may occur. + + ``` + int32_t KWSSdk::KWSSdkImpl::Create() + { + if (kwsHandle_ != INVALID_KWS_HANDLE) { + HILOGE("[KWSSdkImpl]The SDK has been created"); + return KWS_RETCODE_FAILURE; + } + if (InitComponents() != RETCODE_SUCCESS) { + HILOGE("[KWSSdkImpl]Fail to init sdk components"); + return KWS_RETCODE_FAILURE; + } + int32_t retCode = AieClientInit(configInfo_, clientInfo_, algorithmInfo_, nullptr); + if (retCode != RETCODE_SUCCESS) { + HILOGE("[KWSSdkImpl]AieClientInit failed. Error code[%d]", retCode); + return KWS_RETCODE_FAILURE; + } + if (clientInfo_.clientId == INVALID_CLIENT_ID) { + HILOGE("[KWSSdkImpl]Fail to allocate client id"); + return KWS_RETCODE_FAILURE; + } + DataInfo inputInfo = { + .data = nullptr, + .length = 0, + }; + DataInfo outputInfo = { + .data = nullptr, + .length = 0, + }; + retCode = AieClientPrepare(clientInfo_, algorithmInfo_, inputInfo, outputInfo, nullptr); + if (retCode != RETCODE_SUCCESS) { + HILOGE("[KWSSdkImpl]AieclientPrepare failed. Error code[%d]", retCode); + return KWS_RETCODE_FAILURE; + } + if (outputInfo.data == nullptr || outputInfo.length <= 0) { + HILOGE("[KWSSdkImpl]The data or length of output info is invalid"); + return KWS_RETCODE_FAILURE; + } + MallocPointerGuard pointerGuard(outputInfo.data); + retCode = PluginHelper::UnSerializeHandle(outputInfo, kwsHandle_); + if (retCode != RETCODE_SUCCESS) { + HILOGE("[KWSSdkImpl]Get handle from inputInfo failed"); + return KWS_RETCODE_FAILURE; + } + return KWS_RETCODE_SUCCESS; + } + + int32_t KWSSdk::KWSSdkImpl::SyncExecute(const Array &audioInput) + { + intptr_t newHandle = 0; + Array kwsResult = { + .data = nullptr, + .size = 0 + }; + DataInfo inputInfo = { + .data = nullptr, + .length = 0 + }; + DataInfo outputInfo = { + .data = nullptr, + .length = 0 + }; + int32_t retCode = PluginHelper::SerializeInputData(kwsHandle_, audioInput, inputInfo); + if (retCode != RETCODE_SUCCESS) { + HILOGE("[KWSSdkImpl]Fail to serialize input data"); + callback_->OnError(KWS_RETCODE_SERIALIZATION_ERROR); + return RETCODE_FAILURE; + } + retCode = AieClientSyncProcess(clientInfo_, algorithmInfo_, inputInfo, outputInfo); + if (retCode != RETCODE_SUCCESS) { + HILOGE("[KWSSdkImpl]AieClientSyncProcess failed. Error code[%d]", retCode); + callback_->OnError(KWS_RETCODE_PLUGIN_EXECUTION_ERROR); + return RETCODE_FAILURE; + } + if (outputInfo.data == nullptr || outputInfo.length <= 0) { + HILOGE("[KWSSdkImpl] The data or length of outputInfo is invalid. Error code[%d]", retCode); + callback_->OnError(KWS_RETCODE_NULL_PARAM); + return RETCODE_FAILURE; + } + MallocPointerGuard pointerGuard(outputInfo.data); + retCode = PluginHelper::UnSerializeOutputData(outputInfo, newHandle, kwsResult); + if (retCode != RETCODE_SUCCESS) { + HILOGE("[KWSSdkImpl]UnSerializeOutputData failed. Error code[%d]", retCode); + callback_->OnError(KWS_RETCODE_UNSERIALIZATION_ERROR); + return retCode; + } + if (kwsHandle_ != newHandle) { + HILOGE("[KWSSdkImpl]The handle[%lld] of output data is not equal to the current handle[%lld]", + (long long)newHandle, (long long)kwsHandle_); + callback_->OnError(KWS_RETCODE_PLUGIN_SESSION_ERROR); + return RETCODE_FAILURE; + } + callback_->OnResult(kwsResult); + return RETCODE_SUCCESS; + } + + int32_t KWSSdk::KWSSdkImpl::Destroy() + { + if (kwsHandle_ == INVALID_KWS_HANDLE) { + return KWS_RETCODE_SUCCESS; + } + DataInfo inputInfo = { + .data = nullptr, + .length = 0 + }; + int32_t retCode = PluginHelper::SerializeHandle(kwsHandle_, inputInfo); + if (retCode != RETCODE_SUCCESS) { + HILOGE("[KWSSdkImpl]SerializeHandle failed. Error code[%d]", retCode); + return KWS_RETCODE_FAILURE; + } + retCode = AieClientRelease(clientInfo_, algorithmInfo_, inputInfo); + if (retCode != RETCODE_SUCCESS) { + HILOGE("[KWSSdkImpl]AieClientRelease failed. Error code[%d]", retCode); + return KWS_RETCODE_FAILURE; + } + retCode = AieClientDestroy(clientInfo_); + if (retCode != RETCODE_SUCCESS) { + HILOGE("[KWSSdkImpl]AieClientDestroy failed. Error code[%d]", retCode); + return KWS_RETCODE_FAILURE; + } + mfccProcessor_ = nullptr; + pcmIterator_ = nullptr; + callback_ = nullptr; + kwsHandle_ = INVALID_KWS_HANDLE; + return KWS_RETCODE_SUCCESS; + } + ``` + +4. **Sample development** \(similar to keyword spotting\) + + Directory: //applications/sample/camera/ai/asr/keyword\_spotting + + Call the **Create** API. + + ``` + bool KwsManager::PreparedInference() + { + if (capturer_ == nullptr) { + printf("[KwsManager] only load plugin after AudioCapturer ready\n"); + return false; + } + if (plugin_ != nullptr) { + printf("[KwsManager] stop created InferencePlugin at first\n"); + StopInference(); + } + plugin_ = std::make_shared(); + if (plugin_ == nullptr) { + printf("[KwsManager] fail to create inferencePlugin\n"); + return false; + } + if (plugin_->Create() != SUCCESS) { + printf("[KwsManager] KWSSdk fail to create.\n"); + return false; + } + std::shared_ptr callback = std::make_shared(); + if (callback == nullptr) { + printf("[KwsManager] new Callback failed.\n"); + return false; + } + plugin_->SetCallback(callback); + return true; + } + ``` + + Call the **SyncExecute** API. + + ``` + void KwsManager::ConsumeSamples() + { + uintptr_t sampleAddr = 0; + size_t sampleSize = 0; + int32_t retCode = SUCCESS; + while (status_ == RUNNING) { + { + std::lock_guard lock(mutex_); + if (cache_ == nullptr) { + printf("[KwsManager] cache_ is nullptr.\n"); + break; + } + sampleSize = cache_->GetCapturedBuffer(sampleAddr); + } + if (sampleSize == 0 || sampleAddr == 0) { + continue; + } + Array input = { + .data = (int16_t *)(sampleAddr), + .size = sampleSize >> 1 + }; + { + std::lock_guard lock(mutex_); + if (plugin_ == nullptr) { + printf("[KwsManager] cache_ is nullptr.\n"); + break; + } + if ((retCode = plugin_->SyncExecute(input)) != SUCCESS) { + printf("[KwsManager] SyncExecute KWS failed with retCode = [%d]\n", retCode); + continue; + } + } + } + } + ``` + + Call the **Destroy** API. + + ``` + void KwsManager::StopInference() + { + printf("[KwsManager] StopInference\n"); + if (plugin_ != nullptr) { + int ret = plugin_->Destroy(); + if (ret != SUCCESS) { + printf("[KwsManager] plugin_ destroy failed.\n"); + } + plugin_ = nullptr; + } + } + ``` + + +## Repositories Involved + +AI subsystem: + +**ai\_engine** + +Dependency repositories: + +build\_lite + +distributedschedule\_services\_samgr\_lite + +startup\_init\_lite + +## Reference + +- AI Engine Framework Development Guide + diff --git a/en/readme/application-framework.md b/en/readme/application-framework.md old mode 100644 new mode 100755 index 82428d13f543598af63033fcd107e86806e30f66..b574418c286ae3163d6b0068f07bd97653142a90 --- a/en/readme/application-framework.md +++ b/en/readme/application-framework.md @@ -1,18 +1,26 @@ # Application Framework -## Overview +- [Introduction](#section11660541593) +- [Directory Structure](#section1464106163817) +- [Constraints](#section1718733212019) +- [Usage](#section1048719468503) +- [Repositories Involved](#section93061357133720) + +## Introduction The application framework of OpenHarmony consists of two modules: **ability management framework** and **bundle management framework**. -**1. Ability management framework**: This framework is provided by OpenHarmony for you to develop OpenHarmony applications. The following figure shows the modules in the ability management framework. +**1. Ability management framework**: This framework is provided by OpenHarmony for you to develop OpenHarmony applications. The following figure shows the sub-modules in the ability management framework. + +**Figure 1** Architecture of the ability management framework + -**Figure 1** Architecture of the Ability management framework ![](figures/en-us_image_0000001054941316.png) - **AbilityKit** is a development kit provided by the ability management framework. You can use this kit to develop applications based on the **Ability** component. There are two types of applications developed based on the **Ability** component: **JS Ability** developed using the JavaScript language and **Native Ability** developed using the C/C++ language. The **JS application development framework** encapsulates JavaScript UI components on the basis of the AbilityKit and is used to help you quickly develop JS Ability-based applications. - **Ability** is the minimum unit for the system to schedule applications. It is a component that can implement an independent functionality. An application can contain one or more **Ability** instances. There are two types of templates that you can use to create an **Ability** instance: Page and Service. - An **Ability using the Page template** \(Page ability for short\) provides a UI for interacting with users. - - An **Ability using the Service template** does not have a UI and is used for running background tasks. + - An **Ability using the Service template** \(Service ability for short\) does not have a UI and is used for running background tasks. - An **AbilitySlice** represents a single screen and its control logic. It is specific to Page abilities. A Page ability may contain one ability slice or multiple ability slices that provide highly relevant capabilities. The following figure shows the relationship between a Page ability and its ability slices. @@ -25,8 +33,7 @@ The application framework of OpenHarmony consists of two modules: **ability man **Figure 3** Lifecycle state transition of a Page ability ![](figures/lifecycle-state-transition-of-a-page-ability.png "lifecycle-state-transition-of-a-page-ability") - Description of ability lifecycle states: - +- Description of ability lifecycle states: - **UNINITIALIZED**: The ability is not initialized. This state is a temporary state. An ability changes directly to the **INITIAL** state upon its creation. - **INITIAL**: This state refers to the initial or stopped state. The ability in this state is not running. The ability enters the **INACTIVE** state after it is started. @@ -39,112 +46,70 @@ The application framework of OpenHarmony consists of two modules: **ability man - **AbilityLoader** is used to register and load **Ability** classes. After creating an **Ability** class, you should first call the registration API defined in **AbilityLoader** to register the **Ability** class name with the ability management framework so that this **Ability** can be instantiated when being started. -- **AbilityManager** enables inter-process communication \(IPC\) between the AbilityKit and Ability Manager Service. +- **AbilityManager** enables inter-process communication \(IPC\) between the AbilityKit and the Ability Manager Service. - **EventHandler** is provided by the AbilityKit to enable inter-thread communication between abilities. -- The **Ability Manager Service** is a system service used to coordinate the running relationships and lifecycle states of **Ability** instances. It consists of the following modules: - - The **service startup module** starts and registers the Ability Manager Service. - - The **service interface management module** manages external capabilities provided by the Ability Manager Service. - - The **process management module** starts and destroys processes where **Ability** instances are running, and maintains the process information. - - The **ability stack management module** maintains the presentation sequence of abilities in the stack. - - The **lifecycle scheduling module** changes an ability to a particular state based on the current operation of the system. - - The **connection management module** manages connections to Service abilities. +- The **Ability Manager Service** is a system service used to coordinate the running relationships and lifecycle states of **Ability** instances. It consists of the following sub-modules: + - The **service startup** sub-module starts and registers the Ability Manager Service. + - The **service interface management** sub-module manages external capabilities provided by the Ability Manager Service. + - The **process management** sub-module starts and destroys processes where **Ability** instances are running, and maintains the process information. + - The **ability stack management** sub-module maintains the presentation sequence of abilities in the stack. + - The **lifecycle scheduling** sub-module changes an ability to a particular state based on the current operation of the system. + - The **connection management** sub-module manages connections to Service abilities. -- The **AppSpawn** is a system service used to create the process for running an ability. This service has high permissions. It sets permissions for **Ability** instances and pre-loads some common modules to accelerate application startup. +- **AppSpawn** is a system service used to create the process for running an ability. This service has high permissions. It sets permissions for **Ability** instances and pre-loads some common modules to accelerate application startup. -**2. Bundle management framework**: This framework is provided by OpenHarmony for you to manage application bundles. The following figure shows the modules in the bundle management framework. +**2. Bundle management framework**: This framework is provided by OpenHarmony for you to manage application bundles \(installation packages\). The following figure shows the sub-modules in the bundle management framework. **Figure 4** Architecture of the bundle management framework ![](figures/architecture-of-the-bundle-management-framework.png "architecture-of-the-bundle-management-framework") -- **BundleKit**: includes external APIs provided by the Bundle Manager Service, including the APIs for application installation and uninstallation, bundle information query, and bundle state change listeners. -- **Bundle scanning module**: parses pre-installed or installed bundles on the local device and extracts information from them for the bundle management module to manage and make the information persistent for storage. +- **BundleKit** includes external APIs provided by the Bundle Manager Service, including the APIs for application installation and uninstallation, bundle information query, and bundle state change listeners. +- The **bundle scanning sub-module** parses pre-installed or installed bundles on the local device and extracts information from them for the bundle management sub-module to manage and make the information persistent for storage. -- **Bundle installation module**: installs, uninstalls, and updates a bundle. The **Bundle installation service** is an independent process used to create or delete installation directories and has high permissions. +- The **bundle installation sub-module** installs, uninstalls, and updates a bundle. +- The **bundle installation service** is an independent process used to create or delete installation directories and has high permissions. -- **Bundle management module**: manages information related to application bundles and stores persistent bundle information. +- The **bundle management sub-module** manages information related to application bundles and stores persistent bundle information. -- **Bundle security management module**: verifies signatures, and grants and manages permissions. +- The **bundle security management sub-module** verifies signatures, and grants and manages permissions. ## Directory Structure -The following table describes the source code directory structure of the application framework. - -**Table 1** Source code directory structure of the application framework - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Directory

-

Description

-

foundation/aafwk/frameworks/ability_lite

-

Core code for AbilityKit

-

foundation/aafwk/frameworks/abilitymgr_lite

-

Client code for managing the communication between the AbilityKit and Ability Manager Service

-

foundation/aafwk/frameworks/want_lite

-

Implementation code of the information carrier used for interaction between abilities

-

foundation/aafwk/interfaces/kits/abilitykit_lite

-

APIs provided by AbilityKit for developers

-

foundation/aafwk/interfaces/innerkits/abilitymgr_lite

-

APIs provided by the Ability Manager Service for other subsystems

-

foundation/aafwk/interfaces/kits/want_lite

-

External APIs of the information carrier used for interaction between abilities

-

foundation/aafwk/services/abilitymgr_lite

-

Implementation code of the Ability Manager Service

-

foundation/appexecfwk/interfaces/kits/bundle_lite

-

APIs provided by BundleKit for developers

-

foundation/appexecfwk/interfaces/innerkits/bundlemgr_lite

-

Core code for AbilityKit and APIs provided by the Bundle Manager Service for other subsystems

-

foundation/appexecfwk/frameworks/bundle_lite

-

Client code for managing the communication between the BundleKit and Bundle Manager Service

-

foundation/appexecfwk/utils/bundle_lite

-

Tool code used in the implementation of the Bundle Manager Service

-

foundation/appexecfwk/services/bundlemgr_lite

-

Implementation code of the Bundle Manager Service

-
+``` +/foundation +├── aafwk +│ └── aafwk_lite +│ ├── frameworks +│ │ ├── ability_lite # Core implementation code of AbilityKit +│ │ ├── abilitymgr_lite # Client code used for communication between the AbilityKit and Ability Manager Service +│ │ └── want_lite # Implementation code of the information carrier for interaction between abilities +│ ├── interfaces +│ │ ├── kits +│ │ │ ├── ability_lite # AbilityKit APIs exposed externally +│ │ │ └── want_lite # External APIs of the information carrier for interaction between abilities +│ │ └── innerkits +│ │ └── abilitymgr_lite # Internal APIs provided by the Ability Manager Service for other subsystems +│ └── services +│ └── abilitymgr_lite # Implementation code of the Ability Manager Service +└── appexecfwk + └── appexecfwk_lite + ├── frameworks + │ └── bundle_lite # Client code used for communication between the BundleKit and Bundle Manager Service + ├── interfaces + │ ├── kits + │ │ └── bundle_lite # BundleKit APIs exposed externally + │ └── innerkits + │ └── bundlemgr_lite # Core implementation code of BundleKit and internal APIs provided by the Bundle Manager Service for other subsystems + ├── services + │ └── bundlemgr_lite # Implementation code of the Bundle Manager Service + └── utils + └── bundle_lite # Utility code used during the implementation of the Bundle Manager Service +``` ## Constraints - Language version - - C++11 or later + - C++ 11 or later - The specifications of the application framework vary depending on the System-on-a-Chip \(SoC\) and underlying OS capabilities. - Cortex-M RAM and ROM @@ -157,142 +122,14 @@ The following table describes the source code directory structure of the applica -## Compiling the Application Framework - -- Add the configuration for application framework compilation. The following section uses **hi3516dv300\_liteos\_a** as an example: - - - Add the configuration of **appexecfwk** and **aafwk** under the **subsystems** field in the **build/lite/platform/hi3516dv300\_liteos\_a/platform.json** file. The sample code is as follows: - - ``` - { - "subsystem": "aafwk", - "components": [ - { - "component": "ability", - "optional": "true", - "dirs": [ - "foundation/aafwk" - ], - "targets": [ - "//foundation/aafwk/frameworks/ability_lite:aafwk_abilitykit_lite", - "//foundation/aafwk/frameworks/ability_lite:aafwk_abilityMain_lite", - "//foundation/aafwk/frameworks/abilitymgr_lite:aafwk_abilityManager_lite", - "//foundation/aafwk/services/abilitymgr_lite:aafwk_services_lite" - ], - "features": [ - {"enable_ohos_appexecfwk_feature_ability": "true"} - ], - "deps": { - "components": [ - "hilog_a", - "bundle_mgr", - "system_ability_manager", - "distributed_schedule", - "graphic", - "utils", - "ipc" - ], - "third_party": [ - "cjson", - "bounds_checking_function" - ] - } - } - ] - }, - - { - "subsystem": "appexecfwk", - "components": [ - { - "component": "bundle_mgr", - "optional": "true", - "dirs": [ - "foundation/appexecfwk" - ], - "targets": [ - "//foundation/appexecfwk/services/bundlemgr_lite:appexecfwk_services_lite", - "//foundation/appexecfwk/frameworks/bundle_lite:appexecfwk_kits_lite" - ], - "features": [], - "deps": { - "components": [ - "iam", - "app_verify", - "hilog_a", - "system_ability_manager", - "global_resource_manager", - "graphic", - "utils" - ], - "third_party": [ - "cjson", - "zlib" - ] - } - } - ] - }, - ``` - - - Add the configuration of particular application framework components for compilation in **build/lite/config/subsystem/aafwk/BUILD.gn** and **/build/lite/config/subsystem/appexecfwk/BUILD.gn**. The sample code is as follows: - - ``` - import("//build/lite/config/subsystem/lite_subsystem.gni") - - lite_subsystem("aafwk") { - subsystem_components = [ - "//foundation/aafwk/frameworks/ability_lite:aafwk_abilitykit_lite", - "//foundation/aafwk/frameworks/abilitymgr_lite:aafwk_abilityManager_lite", - "//foundation/aafwk/services/abilitymgr_lite:aafwk_services_lite", - ] - } - - ``` - - ``` - import("//build/lite/config/subsystem/lite_subsystem.gni") - - lite_subsystem("appexecfwk") { - subsystem_components = [ - "//foundation/appexecfwk/kits/appkit_lite:appexecfwk_kit_lite", - "//foundation/appexecfwk/services/bundlemgr_lite:appexecfwk_services_lite", - ] - } - ``` - - - Add the configuration of service modules for compilation in **foundation/aafwk** and **foundation/appexecfwk**. Each module has its own **BUILD.gn** file. - -- After the preceding configurations are complete, run the following command to compile the entire system: +## Usage - ``` - python build.py ipcamera_hi3516dv300 -b debug - ``` +- Running the Two Services in the Application Framework + - The application framework has two system services **Ability Manager Service** and **Bundle Manager Service**. They are running in the foundation process. + - **Ability Manager Service** and **Bundle Manager Service** are registered with **sa\_manager**. **sa\_manager** runs in the foundation process and sets up a thread runtime environment for the two services. For details about how to create and use the **Ability Manager Service** and **Bundle Manager Service**, see [SA Framework](en-us_topic_0000001051589563.md). -## Running the Two Services in the Application Framework -- The application framework has two system services **Ability Manager Service** and **Bundle Manager Service**. They are running in the foundation process. -- **Ability Manager Service** and **Bundle Manager Service** are registered with **sa\_manager**. **sa\_manager** runs in the foundation process and sets up a thread runtime environment for the two services. For details about how to create and use **Ability Manager Service** and **Bundle Manager Service**, see [Service Framework](en-us_topic_0000001051589563.md). -- Add the configuration of **abilityms** and **bundlems** for compilation in **foundation/distributedschedule/services/safwk\_lite/BUILD.gn**. The sample code is as follows: - - ``` - - deps = [ - "...", - ] - if (ohos_kernel_type == "liteos_a") { - deps += [ - "...", - "//foundation/aafwk/services/abilitymgr_lite:abilityms", - "//foundation/appexecfwk/services/bundlemgr_lite:bundlems", - "...", - ] - } - ``` - -## Running an Ability Developed Based on AbilityKit - -- The demo code of the ability developed based on AbilityKit is stored in the **foundation/aafwk/frameworks/ability\_lite/example** directory. If you need to modify the functionality, modify the code in the **entry/src/main/cpp** files or add a new code file, and update the configuration in **BUILD.gn** accordingly. +- The demo code of the ability developed based on the AbilityKit is stored in the **foundation/aafwk/aafwk\_lite/frameworks/ability\_lite/example** directory. If you need to modify the functionality, modify the code in the **entry/src/main/cpp** files or add a new code file, and update the configuration in **BUILD.gn** accordingly. - Add the configuration for the ability demo for compilation in the **build/lite/config/subsystem/aafwk/BUILD.gn** file. ``` @@ -301,25 +138,26 @@ The following table describes the source code directory structure of the applica lite_subsystem("aafwk") { subsystem_components = [ "......", - "//foundation/aafwk/frameworks/ability_lite/example:hiability", + "//foundation/aafwk/aafwk_lite/frameworks/ability_lite/example:hiability", "......", ] } ``` -- Run the following command in the shell to compile the demo. After the compilation is successful, the **libhiability.so** file is generated in **out/ipcamera\_hi3516dv300\_liteos\_a/dev\_tools/example**. +- Run the following commands in the shell to build the demo. \(For more building details, see the description of the compilation and building subsystem.\) After the building is successful, the **libhiability.so** file is generated in **out/ipcamera\_hi3516dv300\_liteos\_a/dev\_tools/example**. ``` - python build.py ipcamera_hi3516dv300 -b debug + hb set + hb build ``` -- Compile the **config.json** file. For details, see the **config.json** file in the **foundation/aafwk/frameworks/ability\_lite/example** directory. The file content is as follows: +- Compile the **config.json** file. For details, see the **config.json** file in the **foundation/aafwk/aafwk\_lite/frameworks/ability\_lite/example** directory. The file content is as follows: ``` { "app": { - "bundleName": "com.huawei.hiability", - "vendor": "huawei", + "bundleName": "com.xxxxxx.hiability", + "vendor": "xxxxxx", "version": { "code": 1, "name": "1.0" @@ -383,41 +221,23 @@ The following table describes the source code directory structure of the applica - Install the HAP. - Place the preceding HAP file in a particular directory \(**/nfs/hap/** in this example\). - - Run the following command to install the HAP: + - Run the following command to install the HAP. \(Taking **hispark\_taurus** as an example, you can obtain the bm tool from the **out/hispark\_taurus/ipcamera\_hispark\_taurus/dev\_tools/bin directory** after the version building.\) ``` - ./bin/bm install -p /nfs/hap/hiability.hap + ./bin/bm install -p /nfs/hiability.hap ``` -- After the installation is complete, run the following command to run the demo: +- After the installation is complete, use the aa tool to run the demo through the following command. \(Taking **hispark\_taurus** as an example, you can obtain the aa tool from the **out/hispark\_taurus/ipcamera\_hispark\_taurus/dev\_tools/bin** directory after the version building.\) - ``` - ./bin/aa start -p com.huawei.hiability -n MainAbility - ``` +``` +./bin/aa start -p com.xxxxxx.hiability -n MainAbility +``` ## Repositories Involved -aafwk\_frameworks\_kits\_ability\_lite - -aafwk\_interfaces\_innerkits\_abilitykit\_lite - -aafwk\_frameworks\_kits\_content\_lite - -aafwk\_interfaces\_innerkits\_abilitymgr\_lite - -aafwk\_interfaces\_innerkits\_intent\_lite - -aafwk\_interfaces\_kits\_ability\_lite - -aafwk\_services\_abilitymgr\_lite - -appexecfwk\_frameworks\_bundle\_lite - -appexecfwk\_interfaces\_innerkits\_bundlemgr\_lite - -appexecfwk\_interfaces\_innerkits\_appexecfwk\_lite +**Application framework** -appexecfwk\_services\_bundlemgr\_lite +aafwk\_lite -appexecfwk\_kits\_appkit\_lite +appexecfwk\_lite diff --git a/en/readme/compilation-and-building-subsystem.md b/en/readme/compilation-and-building-subsystem.md old mode 100644 new mode 100755 index b5ce1a49c7a4662d0995a0f3228f49b1a43f4442..87b4b0aae5126217dcdbaf53224a10b9350124bb --- a/en/readme/compilation-and-building-subsystem.md +++ b/en/readme/compilation-and-building-subsystem.md @@ -1,5 +1,11 @@ # Compilation and Building Subsystem +- [Overview](#section11660541593) +- [Directory Structure](#section1464106163817) +- [Constraints](#section1718733212019) +- [Usage](#section641210360552) +- [Repositories Involved](#section6299103515474) + ## Overview The compilation and building subsystem provides a compilation and building framework based on GN and Ninja. Using this subsystem, you can perform the following operations: diff --git a/en/readme/dfx.md b/en/readme/dfx.md old mode 100644 new mode 100755 index 01e84be97eef5ab9a5f8fc32a05c0046909aad97..16614ed8c30922c8d78f1b5707179d4006bc3e20 --- a/en/readme/dfx.md +++ b/en/readme/dfx.md @@ -1,364 +1,48 @@ -# DFX +# DFX -## Introduction +- [Introduction](#section1347419114210) +- [Architecture](#section342962219551) +- [Directory Structure](#section62815498425) +- [Repositories Involved](#section767551120815) -This repository is used to store the code of Design for X \(DFX\) frameworks, including Design for Reliability \(DFR\) and Design for Testability \(DFT\). +## Introduction -As chip resources are limited and hardware platforms are diversified, component-based and customizable DFX frameworks need to be provided for different hardware architectures and resources. Two types of lightweight DFX frameworks \(mini and featured\) are available for hardware platforms powered by RISC-V, Cortex-M, and Cortex-A. +[Design for X](https://en.wikipedia.org/wiki/Design_for_X) \(DFX\) refers to the software design that aims to improve the quality attribute in OpenHarmony. It mainly consists of two parts: design for reliability \(DFR\) and design for testability \(DFT\). -- mini: This framework is intended for hardware platforms with Cortex-M or equivalent processing capabilities. The system memory is generally less than 512 KB. There is only one lightweight file system that can be used in limited scenarios, or no file system at all. The mini framework complies with the Cortex Microcontroller Software Interface Standard \(CMSIS\). +The DFX subsystem provides the following capabilities: -- featured: This framework is intended for hardware platforms with Cortex-A or equivalent processing capabilities. The system memory is generally greater than 512 KB. There is a comprehensive file system for storing a large amount of data. The featured framework complies with the Portable Operating System Interface \(POSIX\) specifications. +- HiLog: Implements the logging capability. +- HiEvent: Implements the event logging capability. +- Hiview: Implements the logging task capability. -## Directory Structure +## Architecture -**Table 1** Directory structure of the source code for lightweight DFX +**Figure 1** Architecture of the DFX subsystem - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Directory

-

Description

-

interface

-

Stores all header files for open APIs.

-

interfaces/kits/hilog

-

Defines open APIs available for logs in the featured framework.

-

interfaces/kits/hilog_lite

-

Defines open APIs available for logs in the mini framework.

-

interfaces/innerkits/hievent_lite

-

Defines open APIs available for event printing in the mini framework.

-

services/hilogcat_lite

-

Stores services and commands related to logs.

-

services/hilogcat_lite/apphilogcat

-

Provides the log flushing to disk service in the featured framework.

-

services/hilogcat_lite/command

-

Provides DFX commands specific to the mini framework.

-

services/hilogcat_lite/hilogcat

-

Provides commands to output logs in the featured framework.

-

services/hiview_lite

-

Registers the DFX service specific to the mini framework.

-

frameworks/ddrdump_lite

-

Dumps Double Data Rate (DDR) memory in the mini framework.

-

frameworks/hievent_lite

-

Records event printing in the DFX-mini framework.

-

frameworks/hilog_lite

-

Defines APIs for logging.

-

frameworks/hilog_lite/featured

-

Defines APIs for logging in the featured framework.

-

frameworks/hilog_lite/mini

-

Defines APIs for logging in the mini framework.

-

utils/lite

-

Stores utils. It contains the configuration items of the mini framework.

-
-## Constraints +![](figures/en-us_image_0000001130109907.png) -The overall code of the mini framework is developed based on the C standard library. - -## Usage \(mini Framework\) - -The mini framework is a simple and compact DFX design that provides the logging function. - -- **The following takes Module A as an example to describe how to add a module and print logs.** - 1. **Step 1: Add the module ID.** - - Define **HILOG\_MODULE\_A** in **HiLogModuleDef** of **interfaces/kits/hilog\_lite/hiview\_log.h**. - - ``` - typedef enum { - /** DFX */ - HILOG_MODULE_HIVIEW = 0, - /** System Module A */ - HILOG_MODULE_A, - /** Maximum number of modules */ - HILOG_MODULE_MAX - } HiLogModuleType; - ``` - - - 1. **Step 2: Register the module.** - - Add the following code to the initialization process of Module A to register it with the logging framework: - - ``` - HiLogRegisterModule(HILOG_MODULE_A, "A"); - ``` - - - 1. **Step 3: Modify the static configuration of the DFX framework.** - - Modify **g\_hiviewConfig** in the following file as required \(By default, modification is not required and logs are output to the serial port\): - - ``` - utils/lite/hiview_config.c - ``` - - - - - - - - - - - - - - - - - - - - - - -

Configuration Item

-

Description

-

outputOption

-

Log output mode. The value can be:

-

OUTPUT_OPTION_DEBUG: Logs are directly output to the serial port without cross-task scheduling. This value is used only for temporary debugging.

-

OUTPUT_OPTION_FLOW (default value): Logs are output as data flow to the serial port.

-

OUTPUT_OPTION_TEXT_FILE: Logs are output as text files.

-

level

-

Log level for output. Only the logs whose levels are higher than or equal to the level specified by this parameter can be output. The value can be:

-

HILOG_LV_DEBUG, HILOG_LV_INFO, HILOG_LV_WARN, HILOG_LV_ERROR, or HILOG_LV_FATAL

-

logSwitch

-

Logging switch. The log component can be successfully initialized even if this switch is turned off before compilation. By default, this switch is turned on. The value can be:

-

HIVIEW_FEATURE_ON or HIVIEW_FEATURE_OFF

-

dumpSwitch

-

Dumping switch. If this switch is turned off before compilation, the DUMP component will not be initialized. By default, this switch is turned off. The value can be:

-

HIVIEW_FEATURE_ON or HIVIEW_FEATURE_OFF

-

eventSwitch

-

Event output switch. If this switch is turned off before compilation, the Event component will not be initialized. By default, this switch is turned off. The value can be:

-

HIVIEW_FEATURE_ON or HIVIEW_FEATURE_OFF

-
- - 2. **Step 4: Print logs.** - - Include **\#include "log.h"** in the **.c** file where logs need to be printed, call the following function: - - HILOG\_INFO\(HILOG\_MODULE\_A, "log test: %d", 88\); - - Parameter description: - - - - - - - - - - - - - - - - - - - - - - - - -

Parameter

-

Mandatory

-

Data Type

-

Description

-

mod

-

Yes

-

uint8

-

Module or service ID.

-

IDs are planned and allocated in a unified manner. A maximum of 64 IDs are supported. Third-party applications use HILOG_MODULE_APP as their module ID.

-

fmt

-

Yes

-

char *

-

Format specifier for output.

-

1. A maximum of six variable parameters are supported. %s is not supported.

-

2. The maximum length of a formatted log record is 128 bytes. If the length of a log exceeds 128 bytes, the log cannot be printed.

-

Variable parameters

-

No

-

int32

-

Only numeric types are supported. A maximum of six variable parameters are allowed.

-
- - - -## Usage \(featured Framework\) - -The featured framework provides comprehensive DFX features and logging APIs. - -**Native C/C++** APIs - -Available hilog APIs: +## Directory Structure ``` -HILOG_DEBUG(type, ...) -HILOG_INFO(type, ...) -HILOG_WARN(type, ...) -HILOG_ERROR(type, ...) -HILOG_FATAL(type, ...) +base/hiviewdfx # DFX base repository, which stores compilation-related configurations +├── hiview_lite # Hiview_lite module, which implements the logging task capability for the mini system +├── hilog_lite # HiLog_lite module, which implements the logging capability for the mini and small systems +├── hievent_lite # HiEvent_lite module, which implements the event logging capability for the mini system ``` -Usage guidelines: - -1. Define the log tag. - -2. Perform local debugging. \(The domain value **0** can be used.\) - -3. Include the header file: \#include - -4. Add the dependent library **libhilog** to **BUILD.gn**. - -API rules: - -1. The format specifier is labeled public by default, for example, **HILOGI\("Hello World\\n"\); \>\> Hello World**. - -2. The formatted parameter is labeled private by default, for example, **HILOGI\("Age is %d\\n", 10\); \>\> Age is **. - -3. Parameters labeled **%\{private\}** are private data, for example, **HILOGI\("Age is %\{private\}d\\n", 10\); \>\> Age is **. - -4. Parameters labeled **%\{public\}** are public data, for example, **HILOGI\("Age is %\{public\}d\\n", 10\); \>\>Age is 10**. - -Parameter description: - - - - - - - - - - - - - - - - - - - - - - -

Parameter

-

Description:

-

domain

-

Domain ID

-

tag

-

Log tag

-

isFmtPrivate

-

Whether the format specifier is private

-

fmt

-

Format specifier

-

args

-

Parameters to be displayed using the format specifier

-
- -**Viewing logs** - -1. Go to the **/storage/data/log/** directory to view hilog logs for debugging purpose. - -2. Run the **hilogcat** command to view hilog logs in real time. - - -**Logging system architecture** - -![](figures/en-us_image_0000001054762887.png) - -1. hilogtask: kernel task for logging - - This is a task or thread of the Linux kernel. It is initialized during system startup. - - When a module in the kernel calls its logging API, it transfers the formatted log content to the task and stores it in a ringbuffer. - - When the logging API is called in user space, the formatted log content is written into the driver node by calling **ioctl**. The driver node then sends the log content to hilogtask, and hilogtask stores the log content in the ringbuffer. - -2. hilogcatd: storing logs in user space - - This is a user-space process. It periodically reads the log content from the ringbuffer and stores it in the log file. - - Log files can be compressed in **gzip** format by using **zlib**. - - The size of a single file and the number of files can be configured during compilation. - -3. hilogcat: command line tool for viewing logs - - This tool reads the content in the ringbuffer content via the kernel driver API, and then outputs the content to **stdout**. - -4. ringbuffer: configurable - - The ringbuffer size can be configured during compilation. - - -## Repositories Involved - -hiviewdfx\_frameworks\_hievent\_lite - -hiviewdfx\_frameworks\_ddrdump\_lite - -hiviewdfx\_frameworks\_hilog\_lite - -hiviewdfx\_interfaces\_innerkits\_hilog +## Repositories Involved -hiviewdfx\_interfaces\_innerkits\_hievent\_lite +DFX subsystem: -hiviewdfx\_interfaces\_kits\_hilog +**hmf/hiviwdfx** -hiviewdfx\_interfaces\_kits\_hilog\_lite +DFX modules: -hiviewdfx\_services\_hiview\_lite +hmf/hiviwdfx/hilog\_lite -hiviewdfx\_services\_hilogcat\_lite +hmf/hiviwdfx/hiview\_lite -hiviewdfx\_utils\_lite +hmf/hiviwdfx/hievent\_lite diff --git a/en/readme/distributed-communication-subsystem.md b/en/readme/distributed-communication-subsystem.md deleted file mode 100644 index cb8276f8d6f4e943f5f4bfe6d77a7a81103e4f6a..0000000000000000000000000000000000000000 --- a/en/readme/distributed-communication-subsystem.md +++ /dev/null @@ -1,183 +0,0 @@ -# Distributed Communication Subsystem - -## Overview - -The use of different communication modes \(such as USB, WLAN, and Bluetooth\) varies greatly and is complex. In addition, the convergence, sharing, and conflicts between communication links cannot be resolved, and communication security is difficult to guarantee. The distributed communication subsystem manages unified distributed communication between near-field devices and provides device discovery and data transmission APIs that apply to all links. Currently, the following features are available: - -- Service publishing: After a service is published, peripheral devices can discover and use it. -- Data transmission: A session is established based on the service name and device ID to transmit data between services. -- Security: Communication data is encrypted. - -You can use APIs of the distributed communication subsystem to implement fast and secure communication between devices without caring about management of communication details, thereby achieving cross-platform development. - -## Directory Structure - -The following figure shows the softbus\_lite source code directory structure. - -**Table 1** softbus\_lite source code directory structure - - - - - - - - - - - - - - - - -

Name

-

Description

-

authmanager

-

Provides the device authentication mechanism and manages device knowledge libraries.

-

discovery

-

Provides a device discovery mechanism that is based on the Constrained Application Protocol (CoAP).

-

trans_service

-

Provides authentication and transmission channels.

-
- -## Constraints - -- Language: C -- Networking: Devices must be in the same LAN. - -## Usage - -1. Discover devices. - -When using device discovery, ensure that the device to perform a discovery and the discovered device are in the same LAN and the devices can receive packets from each other. - -a. After a device sends a discovery request, it uses CoAP to send a broadcast packet in the LAN. The following figure shows the request packet. - -![](figures/1.png) - -b. The discovered device uses the **PublishService** API to publish services. After receiving the broadcast packet, the device sends a CoAP unicast packet to the device that performs the discovery. The following figure shows the packet example. - -![](figures/2.png) - -c. After receiving the packet, the device that performs the discovery updates device information. - -The following is an example of how to use device discovery: - -``` -// Declare the callback function. -void onSuccess(int publishId) -{ - printf("public success,publishId = %d\r\n", publishId); -} -void onFail(int publishId, PublishFailReason reason) -{ - printf("publish failed, publishId = %d, reason = %d\r\n", publishId, reason); -} -// Publish services. -PublishInfo info = {0}; -IPublishCallback cb = {0}; -cb.onPublishSuccess = onSuccess; -cb.onPublishFail = onFail; -char a[] = "456"; -info.capabilityData = a; -info.capability = "ddmpCapability"; -info.dataLen = strlen("456"); -info.medium = 2; -info.publishId = 1; -PublishService("cxx", &info, &cb); -``` - -2. Transmit data. - -The soft bus provides unified session-based transmission. Services can receive and send data or obtain basic attributes through **sessionId**. Currently, services can determine whether to accept a received session based on the service requirements and session attributes. Currently, sessions cannot be enabled. - -The sample code for data transmission is as follows: - -``` -// Define the service name, session name, and related callback. -const char *g_moduleName = "BUSINESS_NAME"; -const char *g_sessionName = "SESSION_NAME"; -struct ISessionListener * g_sessionCallback= NULL; - -// Implement the callback: After receiving data sent by the peer end using SendBytes, return a fixed message. -void OnBytesReceivedTest(int sessionId, const void* data, unsigned int dataLen) -{ - printf("OnBytesReceivedTest\n"); - printf("Recv Data: %s\n", (char *)data); - printf("Recv Data dataLen: %d\n", dataLen); - char *testSendData = "Hello World, Hello!"; - SendBytes(sessionId, testSendData, strlen(testSendData)); - return; -} - -// Implement the callback: Perform relevant operations after the session is closed, for example, releasing service resources related to the current session. The session does not need to be released by the service. -void OnSessionClosedEventTest(int sessionId) -{ - printf("Close session successfully, sessionId=%d\n", sessionId); -} - -// Implement the callback: Perform relevant operations after a session is opened. The return value 0 means to accept the session, and other values mean to reject the session. In the following example, only sessions with the same name from other devices are accepted. -int OnSessionOpenedEventTest(int sessionId) -{ - if (strcmp(GetPeerSessionName(sessionId), SESSION_NAME) != 0) { - printf("Reject the session which name is different from mine, sessionId=%d\n", sessionId); - return -1; - } - printf("Open session successfully, sessionId=%d\n", sessionId); - return 0; -} - -// Register the service session service and its callbacks with the soft bus. -int StartSessionServer() -{ - if (g_sessionCallback == NULL) { - g_sessionCallback = (struct ISessionListener*)malloc(sizeof(struct ISessionListener)); - } - if (g_sessionCallback == NULL) { - printf("Failed to malloc g_sessionCallback!\n"); - return -1; - } - g_sessionCallback->onBytesReceived = OnBytesReceivedTest; - g_sessionCallback->onSessionOpened = OnSessionOpenedEventTest; - g_sessionCallback->onSessionClosed = OnSessionClosedEventTest; - int ret = CreateSessionServer(g_moduleName , g_sessionName, g_sessionCallback); - if (ret < 0) { - printf("Failed to create session server!\n"); - free(g_sessionCallback); - g_sessionCallback = NULL; - } - return ret; -} - -// Delete the service session service and its callbacks from the soft bus. -void StopSessionServer() -{ - int ret = RemoveSessionServer(g_moduleName , g_sessionName); - if (ret < 0) { - printf("Failed to remove session server!\n"); - return; - } - if (g_sessionCallback != NULL) { - free(g_sessionCallback); - g_sessionCallback = NULL; - } -} -``` - -## Repositories Involved - -communication\_frameworks\_wifi\_lite - -communication\_frameworks\_ipc\_lite - -communication\_hals\_wifi\_lite - -communication\_interfaces\_kits\_ipc\_lite - -communication\_interfaces\_kits\_softbuskit\_lite - -communication\_interfaces\_kits\_wifi\_lite - -communication\_services\_softbus\_lite - diff --git a/en/readme/distributed-scheduler.md b/en/readme/distributed-scheduler.md old mode 100644 new mode 100755 index 28435bba82faf265731673538bb511a9d3733ae4..cafd4e165aeaaa2d243fdd5f3a5cdc94f415d838 --- a/en/readme/distributed-scheduler.md +++ b/en/readme/distributed-scheduler.md @@ -1,6 +1,12 @@ # Distributed Scheduler -## Overview +- [Introduction](#section11660541593) +- [Directory Structure](#section1464106163817) +- [Constraints](#section1718733212019) +- [Usage](#section10729231131110) +- [Repositories Involved](#section176111311166) + +## Introduction The Distributed Scheduler is used for cross-device component management. It allows the local device to access or control remote components, and enables application collaboration in distributed scenarios. The following figure shows the modules in the Distributed Scheduler. @@ -19,7 +25,7 @@ The following table describes the directory structure of the Distributed Schedul -

dtbschedmgr_lite

+

dmsfwk_lite

Implementation of the Distributed Scheduler

@@ -29,35 +35,14 @@ The following table describes the directory structure of the Distributed Schedul

Implementation of the foundation process

+

samgr_lite

+ +

Implementation of system ability framework

+ + -The source code directory structure of the Distributed Scheduler is as follows: - -``` -├── BUILD.gn -├── include -│ ├── distributed_schedule_service.h # Header file for the open APIs provided by the Distributed Scheduler -│ ├── dmslite_check_remote_permission.h # Header file for the permission management module of the Distributed Scheduler -│ ├── dmslite_famgr.h # Header file for the FA management module of the Distributed Scheduler -│ ├── dmslite_inner_common.h # Internal common file for the Distributed Scheduler -│ ├── dmslite.h # Header file for the implementation of the Distributed Scheduler Service -│ ├── dmslite_log.h # Header file for the log module -│ ├── dmslite_msg_parser.h # Header file for the distributed message parsing module -│ ├── dmslite_tlv_common.h # Header file for the TLV data parsing module -│ └── dmslite_session.h # Header file for the inter-device communication module -├── readme.md -├── LICENSE -├── source - ├── distributed_schedule_service.c - ├── dmslite.c - ├── dmslite_check_remote_permission.c - ├── dmslite_famgr.c - ├── dmslite_msg_parser.c - ├── dmslite_tlv_common.c - └── dmslite_session.c -``` - ## Constraints **Language**: C or C++ @@ -68,12 +53,12 @@ The source code directory structure of the Distributed Scheduler is as follows: **Limitations and constraints on remote startup**: -- Only FAs can be started remotely. Remote startup is unavailable to abilities using the Service template. +- Only Feature Abilities \(FAs\) can be started remotely. Remote startup is unavailable to abilities using the Service template. - Before the remote startup, ensure that the distributed networking between the primary and secondary devices is successful. Otherwise, the remote startup fails. ## Usage -- **Compiling the Distributed Scheduler** +- **Compiling and Building the Distributed Scheduler** The code of the Distributed Scheduler is stored in the following directory: @@ -81,7 +66,7 @@ The code of the Distributed Scheduler is stored in the following directory: foundation/distributedschedule/services/dtbschedmgr_lite ``` -When compiling the code for a specific platform, you need to specify the target platform. The following code snippet uses code compilation for the Hi3516DV300 platform as an example: +When compiling and building the code for a specific platform, you need to specify the target platform. The following code snippet uses code compilation and building for the Hi3516 DV300 platform as an example: ``` python build.py ipcamera -p hi3516dv300_liteos_a @@ -116,9 +101,7 @@ Call the **startAbility** method on the primary device to start the target FA ## Repositories Involved -distributedschedule\_interfaces\_kits\_samgr\_lite - -distributedschedule\_services\_dtbschedmgr\_lite +[Distributed scheduler](https://gitee.com/openharmony/docs/blob/master/readme/distributedschedule/dmslite.md) -distributedschedule\_services\_safwk\_lite +[System ability framework](https://gitee.com/openharmony/docs/blob/master/readme/distributedschedule/samgrlite.md) diff --git a/en/readme/driver-subsystem.md b/en/readme/driver-subsystem.md old mode 100644 new mode 100755 index 40031eeb443e9bec8f6874c323520c0e22437e6f..4afa2e182669f2cca1a0e1939b4970e7ce846e8d --- a/en/readme/driver-subsystem.md +++ b/en/readme/driver-subsystem.md @@ -1,5 +1,12 @@ # Driver Subsystem +- [Overview](#section11660541593) +- [Architecture](#section101721227145613) +- [Directory Structure](#section1464106163817) +- [Use](#section8496817141616) +- [Installation](#section14778154275818) +- [Repositories Involved](#section134812226297) + ## Overview The OpenHarmony driver subsystem is constructed using the C object-oriented programming \(OOP\). It provides a unified driver platform through platform decoupling, kernel decoupling, and compatible kernels. This unified driver architecture platform is designed to provide a more precise and efficient development environment, where you develop a driver that can be deployed on different systems supporting HDF. @@ -34,155 +41,52 @@ You can use DevEco to manage driver projects, generate driver templates, and man The OpenHarmony driver framework adopts the primary/secondary mode and is developed based on the framework, model, competence library, and tool. -**Figure 1** Interaction between the driver and framework - +**Figure 1** Driver subsystem architecture +![](figures/driver-subsystem-architecture.png "driver-subsystem-architecture") -![](figures/en-us_image_0000001053805078.png) - -- Driver framework stored in the **frameworks/core** directory +- Driver framework stored in the **framework/core** directory - Loads and starts drivers. - Deploys and expands the driver framework flexibly through the object manager. -- Driver models stored in the **frameworks/model** directory +- Driver model stored in the **framework/model** directory - Provides model-based driving capabilities, such as network device models. -- Driver capability library stored in the **frameworks/ability** directory +- Driver capability library stored in the **framework/ability** directory - Provides basic driver models, such as the I/O communication model. -- Driver tools stored in the **frameworks\\tools** directory +- Driver tools stored in the **framework/tools** directory - Provides tools for HDI API conversion, and driver configuration and driver compilation. -- Driver APIs stored in the **lite\\hdi** directory - - Provides normalized driver APIs. +- Driver APIs stored in the **lite/hdi** directory + - Provides standardized driver APIs. -- Support stored in the **frameworks/support** directory +- Support stored in the **framework/support** directory - Provides platform driver APIs and system APIs with normalized abstraction capabilities. -## Directory Structures - -**Table 1** Directory structure of the OpenHarmony driver framework - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Directory

-

Description

-

hdf

-

Indicates the OpenHarmony driver framework.

-

hdf/frameworks

-

Provides the source code to develop the driver frameworks, driver models, and capability model libraries.

-

hdf/frameworks/ability

-

Provides functional capabilities for the driver development, such as the message model libraries.

-

hdf/frameworks/core

-

Provides the core code to implement the OpenHarmony driver framework.

-

hdf/frameworks/core/host

-

Provides functions of the driver host environment framework, including:

-

1. Loading and starting a driver, and dispatching device nodes.

-

2. Dispatching events.

-

3. Managing the internal power status.

-

4. Managing the common driver resource configurations.

-

hdf/frameworks/core/manager

-

Provides the management modules of the driver framework, including:

-

1. Driver API management module.

-

2. Driver configuration management module.

-

3. Device node management module.

-

4. Security management module.

-

5. Fault management module.

-

hdf/frameworks/core/shared

-

Provides shared code for the host and manager.

-

hdf/frameworks/model

-

Provides a universal framework model for drivers.

-

hdf/frameworks/model/network

-

Provides network device models for drivers.

-

hdf/frameworks/support

-

Provides drivers with system APIs and hardware, such as GPIO, I2C, and SPI capabilities.

-

Some interfaces can be migrated across platforms.

-

hdf/frameworks/support/platform

-

Provides APIs that support the common hardware of platforms, such as GPIO, I2C, and SPI capabilities.

-

hdf/frameworks/tools

-

Provides the driver capability libraries, such as the tool that configures and compiles the HCS (HDF Configuration Source).

-

hdf/frameworks/utils

-

Provides basic data structures and algorithms.

-

hdf/lite/adapter

-

Adapts to kernel operation APIs and provides abstract APIs.

-

hdf/lite/include

-

Provides driver APIs for lightweight devices.

-

hdf/lite/hdi

-

Provides APIs of the OpenHarmony driver.

-
- -## Constraints - -None - -## Use +## Directory Structure -**Figure 2** Interaction between the driver and framework +``` +drivers +├── adapter # Adaptation code for differentiated platforms +├── framework # Core code of the HDF +└── peripheral # Peripheral driver code +``` +## Use -![](figures/en-us_image_0000001052764349.png) +**Figure 2** Interaction between the driver and framework +![](figures/interaction-between-the-driver-and-framework.png "interaction-between-the-driver-and-framework") Driver loading is mostly done by the driver framework, and you only need to register and configure required APIs. The driver framework will load and initialize the driver based on the parsing content. Driver development based on the HDF consists of the following three parts: -1. Driver: develop the functions. +1. Driver: Develop the functions. -2. Information configuration: present the loading information of the driver. +2. Information configuration: Present the loading information of the driver. -3. Resource configuration: configure the hardware information of the driver. +3. Resource configuration: Configure the hardware information of the driver. The driver mainly aims to develop the functions. @@ -211,7 +115,7 @@ int32_t SampleDriverBind(struct HdfDeviceObject *deviceObject) } ``` -Description of Init: When devices are successfully bound, the framework calls Init to initialize the driver. After initialization is complete, the driver framework will determine whether to create external service interfaces based on the configuration file. If the driver fails to be initialized, the driver framework will automatically release the created device interface. +**Init**: When devices are successfully bound, the framework calls **Init** to initialize the driver. After initialization is complete, the driver framework will determine whether to create external service interfaces based on the configuration file. If the driver fails to be initialized, the driver framework will automatically release the created device interface. ``` int32_t SampleDriverInit(struct HdfDeviceObject *deviceObject) @@ -221,7 +125,7 @@ int32_t SampleDriverInit(struct HdfDeviceObject *deviceObject) } ``` -**Release**: When you need to uninstall a driver, the drive framework calls this function to release the driver resources. Then, other internal resources will be released. +**Release**: When you need to uninstall a driver, the driver framework calls this function to release the driver resources. Then, other internal resources will be released. ``` void SampleDriverRelease(struct HdfDeviceObject *deviceObject) @@ -235,14 +139,28 @@ void SampleDriverRelease(struct HdfDeviceObject *deviceObject) The OpenHarmony driver is mainly deployed in the kernel space using the static link mode. It is compiled and packed with the kernel subsystem and system image. -**Figure 3** OpenHarmony driver installation +**Figure 3** Driver installation +![](figures/driver-installation.png "driver-installation") +## Repositories Involved -![](figures/en-us_image_0000001053044331.png) +**Driver subsystem** -## Repositories Involved +hmf/drivers/framework + +hmf/drivers/adapter\_uhdf + +hmf/drivers/adapter\_khdf\_linux + +hmf/drivers/adapter\_khdf\_liteos + +hmf/drivers/peripheral\_display + +hmf/drivers/peripheral\_input + +hmf/drivers/peripheral\_wlan -[drivers\_hdf\_frameworks](https://openharmony.gitee.com/openharmony/drivers_hdf_frameworks) +hmf/drivers/peripheral\_audio -[drivers\_hdf\_lite](https://openharmony.gitee.com/openharmony/drivers_hdf_lite) +hmf/drivers/peripheral\_sensor diff --git a/en/readme/figures/1.png b/en/readme/figures/1.png deleted file mode 100644 index 85b66cb7f38a629f1be914dd10c87c66c6acc45e..0000000000000000000000000000000000000000 Binary files a/en/readme/figures/1.png and /dev/null differ diff --git a/en/readme/figures/2.png b/en/readme/figures/2.png deleted file mode 100644 index 55c0567ab2d9d70555dd07ca050bae228ef46752..0000000000000000000000000000000000000000 Binary files a/en/readme/figures/2.png and /dev/null differ diff --git a/en/readme/figures/ai-engine-framework.png b/en/readme/figures/ai-engine-framework.png new file mode 100755 index 0000000000000000000000000000000000000000..91f3e18d940a6a3af7fb7b66cf3d5874d7354f1f Binary files /dev/null and b/en/readme/figures/ai-engine-framework.png differ diff --git a/en/readme/figures/architecture-of-the-ability-management-framework.png b/en/readme/figures/architecture-of-the-ability-management-framework.png deleted file mode 100644 index 0a54bd695996186eb7e806abed508dfaaf26807d..0000000000000000000000000000000000000000 Binary files a/en/readme/figures/architecture-of-the-ability-management-framework.png and /dev/null differ diff --git a/en/readme/figures/architecture-of-the-bundle-management-framework.png b/en/readme/figures/architecture-of-the-bundle-management-framework.png old mode 100644 new mode 100755 index 6f7e3e730e20598be87ce8191b20af9ed33977a8..69a632ac3200339cdc331287427ba30e15f38598 Binary files a/en/readme/figures/architecture-of-the-bundle-management-framework.png and b/en/readme/figures/architecture-of-the-bundle-management-framework.png differ diff --git a/en/readme/figures/architecture-of-the-openharmony-liteos-cortex-a-kernel.png b/en/readme/figures/architecture-of-the-openharmony-liteos-cortex-a-kernel.png new file mode 100755 index 0000000000000000000000000000000000000000..27b8a0e059ea26e2eb4e53c27afd76f722761550 Binary files /dev/null and b/en/readme/figures/architecture-of-the-openharmony-liteos-cortex-a-kernel.png differ diff --git "a/en/readme/figures/bms\347\255\226\347\225\245\344\270\276\344\276\213.png" "b/en/readme/figures/bms\347\255\226\347\225\245\344\270\276\344\276\213.png" old mode 100644 new mode 100755 diff --git a/en/readme/figures/driver-installation.png b/en/readme/figures/driver-installation.png new file mode 100755 index 0000000000000000000000000000000000000000..2498fd7ced5c1f993f88d9fdfbb8e2318a939334 Binary files /dev/null and b/en/readme/figures/driver-installation.png differ diff --git a/en/readme/figures/driver-subsystem-architecture.png b/en/readme/figures/driver-subsystem-architecture.png new file mode 100755 index 0000000000000000000000000000000000000000..a9ec69320308a00585ccbf4671c62e17c3ae7c1d Binary files /dev/null and b/en/readme/figures/driver-subsystem-architecture.png differ diff --git a/en/readme/figures/en-us_image_0000001051282241.png b/en/readme/figures/en-us_image_0000001051282241.png deleted file mode 100644 index 3f88603e64db4a055e0862aa3e4d134e31491ddf..0000000000000000000000000000000000000000 Binary files a/en/readme/figures/en-us_image_0000001051282241.png and /dev/null differ diff --git a/en/readme/figures/en-us_image_0000001051351505.png b/en/readme/figures/en-us_image_0000001051351505.png deleted file mode 100644 index 82ecf5d03a518987429deff0461e9fc4e9c4c583..0000000000000000000000000000000000000000 Binary files a/en/readme/figures/en-us_image_0000001051351505.png and /dev/null differ diff --git a/en/readme/figures/en-us_image_0000001051562162.png b/en/readme/figures/en-us_image_0000001051562162.png deleted file mode 100644 index d5480f2b75138ead68e798c6cdd9311be7c3c8ad..0000000000000000000000000000000000000000 Binary files a/en/readme/figures/en-us_image_0000001051562162.png and /dev/null differ diff --git a/en/readme/figures/en-us_image_0000001051990283.png b/en/readme/figures/en-us_image_0000001051990283.png deleted file mode 100644 index a6e066359edea0cadab2a0a30b2d2becd268e2f5..0000000000000000000000000000000000000000 Binary files a/en/readme/figures/en-us_image_0000001051990283.png and /dev/null differ diff --git a/en/readme/figures/en-us_image_0000001052278423.png b/en/readme/figures/en-us_image_0000001052278423.png deleted file mode 100644 index cb77c5ed78f92292559fadbbbd4d3734056f9a33..0000000000000000000000000000000000000000 Binary files a/en/readme/figures/en-us_image_0000001052278423.png and /dev/null differ diff --git a/en/readme/figures/en-us_image_0000001052584330.png b/en/readme/figures/en-us_image_0000001052584330.png old mode 100644 new mode 100755 diff --git a/en/readme/figures/en-us_image_0000001052764349.png b/en/readme/figures/en-us_image_0000001052764349.png deleted file mode 100644 index e4c9a55609841fcf1d8f9171ceba02682003619d..0000000000000000000000000000000000000000 Binary files a/en/readme/figures/en-us_image_0000001052764349.png and /dev/null differ diff --git a/en/readme/figures/en-us_image_0000001053044331.png b/en/readme/figures/en-us_image_0000001053044331.png deleted file mode 100644 index 13c697a6e38addbc9b6b2b5717fa2b2a5770d092..0000000000000000000000000000000000000000 Binary files a/en/readme/figures/en-us_image_0000001053044331.png and /dev/null differ diff --git a/en/readme/figures/en-us_image_0000001053805078.png b/en/readme/figures/en-us_image_0000001053805078.png deleted file mode 100644 index 3036ff8a5aedd4ad8573797ab94df3858791c94e..0000000000000000000000000000000000000000 Binary files a/en/readme/figures/en-us_image_0000001053805078.png and /dev/null differ diff --git a/en/readme/figures/en-us_image_0000001054501634.png b/en/readme/figures/en-us_image_0000001054501634.png deleted file mode 100644 index 1be8c087486aae1f25b5687fc2d83f1479e1104d..0000000000000000000000000000000000000000 Binary files a/en/readme/figures/en-us_image_0000001054501634.png and /dev/null differ diff --git a/en/readme/figures/en-us_image_0000001054762887.png b/en/readme/figures/en-us_image_0000001054762887.png deleted file mode 100644 index 7c48bb04154d50efe7c6bdfb6e001093f63379d7..0000000000000000000000000000000000000000 Binary files a/en/readme/figures/en-us_image_0000001054762887.png and /dev/null differ diff --git a/en/readme/figures/en-us_image_0000001054941316.png b/en/readme/figures/en-us_image_0000001054941316.png old mode 100644 new mode 100755 diff --git a/en/readme/figures/en-us_image_0000001055103250.png b/en/readme/figures/en-us_image_0000001055103250.png old mode 100644 new mode 100755 index 1123a2ad54538e66721419518ac33c94a6eaa5d3..62318c44f4eaa6603d911485748dcc008242038f Binary files a/en/readme/figures/en-us_image_0000001055103250.png and b/en/readme/figures/en-us_image_0000001055103250.png differ diff --git a/en/readme/figures/en-us_image_0000001055193731.png b/en/readme/figures/en-us_image_0000001055193731.png deleted file mode 100644 index c4de94624a352170d7924faa71f986e2be16eed5..0000000000000000000000000000000000000000 Binary files a/en/readme/figures/en-us_image_0000001055193731.png and /dev/null differ diff --git a/en/readme/figures/en-us_image_0000001055193837.png b/en/readme/figures/en-us_image_0000001055193837.png deleted file mode 100644 index 576287a860b46bcb21017e8a73cf7f6197320661..0000000000000000000000000000000000000000 Binary files a/en/readme/figures/en-us_image_0000001055193837.png and /dev/null differ diff --git a/en/readme/figures/en-us_image_0000001055267336.png b/en/readme/figures/en-us_image_0000001055267336.png old mode 100644 new mode 100755 diff --git a/en/readme/figures/en-us_image_0000001055712348.png b/en/readme/figures/en-us_image_0000001055712348.png deleted file mode 100644 index fa3b3160f094a3dddfa8d46047dfc9da2bb96fcc..0000000000000000000000000000000000000000 Binary files a/en/readme/figures/en-us_image_0000001055712348.png and /dev/null differ diff --git a/en/readme/figures/en-us_image_0000001106694563.png b/en/readme/figures/en-us_image_0000001106694563.png new file mode 100755 index 0000000000000000000000000000000000000000..bb4c2bd03c68110938949d4d1f2bd63f4a21de34 Binary files /dev/null and b/en/readme/figures/en-us_image_0000001106694563.png differ diff --git a/en/readme/figures/en-us_image_0000001130109907.png b/en/readme/figures/en-us_image_0000001130109907.png new file mode 100755 index 0000000000000000000000000000000000000000..b456b1b6a5411799781f37b5c67a51d4c3fea981 Binary files /dev/null and b/en/readme/figures/en-us_image_0000001130109907.png differ diff --git a/en/readme/figures/en-us_image_0000001130297625.png b/en/readme/figures/en-us_image_0000001130297625.png new file mode 100755 index 0000000000000000000000000000000000000000..e6b94cdee5de58a7c19c40acbc747e9daf9bff3e Binary files /dev/null and b/en/readme/figures/en-us_image_0000001130297625.png differ diff --git a/en/readme/figures/framework-architecture.png b/en/readme/figures/framework-architecture.png new file mode 100755 index 0000000000000000000000000000000000000000..3230a1b3cb5e49bddb065762da629e47a66cbbc0 Binary files /dev/null and b/en/readme/figures/framework-architecture.png differ diff --git a/en/readme/figures/interaction-between-the-driver-and-framework.png b/en/readme/figures/interaction-between-the-driver-and-framework.png new file mode 100755 index 0000000000000000000000000000000000000000..c3abddf08655433ba029bee664e29e4f6562b15f Binary files /dev/null and b/en/readme/figures/interaction-between-the-driver-and-framework.png differ diff --git a/en/readme/figures/js-framework.png b/en/readme/figures/js-framework.png deleted file mode 100644 index f39aa861bcad95e8e7917ddc5688216956c7ca72..0000000000000000000000000000000000000000 Binary files a/en/readme/figures/js-framework.png and /dev/null differ diff --git a/en/readme/figures/lifecycle-state-transition-of-a-page-ability.png b/en/readme/figures/lifecycle-state-transition-of-a-page-ability.png old mode 100644 new mode 100755 diff --git a/en/readme/figures/relationship-between-a-page-ability-and-its-ability-slices.gif b/en/readme/figures/relationship-between-a-page-ability-and-its-ability-slices.gif old mode 100644 new mode 100755 index dd5af6fa52800c0d7fad7dbc8ae6e21149ae9897..783f02fe2b93203d093dea385c69682cbde62808 Binary files a/en/readme/figures/relationship-between-a-page-ability-and-its-ability-slices.gif and b/en/readme/figures/relationship-between-a-page-ability-and-its-ability-slices.gif differ diff --git a/en/readme/figures/service-flow.png b/en/readme/figures/service-flow.png new file mode 100755 index 0000000000000000000000000000000000000000..0fac47fbc29296ecdf9078be5e0fa2b6c85617c7 Binary files /dev/null and b/en/readme/figures/service-flow.png differ diff --git a/en/readme/figures/subsystem-architecture.png b/en/readme/figures/subsystem-architecture.png new file mode 100755 index 0000000000000000000000000000000000000000..356a90cd32d5e48960eb6b02c964b761a8d3b380 Binary files /dev/null and b/en/readme/figures/subsystem-architecture.png differ diff --git "a/en/readme/figures/\345\205\250\345\261\200\347\255\226\347\225\2452.png" "b/en/readme/figures/\345\205\250\345\261\200\347\255\226\347\225\2452.png" old mode 100644 new mode 100755 diff --git "a/en/readme/figures/\347\255\226\347\225\245\347\261\273\345\236\2132.png" "b/en/readme/figures/\347\255\226\347\225\245\347\261\273\345\236\2132.png" old mode 100644 new mode 100755 diff --git "a/en/readme/figures/\350\275\273\351\270\277\350\222\231-\345\205\250\347\220\203\345\214\226\345\255\220\347\263\273\347\273\237-\347\263\273\347\273\237\346\236\266\346\236\2043.png" "b/en/readme/figures/\350\275\273\351\270\277\350\222\231-\345\205\250\347\220\203\345\214\226\345\255\220\347\263\273\347\273\237-\347\263\273\347\273\237\346\236\266\346\236\2043.png" new file mode 100755 index 0000000000000000000000000000000000000000..41299d7c0387e9c0b28daf755fc8c7210662cdf4 Binary files /dev/null and "b/en/readme/figures/\350\275\273\351\270\277\350\222\231-\345\205\250\347\220\203\345\214\226\345\255\220\347\263\273\347\273\237-\347\263\273\347\273\237\346\236\266\346\236\2043.png" differ diff --git a/en/readme/globalization-subsystem.md b/en/readme/globalization-subsystem.md deleted file mode 100644 index adbb26a93f8f3b7dcbf16d2cd6f1e1abb25a6d46..0000000000000000000000000000000000000000 --- a/en/readme/globalization-subsystem.md +++ /dev/null @@ -1,18 +0,0 @@ -# Globalization Subsystem - -## Overview - -Users can set the locale regarding about 68 languages and regions on OpenHarmony devices. As the locale settings are synchronized from one OpenHarmony device to another during interconnection, multi-language resource backtracking and multi-language preference support should be taken into account. - -The global resource manager mainly provides the following capabilities: - -- Multi-language resource backtracking: Users in different regions have their own cultural background and use their respective native languages. During resource loading, it is critical to support multi-language locale settings, specifically, to use as few languages as possible to match users' particular cultural background. - -- Multi-language preference support: One of users' multiple preferred languages is selected and displayed for users \(for example, the Swiss\) who have multiple native languages. - -## Repositories Involved - -global\_frameworks\_resmgr\_lite - -global\_interfaces\_innerkits\_resmgr\_lite - diff --git a/en/readme/globalization.md b/en/readme/globalization.md new file mode 100755 index 0000000000000000000000000000000000000000..cba99ea00862ecad021e196ebcf7115a9f3dc1c0 --- /dev/null +++ b/en/readme/globalization.md @@ -0,0 +1,77 @@ +# Globalization + +- [Introduction](#section11516137123416) +- [Architecture](#section8958681672) +- [Directory Structure](#section1121775732114) +- [Constraints](#section43112258019) +- [Repositories Involved](#section5889165803317) + +## Introduction + +If OpenHarmony devices and applications need to be used globally, they must meet the requirements of users in different regions on languages and cultures. The globalization subsystem provides the multi-language and multi-cultural capabilities for global use, including: + +- Resource management + + The subsystem loads, parses, and initializes system and application resources based on device types and system configurations, and provides APIs for obtaining resources such as character strings and images. + + +- Internationalization \(i18n\) + + The subsystem provides the bottom-layer resource backtracking capabilities, with a wide array of i18n APIs for implementing functions such as date/time formatting, number formatting, and singular-plural formatting. + + +## Architecture + +**Figure 1** Architecture of the globalization subsystem + + +![](figures/轻鸿蒙-全球化子系统-系统架构3.png) + +- The resource kit provides the capability of loading built-in resource files for applications and other subsystems. Currently, this capability is not yet open to applications and is used only for other subsystems to obtain framework resources of applications. +- The i18n kit provides i18n APIs for applications and other subsystems to meet the requirements of users in different countries or regions on languages and cultures. Only the date/time, number, and singular-plural formatting capabilities are supported currently. +- The **i18n.dat** file provides cultural data specific to different languages, which ranges from date/time to number, for the i18n framework. + +## Directory Structure + +``` +/base/global/ +├── i18n_lite # Code repository for the i18n framework +│ ├── frameworks # Core code of the i18n framework +│ │ ├── i18n # i18n module +│ │ │ ├── include # Header files +│ │ │ ├── src # Implementation code +│ │ │ └── test # Test cases +│ ├── interfaces # APIs of the i18n framework +│ │ ├── kits # Application APIs +│ │ │ ├── i18n # C/C++ i18n APIs +│ │ │ └── js # C/C++ support for JavaScript APIs +├── resmgr_lite # Code repository for the resource management framework +│ ├── frameworks # Core code of the resource management framework +│ │ ├── resmgr # Core code for resource parsing +│ │ │ ├── include # Header files +│ │ │ └── src # Implementation code +│ ├── interfaces # APIs of the resource management framework +│ │ └── innerkits # APIs of the resource management framework for other subsystems +├── cust_lite # Code repository for the customization framework +│ ├── frameworks # Core code of the customization framework +│ │ ├── cust_lite # Customization framework +│ │ │ ├── src # Implementation code +│ │ │ └── test # Test code +│ ├── interfaces # APIs of the customization framework +│ │ └── innerkits # APIs of the customization framework for other subsystems +``` + +## Constraints + +None + +## Repositories Involved + +Globalization subsystem + +hmf/global/i18n\_lite + +hmf/global/resmgr\_lite + +hmf/global/cust\_lite + diff --git a/en/readme/graphics-subsystem.md b/en/readme/graphics-subsystem.md old mode 100644 new mode 100755 index a42a8dfbab0bf7f4507a8be1d5584be8c0119519..170d0a3844d0e95512dcabccb056cf2af52d499b --- a/en/readme/graphics-subsystem.md +++ b/en/readme/graphics-subsystem.md @@ -1,5 +1,11 @@ # Graphics Subsystem +- [Overview](#section5243712115918) +- [Directory Structure](#section99241319175914) +- [Constraints](#section37625514114) +- [Adding a UI Component](#section266451716115) +- [Repositories Involved](#section78781240113620) + ## Overview The graphics subsystem mainly includes user interface \(UI\) components, layout, animator, font, input event, window management, rendering and drawing modules. It builds an application framework based on the LiteOS to develop applications on Internet of Things \(IoT\) devices with small hardware resources. @@ -15,14 +21,14 @@ Module description: - Input: processes input events. - Display: processes display events. - Render: renders and draws components. -- Draw2d: draws lines, rectangles, circles, arcs, images, and texts, and interconnects with software rendering and hardware acceleration. +- Draw2d: draws lines, rectangles, circles, arcs, images, and texts, and connects to platforms and devices with software rendering and hardware acceleration capabilities. - Surface: applies for and releases shared memory. - Window: manages windows, including creating, showing, hiding a window, and combining windows. -- Adapter: interconnects with underlying interfaces of the adaptation layer. +- Adapter: connects to underlying interfaces of the adaptation layer. ## Directory Structure -**Table 1** Directory structure of source code for the graphics subsystem +**Table 1** Source code directory structure of the graphics subsystem - - -

Directory

@@ -43,7 +49,7 @@ Module description:

frameworks/ui

UI module, which defines functions related to UI components, animators and fonts.

+

UI module, which defines functions related to UI components, animators and fonts

hals

@@ -63,12 +69,12 @@ Module description:

services/ims

Input event management, including processing and distributing input events such as click and press.

+

Input event management, including processing and distributing input events such as click and press

services/wms

Window management, including creating, managing, and combining windows.

+

Window management, including creating, managing, and combining windows

utils

diff --git a/en/readme/intelligent-soft-bus.md b/en/readme/intelligent-soft-bus.md new file mode 100755 index 0000000000000000000000000000000000000000..a5b6812dbcd2f5cea24cac4b11ccdfb40598c6e1 --- /dev/null +++ b/en/readme/intelligent-soft-bus.md @@ -0,0 +1,60 @@ +# Intelligent Soft Bus + +- [Overview](#section11660541593) +- [Directory Structure](#section1464106163817) +- [Constraints](#section1718733212019) +- [Usage](#section167037358130) +- [Repositories Involved](#section4499619123117) + +## Overview + +The use of different communication modes \(such as USB, WLAN, and Bluetooth\) varies greatly and is complex. In addition, the convergence, sharing, and conflicts between communication links cannot be resolved, and communication security is difficult to guarantee. The distributed communication subsystem manages unified distributed communication between near-field devices and provides device discovery and data transmission APIs that apply to all links. Currently, the following features are available: + +- Service publishing: After a service is published, peripheral devices can discover and use it. +- Data transmission: A session is established based on the service name and device ID to transmit data between services. +- Security: Communication data is encrypted. + +You can use APIs of the distributed communication subsystem to implement fast and secure communication between devices without caring about management of communication details, thereby achieving cross-platform development. + +## Directory Structure + +``` +/foundation/communication/softbus_lite/ +├── authmanager # Device authentication mechanism and device knowledge library management +├── discovery # Device discovery based on CoAP +├── os_adapter # OS adaption code +└── trans_service # Authentication and transmission channels +``` + +## Constraints + +**Language**: C + +**Networking**: Devices must be in the same LAN. + +**Operating system**: OpenHarmony + +## Usage + +1. **Device discovery** + +When using device discovery, ensure that the device to perform a discovery and the device to discover are in the same LAN and the devices can receive packets from each other. + +a. After a device sends a discovery request, it uses Constrained Application Protocol \(CoAP\) to send a broadcast packet in the LAN. + +b. The discovered device uses the **PublishService** API to publish services. After receiving the broadcast packet, the device sends a CoAP unicast packet to the device that performs the discovery. + +c. After receiving the packet, the device that performs the discovery updates device information. + +**2. Transmission** + +The soft bus provides unified session-based transmission. Services can receive and send data or obtain basic attributes through **sessionId**. Currently, services can determine whether to accept a received session based on the service requirements and session attributes. Currently, sessions cannot be enabled. + +## Repositories Involved + +communication\_softbus\_lite + +communication\_ipc\_lite + +communication\_wifi\_aware + diff --git a/en/readme/js-application-framework.md b/en/readme/js-application-framework.md old mode 100644 new mode 100755 index 81bd9f7d0e93119f9335bce86b35add69a79f5d0..1a510f9c88f556cab2af057d791d254a6459ef87 --- a/en/readme/js-application-framework.md +++ b/en/readme/js-application-framework.md @@ -1,4 +1,11 @@ -# JS Application Framework +# JS Application Framework + +- [Introduction](#section11660541593) +- [Directory Structure](#section1464106163817) +- [Constraints](#section1718733212019) +- [Using targets](#section1460013282612) +- [Using Runtime-core](#section1460223932718) +- [Repositories Involved](#section11703194974217) ## Introduction @@ -6,25 +13,26 @@ The JS application framework allows you to develop web-like applications across The following figure shows the framework modules. -![](figures/js-framework.png) +**Figure 1** Framework architecture +![](figures/framework-architecture.png "framework-architecture") ## Directory Structure -The source code of the framework is stored in **/foundation/ace**. The following shows the directory structure. +The source code of the framework is stored in **/foundation/ace/ace\_engine\_lite**. The directory structure is as follows. ``` -/foundation/ace -├── frameworks # Framework code -│ └── lite -│ ├── examples # Sample code -│ ├── include # Exposed header files -│ ├── packages # JavaScript implementation -│ ├── src # Source code -│ ├── targets # Configuration file of each target device -│ └── tools # Tool code -├── interfaces # APIs exposed externally -│ └── innerkits # Header files of internal subsystems +/foundation/ace/ace_engine_lite +├── frameworks # Framework code +│ ├── examples # Sample code +│ ├── include # Header files +│ ├── packages # JavaScript implementation +│ ├── src # Source code +│ ├── targets # Configuration files of target devices +│ └── tools # Tool code +├── interfaces # APIs exposed externally +│ └── innerkits # Header files for internal subsystems │ └── builtin # JavaScript third-party module APIs exposed by the JS application framework +└── test # Test cases ``` ## Constraints @@ -58,54 +66,55 @@ The implementation of the JS application framework consists of the following two - Native part: The native part is developed in C++ and is the main body of the framework. - JavaScript part: The JavaScript part supports the runtime environment of JavaScript files, and supports the interaction between the JavaScript runtime and native framework through some global functions or objects exposed to the JavaScript engine. -The framework uses feature macros to customize function code to be compiled on different platforms. The feature macros are stored in header files in **foundation/ace/frameworks/lite/targets**. The directory structure is as follows: +The framework uses feature macros to customize function code to be compiled on different platforms. The feature macros are stored in header files in **foundation/ace/ace\_engine\_lite/frameworks/targets**. The directory structure is as follows: ``` -/foundation/ace/frameworks/lite/targets +/foundation/ace/ace_engine_lite/frameworks/targets ├── default/ │ └── acelite_config.h -├── linux/ # Linux environment configuration files +├── linux/ # Linux environment configuration files │ └── acelite_config.h -├── liteos_a/ # Environment configuration files for LiteOS Cortex-A + ├── liteos_a/ # Environment configuration files for LiteOS Cortex-A │ └── acelite_config.h -├── liteos_m/ # Environment configuration files for LiteOS Cortex-M +├── liteos_m/ # Environment configuration files for LiteOS Cortex-M │ └── acelite_config.h ├── platform_adapter.cpp ├── platform_adapter.h -└── simulator/ # Simulator environment configuration files - └── win/ - └── acelite_config.h* +└── simulator/ # Simulator environment configuration files + ├── acelite_config.h + └── BUILD.gn ``` -Note: Currently only the target compilation for LiteOS Cortex-A is open-source, which is built using Ninja \(BUILD.g\). Other targets such as simulat \(CMake+MingW\), Linux\(Ninja\), and LiteOS Cortex-M \(IAR\) are not completely open and will be gradually released after the adaptation is complete. The following examples describe the role of the **targets** directory in building different targets. +Note: Currently only the target compilation for LiteOS Cortex-A is open-source, which is built using Ninja \(BUILD.gn\). Other targets such as simulator \(CMake+MingW\) and LiteOS Cortex-M \(IAR\) are not completely open and will be gradually released after the adaptation is complete. The following examples describe the role of the **targets** directory in building different targets. -When compiling for different platform targets, use the **acelite\_config.h** file in the corresponding platform directory. You can configure the header file searching path for compilation to locate the file to use. The following takes **ninja** and **cmake** build tools as examples: +When compiling for different platform targets, use the **acelite\_config.h** file in the corresponding platform directory. You can configure the header file searching path for compilation to locate the file to use. The following takes Ninja and CMake build tools as examples: -- **ninja**: +- Ninja ``` if (ohos_kernel_type == "liteos_a" || ohos_kernel_type== "liteos_m" || - ohos_kernel_type == "liteos_riscv") { // Select different header file searching paths based on the target kernel platform. - include_dirs += [ "targets/liteos-a" ] + ohos_kernel_type == "liteos_riscv") { # Select different header file searching paths based on the target kernel platform. + include_dirs += [ "targets/liteos_a" ] } else if (ohos_kernel_type == "linux") { include_dirs += [ "targets/linux" ] } ``` -- **cmake**: +- CMake ``` ...... - set(ACE_LITE_CONFIG_PATH "${CMAKE_CURRENT_SOURCE_DIR}/targets/simulator/win") # Set the simulator search path to targets/simulator/win. + set(ACE_LITE_CONFIG_PATH "${CMAKE_CURRENT_SOURCE_DIR}/targets/simulator") # Set the simulator search path to targets/simulator. + set(ACE_LITE_INNERKITS_PATH "${CMAKE_CURRENT_SOURCE_DIR}/../interfaces/innerkits/builtin") set(JSFWK_INCLUDE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/include") + set(JSFWK_INNERKITS_BUILTIN_PATH "${CMAKE_CURRENT_SOURCE_DIR}/../../../../foundation/ace/ace_engine_lite/interfaces/innerkits/builtin") set(JSFWK_SOURCE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/src/core") - set(UIKIT_PATH "${CMAKE_CURRENT_SOURCE_DIR}/../ui") - set(THIRTY_PATH "${CMAKE_CURRENT_SOURCE_DIR}/../../../third_party") - set(JSFWK_SIMULATOR_PATH "${CMAKE_CURRENT_SOURCE_DIR}/../tools/simulator") - set(JS_API_PATH "${CMAKE_CURRENT_SOURCE_DIR}/../../api/emui_band/MoltenCore/application/framework/ace/api") - set(JSFWK_SIMULATOR_PATH "${CMAKE_CURRENT_SOURCE_DIR}/../tools/simulator") + set(UIKIT_PATH "${CMAKE_CURRENT_SOURCE_DIR}/../../../../foundation/graphic/lite") + set(THIRTY_PATH "${CMAKE_CURRENT_SOURCE_DIR}/../../../../third_party") + set(JSFWK_SIMULATOR_PATH "${CMAKE_CURRENT_SOURCE_DIR}/../../../../tools/developer_tools_lite/graphic_tool/simulator") set(AAFWK_PATH "${CMAKE_CURRENT_SOURCE_DIR}/../../../aafwk") + set(UTILS_PATH "${CMAKE_CURRENT_SOURCE_DIR}/../../../../utils/native/lite") # header files include_directories( @@ -121,14 +130,14 @@ When compiling for different platform targets, use the **acelite\_config.h** f The **acelite\_config.h** file is used to enable or disable the feature macros of different platforms. It can also be used to define constants for shielding platform differences. For example, platform file systems are different, and the names of some fixed directories might be different. These constants can be defined as follows: -- **liteos-a/acelite\_config.h** +- liteos\_a/acelite\_config.h ``` #define JS_FRAMEWORK_PATH "//system/ace/bin/" ``` -- **simulator/win/acelite\_config.h** +- simulator/acelite\_config.h ``` #define JS_FRAMEWORK_PATH "..\\..\\..\\jsfwk\\packages\\runtime-core\\build" @@ -140,32 +149,33 @@ The **acelite\_config.h** file is used to enable or disable the feature macros Runtime-core is a JavaScript-based simple data hijacking framework provided by the JS application framework to implement unidirectional data binding. The directory structure is as follows: ``` -/foundation/ace/frameworks/lite/packages +/foundation/ace/ace_engine_lite/frameworks/packages └── runtime-core - ├── .babelrc # Babel configuration file - ├── .editorconfig # IDE configuration file - ├── .eslintignore # Configuration file of the ESLint tool. You can set a directory or files that will not be scanned by the ESLint tool. - ├── .eslintrc.js # ESLint configuration file for scanning rules + ├── .babelrc # Babel configuration file + ├── contribution.md + ├── .editorconfig # IDE configuration file + ├── .eslintignore # Configuration file of the ESLint tool. You can set a directory or files that will not be scanned by the ESLint tool. + ├── .eslintrc.js # ESLint configuration file for scanning rules ├── .gitignore - ├── package.json # NPM file + ├── package.json # NPM file ├── package-lock.json # NPM dependency lock file - ├── .prettierrc # Configuration file for code formatting rules - ├── scripts # Directory for compilation scripts - │ ├── build.js # Compilation script - │ └── configs.js # Rollup configuration file + ├── .prettierrc # Configuration file for code formatting rules + ├── scripts # Directory for compilation scripts + │ ├── build.js # Compilation script + │ └── configs.js # Rollup configuration file ├── .size-snapshot.json - └── src # Source code - ├── core # ViewModel core implementation code + └── src # Source code + ├── core # ViewModel core implementation code │ └── index.js ├── index.js - ├── observer # Data hijacking implementation code + ├── observer # Data hijacking implementation code │ ├── index.js │ ├── observer.js │ ├── subject.js │ └── utils.js - ├── profiler # profiler directory + ├── profiler # profiler directory │ └── index.js - └── __test__ # Test cases + └── __test__ # Test cases └── index.test.js ``` @@ -177,10 +187,10 @@ The following NPM commands are supported: ``` build/ - ├── framework-dev.js // Framework code used in the development environment (uncompressed and obfuscated) + ├── framework-dev.js // Framework code used in the development environment (uncompressed and obfuscated) ├── framework-dev.min.js // Framework code used in the development environment (compressed and obfuscated) - ├── framework-dev.js // Framework code used in the production environment (uncompressed and obfuscated) - ├── framework-dev.min.js // Framework code used in the production environment (compressed and obfuscated) + ├── framework.js // Framework code used in the production environment (uncompressed and obfuscated) + └── framework.min.js // Framework code used in the production environment (compressed and obfuscated) ``` - **npm run test** @@ -190,6 +200,5 @@ The following NPM commands are supported: ## Repositories Involved -ace\_lite\_jsfwk +ace\_engine\_lite -ace\_interfaces\_innerkits\_builtin diff --git a/en/readme/kernel-subsystem.md b/en/readme/kernel-subsystem.md deleted file mode 100644 index eef0aba845a9f7d693c8af7967e36774b6a6fc72..0000000000000000000000000000000000000000 --- a/en/readme/kernel-subsystem.md +++ /dev/null @@ -1,102 +0,0 @@ -# Kernel Subsystem - -## Overview - -The OpenHarmony kernel is a real-time OS kernel developed by Huawei for IoT devices. It is as lightweight as RTOS and as easy-to-use as Linux. - -The OpenHarmony kernel includes basic kernel functions such as process and thread scheduling, memory management, IPC mechanism, and timer management. - -The source code of the OpenHarmony kernel consists of two repositories: the [`kernel_liteos_a`](https://gitee.com/openharmony/kernel_liteos_a) repository for Cortex-A processors and the [`kernel_liteos_m`](https://gitee.com/openharmony/kernel_liteos_m) repository for Cortex-M processors. The directory structures of the two repositories are similar. The following describes the directory structure of kernel_liteos_a. - -## Directory Structure - -**Table 1** Directory structure of the OpenHarmony kernel source code - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Directory

-

Description

-

apps

-

User-space init and shell application program

-

arch

-

System architecture, such as ARM

-

bsd

-

Code of the driver and adaptation layer module related to the FreeBSD, such as the USB module

-

compat

-

Compatibility with the kernel POSIX interfaces

-

fs

-

File system module, which mainly derives from the NuttX open-source project

-

kernel

-

Kernel modules including the process, memory, and IPC modules

-

lib

-

Kernel library

-

net

-

Network module, which mainly derives from the lwip open-source project

-

platform

-

Code for supporting different systems on a chip (SOCs), such as Hi3516DV300

-

security

-

Code related to security features, including process permission management and virtual ID mapping management

-

syscall

-

System calls

-

tools

-

Building tool as well as related configuration and code

-
- -## Constraints - -Hi3518EV300 uses the JFFS2 file system by default, and Hi3516DV300 uses the VFAT file system by default. If other file systems need to be used, the configurations of the file systems must be added accordingly. - -## Usage - -For details, see [Kernel Usage Guidelines](../kernel/Readme-EN.md). - -## Repositories Involved - -[drivers_liteos](https://gitee.com/openharmony/drivers_liteos) - -[kernel_liteos_a](https://gitee.com/openharmony/kernel_liteos_a) - -[kernel_liteos_a_huawei_proprietary_fs_proc](https://gitee.com/openharmony/kernel_liteos_a_huawei_proprietary_fs_proc) - -[kernel_liteos_m](https://gitee.com/openharmony/kernel_liteos_m) - diff --git a/en/readme/kernel.md b/en/readme/kernel.md new file mode 100755 index 0000000000000000000000000000000000000000..6270e4d17842b2c3006c937e74d3939c856c58cb --- /dev/null +++ b/en/readme/kernel.md @@ -0,0 +1,79 @@ +# Kernel + +- [Overview](#section12995104752113) +- [Directory Structure](#section1121775732114) +- [Constraints](#section1967115154223) +- [Usage](#section1821123352217) +- [Repositories Involved](#section2392425183215) + +## Overview + +The OpenHarmony kernel is a real-time OS kernel developed for IoT devices. It is as lightweight as the real-time operating system \(RTOS\) and as easy-to-use as Linux. + +The OpenHarmony kernel provides basic kernel functions such as process and thread scheduling, memory management, inter-process communication \(IPC\) mechanism, and timer management. + +The source code of the OpenHarmony kernel consists of two repositories: the **kernel\_liteos\_a** repository for standard devices and the **kernel\_liteos\_m** repository for tiny and mini devices. The following describes the **kernel\_liteos\_a** repository. [Figure1](#fig115631528152315) shows the architecture of the LiteOS Cortex-A kernel. + +**Figure 1** Architecture of the OpenHarmony LiteOS Cortex-A kernel +![](figures/architecture-of-the-openharmony-liteos-cortex-a-kernel.png "architecture-of-the-openharmony-liteos-cortex-a-kernel") + +## Directory Structure + +``` +/kernel/liteos_a +├── apps # User-space init and shell application programs +├── arch # System architecture, such as ARM +│ └── arm # Code for ARM architecture +├── bsd # Code of the driver and adaptation layer module related to the FreeBSD, such as the USB module +├── compat # Kernel API compatibility +│ └── posix # POSIX APIs +├── drivers # Kernel drivers +│ └── char # Character device +│ ├── mem # Driver for accessing physical input/output (I/O) devices +│ ├── quickstart # APIs for quick start of the system +│ ├── random # Driver for random number generators +│ └── video # Framework of the framebuffer driver +├── fs # File system module, which mainly derives from the NuttX open-source project +│ ├── fat # FAT file system +│ ├── jffs2 # JFFS2 file system +│ ├── include # Header files exposed externally +│ ├── nfs # NFS file system +│ ├── proc # proc file system +│ ├── ramfs # RAMFS file system +│ └── vfs # VFS layer +├── kernel # Kernel modules including the process, memory, and IPC modules +│ ├── base # Basic kernel modules including the scheduling and memory modules +│ ├── common # Common components used by the kernel +│ ├── extended # Extended kernel modules including the dynamic loading, vDSO, and LiteIPC modules +│ ├── include # Header files exposed externally +│ └── user # Init process loading +├── lib # Kernel library +├── net # Network module, which mainly derives from the lwIP open-source project +├── platform # Code for supporting different systems on a chip (SOCs), such as Hi3516D V300 +│ ├── hw # Logic code related to clocks and interrupts +│ ├── include # Header files exposed externally +│ └── uart # Logic code related to the serial port +├── platform # Code for supporting different systems on a chip (SOCs), such as Hi3516D V300 +├── security # Code related to security features, including process permission management and virtual ID mapping management +├── syscall # System calling +└── tools # Building tools as well as related configuration and code +``` + +## Constraints + +Hi3518E V300 uses the JFFS2 file system by default, and Hi3516D V300 uses the VFAT file system by default. If other file systems need to be used, the configurations of the file systems must be added accordingly. + +## Usage + +For details, see the **Usage** section of _LiteOS Cortex-A_ and _LiteOS Cortex-M_ + +## Repositories Involved + +Kernel subsystem + +drivers\_liteos + +kernel\_liteos\_a + +kernel\_liteos\_m + diff --git a/en/readme/lite-power-management.md b/en/readme/lite-power-management.md new file mode 100755 index 0000000000000000000000000000000000000000..805b9fdaac00769d6d9d5af31816abbc46fbc8db --- /dev/null +++ b/en/readme/lite-power-management.md @@ -0,0 +1,34 @@ +# Lite Power Management + +- [Introduction](#section11660541593) +- [Directory Structure](#section19472752217) +- [Repositories Involved](#section63151229062) + +## Introduction + +The lite power management subsystem provides the following capabilities: + +1. Querying the battery level +2. Keeping the device screen always on using a lock + +**Figure 1** Lite power management subsystem architecture + + +![](figures/en-us_image_0000001130297625.png) + +## Directory Structure + +``` +base/powermgr/powermgr_lite +├── interfaces # APIs +│ └── kits +│ └── battery # API for querying the battery level +└── services # Services + ├── include + └── source +``` + +## Repositories Involved + +**hmf/powermgr/powermgr\_lite** + diff --git a/en/readme/liteipc_driver.md b/en/readme/liteipc_driver.md deleted file mode 100644 index 7d12e75a7697a30e965b8b537c257774b18f1949..0000000000000000000000000000000000000000 --- a/en/readme/liteipc_driver.md +++ /dev/null @@ -1,185 +0,0 @@ -# LiteIPC driver - -## Overview -LiteIPC is a HarmonyOS extension to the LiteOS(a) kernel which provides a means for processes on the same device to communicate with each other. It is a somewhat higher level mechanism than POSIX IPC methods such as message queues or shared memory, providing automatic management of resources used for IPC and control of access rights to send messages to other processes. IPC messages are exchanged between tasks. An IPC service is a task which has been set up to receive request type messages. Access rights are granted to processes, if a process has access to a service then all tasks in the process are able to send requests to the service. - -## API -*Application-layer Interface* -//foundation/communication/frameworks/ipc_lite/liteipc/include/liteipc.h -//foundation/communication/interfaces/kits/ipc_lite/liteipc_adapter.h - -*Implementation* -//kernel/liteos_a/kernel/extended/liteipc/hm_liteipc.h -//kernel/liteos_a/kernel/extended/liteipc/hm_liteipc.c - -`LITEIPC_DRIVER` specifies the name of the character device used to communicate with the LiteIPC driver (currently /dev/lite_ipc). - -Memory mapping allocates a memory area for storing messages received by the process' tasks. ioctl calls to the driver before it has been memory mapped return with error **ENOMEM**. - -The IpcMsg structure is the basic unit of transaction for LiteIPC. -| Member | Type | Description | -| --------- | ----------- | ----------- | -| type | MsgType | The message's type. It can be one of the following values **MT_REQUEST**, **MT_REPLY**, **MT_FAILED_REPLY**, **MT_DEATH_NOTIFY**. | -| target | SvcIdentity | Specifies the message's recipient. | -| flag | IpcFlag | Indicates whether the message can be replied to or is one-way. It can be one of the following values **LITEIPC_FLAG_DEFAULT**, **LITEIPC_FLAG_ONEWAY**. | -| dataSz | UINT32 | The size of the message data in bytes pointed to by data (cannot exceed IPC_MSG_DATA_SZ_MAX, currently 1024 bytes). | -| data | void* | Pointer to the message data. | -| spObjNum | UINT32 | The number of special objects contained in the message data (cannot exceed IPC_MSG_OBJECT_NUM_MAX). | -| offsets | void* | An array of offsets relative to data pointing to SpecialObj special objects in data. | -| code | UINT32 | Service function code. | -| timestamp | UINT64 | Timestamp for when the message was sent. Automatically set by the IPC system for requests and death notifications. | -| taskID | UINT32 | Specifies the message's sender. Automatically set by the IPC system. | -| processID | UINT32 | Additional information on the message's sender. Automatically set by the IPC system. | - -SpecialObj -| Member | Type | Description | -| ------- | ---------- | ----------- | -| type | ObjType | The type of special object. It can be one of the following values **OBJ_FD**, **OBJ_PTR**, **OBJ_SVC**. | -| content | ObjContent | The special object. | - -ObjContent -| SpecialObj type | Member | Type | Description | -| --------------- | ------ | ----------- | ----------- | -| OBJ_FD | fd | UINT32 | Currently does nothing. | -| OBJ_PTR | ptr | BuffPtr | Auxiliary data to be sent (not limited by IPC_MSG_DATA_SZ_MAX). | -| OBJ_SVC | svc | SvcIdentity | A service to give the recipient permission to send requests to. | - -`IPC_SEND_RECV_MSG` is the primary request which provides the ability to send and receive IpcMsg messages as well as free memory used by unneeded messages. Its argument is a pointer to an IpcContent structure. - -IpcContent -| Member | Type | Description | -| ---------- | ----------- | ----------- | -| flag | UINT32 | Specifies the operation(s) to be performed. It is the bitwise-or of one or more of the following flags **SEND**, **RECV**, **BUFF_FREE**. | -| outMsg | IpcMsg* | Points to a message to be sent. | -| inMsg | IpcMsg* | Points to a message that has been received. | -| buffToFree | void* | Points to IPC memory to be freed (a previously received message which is no longer needed). | - -- The **SEND** flag indicates a request to send outMsg. Returns with error **EINVAL** if any member of the message has been given an invalid value. - - Sending a message with type **MT_REQUEST** returns with error **EACCES** if the task doesn't have access rights to the recipient, and **EINVAL** for an invalid recipient. All tasks have access rights to the CMS (see IPC_SET_CMS), and to their own process' IPC services. - - Sending a message with type **MT_REPLY** or **MT_FAILED_REPLY** returns with error **EINVAL** if any of the following are not satisifed: - - buffToFree must point at the message being replied to and the **BUFF_FREE** flag must be set. - - The outMsg recipient (target.handle) must match the buffToFree sender (taskID). - - The outMsg and buffToFree timestamps must match. - - buffToFree must be a **MT_REQUEST** type message and cannot be marked as **LITEIPC_FLAG_ONEWAY**. - - buffToFree must be addressed to a service of the current process. - - Trying to reply to a message sent more than LITEIPC_TIMEOUT_NS nanoseconds ago (currently 5 seconds) returns with error **ETIME**. - - The message is copied into memory allocated from the IPC memory area of the process for the recipient task specified by target.handle. Returns with error **ENOMEM** if the memory cannot be allocated. Special objects in offsets are then processed. **OBJ_PTR** objects' data is copied into memory allocated from the recipient's IPC memory area, discards the message and returns with error **EINVAL** if unable to allocate enough memory. **OBJ_SVC** objects grant the recipient access rights to the service specified by the object if the sender already has access and the service is set as an IPC task (see IPC_SET_IPC_THREAD), discards the message and returns with error **EACCES** if the sender doesn't have access or **EINVAL** if the service isn't running. Access rights are not revokable, on error any access rights granted before the special object which caused the error will remain. The message is then added to the tail end of the recipient's list of received messages, the recipient is woken and the scheduler is called. -- The **BUFF_FREE** flag indicates a request to free the memory used by the buffToFree message so it can be used again later for receiving messages. Returns with error **EFAULT** if buffToFree doesn't point to a received message. Returns with error **EINVAL** if an invalid address. -- The **RECV** flag indicates a request to receive a message. - - If the **SEND** flag is set the task will wait for a message for up to LITEIPC_TIMEOUT_MS milliseconds (currently 5 seconds). Returns with error **ETIME** on timeout. Messages with a type of **MT_REQUEST** and **MT_REPLY** or **MT_FAILED_REPLY** type messages which don't match outMsg (matching timestamp or matching code and target.token depending on kernel configuration) are discarded (resets timer). Sets inMsg to point at the received message and removes it from the list of received messages for **MT_REPLY** or **MT_DEATH_NOTIFY** type messages. Note that receiving a **MT_DEATH_NOTIFY** makes it impossible to receive the reply so send/receive requests shouldn't be used by services which might receive death notifications. Discards the message and returns with error **ENOENT** without changing inMsg if the received message has type **MT_FAILED_REPLY**. - - If the **SEND** flag is not set, the task will sleep until a message with type **MT_REQUEST** or **MT_DEATH_NOTIFY** is received. Sets inMsg to point at the received message, and removes the message from its list of received messages. Discards **MT_REPLY** or **MT_FAILED_REPLY** type messages received while waiting. - -For a single request the operations are processed in the order **SEND**->**BUFF_FREE**->**RECV** with **BUFF_FREE** being processed even if there was an error in **SEND**. Error checking on buffToFree occurs before **SEND**, an error in buffToFree will abort the request without doing anything. - -The `IPC_SET_IPC_THREAD` request designates the current task as the IPC task for the current process. It can only be performed once per process. Returns the ID of the task set as IPC task on success, subsequent calls return with error **EINVAL**. The IPC task receives the death notifications from IPC services the process has access rights to when those services terminate. A service which has been set as IPC task can have access rights to itself distributed through special objects without using the CMS. - -IPC_SEND_RECV_MSG and IPC_SET_IPC_THREAD both return with error **EINVAL** if the CMS has not been set. - -### Internal functions -The first task to use the `IPC_SET_CMS` request sets itself as the system's CMS. HarmonyOS assigns this role to the distributed scheduler's samgr. Once set it cannot be changed. Returns with error **EEXIST** if the CMS has already been set. Messages are sent to the CMS by setting a recipient handle of 0. The argument to the request specifies the maximum size of a message sent to the CMS. Sending a message whose total size including IpcMsg data structure, data size, size of special object offsets, and data in any BuffPtr special objects exceeds the maximum size (currently 256 bytes) returns with error **EINVAL**. - -The `IPC_CMS_CMD` request provides various service related utility functions to the CMS. It can only be used by the CMS, any other task making this request will get an **EACCES** error. The argument to the request is a pointer to a CmsCmdContent structure. The cmd member indicates the function to be performed. -- **CMS_GEN_HANDLE** creates a service handle for the task specified by taskID member and stores the handle in the serviceHandle member. The CMS always has access rights to any created IPC services. -- **CMS_REMOVE_HANDLE** unregisters the service handle specified by the serviceHandle member. -- **CMS_ADD_ACCESS** gives the task specified by the taskID member access rights to the service specified by the serviceHandle member. - -LiteIPC includes utility functions for the kernel to manage the IPC system. -`LiteIpcInit` initializes the IPC system and must be called before it can be used. -`LiteIpcPoolInit` performs basic initialization of a ProcIpcInfo. Called by the kernel on task creation to initialize the IPC variables in the task's control block. -`LiteIpcPoolReInit` initializes the IPC variables of a child task from it's parent's task. Called by the kernel on the creation of child tasks for basic initialization. -`LiteIpcPoolDelete` removes a process' IPC memory pool allocated by memory mapping and all the process' access rights. Called by the kernel on process deletion for automatic memory and IPC resource management. -`LiteIpcRemoveServiceHandle` deregisters a service, clearing out the service task's message list and the list of processes with access rights to the service and sending death notification messages to any services with a set IPC task which had access. Death notification messages are only sent once, if there is an error in the send (**ENOMEM**) the recipient will not get the death notification. Death notification messages set target.token to the sevice handle of the service which terminated. Called by the kernel on task deletion for automatic IPC resource management. - -### Sample code -1. Initialization before we can use LiteIPC. - ``` - #include "liteipc_adapter.h" - #include "liteipc.h" - - int fd = open(LITEIPC_DRIVER, O_RDONLY); - mmap(NULL, 10000, PROT_READ, MAP_PRIVATE, fd, 0); - ``` - -2. Send a message to the CMS. For simplicity let's say we have a primitive CMS which simply gives us access to and returns the handle of the service named in the request we send to it. - ``` - #define SVCNAME "wakeup service" - IpcMsg msg = { - .type = MT_REQUEST, - .target = { 0, 0, 0 }, - .flag = LITEIPC_FLAG_DEFAULT, - .dataSz = sizeof(SVCNAME), - .data = SVCNAME, - .spObjNum = 0, - .offsets = NULL - }; - IpcContent content = { - .flag = SEND | RECV, - .outMsg = &msg - }; - - // Send a message to the CMS - if (ioctl(fd, IPC_SEND_RECV_MSG, &content) < 0) { - goto ERROR; - } - ``` - -3. Set our IPC task and send a message to the wakeup service. - ``` - // Set ourselves as IPC task so we can distribute access on our own - int myId = ioctl(fd, IPC_SET_IPC_THREAD, 0); - - struct { - char summary[20]; - SpecialObj command; - SpecialObj svc; - } wakeupData = { - .summary = "one wakeup" - }; - char commandStr[100] = "Wake me up at 9:00 in the morning."; - void* wakeupOffsets[2] = { - (void*)((uintptr_t)&wakeupData.command - (uintptr_t)&wakeupData), - (void*)((uintptr_t)&wakeupData.svc - (uintptr_t)&wakeupData) - }; - - // Send a request to the wakeup service and free the CMS's reply - content.flag = SEND | BUFF_FREE; - content.buffToFree = content.inMsg; - msg.type = MT_REQUEST; - // Set the recipient from the CMS' reply - msg.target.handle = *(uint32_t*)content.inMsg->data; - // Add the auxiliary data. - wakeupData.command.type = OBJ_PTR; - wakeupData.command.content.ptr.buffSz = sizeof(commandStr); - wakeupData.command.content.ptr.buff = commandStr; - // Give the wakeup service access to send us requests. - wakeupData.svc.type = OBJ_SVC; - wakeupData.svc.content.svc.handle = myId; - // Complete the message and send it. - msg.data = &wakeupData; - msg.dataSz = sizeof(wakeupData); - msg.offsets = wakeupOffsets; - msg.spObjNum = 2; - if (ioctl(fd, IPC_SEND_RECV_MSG, &content) < 0) { - goto ERROR; - } - ``` - -4. Wait for wakeup and process the wakeup message. - ``` - // Enter "server" mode, wait for the service to wake us up. - content.flag = RECV; - ioctl(fd, IPC_SEND_RECV_MSG, &content); - - // Free the received message - content.flag = BUFF_FREE; - content.buffToFree = content.inMsg; - ioctl(fd, IPC_SEND_RECV_MSG, &content); - ``` - -5. LiteIPC automatically cleans up our IPC resources when we exit, but closing the file descriptor when we're done using it is a good habit. - ``` - ERROR: - close(fd); - ``` diff --git a/en/readme/media-subsystem.md b/en/readme/multimedia.md old mode 100644 new mode 100755 similarity index 52% rename from en/readme/media-subsystem.md rename to en/readme/multimedia.md index d201b0d76516a02f3c223edd74b164cadab1a4cb..f23d3bbd45dffd87ea56a789eebcc616cb123e9b --- a/en/readme/media-subsystem.md +++ b/en/readme/multimedia.md @@ -1,113 +1,121 @@ -# Multimedia Subsystem +# Multimedia -## Overview +- [Introduction](#section38510214395) +- [Directory Structure](#section1937963913399) +- [Constraints](#section722512541395) +- [Installation](#section11914418405) +- [Usage Guidelines](#section1467220266400) +- [Repositories Involved](#section7666411192217) + +## Introduction This repository stores source code information of the multimedia subsystem. It provides unified interfaces for you to develop media applications. With this repository, you can easily obtain media resources and focus on service development. The following two figures show the framework and service flow of the multimedia subsystem, respectively. -**Figure 1** Subsystem architecture -![](figures/en-us_image_0000001055193837.png "subsystem-architecture") +**Figure 1** Subsystem architecture +![](figures/subsystem-architecture.png "subsystem-architecture") + +The multimedia framework supports the camera, recording, and playback functions. These functions support the development of JavaScript applications and various kit modules that use media capabilities. + +The multimedia framework includes the framework and system service layers. -As shown in Figure 1, the multimedia framework supports the camera, recording, and playback functions. These functions support the development of HarmonyOS JavaScript applications and various kit modules that use media capabilities. The multimedia framework consists of the framework and core service layers. The framework layer provides native APIs and corresponding service implementation for applications. It implements audio/video input and output, audio/video encoding and decoding, as well as video file packing and demultiplexing for camera, recording, and playback services. The core service layer leverages the capabilities provided by the hardware platform to use the underlying hardware and related drivers. In addition, the core server implements file management, storage management, and log management. +- The framework layer provides native APIs and corresponding service implementation for applications. It implements audio/video input and output, audio/video encoding and decoding, as well as video file packing and demultiplexing for camera, recording, and playback services. +- The system service layer uses the platform capabilities to invoke underlying hardware and related drivers. -**Figure 2** Multimedia service flow -![](figures/en-us_image_0000001055193731.png "multimedia-service-flow") +**Figure 2** Service flow +![](figures/service-flow.png "service-flow") -As shown in Figure 2, the multimedia subsystem consists of camera, recorder, and player modules. The camera module provides YUV or RGB, JPEG, and H.264 or H.265 data, which is stored in the surface \(shared memory\); the recorder module packs H.264 or H.265 and AAC data in the surface into MP4 files; the player module demultiplexes the MP4 files into audio and video data, sends the data to corresponding decoders, and then plays the audio and video. +The multimedia subsystem includes camera, recorder, and player modules. The camera module provides YUV or RGB, JPEG, and H.264 or H.265 data, which is stored in the surface \(shared memory\); the recorder module packs H.264 or H.265 and AAC data in the surface into MP4 files; the player module demultiplexes the MP4 files into audio and video data, sends the data to corresponding decoders, and then plays the audio and video. ## Directory Structure -**Table 1** Directory structure of multimedia source code \(native APIs\) - - - - - - - - - - - - - - - - - - - - - - -

Directory

-

Description

-

foundation/multimedia/frameworks

-

Internal framework implementation, including Audio, Camera, Player, and Recorder.

-

foundation/multimedia/interfaces/kits

-

External header files

-

foundation/multimedia/services/media_lite

-

Underlying service implementation

-

foundation/multimedia/utils/lite

-

Common module implementation

-

foundation/multimedia/hals

-

Header files of multimedia adaptation APIs related to the hardware platform

-
+The directory structure of the source code is as follows \(only the main part is listed\): + +``` +foundation/multimedia # Main directory +├── audio_lite +│ ├── frameworks # Implementation of the audio module +│ └── interfaces # Definition of audio module APIs +├── camera_lite +│ ├── frameworks # Implementation of the camera module +│ └── interfaces # Definition of camera module APIs +├── media_lite +│ ├── frameworks +│ │ ├── player_lite # Implementation of the player module +│ │ └── recorder_lite # Implementation of the recorder module +│ └── interfaces +│ │ └── kits +│ │ ├── player_lite # Implementation of player module APIs +│ │ ├── recorder_lite # Implementation of recorder module APIs +│ ├── services # Code for starting the media service +│ └── test # Test code +└── utils + └── lite # Implementation of common module APIs + └── hals # Header file declaring media adaptation APIs +``` ## Constraints -- C++11 or later -- Hi3516DV300 and Hi3518EV300 are supported, and only Hi3516DV300 supports the playback function. -- By default, Hi3516DV300 supports Sony IMX335, and Hi3518EV300 supports crystalline phase JXF23. +- C++ 11 or later ## Installation - Load the kernel and related drivers before installing the repository. For details, see readme files of kernel and driver subsystems. - Configure a proper configuration file. For details, see the configuration file in **applications/sample/camera/media** directory. If you want to adapt to other sensors, seek help from the open source community. Ensure that the configuration file is stored in the **/storage/data** directory of the development board in use. You can use this configuration file to adapt to the sensor, resolution, and frame rate. -## Usage +## Usage Guidelines For details about how to call native APIs, see the demo in the **applications/sample/camera/media** directory. For details about how to call multimedia APIs to implement the video recording, preview, and playback, see _Multimedia Development Guide_. -The following example overrides the event class: - Create a **CameraKit** object and register various callbacks to respond to many events in the media module. Then, create a **Camera** object to operate camera resources, for example, to start preview, recording, and stream capturing, and set related parameters. -``` -/* - * Copyright (c) 2020 Huawei Device Co., Ltd. - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ +The following example code overrides the event callbacks: +``` #include "camera_kit.h" #include "recorder.h" -#include #include +#include +#include #include #include #include +#include +#include +#include +#include using namespace std; using namespace OHOS; using namespace OHOS::Media; +static int32_t SampleGetRecordFd() +{ + struct timeval tv = {}; + gettimeofday(&tv, nullptr); + struct tm *ltm = localtime(&tv.tv_sec); + int32_t fd = -1; + if (ltm != nullptr) { + ostringstream ss("Capture_"); + ss << "Record" << ltm->tm_hour << "-" << ltm->tm_min << "-" << ltm->tm_sec << ".mp4"; + fd = open(("/sdcard/" + ss.str()).c_str(), O_RDWR | O_CREAT, S_IRUSR | S_IWUSR); + cout << "Open " + << "/sdcard/" << ss.str() << endl; + + if (fd == -1) { + cout << "Failed to open the recorder file. strerr=" << strerror(errno) << endl; + } + } + return fd; +} + static void SampleSaveCapture(const char *p, uint32_t size) { - cout << "Start saving picture" << endl; - struct timeval tv; - gettimeofday(&tv, NULL); + cout << "Picture saving starts." << endl; + struct timeval tv = {}; + gettimeofday(&tv, nullptr); struct tm *ltm = localtime(&tv.tv_sec); if (ltm != nullptr) { ostringstream ss("Capture_"); @@ -116,7 +124,8 @@ static void SampleSaveCapture(const char *p, uint32_t size) ofstream pic("/sdcard/" + ss.str(), ofstream::out | ofstream::trunc); cout << "write " << size << " bytes" << endl; pic.write(p, size); - cout << "Saving picture end" << endl; + pic.close(); + cout << "Saving picture complete." << endl; } } @@ -130,7 +139,7 @@ Recorder *SampleCreateRecorder() int32_t audioEncodingBitRate = sampleRate; VideoSourceType source = VIDEO_SOURCE_SURFACE_ES; int32_t frameRate = 30; - float fps = 30; + double fps = 30; int32_t rate = 4096; int32_t sourceId = 0; int32_t audioSourceId = 0; @@ -143,66 +152,63 @@ Recorder *SampleCreateRecorder() Recorder *recorder = new Recorder(); if ((ret = recorder->SetVideoSource(source, sourceId)) != SUCCESS) { cout << "SetVideoSource failed." << ret << endl; - delete recorder; - return nullptr; + goto ERROR; } if ((ret = recorder->SetVideoEncoder(sourceId, encoder)) != SUCCESS) { cout << "SetVideoEncoder failed." << ret << endl; - delete recorder; - return nullptr; + goto ERROR; } if ((ret = recorder->SetVideoSize(sourceId, width, height)) != SUCCESS) { cout << "SetVideoSize failed." << ret << endl; - delete recorder; - return nullptr; + goto ERROR; } if ((ret = recorder->SetVideoFrameRate(sourceId, frameRate)) != SUCCESS) { cout << "SetVideoFrameRate failed." << ret << endl; - delete recorder; - return nullptr; + goto ERROR; } if ((ret = recorder->SetVideoEncodingBitRate(sourceId, rate)) != SUCCESS) { cout << "SetVideoEncodingBitRate failed." << ret << endl; - delete recorder; - return nullptr; + goto ERROR; } - if ((ret = recorder->SetCaptureRate(sourceId, frameRate)) != SUCCESS) { + if ((ret = recorder->SetCaptureRate(sourceId, fps)) != SUCCESS) { cout << "SetCaptureRate failed." << ret << endl; - delete recorder; - return nullptr; + goto ERROR; } if ((ret = recorder->SetAudioSource(inputSource, audioSourceId)) != SUCCESS) { cout << "SetAudioSource failed." << ret << endl; - delete recorder; - return nullptr; + goto ERROR; } if ((ret = recorder->SetAudioEncoder(audioSourceId, audioFormat)) != SUCCESS) { cout << "SetAudioEncoder failed." << ret << endl; - delete recorder; - return nullptr; + goto ERROR; } if ((ret = recorder->SetAudioSampleRate(audioSourceId, sampleRate)) != SUCCESS) { cout << "SetAudioSampleRate failed." << ret << endl; - delete recorder; - return nullptr; + goto ERROR; } if ((ret = recorder->SetAudioChannels(audioSourceId, channelCount)) != SUCCESS) { cout << "SetAudioChannels failed." << ret << endl; - delete recorder; - return nullptr; + goto ERROR; } if ((ret = recorder->SetAudioEncodingBitRate(audioSourceId, audioEncodingBitRate)) != SUCCESS) { cout << "SetAudioEncodingBitRate failed." << ret << endl; - delete recorder; - return nullptr; + goto ERROR; + } + if ((ret = recorder->SetMaxDuration(36000)) != SUCCESS) { // 36000s=10h + cout << "SetAudioEncodingBitRate failed." << ret << endl; + goto ERROR; } return recorder; + +ERROR: + delete recorder; + return nullptr; } class SampleFrameStateCallback : public FrameStateCallback { void OnFrameFinished(Camera &camera, FrameConfig &fc, FrameResult &result) override { - cout << "Receive frame complete inform." << endl; + cout << "Receive complete frame information." << endl; if (fc.GetFrameConfigType() == FRAME_CONFIG_CAPTURE) { cout << "Capture frame received." << endl; list surfaceList = fc.GetSurfaces(); @@ -217,8 +223,8 @@ class SampleFrameStateCallback : public FrameStateCallback { } delete surface; } - delete &fc; } + delete &fc; } }; @@ -228,14 +234,11 @@ public: SampleCameraStateMng(EventHandler &eventHdlr) : eventHdlr_(eventHdlr) {} ~SampleCameraStateMng() { - if (recorder_ != nullptr) { - recorder_->Release(); - delete recorder_; - } + CloseRecorder(); } void OnCreated(Camera &c) override { - cout << "Sample recv OnCreate camera." << endl; + cout << "Receive information upon camera creation." << endl; auto config = CameraConfig::CreateCameraConfig(); config->SetFrameStateCallback(&fsCb_, &eventHdlr_); c.Configure(*config); @@ -244,56 +247,98 @@ public: void OnCreateFailed(const std::string cameraId, int32_t errorCode) override {} void OnReleased(Camera &c) override {} - void StartRecord() + void CloseRecorder() { - int ret; - if (isRecording_) { - cout << "Camera is already recording." << endl; - return; + if (recorder_ != nullptr) { + recorder_->Stop(true); + recorder_->Release(); + delete recorder_; + recorder_ = nullptr; + } + if (recordFd_ != -1) { + close(recordFd_); + recordFd_ = -1; + } + } + + int PrepareRecorder() + { + if (cam_ == nullptr) { + cout << "The camera is not ready." << endl; + return -1; } if (recorder_ == nullptr) { recorder_ = SampleCreateRecorder(); } if (recorder_ == nullptr) { - cout << "Recorder not available" << endl; + cout << "The recorder is not available." << endl; + return -1; + } + if (recordFd_ == -1) { + recordFd_ = SampleGetRecordFd(); + } + if (recordFd_ == -1) { + cout << "Failed to create the file descriptor." << endl; + return -1; + } + return SUCCESS; + } + + void StartRecord() + { + if (recordState_ == STATE_RUNNING) { + cout << "The camera is recording." << endl; + return; + } + int ret = PrepareRecorder(); + if (ret != SUCCESS) { + cout << "PrepareRecorder failed." << endl; + CloseRecorder(); return; } - string path = "/sdcard"; - ret = recorder_->SetOutputPath(path); + ret = recorder_->SetOutputFile(recordFd_); if (ret != SUCCESS) { - cout << "SetOutputPath fialed :" << ret << std::endl; + cout << "SetOutputPath failed. ret=" << ret << endl; + CloseRecorder(); return; } ret = recorder_->Prepare(); if (ret != SUCCESS) { - cout << "Prepare failed.=" << ret << endl; + cout << "Prepare failed. ret=" << ret << endl; + CloseRecorder(); return; } + ret = recorder_->Start(); + if (ret != SUCCESS) { + cout << "Failed to start the recorder. ret=" << ret << endl; + CloseRecorder(); + return; + } + FrameConfig *fc = new FrameConfig(FRAME_CONFIG_RECORD); Surface *surface = (recorder_->GetSurface(0)).get(); surface->SetWidthAndHeight(1920, 1080); surface->SetQueueSize(3); surface->SetSize(1024 * 1024); - FrameConfig *fc = new FrameConfig(FRAME_CONFIG_RECORD); fc->AddSurface(*surface); - ret = recorder_->Start(); - if (ret != SUCCESS) { - delete fc; - cout << "recorder start failed. ret=" << ret << endl; - return; - } ret = cam_->TriggerLoopingCapture(*fc); if (ret != 0) { delete fc; - cout << "camera start recording failed. ret=" << ret << endl; + CloseRecorder(); + cout << "Failed to start camera recording. ret=" << ret << endl; return; } - isRecording_ = true; - cout << "camera start recording succeed." << endl; + recordState_ = STATE_RUNNING; + cout << "Camera recording starts." << endl; } + void StartPreview() { - if (isPreviewing_) { - cout << "Camera is already previewing." << endl; + if (cam_ == nullptr) { + cout << "The camera is not ready." << endl; + return; + } + if (previewState_ == STATE_RUNNING) { + cout << "The camera is in preview." << endl; return; } FrameConfig *fc = new FrameConfig(FRAME_CONFIG_PREVIEW); @@ -312,17 +357,17 @@ public: int32_t ret = cam_->TriggerLoopingCapture(*fc); if (ret != 0) { delete fc; - cout << "camera start preview failed. ret=" << ret << endl; + cout << "Failed to start camera preview. ret=" << ret << endl; return; } delete surface; - isPreviewing_ = true; - cout << "camera start preview succeed." << endl; + previewState_ = STATE_RUNNING; + cout << "Camera preview starts." << endl; } void Capture() { if (cam_ == nullptr) { - cout << "Camera is not ready." << endl; + cout << "The camera is not ready." << endl; return; } FrameConfig *fc = new FrameConfig(FRAME_CONFIG_CAPTURE); @@ -339,46 +384,49 @@ public: void Stop() { if (cam_ == nullptr) { - cout << "Camera is not ready." << endl; + cout << "The camera is not ready." << endl; return; } - if (recorder_ != nullptr) { - recorder_->Stop(false); - } cam_->StopLoopingCapture(); - isPreviewing_ = false; - isRecording_ = false; + if (recordState_ == STATE_RUNNING) { + CloseRecorder(); + } + recordState_ = STATE_IDLE; + previewState_ = STATE_IDLE; } private: - bool isPreviewing_ = false; - bool isRecording_ = false; + enum State : int32_t { STATE_IDLE, STATE_RUNNING, STATE_BUTT }; + State previewState_ = STATE_IDLE; + State recordState_ = STATE_IDLE; EventHandler &eventHdlr_; Camera *cam_ = nullptr; + int32_t recordFd_ = -1; Recorder *recorder_ = nullptr; SampleFrameStateCallback fsCb_; }; -class SampleCameraDeviceCallback : public CameraDeviceCallback {}; +class SampleCameraDeviceCallback : public CameraDeviceCallback { +}; void SampleHelp() { cout << "*******************************************" << endl; - cout << "Select the behavior of avrecorder." << endl; - cout << "1: Capture" << endl; - cout << "2: Record(Press s or S to stop)" << endl; - cout << "3: Preview(Press s or S to stop)" << endl; - cout << "q: quit the sample." << endl; + cout << "Select the action to take for the AVRecorder." << endl; + cout << "1: Take a picture." << endl; + cout << "2: Record (press S to stop)" << endl; + cout << "3: Preview (press S to stop)" << endl; + cout << "Press Q to quit." << endl; cout << "*******************************************" << endl; } int main() { - cout << "Camera sample begin." << endl; + cout << "The sample starts." << endl; SampleHelp(); CameraKit *camKit = CameraKit::GetInstance(); if (camKit == nullptr) { - cout << "Can not get CameraKit instance" << endl; + cout << "Failed to get the CameraKit instance" << endl; return 0; } list camList = camKit->GetCameraIds(); @@ -386,16 +434,18 @@ int main() for (auto &cam : camList) { cout << "camera name:" << cam << endl; const CameraAbility *ability = camKit->GetCameraAbility(cam); - /* Find the camera that fits your ability. */ + /* find camera which fits user's ability */ list sizeList = ability->GetSupportedSizes(0); - if (find(sizeList.begin(), sizeList.end(), CAM_PIC_1080P) != sizeList.end()) { - camId = cam; - break; + for (auto &pic : sizeList) { + if (pic.width == 1920 && pic.height == 1080) { + camId = cam; + break; + } } } if (camId.empty()) { - cout << "No available camera.(1080p wanted)" << endl; + cout << "No available camera (1080p required)." << endl; return 0; } @@ -428,32 +478,18 @@ int main() } } EXIT: - cout << "Camera sample end." << endl; + cout << "The sample ends." << endl; return 0; } - ``` ## Repositories Involved -multimedia\_frameworks\_camera\_lite - -multimedia\_frameworks\_audio\_lite - -multimedia\_frameworks\_player\_lite - -multimedia\_frameworks\_recorder\_lite - -multimedia\_hals\_camera\_lite - -multimedia\_interfaces\_kits\_recorder\_lite - -multimedia\_interfaces\_kits\_audio\_lite +/hmf/multimedia/camera\_lite -multimedia\_interfaces\_kits\_camera\_lite +/hmf/multimedia/audio\_lite -multimedia\_interfaces\_kits\_player\_lite +/hmf/multimedia/media\_lite -multimedia\_services\_media\_lite +/hmf/multimedia/utils\_lite -multimedia\_utils\_lite \ No newline at end of file diff --git a/en/readme/overview.md b/en/readme/overview.md deleted file mode 100644 index d0029cf1cee1b4caad845dd38a9ab3ad5c3f5d1f..0000000000000000000000000000000000000000 --- a/en/readme/overview.md +++ /dev/null @@ -1,18 +0,0 @@ -# Overview - -## Globalization Subsystem - -Users can set the locale regarding about 68 languages and regions on OpenHarmony devices. As the locale settings are synchronized from one OpenHarmony device to another during interconnection, multi-language resource backtracking and multi-language preference support should be taken into account. - -The global resource manager mainly provides the following capabilities: - -- Multi-language resource backtracking: Users in different regions have their own cultural background and use their respective native languages. During resource loading, it is critical to support multi-language locale settings, specifically, to use as few languages as possible to match users' particular cultural background. - -- Multi-language preference support: One of users' multiple preferred languages is selected and displayed for users \(for example, the Swiss\) who have multiple native languages. - -## Repositories Involved - -global\_frameworks\_resmgr\_lite - -global\_interfaces\_innerkits\_resmgr\_lite - diff --git a/en/readme/pan-sensor.md b/en/readme/pan-sensor.md new file mode 100755 index 0000000000000000000000000000000000000000..6432808317b3dafc7c732e7ccfe70c4811f2f2bb --- /dev/null +++ b/en/readme/pan-sensor.md @@ -0,0 +1,49 @@ +# Pan-Sensor + +- [Introduction](#section11660541593) +- [Directory Structure](#section161941989596) +- [Usage](#section1312121216216) +- [Repositories Involved](#section1371113476307) + +## Introduction + +The pan-sensor service subsystem provides a lightweight sensor service framework, through which you can perform the following operations: + +- Query the sensor list. +- Enable or disable a sensor. +- Subscribe to or unsubscribe from sensor data. +- Set the data reporting mode of a sensor. + +The following figure shows the architecture of the pan-sensor service framework. + +**Figure1** Pan-sensor service architecture + +![](figures/en-us_image_0000001106694563.png) + +## Directory Structure + +``` +/base/sensors +├── sensor_lite # Sensor directory +│ ├── frameworks # Framework code +│ ├── interfaces # Native APIs +│ └── services # Code of services +└── miscdevice_lite # Misc device directory +``` + +## Usage + +The following modules work cooperatively to implement pan-sensor capabilities: Sensor API, Sensor Framework, and Sensor Service. + +- Sensor API: provides APIs for performing basic operations on sensors, including querying the sensor list, enabling or disabling sensors, and subscribing to or unsubscribing from sensor data. +- Sensor Framework: manages sensor data subscription, creates and destroys data channels, subscribes to or unsubscribes from sensor data, and implements communication with the Sensor Service module. +- Sensor Service: interacts with the HDF module to receive, parse, and distribute data, manages sensor services and sensor data reporting, and controls sensor permissions. + +## Repositories Involved + +**Pan-sensor subsystem** + +hmf/sensors/sensor\_lite + +hmf/sensors/miscdevice\_lite + diff --git a/en/readme/public_sys-resources/icon-caution.gif b/en/readme/public_sys-resources/icon-caution.gif old mode 100644 new mode 100755 diff --git a/en/readme/public_sys-resources/icon-danger.gif b/en/readme/public_sys-resources/icon-danger.gif old mode 100644 new mode 100755 diff --git a/en/readme/public_sys-resources/icon-note.gif b/en/readme/public_sys-resources/icon-note.gif old mode 100644 new mode 100755 diff --git a/en/readme/public_sys-resources/icon-notice.gif b/en/readme/public_sys-resources/icon-notice.gif old mode 100644 new mode 100755 diff --git a/en/readme/public_sys-resources/icon-tip.gif b/en/readme/public_sys-resources/icon-tip.gif old mode 100644 new mode 100755 diff --git a/en/readme/public_sys-resources/icon-warning.gif b/en/readme/public_sys-resources/icon-warning.gif old mode 100644 new mode 100755 diff --git a/en/readme/security-subsystem.md b/en/readme/security-subsystem.md old mode 100644 new mode 100755 index 30c862444102bfbe7efd78194af11e630a0bd52d..4e52b988fe6f930c854186e1289ea3776dba9f33 --- a/en/readme/security-subsystem.md +++ b/en/readme/security-subsystem.md @@ -1,32 +1,49 @@ # Security Subsystem +- [Overview](#section6309125817418) +- [Directory Structure](#section5614117756) +- [Constraints](#section14134111467) +- [Secure Boot](#section10750510104718) +- [Application Permission Management](#section20822104317111) +- [IPC Authentication](#section156859591110) +- [HUKS](#section9819115764715) +- [HiChain](#section19390142934814) +- [Application Integrity Verification](#section15468226154919) +- [Repositories Involved](#section1665013282177) + ## Overview -This section provides samples about how to use existing security mechanisms to improve system security features, including secure boot, application permission management, inter-process communication \(IPC\) authentication, Huawei Universal Keystore Service \(HUKS\), HiChain, and application signature verification. +This document provides samples about how to use existing security mechanisms to improve system security features, including secure boot, application permission management, inter-process communication \(IPC\) authentication, Huawei Universal Keystore Service \(HUKS\), HiChain, and application signature verification. ## Directory Structure ``` -security -├── framework -│ ├── appverify Application signature verification -│ ├── crypto_lite Encryption and decryption -│ ├── hichainsdk_lite Device authentication -│ ├── huks_lite Key and certificate management -│ ├── secure_os Secure OS -├── interface Interface directory -│ ├── innerkits Internal kit directory -│ │ ├── appverify Application signature verification -│ │ ├── crypto_lite Encryption and decryption -│ │ ├── hichainsdk_lite Device authentication -│ │ ├── huks_lite Key and certificate management -│ │ ├── iam_lite Application permission management -│ │ ├── secure_os Secure OS -│ ├── kits External kit directory -│ │ ├── iam_lite Application permission management -├── services Implementation -│ ├── iam_lite Application permission management -│ ├── secure_os Secure OS +base/security +├── appverify +│ └── interfaces +│ └── innerkits +│ └── appverify_lite # Application signature verification APIs +├── deviceauth +│ ├── frameworks +│ │ └── deviceauth_lite # Device authentication implementation +│ └── interfaces +│ └── innerkits +│ └── deviceauth_lite # Device authentication APIs +├── huks +│ ├── frameworks +│ │ ├── crypto_lite # Encryption and decryption implementation +│ │ └── huks_lite # Key management implementation +│ └── interfaces +│ └── innerkits +│ └── huks_lite # Key management APIs +└── permission + ├── interfaces + │ ├── innerkits + │ │ └── permission_lite # Internal APIs for permission management + │ └── kits + │ └── permission_lite # External APIs for permission management + └── services + └── permission_lite # Permission management service ``` ## Constraints @@ -43,38 +60,40 @@ Application permissions are used to control access to system resources and featu The following table describes fields in a permission. +**Table 1** Descriptions of fields in a permission + -

Field

+ - - - - - - - - - - - @@ -142,7 +161,7 @@ HUKS consists of native APIs, the hardware abstraction layer \(HAL\), and Core M 1. Native APIs are implemented using the C language to ensure consistency among all devices, and include the APIs for key generation, encryption, and decryption. 2. Core Module depends on the HAL and provides core functions such as encryption and decryption, signature verification, and key storage. -3. HAL shields differences between hardware and OSs and defines the unified APIs for HUKS. It contains platform algoIOrithm libraries, file systems, and logs. +3. HAL shields differences between hardware and OSs and defines the unified APIs for HUKS. It contains platform algorithm libraries, file systems, and logs. ## HiChain @@ -180,89 +199,21 @@ During this process, the user needs to enter or scan the PIN provided by the IoT When an IoT controller and an IoT device communicate with each other after establishing a trust relationship, they authenticate each other by using the locally stored identity public key of the peer. Bidirectional identity authentication and session key exchange are performed using the Station-to-Station \(STS\) protocol during each communication. The session key is used to encrypt the data transmission channel between the devices. -## Application Signature Verification - -To ensure the integrity of application content, OpenHarmony uses application signatures and profiles to manage application sources. Only pre-installed applications and applications from HUAWEI AppGallery can be installed on devices. - -**Basic Concepts** - -- **Developer certificate** - - -Identity digital certificate of a developer, which is used to sign local debugging software - -- **Application debugging profile** - - -Application debugging authorization file that allows you to install and debug an application on a specified device - -- **Application publishing certificate** - - -Identity digital certificate of an application publisher, which is used to sign an application to be published or preset - -- **Application publishing profile** - - -Description file of an application, which is used for reviewing an application to be published or preset - -- **APPID** - - -Unique identifier of an application, which consists of the application bundle name and the public key of the application publishing certificate +## Application Integrity Verification -**How Application Signature Verification Works** +To ensure the integrity and trustworthiness of the applications to be installed in OpenHarmony, the applications must be signed and their signatures must be verified. -1. Apply for becoming an authorized application developer on HUAWEI AppGallery. -2. Install and debug an application on a specified device. -3. Publish the application. - -## **Signature of an Application Published on HUAWEI AppGallery** - -- **Application debugging scenario** - -To develop and debug applications for OpenHarmony devices, you need to apply for becoming an authorized application developer on HUAWEI AppGallery. You need to generate a public/private key pair and upload the public key to HUAWEI AppGallery. HUAWEI AppGallery creates a developer certificate based on your identity information and the uploaded public key, and issues the certificate through the developer certificate CA. You also need to upload the application information and debugging device ID for creating an application debugging profile, which contains the HUAWEI AppGallery signature and cannot be tampered with. Upon obtaining the developer certificate and application debugging profile, you can install and debug applications signed with the private key on a specified OpenHarmony device. - -The application installation service of OpenHarmony verifies the application signature to ensure application integrity. In addition, the service verifies the developer certificate, application debugging profile, and the mapping between them to ensure the validity of your identity and the application. - -![](figures/en-us_image_0000001051282241.png) - -- **Application publishing** - -To publish applications in HUAWEI AppGallery, you need to use the application publishing certificate and profile issued by HUAWEI AppGallery to sign the applications. As shown in the following figure, the procedure of applying for the application publishing certificate and profile is similar to that of applying for the developer certificate and application debugging profile \(you can use the same public/private key pair\). Applications signed by the application publishing certificate cannot be directly installed on devices. Instead, the applications must be published in HUAWEI AppGallery for review. After the applications are reviewed and approved, HUAWEI AppGallery uses the publishing certificate to re-sign the applications. The re-signed applications can be downloaded and installed by users. - -The application installation service of OpenHarmony verifies the application signature to ensure application integrity. In addition, the service checks whether the signature certificate is from HUAWEI AppGallery to ensure that the application is trusted. - -![](figures/en-us_image_0000001051562162.png) +In application development: After developing an application, you need to sign its installation package to ensure that the installation package is not tampered with when it is released on devices. To sign the application package, you can use the signature tools and the public key certificates and follow the signing certificate generation specifications provided by the application integrity verification module. For your convenience, a public key certificate and a corresponding private key are preset in OpenHarmony. You need to replace the public key certificate and private key in your commercial version of OpenHarmony. +In application installation: The application framework subsystem of OpenHarmony installs applications. Upon receiving an application installation package, the Application Framework subsystem parses the signature of the installation package, and verifies the signature using the application integrity verification APIs. The application can be installed only after the verification succeeds. During the verification, the application integrity verification module uses the preset public key certificate to verify the signature. ## Repositories Involved -security\_services\_app\_verify - -security\_frameworks\_crypto\_lite - -security\_services\_hichainsdk\_lite - -security\_services\_huks\_lite - -security\_frameworks\_secure\_os - -security\_interfaces\_innerkits\_hichainsdk\_lite - -security\_interfaces\_innerkits\_iam\_lite - -security\_interfaces\_innerkits\_huks\_lite - -security\_interfaces\_innerkits\_app\_verify - -security\_interfaces\_innerkits\_crypto\_lite - -security\_interfaces\_innerkits\_secure\_os +security\_permission -security\_interfaces\_kits\_iam\_lite +security\_appverify -security\_services\_iam\_lite +security\_deviceauth -security\_services\_secure\_os +security\_huks diff --git a/en/readme/service-framework-subsystem.md b/en/readme/service-framework-subsystem.md deleted file mode 100644 index 6bd50c3a76cebfab33b6d72cf1fee8324c8b1755..0000000000000000000000000000000000000000 --- a/en/readme/service-framework-subsystem.md +++ /dev/null @@ -1,622 +0,0 @@ -# Service Framework Subsystem - -## Introduction - -Due to limited platform resources, a unified service framework is provided to harmonize differences of hardware architectures \(for example, RISC-V, Cortex-M, and Cortex-A\), resources, and running modes. Two types of hardware platforms \(M- and A-core\) are defined. - -M-core: Hardware platforms with Cortex-M or equivalent processing capabilities. The system memory is generally less than 512 KB. There is only a lightweight file system that can be used in limited scenarios, or no file system at all. M-core platforms comply with the Cortex Microcontroller Software Interface Standard \(CMSIS\). - -A-core: Hardware platforms with Cortex-A or equivalent processing capabilities. The system memory is greater than 512 KB. There is a comprehensive file system for storing a large amount of data. A-core platforms comply with the Portable Operating System Interface \(POSIX\) specifications. - -This service-oriented service framework enables you to develop services, features, and external APIs, and implement multi-service process sharing and service invoking for inter-process communication \(IPC\). - -- M core provides services, features, external APIs, and multi-service process sharing development. -- In addition to the capabilities provided by M-core, A-core provides capabilities such as IPC service invoking, permission control for IPC service invoking, and IPC service API development. - -Service-oriented architecture - -![](figures/en-us_image_0000001051351505.png) - -Provider: a service provider that provides capabilities \(external APIs\) for the system - -Consumer: a service consumer that invokes the features \(external APIs\) provided by the service - -Samgr: an agency that manages capabilities provided by providers and helps consumers discover providers' capabilities - -Main objects of the service framework: - -![](figures/en-us_image_0000001051990283.png) - -- SamgrLite: provides service registration and discovery. -- Service: implements lifecycle APIs of the service during service development. -- Feature: implements lifecycle APIs of the feature during feature development. -- IUnknown: implements external APIs for services or features based on **IUnknown**. -- IClientProxy: implements the consumer's proxy to send messages during IPC invoking. -- IServerProxy: implements the provider's proxy during IPC invoking, which needs to be implemented by developers. - -## Directory - -**Table 1** Structure of the source code directory of the service framework subsystem - - -

Field

Value

+

Value

Description

+

Description

name

+

name

String

+

String

Permission name

+

Permission name

reason

+

reason

Multi-language string ID

+

Multi-language string ID

Purpose of requesting the permission.

+

Purpose of requesting the permission.

used-scene{

+

used-scene{

ability,

when

}

ability: string of the component class name

+

ability: string of the component class name

when: inuse and always

Scene where the APIs controlled by this permission are called.

+

Scene where the APIs controlled by this permission are called.

This field declares what components can call the APIs controlled by this permission in the specified scene (foreground/background).
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Directory

-

Description

-

interfaces/kits/samgr_lite/samgr

-

External APIs of the M- and A-core service frameworks

-

interfaces/kits/samgr_lite/registry

-

External APIs for service invocation between A-core processes

-

interfaces/kits/samgr_lite/communication/broadcast

-

External APIs of the event broadcast service within M- and A-core processes

-

services/samgr_lite/samgr/adapter

-

POSIX and CMSIS interface adaptation layer, which is used to harmonize the differences between the APIs of M- and A-core

-

services/samgr_lite/samgr/registry

-

Stub functions for M-core service registration and discovery

-

services/samgr_lite/samgr/source

-

Basic code for the M- and A-core service frameworks

-

services/samgr_lite/samgr_client

-

Registration and discovery for service invocation between A-core processes

-

services/samgr_lite/samgr_server

-

IPC address management and access control for service invocation between A-core processes

-

services/samgr_lite/samgr_endpoint

-

Packet RX/TX management for A-core IPC

-

services/samgr_lite/communication/broadcast

-

Event broadcast service for M- and A-core processes

-
- -## Restrictions - -The service framework is developed using the C programming language. - -Services in the same process use **IUnknown** for invoking. Messages are passed to the service through **IUnknown**. - -The service name and feature name must be constant character strings and the length must be less than 16 bytes. - -More-core depends on the Bootstrap service and calls the **OHOS\_SystemInit\(\)** function in the system startup function. - -A-core depends on the Samgr library and calls the **SAMGR\_Bootstrap\(\)** function in the **main** function. - -## Developing a Service - -- Inherit and redefine a service. - - ``` - typedef struct ExampleService { - INHERIT_SERVICE; - INHERIT_IUNKNOWNENTRY(DefaultFeatureApi); - Identity identity; - } ExampleService; - ``` - -- Implement the lifecycle function of the service. - - ``` - static const char *GetName(Service *service) - { - return EXAMPLE_SERVICE; - } - - static BOOL Initialize(Service *service, Identity identity) - { - ExampleService *example = (ExampleService *)service; - // Save the unique ID of the service, which is used when IUnknown is used to send messages to the service. - example->identity = identity; - return TRUE; - } - static BOOL MessageHandle(Service *service, Request *msg) - { - ExampleService *example = (ExampleService *)service; - switch (msg->msgId) { - case MSG_SYNC: - // Process the service. - break; - default:break; - } - return FALSE; - } - static TaskConfig GetTaskConfig(Service *service) - { - TaskConfig config = {LEVEL_HIGH, PRI_BELOW_NORMAL, - 0x800, 20, SHARED_TASK}; - return config; - } - ``` - -- Create a service object. - - ``` - static ExampleService g_example = { - .GetName = GetName, - .Initialize = Initialize, - .MessageHandle = MessageHandle, - .GetTaskConfig = GetTaskConfig, - SERVER_IPROXY_IMPL_BEGIN, - .Invoke = NULL, - .SyncCall = SyncCall, - IPROXY_END, - }; - ``` - -- Register the service and API with Samgr. - - ``` - static void Init(void) - { - SAMGR_GetInstance()->RegisterService((Service *)&g_example); - SAMGR_GetInstance()->RegisterDefaultFeatureApi(EXAMPLE_SERVICE, GET_IUNKNOWN(g_example)); - } - ``` - -- Define the initializer of the service. - - ``` - SYSEX_SERVICE_INIT(Init); - ``` - - -## Developing a Feature of a Service - -- Inherit and redefine a feature. - - ``` - typedef struct DemoFeature { - INHERIT_FEATURE; - INHERIT_IUNKNOWNENTRY(DemoApi); - Identity identity; - Service *parent; - } DemoFeature; - ``` - -- Implement the lifecycle function of the feature. - - ``` - static const char *FEATURE_GetName(Feature *feature) - { - return EXAMPLE_FEATURE; - } - - static void FEATURE_OnInitialize(Feature *feature, Service *parent, Identity identity) - { - DemoFeature *demoFeature = (DemoFeature *)feature; - demoFeature->identity = identity; - demoFeature->parent = parent; - } - - static void FEATURE_OnStop(Feature *feature, Identity identity) - { - g_example.identity.queueId = NULL; - g_example.identity.featureId = -1; - g_example.identity.serviceId = -1; - } - - static BOOL FEATURE_OnMessage(Feature *feature, Request *request) - { - if (request->msgId == MSG_PROC) { - Response response = {.data = "Yes, you did!", .len = 0}; - SAMGR_SendResponse(request, &response); - return TRUE; - } else { - if (request->msgId == MSG_TIME_PROC) { - LOS_Msleep(WAIT_FEATURE_PROC * 10); - if (request->msgValue) { - SAMGR_PrintServices(); - } else { - SAMGR_PrintOperations(); - } - AsyncTimeCall(GET_IUNKNOWN(g_example)); - return FALSE; - } - } - return FALSE; - } - ``` - -- Create a feature object. - - ``` - static DemoFeature g_example = { - .GetName = FEATURE_GetName, - .OnInitialize = FEATURE_OnInitialize, - .OnStop = FEATURE_OnStop, - .OnMessage = FEATURE_OnMessage, - DEFAULT_IUNKNOWN_ENTRY_BEGIN, - .AsyncCall = AsyncCall, - .AsyncTimeCall = AsyncTimeCall, - .SyncCall = SyncCall, - .AsyncCallBack = AsyncCallBack, - DEFAULT_IUNKNOWN_ENTRY_END, - .identity = {-1, -1, NULL}, - }; - ``` - -- Register the feature and API with Samgr. - - ``` - static void Init(void){ - SAMGR_GetInstance()->RegisterFeature(EXAMPLE_SERVICE, (Feature *)&g_example); - SAMGR_GetInstance()->RegisterFeatureApi(EXAMPLE_SERVICE, EXAMPLE_FEATURE, GET_IUNKNOWN(g_example)); - } - ``` - -- Define the initializer of the feature. - - ``` - SYSEX_FEATURE_INIT(Init); - ``` - - -## Developing an External API for Intra-process Communication - -- Define the **IUnknown** API. - - ``` - typedef struct DemoApi { - INHERIT_IUNKNOWN; - BOOL (*AsyncCall)(IUnknown *iUnknown, const char *buff); - BOOL (*AsyncTimeCall)(IUnknown *iUnknown); - BOOL (*SyncCall)(IUnknown *iUnknown, struct Payload *payload); - BOOL (*AsyncCallBack)(IUnknown *iUnknown, const char *buff, Handler handler); - } DemoApi; - ``` - -- Define the reference object of **IUnknown**. - - ``` - typedef struct DemoRefApi { - INHERIT_IUNKNOWNENTRY(DemoApi); - } DemoRefApi; - ``` - -- Initialize the object of **IUnknown**. - - ``` - static DemoRefApi api = { - DEFAULT_IUNKNOWN_ENTRY_BEGIN, - .AsyncCall = AsyncCall, - .AsyncTimeCall = AsyncTimeCall, - .SyncCall = SyncCall, - .AsyncCallBack = AsyncCallBack, - DEFAULT_IUNKNOWN_ENTRY_END, - }; - ``` - -- Register the feature API. - - ``` - SAMGR_GetInstance()->RegisterFeatureApi(EXAMPLE_SERVICE, EXAMPLE_FEATURE, GET_IUNKNOWN(api)); - ``` - - -## Invoking a Service in the Same Process - -- Obtain the external API of the service. - - ``` - DemoApi *demoApi = NULL; - IUnknown *iUnknown = SAMGR_GetInstance()->GetFeatureApi(EXAMPLE_SERVICE, EXAMPLE_FEATURE); - if (iUnknown == NULL) { - return NULL; - } - int result = iUnknown->QueryInterface(iUnknown, DEFAULT_VERSION, (void **)&demoApi); - if (result != 0 || demoApi == NULL) { - return NULL; - } - ``` - -- Call the API. - - ``` - if (demoApi->AsyncCallBack == NULL) { - return NULL; - } - demoApi->AsyncCallBack((IUnknown *)demoApi, "I wanna async call callback good result!", AsyncHandler); - ``` - -- Release the API. - - ``` - int32 ref = demoApi->Release((IUnknown *)demoApi); - ``` - - -## Developing an External API for IPC - -- Inherit **IServerProxy** to replace **IUnknown**: INHERIT\_SERVER\_IPROXY - - ``` - typedef struct DemoFeatureApi { - INHERIT_SERVER_IPROXY; - BOOL (*AsyncCall)(IUnknown *iUnknown, const char *buff); - BOOL (*AsyncTimeCall)(IUnknown *iUnknown); - BOOL (*SyncCall)(IUnknown *iUnknown, struct Payload *payload); - BOOL (*AsyncCallBack)(IUnknown *iUnknown, const char *buff, IOwner notify, INotifyFunc handler); - } DemoFeatureApi; - ``` - -- Initialize the **IServerProxy** object. - - ``` - static DemoFeature g_example = { - SERVER_IPROXY_IMPL_BEGIN, - .Invoke = Invoke, - .AsyncCall = AsyncCall, - .AsyncTimeCall = AsyncTimeCall, - .SyncCall = SyncCall, - .AsyncCallBack = AsyncCallBack, - IPROXY_END, - }; - ``` - -- Implement the **Invoke** function to process IPC messages. - - ``` - static int32 Invoke(IServerProxy *iProxy, int funcId, void *origin, IpcIo *req, IpcIo *reply) - { - DemoFeatureApi *api = (DemoFeatureApi *)iProxy; - BOOL ret; - size_t len = 0; - switch (funcId) { - case ID_ASYNCALL: - ret = api->AsyncCall((IUnknown *)iProxy, (char *)IpcIoPopString(req, &len)); - IpcIoPushBool(reply, ret); - break; - case ID_ASYNTIMECALL: - ret = api->AsyncTimeCall((IUnknown *)iProxy); - IpcIoPushBool(reply, ret); - break; - case ID_SYNCCALL: { - struct Payload payload; - payload.id = IpcIoPopInt32(req); - payload.value = IpcIoPopInt32(req); - payload.name = (char *)IpcIoPopString(req, &len); - ret = api->SyncCall((IUnknown *)iProxy, &payload); - IpcIoPushString(reply, ret ? "TRUE" : "FALSE"); - } - break; - case ID_ASYNCCALLBACK: { // convert to sync proxy - IpcIoPushString(reply, "Yes, you did!"); - IpcIoPushBool(reply, TRUE); - } - break; - default: - IpcIoPushBool(reply, FALSE); - break; - } - return EC_SUCCESS; - } - ``` - -- Register the API. This step is same as the API registration for intra-process communication. - - ``` - SAMGR_GetInstance()->RegisterFeatureApi(EXAMPLE_SERVICE, EXAMPLE_FEATURE, GET_IUNKNOWN(g_example)); - ``` - - -## Invoking a Service in Another Process - -- Obtain the external API of the service in another process. - - ``` - IClientProxy *demoApi = NULL; - IUnknown *iUnknown = SAMGR_GetInstance()->GetFeatureApi(EXAMPLE_SERVICE, EXAMPLE_FEATURE); - if (iUnknown == NULL) { - return NULL; - } - int result = iUnknown->QueryInterface(iUnknown, CLIENT_PROXY_VER, (void **)&demoApi); - if (result != 0 || demoApi == NULL) { - return NULL; - } - ``` - -- Invoke the API for sending IPC messages. - - ``` - IpcIo request;char data[250]; - IpcIoInit(&request, data, sizeof(data), 0); - demoApi->Invoke(demoApi, 0, &request, NULL, NULL); - ``` - -- Release the API. - - ``` - int32 ref = demoApi->Release((IUnknown *)demoApi); - ``` - - -## Developing a Client Proxy for Inter-Process Service Invocation - -- Define a client proxy for the IPC API. - - ``` - typedef struct DemoClientProxy { - INHERIT_CLIENT_IPROXY; - BOOL (*AsyncCall)(IUnknown *iUnknown, const char *buff); - BOOL (*AsyncTimeCall)(IUnknown *iUnknown); - BOOL (*SyncCall)(IUnknown *iUnknown, struct Payload *payload); - BOOL (*AsyncCallBack)(IUnknown *iUnknown, const char *buff, IOwner notify, INotifyFunc handler); - } DemoClientProxy; - typedef struct DemoClientEntry { - INHERIT_IUNKNOWNENTRY(DemoClientProxy); - } DemoClientEntry; - ``` - -- Enable the client proxy to encapsulate the IPC message API. - - ``` - static BOOL AsyncCall(IUnknown *iUnknown, const char *buff) - { - DemoClientProxy *proxy = (DemoClientProxy *)iUnknown; - IpcIo request; - char data[MAX_DATA_LEN]; - IpcIoInit(&request, data, MAX_DATA_LEN, 0); - IpcIoPushString(&request, buff); - int ret = proxy->Invoke((IClientProxy *)proxy, ID_ASYNCALL, &request, NULL, NULL); - return ret == EC_SUCCESS; - } - - static BOOL AsyncTimeCall(IUnknown *iUnknown) - { - DemoClientProxy *proxy = (DemoClientProxy *)iUnknown; - IpcIo request; - char data[MAX_DATA_LEN]; - IpcIoInit(&request, data, MAX_DATA_LEN, 0); - int ret = proxy->Invoke((IClientProxy *)proxy, ID_ASYNTIMECALL, &request, NULL, NULL); - return ret == EC_SUCCESS; - } - - static int Callback(IOwner owner, int code, IpcIo *reply) - { - size_t len = 0; - return strcpy_s(owner, MAX_DATA_LEN, (char *)IpcIoPopString(reply, &len)); - } - - static BOOL SyncCall(IUnknown *iUnknown, struct Payload *payload) - { - DemoClientProxy *proxy = (DemoClientProxy *)iUnknown; - IpcIo request; - char data[MAX_DATA_LEN]; - IpcIoInit(&request, data, MAX_DATA_LEN, 0); - IpcIoPushInt32(&request, payload->id); - IpcIoPushInt32(&request, payload->value); - IpcIoPushString(&request, payload->name); - int ret = proxy->Invoke((IClientProxy *)proxy, ID_SYNCCALL, &request, data, Callback); - data[MAX_DATA_LEN - 1] = 0; - HILOG_INFO(HILOG_MODULE_APP, "[TID:0x%lx]Remote response is %s!", pthread_self(), data); - return ret == EC_SUCCESS; - } - - struct CurrentNotify { - IOwner notify; - INotifyFunc handler; - }; - - static int CurrentCallback(IOwner owner, int code, IpcIo *reply) - { - struct CurrentNotify *notify = (struct CurrentNotify *)owner; - size_t len = 0; - char *response = (char *)IpcIoPopString(reply, &len); - HILOG_INFO(HILOG_MODULE_APP, "[TID:0x%lx]Notify Remote response is %s!", pthread_self(), response); - notify->handler(notify->notify, response); - return EC_SUCCESS; - } - - static BOOL AsyncCallBack(IUnknown *iUnknown, const char *buff, IOwner notify, INotifyFunc handler) - { - struct CurrentNotify owner = {notify, handler}; - DemoClientProxy *proxy = (DemoClientProxy *)iUnknown; - IpcIo request; - char data[MAX_DATA_LEN]; - IpcIoInit(&request, data, MAX_DATA_LEN, 0); - IpcIoPushString(&request, buff); - int ret = proxy->Invoke((IClientProxy *)proxy, ID_ASYNCCALLBACK, &request, &owner, CurrentCallback); - return ret == EC_SUCCESS; - } - ``` - -- Implement the factory method for creating the client proxy. - - ``` - void *DEMO_CreatClient(const char *service, const char *feature, uint32 size) - { - (void)service; - (void)feature; - uint32 len = size + sizeof(DemoClientEntry); - uint8 *client = malloc(len); - (void)memset_s(client, len, 0, len); - DemoClientEntry *entry = (DemoClientEntry *)&client[size]; - entry->ver = ((uint16)CLIENT_PROXY_VER | (uint16)DEFAULT_VERSION); - entry->ref = 1; - entry->iUnknown.QueryInterface = IUNKNOWN_QueryInterface; - entry->iUnknown.AddRef = IUNKNOWN_AddRef; - entry->iUnknown.Release = IUNKNOWN_Release; - entry->iUnknown.Invoke = NULL; - entry->iUnknown.AsyncCall = AsyncCall; - entry->iUnknown.AsyncTimeCall = AsyncTimeCall; - entry->iUnknown.SyncCall = SyncCall; - entry->iUnknown.AsyncCallBack = AsyncCallBack; - return client; - } - void DEMO_DestroyClient(const char *service, const char *feature, void *iproxy) - { - free(iproxy); - } - ``` - -- Register the factory method of the client proxy with Samgr. - - ``` - SAMGR_RegisterFactory(EXAMPLE_SERVICE, EXAMPLE_FEATURE, DEMO_CreatClient, DEMO_DestroyClient); - ``` - -- Obtain the external API of the service in another process. - - ``` - DemoClientProxy *demoApi = NULL; - IUnknown *iUnknown = SAMGR_GetInstance()->GetFeatureApi(EXAMPLE_SERVICE, EXAMPLE_FEATURE); - if (iUnknown == NULL) { - return NULL; - } - int result = iUnknown->QueryInterface(iUnknown, DEFAULT_VERSION, (void **)&demoApi); - if (result != 0 || demoApi == NULL) { - return NULL; - } - ``` - -- Invoke the client proxy API of the service in another process. - - ``` - if (demoApi->AsyncCallBack == NULL) { - return NULL; - } - demoApi->AsyncCallBack((IUnknown *)demoApi, - "I wanna async call callback good result!", NULL, AsyncHandler); - ``` - -- Release the API. - - ``` - int32 ref = demoApi->Release((IUnknown *)demoApi); - ``` - - -## Repositories Involved - -distributedschedule\_interfaces\_kits\_samgr\_lite - -distributedschedule\_services\_samgr\_lite - diff --git a/en/readme/startup.md b/en/readme/startup.md old mode 100644 new mode 100755 index 0526c696429c6df06ace4fd8e22a979c7a3b7fea..810a6abddfc0096c1aabbdd663df937160fb9e53 --- a/en/readme/startup.md +++ b/en/readme/startup.md @@ -1,184 +1,161 @@ -# Startup +# Startup + +- [Introduction](#section11660541593) +- [Directory Structure](#section161941989596) +- [Constraints](#section1718733212019) +- [Usage](#section8533192617117) +- [Repositories Involved](#section1371113476307) ## Introduction -The startup subsystem is responsible for starting key system processes and services after the kernel is started and before applications are started. This subsystem has the following modules: +The startup subsystem is responsible for starting key system processes and services after the kernel is started and before applications are started. The subsystem consists of the following modules: -- **init** for starting system service processes +- init\_lite -This module can be used on the Hi3516DV300 and Hi3518EV300 platforms powered by LiteOS Cortex-A. + This module can be used on the Hi3516D V300 and Hi3518E V300 platforms powered by LiteOS Cortex-A. -It starts system service processes from the time the kernel loads the first user-space process to the time the first application program is started. In addition to loading key system processes, the startup subsystem needs to configure required permissions during the startup, and keeps the specified process alive after sub-processes are started. If a process exits abnormally, the startup subsystem needs to restart it, and to perform system reset for a special process. + It starts system service processes from the time the kernel loads the first user-space process to the time the first application is started. In addition to loading key system processes, the module needs to configure their permissions during the startup and keep the specified process alive after sub-processes are started. If a process exits abnormally, the module needs to restart it, and to perform system reset for a special process. -- **appspawn** for spawning applications - This module can be used on the Hi3516DV300 and Hi3518EV300 platforms powered by LiteOS Cortex-A. +- appspawn\_lite - It spawns application processes upon receiving commands from the application framework, configures required permissions, and invokes the entry of the application framework. + This module can be used on the Hi3516D V300 and Hi3518E V300 platforms powered by LiteOS Cortex-A. -- **bootstrap** for starting service modules + This module spawns application processes upon receiving commands from the application framework, configures permissions for new processes, and calls the entry function of the application framework. - This module can be used on the Hi3861 platform powered by LiteOS Cortex-M. +- bootstrap\_lite - It provides identifiers for starting services and functions. When the SAMGR is started, the entry function identified by **boostrap** is invoked and system services are started. + This module can be used on the Hi3861 platform powered by LiteOS Cortex-M. -- **Syspara** + This module provides entry identifiers for starting services and features. When Samgr starts, it will call the entry function identified by bootstrap\_lite and start system services. - This module can be used on the Hi3861, Hi3516DV300 and Hi3518EV300 platforms powered by LiteOS Cortex-M and LiteOS Cortex-A. +- syspara\_lite - It obtains and sets system attributes for the operating system. + This module obtains and sets system attributes. - System attributes consist of default, OEM-specified, and custom system attributes. OEM-specified system attributes provide only default values. The specific values need to be adjusted as required. For details, see [Usage](#section674513182447). + It can be used on the Hi3861, Hi3516D V300, and Hi3518E V300 platforms powered by LiteOS Cortex-M and LiteOS Cortex-A. Supported system attributes consist of default, OEM-specified, and custom system attributes. OEM-specified system attributes provide only default values. The specific values need to be adjusted as required. For details, see [Usage](#section8533192617117). -## Directory Structure +## Directory Structure -**Table 1** Directory structure of the source code for the Startup subsystem +**Table 1** Directory structure of the source code for the startup subsystem - - - - - - @@ -238,7 +211,7 @@ After the init process starts, it reads the **/etc/init.cfg** file, parses the - @@ -247,81 +220,79 @@ After the init process starts, it reads the **/etc/init.cfg** file, parses the It is worth noting that the modified **init.cfg** file must be in JSON format. Otherwise, the init process fails to parse the file, and no service will be started. The configured service permission **uid/gid/capability** must meet the requirements imposed by the security subsystem and comply with the principle of least permission. In addition, if the values of **once** and **importance** of a service are both **0** and the service exits for more than four consecutive times within four minutes, the init process will stop restarting the service. - System parameters - - OEM-specific system attributes - For Hi3516DV300 and Hi3518EV300 development boards, you need to modify the source files in the **vendor/huawei/camera/hals/utils/sys\_param** directory. - - ``` - static const char HOS_PRODUCT_TYPE[] = {"****"}; - static const char HOS_MANUFACTURE[] = {"****"}; - static const char HOS_BRAND[] = {"****"}; - static const char HOS_MARKET_NAME[] = {"****"}; - static const char HOS_PRODUCT_SERIES[] = {"****"}; - static const char HOS_PRODUCT_MODEL[] = {"****"}; - static const char HOS_SOFTWARE_MODEL[] = {"****"}; - static const char HOS_HARDWARE_MODEL[] = {"****"}; - static const char HOS_HARDWARE_PROFILE[] = {"aout:true,display:true"}; - static const char HOS_BOOTLOADER_VERSION[] = {"bootloader"}; - static const char HOS_SECURE_PATCH_LEVEL[] = {"2020-6-5"}; - static const char HOS_ABI_LIST[] = {"****"}; - ``` - - For Hi3861 development boards, you need to modify the source files in the **vendor/huawei/wifi-iot/hals/utils/sys\_param** directory. - - ``` - static const char HOS_PRODUCT_TYPE[] = {"****"}; - static const char HOS_MANUFACTURE[] = {"****"}; - static const char HOS_BRAND[] = {"****"}; - static const char HOS_MARKET_NAME[] = {"****"}; - static const char HOS_PRODUCT_SERIES[] = {"****"}; - static const char HOS_PRODUCT_MODEL[] = {"****"}; - static const char HOS_SOFTWARE_MODEL[] = {"****"}; - static const char HOS_HARDWARE_MODEL[] = {"****"}; - static const char HOS_HARDWARE_PROFILE[] = {"aout:true,display:true"}; - static const char HOS_BOOTLOADER_VERSION[] = {"bootloader"}; - static const char HOS_SECURE_PATCH_LEVEL[] = {"2020-6-5"}; - static const char HOS_ABI_LIST[] = {"****"}; - ``` - - - Obtaining default system attributes - - ``` - char* value1 = GetProductType(); - printf("Product type =%s\n", value1); - free(value1); - char* value2 = GetManufacture(); - printf("Manufacture =%s\n", value2); - free(value2); - char* value3 = GetBrand(); - printf("GetBrand =%s\n", value3); - free(value3); - ``` - - - Obtaining custom system attributes - - ``` - const char* defSysParam = "data of sys param ***..."; - char key[] = "rw.parameter.key"; - char value[] = "OEM-hisi-10.1.0"; - int ret = SetParameter(key, value); - char valueGet[128] = {0}; - ret = GetParameter(key, defSysParam, valueGet, 128); - printf("value = %s\n", valueGet); - ``` - - -## Repositories Involved - -startup\_frameworks\_syspara\_lite - -startup\_hals\_syspara\_lite - -startup\_interfaces\_kits\_syspara\_lite - -startup\_appspawn\_lite - -startup\_services\_bootstrap\_lite - -startup\_init\_lite + For Hi3516D V300 and Hi3518E V300 development boards, you need to modify the source files in the **vendor/hisilicon/hispark\_aries/hals/utils/sys\_param** directory. + + ``` + static const char HOS_PRODUCT_TYPE[] = {"****"}; + static const char HOS_MANUFACTURE[] = {"****"}; + static const char HOS_BRAND[] = {"****"}; + static const char HOS_MARKET_NAME[] = {"****"}; + static const char HOS_PRODUCT_SERIES[] = {"****"}; + static const char HOS_PRODUCT_MODEL[] = {"****"}; + static const char HOS_SOFTWARE_MODEL[] = {"****"}; + static const char HOS_HARDWARE_MODEL[] = {"****"}; + static const char HOS_HARDWARE_PROFILE[] = {"aout:true,display:true"}; + static const char HOS_BOOTLOADER_VERSION[] = {"bootloader"}; + static const char HOS_SECURE_PATCH_LEVEL[] = {"2020-6-5"}; + static const char HOS_ABI_LIST[] = {"****"}; + ``` + + For Hi3861 development boards, you need to modify the source files in the **vendor/hisilicon/hispark\_pegasus/hals/utils/sys\_param** directory. + + ``` + static const char HOS_PRODUCT_TYPE[] = {"****"}; + static const char HOS_MANUFACTURE[] = {"****"}; + static const char HOS_BRAND[] = {"****"}; + static const char HOS_MARKET_NAME[] = {"****"}; + static const char HOS_PRODUCT_SERIES[] = {"****"}; + static const char HOS_PRODUCT_MODEL[] = {"****"}; + static const char HOS_SOFTWARE_MODEL[] = {"****"}; + static const char HOS_HARDWARE_MODEL[] = {"****"}; + static const char HOS_HARDWARE_PROFILE[] = {"aout:true,display:true"}; + static const char HOS_BOOTLOADER_VERSION[] = {"bootloader"}; + static const char HOS_SECURE_PATCH_LEVEL[] = {"2020-6-5"}; + static const char HOS_ABI_LIST[] = {"****"}; + ``` + + - Default system attributes + + ``` + char* value1 = GetProductType(); + printf("Product type =%s\n", value1); + free(value1); + char* value2 = GetManufacture(); + printf("Manufacture =%s\n", value2); + free(value2); + char* value3 = GetBrand(); + printf("GetBrand =%s\n", value3); + free(value3); + ``` + + - Custom system attributes + + ``` + const char* defSysParam = "data of sys param ***..."; + char key[] = "rw.parameter.key"; + char value[] = "OEM-hisi-10.1.0"; + int ret = SetParameter(key, value); + char valueGet[128] = {0}; + ret = GetParameter(key, defSysParam, valueGet, 128); + printf("value = %s\n", valueGet); + ``` + + + +## Repositories Involved + +Startup subsystem + +hmf/startup/syspara\_lite + +hmf/startup/appspawn\_lite + +hmf/startup/bootstrap\_lite + +hmf/startup/init\_lite diff --git a/en/readme/testing-subsystem.md b/en/readme/testing-subsystem.md old mode 100644 new mode 100755 index 0b25654affbe06d0905e2f8790f26c5a75cb5f60..f6894560eaad7591d7b3f1af4715c880fa9a4add --- a/en/readme/testing-subsystem.md +++ b/en/readme/testing-subsystem.md @@ -1,209 +1,204 @@ # Testing Subsystem +- [Overview](#section7375710115617) +- [Directory Structure](#section102031353175317) +- [Constraints](#section87444710110) +- [Installation](#section1347156474) +- [Test Cases](#section125411936102918) +- [Test Framework Usage](#section75882026185016) +- [Test Result and Logs](#section414715805819) +- [Repositories Involved](#section6299103515474) + ## Overview -The test-driven development mode is used during the development process. You can develop new cases or modify existing cases to test new or enhanced system features. The test helps you develop high-quality code in the development phase. +The testing subsystem allows you to develop new test cases for new features, or modify existing test cases for modified features. The developers test framework helps you develop high-quality code. ## Directory Structure -**Table 1** Directory structure of the source code for test tools - - -

Directory

+ - - - - - - - - - - - - -

Name

Description

+

Description

Applicable Platform

base/startup/services/appspawn_lite

+

base/startup/appspawn_lite

appspawn module for spawning application processes. It receives AMS messages via lightweight IPC, parses the messages, starts application processes based on the parsing result, and grants permissions to them.

+

appspawn_lite module for spawning application processes. It receives Ability Manager Service (AMS) messages via IPC, parses the messages, starts application processes based on the parsing result, and grants permissions to them.

Hi3516DV300

Hi3518EV300

base/startup/services/bootstrap_lite

+

base/startup/bootstrap_lite

bootstrap module for starting all services except core system services.

+

bootstrap_lite module for starting all services except core system services.

Hi3861

base/startup/services/init_lite

+

base/startup/init_lite

init module for the init process, which is the first user-space process loaded after the kernel is initialized. After the startup, the configuration file in /etc/init.cfg is parsed. Based on the parsing result, other key system processes are started and granted required permissions.

+

init_lite module for implementing the init process, which is the first user-space process loaded after the kernel is initialized. Upon startup, the process parses the configuration file in /etc/init.cfg. Based on the parsing result, the process then starts other key system processes and grants required permissions to them.

Hi3516DV300

Hi3518EV300

base/startup/interfaces

+

base/startup/syspara_lite

Open APIs provided by the bootstrap module. The main function directs the calls to these APIs to start the service framework.

+

syspara_lite module that provides APIs to obtain device information, including the product name, brand name, category name, and manufacturer name.

Hi3861

+

Hi3861

Hi3516DV300

Hi3518EV300

base/startup/frameworks/syspara_lite

-

syspara module. It provides APIs to obtain device information, including the product name, brand name, category name, and manufacturer name.

-
``` -base -├──startup Root directory of the startup subsystem -├──── frameworks -│ └── syspara_lite -│ ├── LICENSE License file for open-source code -│ ├── parameter Source files for the syspara module -│ │ ├── BUILD.gn -│ │ └── src -│ │ ├── BUILD.gn -│ │ ├── param_impl_hal syspara module implemented based on LiteOS Cortex-M -│ │ └── param_impl_posix syspara module implemented based on LiteOS Cortex-A -│ └── token -│ ├── BUILD.gn -│ └── src -│ ├── token_impl_hal -│ └── token_impl_posix -├──── hals -│ └── syspara_lite Header files at the hardware abstraction layer of the syspara module -├──── interfaces -│ └── kits -│ └── syspara_lite Open APIs related to the syspara module -└──── services - ├── appspawn_lite appspawn module - │ ├── BUILD.gn Compilation and configuration of the appspawn module - │ ├── include Header files for the appspawn module - │ ├── LICENSE License file for open-source code - │ ├── moduletest Self-testing code for the appspawn module - │ └── src Source files for the appspawn module - ├── bootstrap_lite bootstrap module - │ ├── BUILD.gn Compilation and configuration of the bootstrap module - │ ├── LICENSE License file for open-source code - │ └── source Source files for the bootstrap module - └── init_lite init module - ├── BUILD.gn Compilation and configuration of the init module - ├── include Header files for the init module - ├── LICENSE License file for open-source code - ├── moduletest Self-testing code for the init module - └── src Sources for the init module -vendor -└──huawei - └──camera - └──init_configs Configuration file of the init module (in JSON format, in the /etc/ directory) +base/startup/ +├── appspawn_lite # appspawn_lite module +│ └── services +│ ├── include # Header files for the appspawn_lite module +│ ├── src # Source files for the appspawn_lite module +│ └── test # Source files of the test cases for the appspawn_lite module +├── bootstrap_lite # bootstrap_lite module +│ └── services +│ ├── source # Source files for the bootstrap_lite module +├── init_lite # init_lite module +│ └── services +│ ├── include # Header files for the init_lite module +│ ├── src # Source files for the init_lite module +│ └── test # Source files of the test cases for the init_lite module +└── syspara_lite # syspara_lite module + ├── frameworks # Source files for the syspara_lite module + ├── hals # Header files for the hardware abstraction layer of the syspara_lite module + └── interfaces # External APIs for the syspara_lite module ``` ## Constraints -- The startup subsystem is developed using the C language. -- OEM-specified system attributes provide only default values. The specific values need to be adjusted as required. +OEM-specified system attributes provide only default values. The specific values need to be adjusted as required. -## Usage +## Usage -- Configuration file of the init module +- Configuration file of the init\_lite module -The configuration file **init.cfg** of the **init** module contains service names, executable file paths, permissions, and other attributes of all key system services that need to be started by the init process. The file is stored in **/vendor/huawei/camera/init\_configs/** under **/etc/**. It is in JSON format, and its size cannot exceed 100 KB. + The configuration file **init.cfg** of the init\_lite module contains service names, executable file paths, permissions, and other attributes of all key system services that need to be started by the init process. The file is stored in **/vendor/hisilicon/hispark\_aries/init\_configs/** under **/etc/**. It is in JSON format, and its size cannot exceed 100 KB. + + After the init process starts, it reads the **/etc/init.cfg** file, parses the JSON content, and loads system services in sequence based on the parsing result. The format and content of the **init.cfg** file are described as follows: -After the init process starts, it reads the **/etc/init.cfg** file, parses the JSON content, and loads system services in sequence based on the parsing result. The format and content of the configuration file are described as follows: ``` { "jobs" : [{ - "name" : "pre-init", -------- Job executed before the initialization. It can be used to store some pre-operations (for example, creating a folder) before the init process is started. - "cmds" : [ - "mkdir /testdir", -------- Command for creating a folder. mkdir and the target folder must be separated by only one space. - "chmod 0700 /testdir", -------- Command for modifying the permission, which must be in the 0xxxx format. chmod, permission, and the target folder must be separated by only one space. - "chown 99 99 /testdir",-------- Command for modifying the owner group. chown, UID, GID, and the target folder must be separated by only one space. + "name" : "pre-init", -------- Job executed before the initialization. It can be used to store some operations (for example, creating a directory) performed before the init process is started. + "cmds" : [ -------- Commands supported by the current job. Currently, only start, mkdir, chmod, chown, and mount are supported. + -------- The command name and the parameters (128 bytes or less) must be separated by only one space. + "mkdir /testdir", -------- Command for creating a directory. mkdir and the target directory must be separated by only one space. + "chmod 0700 /testdir", -------- Command for modifying the permission. chmod, permission, and the target directory must be separated by only one space. The permission must be in the 0xxx format. + "chown 99 99 /testdir",-------- Command for modifying the owner group. chown, UID, GID, and the target directory must be separated by only one space. "mkdir /testdir2", "mount vfat /dev/mmcblk0p0 /testdir2 noexec nosuid" -------- mount command in the following format: mount file system type source target flags data - -------- flags currently supports only nodev, noexec, nosuid, and rdonly, which are separated by a space. + -------- Supported flags include only nodev, noexec, nosuid, and rdonly, which are separated by a space. ] }, { - "name" : "init", -------- Job name supported by the init process. Ensure that an extended job name contains a maximum of 32 bytes. - "cmds" : [ -------- Command set supported by the current job. Only one space is allowed between the command name (less than 10 bytes) and the following parameter (less than 32 bytes). - "start service1", -------- First command of the current job - "start service2" -------- Second command of the current job (You can adjust the sequence of commands in the array as required. The init process executes the commands in the same order as they are parsed.) + "name" : "init", -------- Job name, which currently supports only pre-init, init, and post-init. + "cmds" : [ -------- A single job currently supports a maximum of 30 commands. + "start service1", -------- Service startup command 1. + "start service2" -------- Service startup command 2. The sequence of the commands in the array can be adjusted as required. The init process then executes the commands in the same sequence as they are parsed. ] }, { "name" : "post-init", -------- Job executed after the initialization. It can be used to store some operations performed after the init process is started. "cmds" : [] } ], - "services" : [{ -------- service set (in an array), including all system services that need to be started by the init process + "services" : [{ -------- Service set (in an array), including all system services that need to be started by the init process. Currently, a maximum of 100 services are supported. "name" : "service1", -------- Name of the current service. A maximum of 32 bytes must be specified for the name. "path" : "/bin/process1" -------- Full path of the executable file of the current service. A maximum of 64 bytes must be specified for the path. - "uid" : 1, -------- UID of the current service process - "gid" : 1, -------- GID of the current service process - "once" : 0, -------- Whether the current service process is a one-off process - 0 --- The current service process is not a one-off process. If the process exits due to any reason, the init module restarts the service process upon receiving the SIGCHLD signal. - non-0 --- The current service is a one-off process. If the process exits due to any reason, the init module does not restart the service process. - "importance" : 1, -------- Whether the current service is a key system process - 0 --- The current service is not a key system process. If the process exits due to any reason, the init module does not reset the system. - non-0 --- The current service is a key system process. If the process exits due to any reason, the init module resets and restarts the system upon receiving the SIGCHLD signal. - "caps" : [0, 1, 2, 5] -------- Capabilities required by the current service. They are evaluated based on the capabilities supported by the security subsystem and configured in accordance with the principle of least permission. + "uid" : 1, -------- UID of the current service process. + "gid" : 1, -------- GID of the current service process. + "once" : 0, -------- Whether the current service process is a one-off process. + 0 --- The current service process is not a one-off process. If the process exits for a certain reason, the init_lite module restarts the service process upon receiving the SIGCHLD signal. + non-0 --- The current service process is a one-off process. If the process exits for a certain reason, the init_lite module does not restart the service process. + "importance" : 1, -------- Whether the current service process is a key system process + 0 --- The current service process is not a key system process. If the process exits due to any reason, the init_lite module does not reset the system. + non-0 --- The current service process is a key system process. If the process exits due to any reason, the init_lite module resets and restarts the system upon receiving the SIGCHLD signal. + "caps" : [0, 1, 2, 5] -------- Capabilities required by the current service. They are determined by the capabilities supported by the security subsystem and configured in accordance with the principle of least permission. (Currently, a maximum of 100 values can be configured.) }, { - "name" : "service2", -------- Next service that needs to be started by the init module. The service sequence is irrelevant to the startup sequence, which is determined by the cmd sequence in the previous job. + "name" : "service2", -------- Next service that needs to be started by the init_lite module. The service sequence is irrelevant to the startup sequence, which is determined by the command sequence in the previous job. "path" : "/bin/process2", "uid" : 2, "gid" : 2, @@ -203,32 +180,28 @@ After the init process starts, it reads the **/etc/init.cfg** file, parses the

start

start ServiceName

-

Only one space is allowed.

+

start ServiceName (Only one space is allowed.)

Starts a service. The service name must be the same as that in the services array in the file.

+

Starts a service. The service name must be the same as that in the services array in the file.

mkdir

mkdir /xxxx/xxx

-

Only one space is allowed.

+

mkdir /xxxx/xxx (Only one space is allowed.)

Creates a directory.

chmod

chmod 0xxx /xxx/xx

-

Only one space is allowed.

+

chmod 0xxx /xxx/xx (Only one space is allowed.)

Changes the permission. The permission value must be in 0xxx format, for example, 0755 and 0600. This configuration must comply with the principle of least permission.

chown

chown uid gid /xxx/xx

-

Only one space is allowed.

+

chown uid gid /xxx/xx (Only one space is allowed.)

Changes the owner group.

mount fileSysType source target flags data

Only one space is allowed.

Mounts data. Currently, flags supports only nodev, noexec, nosuid, and rdonly, and other strings are considered as data.

+

Mounts data. Currently, flags supports only nodev, noexec, nosuid, and rdonly, and other strings are considered as data.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Name

-

Description

-

developertest

-

Development test framework

-

developertest/src

-

Test framework source code

-

developertest/src/core

-

Test executor

-

developertest/src/core/build

-

Test case compilation

-

developertest/src/core/command

-

Processing of command lines entered by users

-

developertest/src/core/config

-

Test framework configuration management

-

developertest/src/core/driver

-

Test framework driver executor

-

developertest/src/core/resource

-

Test framework configuration file

-

developertest/src/core/testcase

-

Test case management

-

developertest/src/core/common.py

-

Common operations on the test framework

-

developertest/src/core/constants.py

-

Global constants of the test framework

-

developertest/src/core/exception.py

-

Test framework exceptions

-

developertest/src/core/utils.py

-

Test framework tools and methods

-

developertest/src/main

-

Test framework platform

-

developertest/src/main/__main__.py

-

Internal entrance of the test framework

-

developertest/example

-

Test framework demo cases

-

developertest/third_party

-

Third-party components

-

developertest/BUILD.gn

-

Compilation configuration of the test subsystem

-

developertest/start.bat

-

Developer test entry (Windows)

-

developertest/start.sh

-

Developer test entry (Linux)

-
+``` +test/ +├── developertest # Developers test framework +│ ├── aw # Static library of the test framework +│ ├── config # Test framework configuration +│ ├── examples # Test case examples +│ ├── src # Source code of the test framework +│ ├── third_party # Adaptation code for third-party components on which the test framework depends +│ ├── start.bat # Developers test entry for Windows +│ ├── start.sh # Developers test entry for Linux +│ └── BUILD.gn # Build entry of the test framework +├── xdevice # Basic component of the test framework +│ ├── config # Framework configuration file +│ ├── extension # Extension repository for the basic component +│ ├── resource # Test resources of the basic component +│ └── src # Source code of the basic component +└── xts # X test suite +``` ## Constraints -Test tool environment dependency +The test tool environment must meet the following requirements: 1. Python version: 3.7.5 or later -2. NFS version: V4 or later -3. Windows: Windows 10 or later; Linux: Ubuntu 18.04 +2. Paramiko version: 2.7.1 or later +3. Setuptools version: 40.8.0 or later +4. RSA version: 4.0 or later +5. NFS version: V4 or later \(required when device supports connection using the serial port but not the hdc\) +6. pySerial version: 3.3 or later \(required when the device supports connection using the serial port but not the hdc\) +7. OS version: Windows 10 or later; Ubuntu 18.04 ## Installation -Depend on the Python environment. +- The Python environment is required. + 1. Run the following command to install the Linux extension component Readline: + + ``` + sudo apt-get install libreadline-dev + ``` + + If the installation is successful, the following prompts are displayed: + + ``` + Reading package lists... Done + Building dependency tree + Reading state information... Done + libreadline-dev is already the newest version (7.0-3). + 0 upgraded, 0 newly installed, 0 to remove and 11 not upgraded. + ``` + + 2. Run the following command to install the plug-in Setuptools: + + ``` + pip3 install setuptools + ``` + + If the installation is successful, the following prompts are displayed: + + ``` + Requirement already satisfied: setuptools in d:\programs\python37\lib\site-packages (41.2.0) + ``` + + 3. Run the following command to install the plug-in Paramiko: + + ``` + pip3 install paramiko + ``` + + If the installation is successful, the following prompts are displayed: + + ``` + Installing collected packages: pycparser, cffi, pynacl, bcrypt, cryptography, paramiko + Successfully installed bcrypt-3.2.0 cffi-1.14.4 cryptography-3.3.1 paramiko-2.7.2 pycparser-2.20 pynacl-1.4.0 + ``` + + 4. Run the following command to install the Python plug-in RSA: + + ``` + pip3 install rsa + ``` + + If the installation is successful, the following prompts are displayed: + + ``` + Installing collected packages: pyasn1, rsa + Successfully installed pyasn1-0.4.8 rsa-4.7 + ``` + + 5. Run the following command to install the serial port plug-in pySerial for Python on the local PC: + + ``` + pip3 install pyserial + ``` + + If the installation is successful, the following prompts are displayed: -Install the serial port plugins **pyserial** and **readline** on the local Python, and run the **pip install pyserial** and **sudo apt-get install libreadline-dev** commands on the shell. The following figure is displayed when the installation is complete. + ``` + Requirement already satisfied: pyserial in d:\programs\python37\lib\site-packages\pyserial-3.4-py3.7.egg (3.4) + ``` + + 6. If the device supports test result output only using the serial port, install the NFS server. + + For example, to install haneWIN NFS Server 1.2.50 for Windows, download the installation package from https://www.hanewin.net/nfs-e.htm. + + For Linux, run the following command: -![](figures/en-us_image_0000001052278423.png) + ``` + sudo apt install nfs-kernel-server + ``` + + If the installation is successful, the following prompts are displayed: -## Compiling Test Cases + ``` + Reading package lists... Done + Building dependency tree + Reading state information... Done + nfs-kernel-server is already the newest version (1:1.3.4-2.1ubuntu5.3). + 0 upgraded, 0 newly installed, 0 to remove and 11 not upgraded. + ``` + + + +## Test Cases - Test case specifications - Naming rules The source file name of the test case must be consistent with the test suite content. The relationship between the test suite and the test case is 1:N and the test suite and the test source file is 1:1. Each source file is globally unique and named in the format of \[Feature\]\_\[Function\]\_\[Subfunction 1\]\_\[Subfunction 1.1\]. Subfunctions can be further divided. - The file name consists of lowercase letters and underscores \(\_\) and ends with test, for example, **developertest/example/cxx\_demo**. + A source file name consists of lowercase letters and underscores \(\_\), and must end with **test**, for example, **developertest/examples**. - Test case coding specifications - The test cases must comply with the feature code coding specifications. In addition, necessary case description information must be added. For details, see [\#li2069415903917](#li2069415903917). + The test cases must comply with the feature code coding specifications. In addition, necessary case description information must be added. For details, see [Test case template](#li2069415903917). - Test case compilation and configuration specifications - The test cases are compiled in GN mode. The configuration must comply with the compilation guide of the open source project. For details, see [en-us\_topic\_0000001051580775.md](en-us_topic_0000001051580775.md). + The test cases are compiled in GN mode. The configuration must comply with the compilation guide of the open-source project. For details, see [Usage](en-us_topic_0000001051580775.md). - Test case template - For details, see the test case **demo** developertest/example/cxx\_demo/test/unittest/common/calc\_subtraction\_test.cpp. + For details, see the test case **developertest/examples**. - >![](public_sys-resources/icon-note.gif) **NOTE:** - >Feature: Description of the tested feature - >Function: Function of the tested feature - >SubFunction: Subfunction of the tested feature - >FunctionPoints: Function points to test - >EnvConditions: Environment and conditions of the feature to test - >CaseDescription: Test case description - >step: Procedure for executing the test case when the complex logic is tested - -- Directory plan for test cases +- Directories planned for test cases ``` - subsystem (subsystem, system component) - ├── module (module) - │ └── test (module test directory) - │ └── unittest (unit test) - │ ├── common (common test cases) - │ ├── liteos (only for LiteOS core test cases) - │ └── linux (only for Linux core test cases) - │ └── moduletest (module test) + subsystem # Subsystem and system module + ├── part # Components + │ └── test # Module test + │ └── unittest # Unit test + │ ├── common # Common test cases + │ ├── liteos # Test cases for the LiteOS kernel only + │ └── linux # Test cases for the Linux kernel only + │ └── moduletest # Module test │ ├── common │ ├── liteos │ └── linux - └── test (subsystem test directory) - └── unittest (unit test) + └── test # Subsystem test + └── unittest # Unit test ├── common ├── liteos ├── linux - └── moduletest (module test) + └── moduletest # Module test ├── common ├── liteos ├── linux - ``` - >![](public_sys-resources/icon-note.gif) **NOTE:** - >The LiteOS and Linux are used as examples only for different device models. For the same feature on different development boards, if the test cases are the same, they are stored in the **common** directory. For the same feature, if the test cases are used to distinguish different device models and may include kernel differences and chip platform differences, the test cases are distinguished by directory. + >![](public_sys-resources/icon-note.gif) **NOTE:** + >The **liteos** and **linux** test cases are used as examples only for different device forms. For the same feature on different development boards, if the test cases are the same, they are stored in the **common** directory. For the same feature, if the test cases are used to distinguish different device forms and may include kernel differences and chip platform differences, the test cases are distinguished by directory. -- Procedure for compiling test cases +- Writing a test case 1. Add comments to the test case header file. 2. Reference the **gtest** header file and **ext** namespace. 3. Add the header file to test. 4. Define test suites \(test classes\). 5. Implement specific test cases of the test suite, including test case comments and logic implementation. - 6. Compile the test case compilation configuration. + 6. Set the test case compilation configuration. - >![](public_sys-resources/icon-note.gif) **NOTE:** - >\* Example: developertest/example/cxx\_demo/test/unittest/common/calc\_subtraction\_test.cpp + >![](public_sys-resources/icon-note.gif) **NOTE:** + >The following examples are provided for reference: + >For devices supporting the serial port only: **developertest/examples/lite/cxx\_demo/test/unittest/common/calc\_subtraction\_test.cpp**. + >For devices supporting the hdc: **developertest/examples/calculator/test/unittest/common/calculator\_add\_test.cpp**. >Notes: >- **SetUp** and **TearDown** are the processing logic before and after each test case in the test suite is executed. >- **SetUpTestCase** and **TearDownTestCase** are the processing logic before and after all cases in the test suite are executed. @@ -211,57 +206,78 @@ Install the serial port plugins **pyserial** and **readline** on the local P >- Use the **printf** function to print logs. -- Compile a test case compilation file. +- Writing a test case compilation file - Define test case compilation and building objectives. 1. Add comments to the test case compilation header file. 2. Import the test case compilation template file. 3. Specify the output path of the test case file. 4. Configure the directory contained in the test case compilation dependency. 5. Specify the file name generated by the test case compilation target. - 6. Compile a specific test case compilation script and add the source files, configurations, and dependencies involved in the compilation. + 6. Write a specific test case compilation script and add the source files, configurations, and dependencies involved in the compilation. 7. Group the target test case files by condition. The group name is fixed to **unittest/moduletest**. - If there are multiple test suites, define the common compilation configuration. - Add test cases to the build system. - >![](public_sys-resources/icon-note.gif) **NOTE:** - >\* Example: developertest/example/cxx\_demo/test/unittest/common/BUILD.gn + >![](public_sys-resources/icon-note.gif) **NOTE:** + >The following examples are provided for reference: + >- Devices supporting serial port connection only + >Test case compilation configuration: **developertest/examples/lite/cxx\_demo/test/unittest/common/BUILD.gn** + >Compilation entry configuration: **developertest/examples/lite/BUILD.gn** + >- Devices supporting the hdc connection + >Test case compilation configuration: **developertest/examples/calculator/test/unittest/common/BUILD.gn** + >Compilation entry configuration: **developertest/examples/ohos.build** -- Test case level definition - - Basic \(Level 1\) - - Major \(Level 2\) - - Minor \(Level 3\) - - Uncommon \(Level 4\) +- Test case levels + - Basic \(level 1\) + - Major \(level 2\) + - Minor \(level 3\) + - Uncommon \(level 4\) -## Using Test Framework +## Test Framework Usage -- Install the basic framework **xdevice**. - 1. Open the **xdevice** installation directory, for example, **test/xdevice** in Windows. - 2. Open the console window and run the following command: +- Install the basic component **xdevice** of the framework. + 1. Open the XDevice installation directory, for example, **test/xdevice** in Windows. + 2. Open the console and run the following command: ``` python setup.py install ``` - 3. The following figure is displayed when the installation is complete. + If the installation is successful, the following prompts are displayed: - ![](figures/en-us_image_0000001054501634.png) + ``` + Installed d:\programs\python37\lib\site-packages\xdevice-0.0.0-py3.7.egg + Processing dependencies for xdevice==0.0.0 + Finished processing dependencies for xdevice==0.0.0 + ``` -- Modify the configuration of the basic framework **xdevice**. +- Configure the developers test module. + 1. For devices that support the Harmony device connector \(hdc\), modify the configuration file as follows: - File: xdevice/config/user\_config.xml + Inside the **** tags with the **type="usb-hdc"** attribute, configure the test device IP address and the matched hdc port. For example: - 1. \[device\] \# Configure the serial port information with the label IP camera, COM port, and baud rate. Example: + ``` + + 192.168.1.1 + 9111 + + + ``` + + 2. For devices that only support the serial port connection, modify the configuration file as follows: + + Inside the **** tags with the **label="ipcamera"** attribute, configure the serial port information, including the COM port and baud rate. For example: ``` COM1 cmd - 115200 + 115200 8 1 1 @@ -270,77 +286,78 @@ Install the serial port plugins **pyserial** and **readline** on the local P ``` -- Modify the configuration of the **developertest** component. + - Modify the configuration of the **developertest** module. \(Optional\) If a test case has been compiled, specify the compilation output path of the test case. In this case the test platform will not recompile the test case. - File: resource/config/user\_config.xml + Configuration file: **resource/config/user\_config.xml** - 1. \[test\_cases\] \# Specify the output path of the test case and the compilation output directory. Example: + 1. Specify the output path of the test case and the compilation output directory. Example: - ``` - - S:\out\ipcamera_hi3518ev300_liteos_a\test - - ``` + ``` + + /home/source_code/out/release/tests + + ``` - 2. \[NFS\] \# Specify the NFS mapping path. **host\_dir** is the NFS directory on the PC, and **board\_dir** is the directory created on the board. Example: + 2. For devices that support serial port connection only, specify the NFS directory for the PC \(**host\_dir**\) and the corresponding directory for the development board \(**board\_dir**\) between the **** tags. For example: + + ``` + + D:\nfs + user + + ``` - ``` - - D:\nfs - user - - ``` -- Check the environment before executing the test cases. - - The system image and file system have been burnt to a development board and are running properly on the development board. In system mode, for example, the device prompt **OHOS\#** is displayed during shell login. - - The development host is properly connected to the serial port of the development board, and the development host is properly connected to the serial port of the development board. +- Check that the test environment meets the following conditions: + - The system image and file system have been burnt into a development board and are running properly on the development board. In system mode, for example, the device prompt **OHOS\#** is displayed during shell login. + - The development host has been connected to the serial port of the development board and the network port. - The IP addresses of the development host and development board are in the same network segment and can ping each other. - An empty directory is created on the development host for mounting test cases through NFS, and the NFS service is started properly. - Run test suites. - Start the test framework and go to the **test/developertest** directory. - 1. Start the test framework on Windows. + 1. Run the following command to start the test framework in Windows. ``` start.bat ``` - 2. Start the test framework on Linux. + 2. Run the following command to start the test framework in Linux. ``` ./strat.sh ``` - - Select a device mode. + - Select a device form. - Configure device models based on the actual development board, for example, **developertest/src/core/resource/config/framework\_config.xml**. + Configure device forms based on the actual development board, for example, **developertest/config/framework\_config.xml**. - Run the test command. - 1. To query the subsystems, modules, product forms, and test types supported by test cases, run the **show** command. + 1. To query the subsystems, modules, product forms, and test types supported by test cases, run the **show** commands. ``` - usage: - show productlist Querying Supported Product Forms - show typelist Querying the Supported Test Type - show subsystemlist Querying Supported Subsystems - show modulelist Querying Supported Modules + usage: + show productlist Querying supported product forms + show typelist Querying the supported test type + show subsystemlist Querying supported subsystems + show modulelist Querying supported modules ``` - 2. The following example shows how to run the test command. **-t** is mandatory, and **-ss** and **-tm** are optional. + 2. Run the following command to execute the test \(**-t** is mandatory, and **-ss** and **-tm** are optional\): ``` run -t ut -ss test -tm example ``` - 3. Specify the parameters that can be used to execute the test suite corresponding to a specific feature or module. + 3. Specify the parameters that can be used to execute the test suite specific to a specified feature or module. ``` usage: run [-h] [-p PRODUCTFORM] [-t [TESTTYPE [TESTTYPE ...]]] [-ss SUBSYSTEM] [-tm TESTMODULE] [-ts TESTSUIT] - [-tc TESTCASE] [-tl TESTLEVEL] - + [-tc TESTCASE] [-tl TESTLEVEL] + optional arguments: -h, --help show this help message and exit -p PRODUCTFORM, --productform PRODUCTFORM Specified product form @@ -348,15 +365,15 @@ Install the serial port plugins **pyserial** and **readline** on the local P Specify test type(UT,MST,ST,PERF,ALL) -ss SUBSYSTEM, --subsystem SUBSYSTEM Specify test subsystem -tm TESTMODULE, --testmodule TESTMODULE Specified test module - -ts TESTSUIT, --testsuit TESTSUIT Specify test suit + -ts TESTSUIT, --testsuit TESTSUIT Specify test suite -tc TESTCASE, --testcase TESTCASE Specify test case -tl TESTLEVEL, --testlevel TESTLEVEL Specify test level ``` -- See the test framework help if needed. - - The help command is used to query test commands that are supported by the test platform. +- View test framework help if needed. + - Run the following command to query commands supported by the test platform: ``` help @@ -364,20 +381,18 @@ Install the serial port plugins **pyserial** and **readline** on the local P -- Exit the self-test platform. - - Run the following command to exit the test platform: - - ``` - quit - ``` +- Run the following command to exit the test platform: + ``` + quit + ``` -## Test Result and Log +## Test Result and Logs -- Test logs and test reports are generated after you execute test instructions in the test framework. +- Test logs and test reports are generated after you execute the test commands. - Test result - - The test result is displayed on the console. The root path of the test result is as follows: + - Reports are displayed on the console. The root directory of the test result is as follows: ``` reports/xxxx-xx-xx-xx-xx-xx @@ -389,32 +404,32 @@ Install the serial port plugins **pyserial** and **readline** on the local P result/ ``` - - Test case log + - Test case logs ``` log/plan_log_xxxx-xx-xx-xx-xx-xx.log ``` - - Test report summary + - Report summary ``` summary_report.html ``` - - Test report details + - Report details ``` details_report.html ``` -- Test framework log +- Test framework logs ``` reports/platform_log_xxxx-xx-xx-xx-xx-xx.log ``` -- Latest test report +- Latest test reports ``` reports/latest diff --git a/en/readme/update.md b/en/readme/update.md new file mode 100755 index 0000000000000000000000000000000000000000..7b6d135ba9c0f292997a833831ee1f18de9e9ffe --- /dev/null +++ b/en/readme/update.md @@ -0,0 +1,80 @@ +# Update + +- [Introduction](#section11660541593) +- [Directory Structure](#section1464106163817) +- [Constraints](#section1718733212019) +- [Usage](#section18867101215181) +- [Repositories Involved](#section68521336131912) + +## Introduction + +Over the Air \(OTA\) provides the remote device update capability. Your devices will be able to support OTA update through secondary development on the provided APIs. + +By providing unified update APIs externally, the update subsystem shields the differences of underlying chips. + +## Directory Structure + +``` +/base/update/ota_lite +├── frameworks # OTA update implementation, including update package parsing, verification, writing, and updating +├── interfaces/kits # External APIs for OTA update +├── hals # Chip adaptation code, for example, Hisilicon chip adaptation code is located at device\hisilicon\hardware\update +``` + +## Constraints + +The update subsystem is compiled using the C language. Currently, only the Hi3518E V300, Hi3516D V300, and Hi3861 development boards are supported. If you want to support devices that use other chips, you can implement the OpenHarmony integration APIs in the **vendor** directory. Currently, only the full-package update is supported. + +## Usage + +Add the dependency on the update subsystem. The following uses the Hi3516D V300 development board as an example. + +- Add **update** to the **subsystem\_list field in the vendor\\hisilicon\\ipcamera\_hi3516dv300\_liteos\\config.json** file, and add the following code under **subsystem\_list**: + + ``` + { + "subsystem": "update", + "components": [ + { "component": "hota", "features": [] } + ] + }, + ``` + + +- Add the **update.json** file to the **build\\lite\\components** directory. + + ``` + "components": [ + { + "component": "hota", + "description": "", + "optional": "false", + "dirs": [ + "base/update/ota_lite/frameworks", + "base/update/ota_lite/interfaces/kits" + ], + "targets": [ + "//base/update/ota_lite/frameworks:ota_lite" + ], + ... + ``` + + +- Add test code. For example, add **subsystem\_test** to the **base\\update\\ota\_lite\\frameworks\\BUILD.gn** file. + +- Run the following commands to compile the system. You can experience the OTA update function after flashing the system to the Hi3516 chip. + + ``` + hb set + hb build + ``` + + +## Repositories Involved + +Update subsystem + +update\_ota\_lite + +hmf/device/hisilicon/hardware + diff --git a/en/readme/utils-library.md b/en/readme/utils-library.md deleted file mode 100644 index e825caf83791854ea29892aebb240490d234004b..0000000000000000000000000000000000000000 --- a/en/readme/utils-library.md +++ /dev/null @@ -1,154 +0,0 @@ -# Utils Library - -## Overview - -The Utils library stores basic components of OpenHarmony. These basic components are used by OpenHarmony service subsystems and upper-layer applications. - -The Utils library provides the following capabilities on different platforms: - -- LiteOS Cortex-M \(Hi3861 platform\): KV stores, file operations, timers, and IoT peripheral control -- LiteOS Cortex-A \(Hi3516 and Hi3518 platforms\): KV stores, timers, and ACE JavaScript APIs - -## Directory Structure - -``` -utils/native/lite/ # Root directory of the Utils library -├── file # Implementation of the file interface -├── hals # HAL directory -│ └── file # Header files of the hardware abstraction layer for file operations -├── include # Files of external interfaces provided by the Utils library -├── js # ACE JavaScript API directory -│ └── builtin -│ ├── common -│ ├── deviceinfokit # Device information kit -│ ├── filekit # File kit -│ └── kvstorekit # KV store kit -├── kal # KAL directory -│ └── timer # KAL implementation of the timer -├── kv_store # KV store implementation -│ ├── innerkits # Internal KV store interfaces -│ └── src # KV store source file -└── timer_task # Timer implementation - -base/iot_hardware # IoT peripheral control -├── frameworks -│ └── wifiiot_lite # Implementation of the IoT peripheral control module -├── hals -│ └── wifiiot_lite # HAL interfaces -└── interfaces - └── kits # Interfaces of the IoT peripheral control module - -vendor/hisi/hi3861/hi3861_adapter/hals/iot_hardware # HAL for IoT peripheral control -└── wifiiot_lite # Implementation of the interfaces at the HAL -``` - -## Constraints - -The Utils library is developed using the C language. - -**Table 1** Capabilities and constraints of the Utils library - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Component

-

Platform

-

Description

-

Constraint

-

KV store

-

LiteOS Cortex-M and LiteOS Cortex-A

-

Provides KV storage for applications.

-

N/A

-

File operation

-

LiteOS Cortex-M

-

Provides unified file operation interfaces that can be used on different underlying chip components.

-

N/A

-

Timer

-

LiteOS Cortex-M and LiteOS Cortex-A

-

Provides unified timer operation interfaces that can be used on different underlying chip components.

-

N/A

-

IoT peripheral control

-

LiteOS Cortex-M

-

Provides the capability of performing operations for peripherals.

-		  
- -## Usage - -- **KV store** - - ``` - Obtaining an interface - char key1[] = "rw.sys.version"; - char value1[32] = {0}; - int ret = UtilsGetValue(key1, value1, 32); - - Setting the interface - char key14[] = "key_14"; - ret = UtilsSetValue(key14, defValue); - ``` - -- **File operation** - - ``` - // open && write - char fileName[] = "testfile"; - int fd = UtilsFileOpen(fileName, O_RDWR_FS | O_CREAT_FS | O_TRUNC_FS, 0); - printf("file handle = %d\n", fd); - int ret = UtilsFileWrite(fd, def, strlen(def)); - printf("write ret = %d\n", ret); - - // stat - int fileLen = 0; - ret = UtilsFileStat(fileName, &fileLen); - printf("file size = %d\n", fileLen); - - // seek - int fd1 = UtilsFileOpen(fileName, O_RDWR_FS, 0); - ret = UtilsFileSeek(fd1, 5, SEEK_SET_FS); - printf("lseek ret = %d\n", ret); - char buf[32] = {0}; - int readLen = UtilsFileRead(fd1, buf, 32); - ret = UtilsFileClose(fd1); - printf("read len = %d : buf = %s\n", readLen, buf); - - // delete - ret = UtilsFileDelete(fileName); - printf("delete ret = %d\n", ret); - ``` - - -## Repositories Involved - -iothardware\_frameworks\_wifiiot\_lite - -iothardware\_hals\_wifiiot\_lite - -iothardware\_interfaces\_kits\_wifiiot\_lite - -utils\_native\_lite - diff --git a/en/readme/utils.md b/en/readme/utils.md new file mode 100755 index 0000000000000000000000000000000000000000..9a3845717cfb25f8725fc6889d02898999d2b964 --- /dev/null +++ b/en/readme/utils.md @@ -0,0 +1,186 @@ +# Utils + +- [Overview](#section11660541593) +- [Directory Structure](#section1464106163817) +- [Usage](#section83091355151312) +- [Repositories Involved](#section6250105871917) + +## Overview + +The Utils repository stores basic components of OpenHarmony. These basic components are used by OpenHarmony subsystems and upper-layer applications. + +The Utils library provides the following capabilities on different platforms: + +- LiteOS Cortex-M \(Hi3861 platform\): key value \(KV\) store, file operations, timer, IoT peripheral control, and system attribute dumping +- LiteOS Cortex-A \(Hi3516 or Hi3518 platform\): KV store, timer, JavaScript APIs for device query and data storage, and system attribute dumping + +**Table 1** Utils capabilities + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Module

+

Platform

+

Description

+

KV store

+

LiteOS Cortex-M and LiteOS Cortex-A

+

Provides KV storage for applications.

+

File operation

+

LiteOS Cortex-M

+

Provides unified file operation interfaces that can be used on different underlying chip components.

+

Timer

+

LiteOS Cortex-M and LiteOS Cortex-A

+

Provides unified timer operation interfaces that can be used on different underlying chip components.

+

JavaScript API

+

LiteOS Cortex-A

+

Provides JavaScript APIs for obtaining device information and storing data.

+

IoT peripheral control

+

LiteOS Cortex-M

+

Provides the capability of performing operations for peripherals.

+

System attribute dumping

+

LiteOS Cortex-M and LiteOS Cortex-A

+

Provides the command line tool for dumping system attributes.

+
+ +## Directory Structure + +``` +utils/native/lite/ # Root directory +├── file # Implementation of the file system APIs +├── hals # HAL directory +│ └── file # Header files of the hardware abstraction layer for file operations +├── include # Header files of external APIs +├── js # JavaScript APIs +│ └── builtin +│ ├── common +│ ├── deviceinfokit # Device information kit +│ ├── filekit # File kit +│ └── kvstorekit # KV store kit +├── kal # KAL directory +│ └── timer # KAL implementation of the timer +├── kv_store # KV store implementation +│ ├── innerkits # Internal KV store APIs +│ └── src # KV store source file +├── memory +│ └── include # Memory pool management APIs +├── os_dump # System attribute dumping +├── timer_task # Timer implementation +└── unittest # Self-test cases + +base/iot_hardware # IoT peripheral control +├── frameworks +│ └── wifiiot_lite # Implementation of the IoT peripheral control module +├── hals +│ └── wifiiot_lite # HAL API declaration +└── interfaces + └── kits # APIs of the IoT peripheral control module + +vendor/hisi/hi3861/hi3861_adapter/hals/iot_hardware # HAL for IoT peripheral control +└── wifiiot_lite # Implementation of the APIs at the HAL +``` + +## Usage + +- **KV store** + + ``` + // Store or update the value of a key. + const char key1[] = "key_sample"; + const char defValue[] = "test case of key value store."; + int ret = UtilsSetValue(key1, defValue); + + // Obtain the value of the key. + char value1[32] = {0}; + ret = UtilsGetValue(key1, value1, 32); + + // Delete the value of the key. + UtilsDeleteValue(key1); + ``` + +- **File operation** + + ``` + // Open or create a file. + const char fileName[] = "testfile"; + int fd = UtilsFileOpen(fileName, O_RDWR_FS | O_CREAT_FS | O_TRUNC_FS, 0); + + // Write a specified length of data into a file with the specified file descriptor. + const char defValue[] = "test case of file system."; + int ret = UtilsFileWrite(fd, defValue, strlen(defValue)); + + // Close a file with a specified file descriptor. + UtilsFileClose(fd); + + // Obtain the file size. + int fileLen = 0; + ret = UtilsFileStat(fileName, &fileLen); + printf("file size = %d\n", fileLen); + + // Adjust the read and write position offset in a file. + int fd1 = UtilsFileOpen(fileName, O_RDWR_FS, 0); + ret = UtilsFileSeek(fd1, 5, SEEK_SET_FS); + + // Read a specified length of data from a file with the specified file descriptor and write the data into the buffer. + char buf[32] = {0}; + int readLen = UtilsFileRead(fd1, buf, 32); + ret = UtilsFileClose(fd1); + printf("read len = %d : buf = %s\n", readLen, buf); + + // Delete a specified file. + ret = UtilsFileDelete(fileName); + ``` + + +- **System attribute dumping** + + LiteOS Cortex-M kernel: Run the following command over the serial port to dump the current system parameters: + + ``` + AT+SYSPARA + ``` + + LiteOS Cortex-A kernel: Run the **os\_dump** command in the **bin** directory to dump the current system parameters: + + ``` + ./bin/os_dump syspara + ``` + + +## Repositories Involved + +iothardware\_frameworks\_wifiiot\_lite + +iothardware\_hals\_wifiiot\_lite + +iothardware\_interfaces\_kits\_wifiiot\_lite + +utils\_native\_lite + diff --git a/en/readme/x-test-suite-certification-subsystem.md b/en/readme/x-test-suite-certification-subsystem.md deleted file mode 100644 index d0bec47e1201841a1e0e88b055bd389862528806..0000000000000000000000000000000000000000 --- a/en/readme/x-test-suite-certification-subsystem.md +++ /dev/null @@ -1,423 +0,0 @@ -# X Test Suite Certification Subsystem - -## Overview - -X test suite is a set of OpenHarmony certification test suites, including the currently supported application compatibility test suite \(ACTS\) and the device compatibility test suite \(DCTS\) that will be supported in the future. - -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 to OpenHarmony during the entire development process. -- The **tools** software package stores the test case development framework related to **acts**. - -## Directory Structure - -The directory structure of the **test/xts** repository is as follows: - -├── acts - -│ ├── BUILD.gn \#Compilation configuration of test cases - -│ └── subsystem\_lite \# Test case source code - -└── tools - -│ └── build \#Templates and scripts related to test cases compilation - -│ └── hcpptest \#Source code of the development framework for SmartVision device \(IP camera\) test cases - -│ └── hctest \#Source code of the development framework for IoTLink module test cases - -│ └── BUILD.gn \#Compilation configuration - -│ └── build.sh \#Compiling entry - -## Constraints - -You must use the C language to develop IoTLink module ACTS cases, and C++ for SmartVision device \(IP camera\) ACTS cases. - -## ACTS Cases for the IoTLink Module - -The HCTest framework is used. - -The HCTest framework supports the C language and allows you to execute your test cases on the connecting module. The framework is enhanced and adapted based on the open-source test framework Unity. - -1. Store test cases in the **test/xts/acts** repository. - -├── acts - -│ ├── BUILD.gn - -│ └──subsystem\_lite - -│ │ └── module\_hal - -│ │ │ └── BUILD.gn - -│ │ │ └── src - -2. Write the test case stored in the **src** directory. - -\(1\) Import the test framework. - -``` -#include "hctest.h" -``` - -\(2\) Use the **LITE\_TEST\_SUIT** macro to define names of the subsystem, module, and test suite. - -``` -/** -* @brief register a test suit named "IntTestSuite" -* @param test subsystem name -* @param example module name -* @param IntTestSuite test suit name -*/ -LITE_TEST_SUIT(test, example, IntTestSuite); -``` - -\(3\) Define Setup and TearDown. - -Format: test suite name+Setup, test suite name+TearDown. - -The Setup and TearDown functions must exist, but function bodies can be empty. - -\(4\) Use the **LITE\_TEST\_CASE** macro to write the test case. - -Three parameters are involved: test suite name, test case name, and test case level. - -The case level can be one of the following: - -**Level0**, **Level1**, **Level2**, **Level3**, and **Level4**. - -``` -LITE_TEST_CASE(IntTestSuite, TestCase001, Level0) -{ - // Do something. -}; -``` - -The following table describes the case levels. - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Level

-

Definition

-

Testing Scope

-

Level0

-

Smoke

-

Verifies basic functionalities of key features and basic DFX attributes with the most common input. The pass result indicates that the features are runnable.

-

Level1

-

Basic

-

Verifies basic functionalities of key features and basic DFX attributes with common input. The pass result indicates that the features are testable.

-

Level2

-

Major

-

Verifies basic functionalities of key features and basic DFX attributes with common input and errors. The pass result indicates that the features are functional and ready for beta testing.

-

Level3

-

Regular

-

Verifies functionalities of all key features, and all DFX attributes with common and uncommon input combinations or normal and abnormal preset conditions.

-

Level4

-

Rare

-

Verifies functionalities of key features under extremely abnormal presets and uncommon input combinations.

-
- -\(5\) Use the **RUN\_TEST\_SUITE** macro to register the test suite. - -``` -RUN_TEST_SUITE(IntTestSuite); -``` - -3. Create the configuration file of the test module. - -Create a **BUILD.gn** \(example\) compilation file in each test module directory. Specify the name of the compiled static library and its dependent header file and library in the compilation file. The format is as follows: - -``` -import("//test/xts/tools/build/suite_lite.gni") -hctest_suite("ActsDemoTest") { - suite_name = "acts" - sources = [ - "src/test_demo.c", - ] - include_dirs = [ ] - cflags = [ "-Wno-error" ] -} -``` - -4. Add compilation options to the **BUILD.gn** file in the **acts** directory. - -You need to add the test module to the **test/xts/acts/BUILD.gn** script in the **acts** directory. - -``` -lite_component("acts") { - ... - if(board_name == "liteos_riscv") { - features += [ - ... - "//xts/acts/subsystem_lite/module_hal:ActsDemoTest" - ] - } -} -``` - -5. Run compilation commands. - -\(1\) **python build.py wifiiot -b debug** - -\(2\) **out/wifiiot** - -Note: The ACTS compilation middleware used for IoTLink modules is a static library, which will be linked to the version image **Hi3861\_wifiiot\_app\_allinone.bin**. - -## ACTS Cases for the SmartVision Device \(IP Camera\) - -The HCPP Test framework is enhanced and adapted based on the open-source googletest framework. - -1. Store test cases in the **test/xts/acts** repository. - -├── acts - -│ ├── BUILD.gn - -│ └──subsystem\_lite - -│ │ └── module\_posix - -│ │ │ └── BUILD.gn - -│ │ │ └── src - -2. Write the test case stored in the **src** directory. - -\(1\) Import the test framework. - -The following statement imports **gtest.h**. - -``` -#include "gtest/gtest.h" -``` - -\(2\) Define Setup and TearDown. - -``` -class TestSuite: public testing::Test { -protected: -// Preset action of the test suite, which is executed before the first test case -static void SetUpTestCase(void){ -} -// Test suite cleanup action, which is executed after the last test case -static void TearDownTestCase(void){ -} -// Preset action of the test case -virtual void SetUp() -{ -} -// Cleanup action of the test case -virtual void TearDown() -{ -} -}; -``` - -\(3\) Use the **HWTEST** or **HWTEST\_F** macro to write the test case. - -**HWTEST**: definition of common test cases, including the test suite name, test case name, and case marking. - -**HWTEST\_F**: definition of SetUp and TearDown test cases, including the test suite name, test case name, and case marking. - -A macro definition contains three parameters: test suite name, test case name, and test case level. - -The case level can be one of the following: - -**Level0**, **Level1**, **Level2**, **Level3**, and **Level4**. - -``` -HWTEST_F(TestSuite, TestCase_0001, Level0) { -// Do something. -} -``` - -The following table describes the case levels. - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Level

-

Definition

-

Testing Scope

-

Level0

-

Smoke

-

Verifies basic functionalities of key features and basic DFX attributes with the most common input. The pass result indicates that the features are runnable.

-

Level1

-

Basic

-

Verifies basic functionalities of key features and basic DFX attributes with common input. The pass result indicates that the features are testable.

-

Level2

-

Major

-

Verifies basic functionalities of key features and basic DFX attributes with common input and errors. The pass result indicates that the features are functional and ready for beta testing.

-

Level3

-

Regular

-

Verifies functionalities of all key features, and all DFX attributes with common and uncommon input combinations or normal and abnormal preset conditions.

-

Level4

-

Rare

-

Verifies functionalities of key features under extremely abnormal presets and uncommon input combinations.

-
- -3. Create the configuration file of the test module. - -Create a **BUILD.gn** \(example\) compilation file in each test module directory. Specify the name of the compiled static library and its dependent header file and library in the compilation file. Each test module is independently compiled into a **.bin** executable file, which can be directly mounted to the development board for testing. - -The following is an example: - -``` -import("//test/xts/tools/build/suite_lite.gni") - -hcpptest_suite("ActsDemoTest") { - suite_name = "acts" - sources = [ - "src/TestDemo.cpp" - ] - - include_dirs = [ - "src", - ... - ] - deps = [ - ... - ] - cflags = [ "-Wno-error" ] -} - -``` - -4. Add compilation options to the **BUILD.gn** file in the **acts** directory. - -You need to add the test module to the **test/xts/acts/BUILD.gn** script in the **acts** directory. - -``` - lite_component("acts") { -... -else if(board_name == "liteos_a") { - features += [ - ... - "//xts/acts/subsystem_lite/module_posix:ActsDemoTest" - ] - } -} -``` - -5. Run compilation commands. - -1.1 Hi3518EV300 - -\(1\) **python build.py ipcamera\_hi3518ev300 -b debug** - -\(2\) **out/ipcamera\_hi3518ev300** - -1.2 Hi3516DV300 - -\(1\) **python build.py ipcamera\_hi3516dv300 -b debug** - -\(2\) **out/ipcamera\_hi3516dv300** - -Note: The ACTS for the SmartVision device \(IP camera\) is independently compiled to a **.bin** executable file, which can be directly mounted to the development board for testing. - -## Executing ACTS Cases for the IoTLink Module - -1. Obtain the testing software package. - -Obtain the image from the **out\\wifiiot\\Hi3861\_wifiiot\_app\_allinone.bin** directory. - -Note: To check whether the ACTS is integrated into the current image, go to **out\\wifiiot\\Hi3861\_wifiiot\_app.map** to check whether the corresponding **.a** file is compiled. - -2. Burn the image into the development board. - -3. Perform testing. - -\(1\) Use a serial port tool to log in to the development board and save information about the serial port. - -\(2\) Restart the device and view serial port logs. - -4. Analyze the test result. - -View the serial port logs, and the format is as follows: - -The log for each test suite starts with **Start to run test suite:** and ends with **xx Tests xx Failures xx Ignored**. - -## Executing ACTS Cases for the SmartVision Device \(IP Camera\) - -Currently, test cases are shared by the NFS and mounted to the development board for execution. - -1. Set up the environment. - -1. Use a network cable or wireless network to connect the IP camera development board to your personal computer \(PC\). -2. Configure the IP address, subnet mask, and gateway for the IP camera development board. Ensure that the development board and the PC are in the same network segment. -3. Install and register the NFS server on the PC and start the NFS service. -4. Run the **mount** command for the IP camera development board to ensure that the development board can access NFS shared files on the PC. - - Format: **mount **_NFS server IP address_**:/**_NFS shared directory_**/**_IP camera development board directory_** nfs** - - Example: - - ``` - mount 192.168.1.10:/nfs /nfs nfs - ``` - - -2. Execute test cases. - -\(1\) Analyze serial port logs. - -\(2\) Run the **./**_Test module_**.bin** command to execute test cases of each test suite. - -## Repositories Involved - -xts\_acts - -xts\_tools\_lite - diff --git a/en/readme/x-test-suite.md b/en/readme/x-test-suite.md new file mode 100755 index 0000000000000000000000000000000000000000..8a554711b23a49f7ce0f021ee7a4dcc4a146c490 --- /dev/null +++ b/en/readme/x-test-suite.md @@ -0,0 +1,375 @@ +# X Test Suite + +- [Introduction](#section465982318513) +- [Devices](#section125090457443) +- [Directory Structure](#section161941989596) +- [Constraints](#section119744591305) +- [Usage Guidelines](#section137768191623) +- [Test Case Development Guidelines](#section3695134065513) + - [C-based Test Case Development and Compilation \(for Mini-System Devices\)](#section1551164914237) + - [C-based Test Case Execution \(for Mini-System Devices\)](#section10100701294) + +- [Repositories Involved](#section1371113476307) + +## Introduction + +The X test suite \(XTS\) subsystem contains a set of OpenHarmony certification test suites, including the currently supported application compatibility test suite \(ACTS\) and the device compatibility test suite \(DCTS\) that will be supported in the future. + +This subsystem contains the ACTS 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 to OpenHarmony during the entire development process. +- The **tools** software package stores the test case development framework related to **acts**. + +## Devices + +OpenHarmony supports the following device types: + +- **Mini-System Devices \(reference memory ≥ 128 KB\)** + + Such devices are equipped with MCU processors such as ARM Cortex-M and 32-bit RISC-V. They provide rich short-distance connection and peripheral bus access capabilities. Typical products include LinkIoT module devices and sensors in the smart home field. The LinkIoT module is usually used for smart Internet of Things \(IoT\) devices as the hardware module that implements connectivity functions. In the smart home field, the LinkIoT module is integrated into devices by vendors. For example, a LinkIoT module provides WLAN/Bluetooth access and data connection, and it usually communicates with the chip of smart home devices via a universal asynchronous receiver-transmitter \(UART\) or general-purpose input/output \(GPIO\) interface. + +- **Small-System Devices \(reference memory ≥ 1 MB\)** + + Such devices are equipped with application processors such as ARM Cortex-A. They provide higher security capabilities, standard graphics framework, and multimedia capabilities for video encoding and decoding. Typical products include IP cameras, electronic cat eyes, and routers in the smart home field, as well as event data recorders \(EDRs\) in the smart travel field. + + +## Directory Structure + +``` +/test/xts +├── acts # Test code +│ └── subsystem # Source code of subsystem test cases for large-system devices +│ └── subsystem_lite # Source code of subsystems test cases for mini- and small-system devices +│ └── BUILD.gn # Build configuration of test cases for large-system devices +│ └── build_lite # Build configuration of test cases for mini-and small-system devices +│ └── build_lite # Build configuration +└── tools # Test tool code +``` + +## Constraints + +Test cases for mini system devices must be developed based on C, and those for small system devices must be developed based on C++. + +## Usage Guidelines + +**Table 1** Test case levels + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Level

+

Definition

+

Scope

+

Level0

+

Smoke

+

Verifies basic functionalities of key features and basic DFX attributes with the most common input. The pass result indicates that the features are runnable.

+

Level1

+

Basic

+

Verifies basic functionalities of key features and basic DFX attributes with common input. The pass result indicates that the features are testable.

+

Level2

+

Major

+

Verifies basic functionalities of key features and basic DFX attributes with common input and errors. The pass result indicates that the features are functional and ready for beta testing.

+

Level3

+

Regular

+

Verifies functionalities of all key features, and all DFX attributes with common and uncommon input combinations or normal and abnormal preset conditions.

+

Level4

+

Rare

+

Verifies functionalities of key features under extremely abnormal presets and uncommon input combinations.

+
+ +**Table 2** Test case granularities + + + + + + + + + + + + + + + + + + + + +

Test Scale

+

Test Objects

+

Test Environment

+

LargeTest

+

Service functionalities, all-scenario features, and mechanical power environment (MPE) and scenario-level DFX

+

Devices close to real devices

+

MediumTest

+

Modules, subsystem functionalities after module integration, and DFX

+

Single device that is actually used. You can perform message simulation, but do not mock functions.

+

SmallTest

+

Modules, classes, and functions

+

Local PC. Use a large number of mocks to replace dependencies with other modules.

+
+ +**Table 3** Test types + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Type

+

Definition

+

Function

+

Tests the correctness of both service and platform functionalities provided by the tested object for end users or developers.

+

Performance

+

Tests the processing capability of the tested object under specific preset conditions and load models. The processing capability is measured by the service volume that can be processed in a unit time, for example, call per second, frame per second, or event processing volume per second.

+

Power

+

Tests the power consumption of the tested object in a certain period of time under specific preset conditions and load models.

+

Reliability

+

Tests the service performance of the tested object under common and uncommon input conditions, or specified service volume pressure and long-term continuous running pressure. The test covers stability, pressure handling, fault injection, and Monkey test times.

+

Security

+
  • Tests the capability of defending against security threats, including but not limited to unauthorized access, use, disclosure, damage, modification, and destruction, to ensure information confidentiality, integrity, and availability.
  • Tests the privacy protection capability to ensure that the collection, use, retention, disclosure, and disposal of users' private data comply with laws and regulations.
  • Tests the compliance with various security specifications, such as security design, security requirements, and security certification of the Ministry of Industry and Information Technology (MIIT).
+

Global

+

Tests the internationalized data and localization capabilities of the tested object, including multi-language display, various input/output habits, time formats, and regional features, such as currency, time, and culture taboos.

+

Compatibility

+
  • Tests backward compatibility of an application with its own data, the forward and backward compatibility with the system, and the compatibility with different user data, such as audio file content of the player and smart SMS messages.
  • Tests system backward compatibility with its own data and the compatibility of common applications in the ecosystem.
  • Tests software compatibility with related hardware.
+

User

+

Tests user experience of the object in real user scenarios. All conclusions and comments should come from the users, which are all subjective evaluation in this case.

+

Standard

+

Tests the compliance with industry and company-specific standards, protocols, and specifications. The standards here do not include any security standards that should be classified into the security test.

+

Safety

+

Tests the safety property of the tested object to avoid possible hazards to personal safety, health, and the object itself.

+

Resilience

+

Tests the resilience property of the tested object to ensure that it can withstand and maintain the defined running status (including downgrading) when being attacked, and recover from and adapt defense to the attacks to approach mission assurance.

+
+ +## Test Case Development Guidelines + +You should select the appropriate programming language and your target test framework to develop test cases for the devices to test. + +**Table 4** Test frameworks and test case languages for different devices + + + + + + + + + + + + + + + + + + + + + + + + +

Device Type

+

Test Framework

+

Language

+

Mini-system devices

+

HCTest

+

C

+

Small-system devices

+

HCPPTest

+

C++

+

Standard-system devices

+

HJUnit and HCPPTest

+

Java and C++

+

Large-system devices

+

HJUnit and HCPPTest

+

Java and C++

+
+ +### C-based Test Case Development and Compilation \(for Mini-System Devices\) + +**Developing test cases for mini-system devices** + +The HCTest framework is used to support test cases developed with the C language. HCTest is enhanced and adapted based on the open-source test framework Unity. + +1. Access the **test/xts/acts** repository where the test cases will be stored. + + ``` + ├── acts + │ └──subsystem_lite + │ │ └── module_hal + │ │ │ └── BUILD.gn + │ │ │ └── src + │ └──build_lite + │ │ └── BUILD.gn + ``` + +2. Write the test case in the **src** directory. + + 1 Import the test framework header file. + + ``` + #include "hctest.h" + ``` + + 2. Use the **LITE\_TEST\_SUIT** macro to define names of the subsystem, module, and test suite. + + ``` + /** + * @brief Registers a test suite named IntTestSuite. + * @param test Subsystem name + * @param example Module name + * @param IntTestSuite Test suite name + */ + LITE_TEST_SUIT(test, example, IntTestSuite); + ``` + + 3. Define Setup and TearDown. + + Format: Test suite name+Setup, Test suite name+TearDown. + + The Setup and TearDown functions must exist, but function bodies can be empty. + + 4. Use the **LITE\_TEST\_CASE** macro to write the test case. + + Three parameters are involved: test suite name, test case name, and test case properties \(including type, granularity, and level\). + + ``` + LITE_TEST_CASE(IntTestSuite, TestCase001, Function | MediumTest | Level1) + { + // Do something + }; + ``` + + 5. Use the **RUN\_TEST\_SUITE** macro to register the test suite. + + ``` + RUN_TEST_SUITE(IntTestSuite); + ``` + +3. Create the configuration file \(**BUILD.gn**\) of the test module. + + Create a **BUILD.gn** \(example\) compilation file in each test module directory. Specify the name of the compiled static library and its dependent header file and library in the compilation file. The format is as follows: + + ``` + import("//test/xts/tools/lite/build/suite_lite.gni") + hctest_suite("ActsDemoTest") { + suite_name = "acts" + sources = [ + "src/test_demo.c", + ] + include_dirs = [ ] + cflags = [ "-Wno-error" ] + } + ``` + +4. Add compilation options to the **BUILD.gn** file in the **acts** directory. + + You need to add the test module to the **test/xts/acts/build\_lite/BUILD.gn** script in the **acts** directory. + + ``` + lite_component("acts") { + ... + if(board_name == "liteos_m") { + features += [ + ... + "//xts/acts/subsystem_lite/module_hal:ActsDemoTest" + ] + } + } + ``` + +5. Run compilation commands. + + Test suites are compiled along with version compilation. The ACTS is compiled together with the debug version. + + >![](public_sys-resources/icon-note.gif) **NOTE:** + >The ACTS compiles middleware as a static library, which will be linked to the image. + + +### C-based Test Case Execution \(for Mini-System Devices\) + +**Executing test cases for mini-system devices** + +Burn the image into the development board. + +**Executing the test** + +1. Use a serial port tool to log in to the development board and save information about the serial port. +2. Restart the device and view serial port logs. + +**Analyzing the test result** + +View the serial port logs, whose format is as follows: + +The log for each test suite starts with **Start to run test suite:** and ends with **xx Tests xx Failures xx Ignored**. + +## Repositories Involved + +xts\_acts + +xts\_tools +