diff --git a/zh-cn/device-dev/porting/Readme-CN.md b/zh-cn/device-dev/porting/Readme-CN.md index 8d2c217aee92178f6eb562066e5bcac3465bb7f5..e838579f9185afdb7da4a1f1028dedd48793689f 100644 --- a/zh-cn/device-dev/porting/Readme-CN.md +++ b/zh-cn/device-dev/porting/Readme-CN.md @@ -22,21 +22,18 @@ repo init -u https://gitee.com/openharmony-sig/manifest.git -b master -m devboar ## 芯片移植指导 - 轻量系统芯片移植指导 - - 移植准备 - - [移植须知](porting-chip-prepare-knows.md) - - [编译构建适配流程](porting-chip-prepare-process.md) - - 内核移植 - - [移植概述](porting-chip-kernel-overview.md) - - [内核基础适配](porting-chip-kernel-adjustment.md) - - [内核移植验证](porting-chip-kernel-verify.md) - - 板级系统移植 - - [移植概述](porting-chip-board-overview.md) - - [板级驱动适配](porting-chip-board-driver.md) - - [HAL层实现](porting-chip-board-hal.md) - - [系统组件调用](porting-chip-board-component.md) - - [lwIP组件适配](porting-chip-board-lwip.md) - - [三方组件适配](porting-chip-board-bundle.md) - - [XTS认证](porting-chip-board-xts.md) + - [概述](porting-minichip-overview.md) + - [移植准备](porting-minichip-prepare.md) + - [移植内核](porting-minichip-kernel.md) + - 移植子系统 + - [移植子系统概述](porting-minichip-subsys-overview.md) + - [移植启动恢复子系统](porting-minichip-subsys-startup.md) + - [移植文件子系统](porting-minichip-subsys-filesystem.md) + - [移植安全子系统](porting-minichip-subsys-security.md) + - [移植通信子系统](porting-minichip-subsys-communication.md) + - [移植外设驱动子系统](porting-minichip-subsys-driver.md) + - [配置其他子系统](porting-minichip-subsys-others.md) + - [移植验证](porting-minichip-verification.md) - [常见问题](porting-chip-faqs.md) - 小型系统芯片移植指导 - 移植准备 diff --git a/zh-cn/device-dev/porting/figures/zh-cn_image_0000001378282213.png b/zh-cn/device-dev/porting/figures/zh-cn_image_0000001378282213.png new file mode 100644 index 0000000000000000000000000000000000000000..ac8aec399dec95557fe4956a97c07d340cca37e6 Binary files /dev/null and b/zh-cn/device-dev/porting/figures/zh-cn_image_0000001378282213.png differ diff --git a/zh-cn/device-dev/porting/figures/zh-cn_image_0000001378481233.png b/zh-cn/device-dev/porting/figures/zh-cn_image_0000001378481233.png new file mode 100644 index 0000000000000000000000000000000000000000..662b54c3c5549b8d473aa89c930f84d8290066b2 Binary files /dev/null and b/zh-cn/device-dev/porting/figures/zh-cn_image_0000001378481233.png differ diff --git a/zh-cn/device-dev/porting/porting-minichip-kernel.md b/zh-cn/device-dev/porting/porting-minichip-kernel.md new file mode 100644 index 0000000000000000000000000000000000000000..b7917d9fff8183b0721bfa750f12b52739618197 --- /dev/null +++ b/zh-cn/device-dev/porting/porting-minichip-kernel.md @@ -0,0 +1,262 @@ +# 移植内核 + + +## 移植芯片架构 + +芯片架构的移植是内核移植的基础，在OpenHarmony中芯片架构移植是可选过程，如果当前OpenHarmony已经支持对应芯片架构则不需要移植操作，在“liteos_m/arch”目录下可看到当前已经支持的架构，如表1： + + **表1** OpenHarmony已支持的架构 + +| **系列** | **型号** | +| -------- | -------- | +| arm | arm9
cortex-m3
cortex-m4
cortex-m7
cortex-m33 | +| csky | v2 | +| risc-v | nuclei
riscv32 | +| xtensa | lx6 | + + +如果当前OpenHarmony尚未支持对应芯片架构，则需要芯片厂商自行适配，arch/include目录包含了通用的芯片架构适配所需要实现的函数。部分芯片架构代码由汇编实现，而汇编代码会因编译器的不同而不同，因此在具体的芯片架构下，还包含使用不同编译器（iar、keil、gcc等）编译的架构代码。 + + + +``` +kernel/liteos_m/arch # 不同版本路径有差异 +├── arm # arm系列 +│ ├── arm9 +│ ├── cortex-m3 +│ ├── cortex-m33 +│ │ ├── gcc # 使用gcc编译器编译的架构代码 +│ │ └── iar # 使用iar编译器编译的架构代码 +│ ├── cortex-m4 +│ ├── cortex-m7 +├── csky # csky系列 +├── include # 包含通用的芯片架构所需要实现的函数 +│ ├── los_arch.h # 定义芯片架构初始化所需要的函数 +│ ├── los_atomic.h # 定义芯片架构所需要实现的原子操作函数 +│ ├── los_context.h # 定义芯片架构所需要实现的任务上下文相关函数 +│ ├── los_interrupt.h # 定义芯片架构所需要实现的中断和异常相关的函数 +│ └── los_timer.h # 定义芯片架构所需要实现的系统时钟相关的函数 +├── risc-v # risc-v系列 +│ ├── nuclei +│ └── riscv32 +└── xtensa # xtensa系列 + └── lx6 +``` + + +## 移植芯片厂商SDK + +编译框架搭建完成后，需要将芯片厂商的SDK加入OpenHarmony编译框架，从而可以编译出带SDK的烧录文件（此时编译出的是不带系统的裸机工程），以便OpenHarmony可以调用SDK中的接口。通过以下步骤将厂商SDK加入OpenHarmony编译框架中： + +1. 将芯片厂商sdk置于device目录下合适的位置，SDK的编译脚本/镜像打包脚本整合进编译框架中。 + 参考编译脚本：“device/MyDeviceCompany/MyBoard/BUILD.gn” + + + ``` + import("//build/lite/config/component/lite_component.gni") + + executable("OHOS_Image.elf") { # 生成可执行程序 + libs = [ + "xxx/xxx/libxxx.a", # 链接厂商闭源静态库方法一 + ] + asmflags = [ # 汇编编译参数 + "", + ] + ldflags = [ + "-T./xxx/xxx/xxx.ld", # 链接脚本文件 + "-Lxxx/xxx/", # 指定厂商静态库路径 + "-lxxx", # 链接厂商闭源静态库方法二 + "-Wl,--whole-archive", + "-lmodule_xxx", + "-Wl,--no-whole-archive", + ] + deps = [ + "//build/lite:ohos", # 依赖OpenHarmony静态库编译完成，链接OpenHarmony编译出来的静态库 + ":sdk", # 依赖厂商源码静态库编译完成，链接厂商源码生成的静态库 + ] + } + + copy("prebuilt") { # 准备镜像生成工具等，一般把镜像生成工具拷贝到out目录 + sources = [ ] # 复制的源文件 + outputs = [ ] # 复制的目标文件 + } + static_library("sdk") { + sources = [ ] # 添加厂商源码编译成静态库 + include_dirs = [ ] # 厂商源码包含头文件路径 + } + build_ext_component("image") { # 调用shell命令，生成可烧写镜像文件 + exec_path = rebase_path(root_out_dir) #指定shell命令执行目录 + objcopy = "arm-none-eabi-objcopy" + objdump = "arm-none-eabi-objdump" + command = "$objcopy -O binary OHOS_Image.elf OHOS_Image.bin" + command += " && sh -c '$objdump -t OHOS_Image.elf | sort > OHOS_Image.sym.sorted'" + command += " && sh -c '$objdump -d OHOS_Image.elf > OHOS_Image.asm'" + deps = [ + ":prebuilt", # 无需准备镜像生成工具等可以删除此依赖 + ":OHOS_Image.elf", # 依赖elf文件的生成 + ] + } + group("MyBoard") { # MyBoard与当前路径名称一致 + } + ``` + + **图1** 目标的依赖执行顺序   + ![zh-cn_image_0000001378481233](figures/zh-cn_image_0000001378481233.png) + +1. 自定义芯片厂“target_config.h”文件。 + 厂商应在“device/MyDeviceCompany/MyBoard”下合适位置创建内核配置文件“target_config.h”，并根据芯片的硬件资源修改参数（具体参数介绍详见表2target_config.h文件主要配置项）。 + + 参考文件路径：“device/hisilicon/hispark_pegasus/sdk_liteos/platform/os/Huawei_LiteOS/targets/hi3861v100/include/target_config.h” + + > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** + > 1. 若已有的配置项不能满足需求，可查看“kernel/liteos_m/kernel/include/los_config.h”，其为liteos_m内核的全量配置文件。 + > + > 2. “target_config.h”文件中出现的配置将会覆盖“los_config.h”中的配置。 + + **表2** target_config.h文件主要配置项 + + | 配置项 | 说明 | 参考值 | + | -------- | -------- | -------- | + | OS_SYS_CLOCK | 系统时钟。 | 40000000UL | + | LOSCFG_BASE_CORE_TICK_PER_SECOND | 操作系统节拍的时钟周期。 | 100UL | + | LOSCFG_BASE_CORE_TICK_HW_TIME | 定时器裁剪的外部配置项。 | YES | + | LOSCFG_PLATFORM_HWI | 是否采用接管中断的方式。 | YES | + | LOSCFG_BASE_CORE_TSK_LIMIT | 支持的最大任务个数（除去空闲任务）。 | 32 | + | LOSCFG_BASE_CORE_TSK_IDLE_STACK_SIZE | 空闲任务的堆栈大小。 | 0x180UL | + | LOSCFG_BASE_CORE_TSK_DEFAULT_STACK_SIZE | 指定默认的任务栈大小，任务栈的大小按 8 字节大小对齐。 | 0x1000UL | + | LOSCFG_BASE_CORE_TSK_MIN_STACK_SIZE | 表示任务最小需要的堆栈大小。 | ALIGN(0x180, 4) | + | LOSCFG_BASE_CORE_TIMESLICE_TIMEOUT | 具有相同优先级任务的最长执行时间。 | 2 | + | LOSCFG_BASE_IPC_SEM_LIMIT | 最大支持信号量的个数。 | 100 | + | LOSCFG_BASE_IPC_MUX_LIMIT | 最大支持互斥量的个数。 | 64 | + | LOSCFG_BASE_IPC_QUEUE_LIMIT | 最大支持消息队列量的个数。 | 64 | + | LOSCFG_BASE_CORE_SWTMR_LIMIT | 支持的最大软件定时器数量，而不是可用的软件定时器数量。 | 80 | + | LOSCFG_BASE_MEM_NODE_SIZE_CHECK | 配置内存节点大小检查。 | NO | + | LOSCFG_PLATFORM_EXC | 异常模块配置项。 | YES | + | LOSCFG_USE_SYSTEM_DEFINED_INTERRUPT | 是否使用OS默认的中断。 | NO | + +1. 修改内核中断。 + 内核提供了两种中断修改方式： + + 1. 使用厂商默认中断。 + + 将“target_config.h”中的宏"LOSCFG_USE_SYSTEM_DEFINED_INTERRUPT"置为NO (0)，但需要在xxx.s启动文件中作以下修改: + + - PendSV_Handler：厂商sdk自带中断入口函数，需要替换为OpenHarmony的接口HalPendSV; + - SysTick_Handler：厂商sdk自带时钟中断入口函数，需要替换为OpenHarmony的接口OsTickHandler。 + + 1. 系统初始化时重定向中断。 + + 将“target_config.h”中的宏"LOSCFG_USE_SYSTEM_DEFINED_INTERRUPT"和"LOSCFG_PLATFORM_HWI"置为YES (1)。 + + > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** + > 重定向后的中断向量表g_hwiForm需要根据arch手册要求进行字节对齐，通常0x200字节对齐。 + + +## 添加内核子系统 + +添加完内核子系统后，可以编译出带有系统的工程。通过以下步骤添加内核子系统： + +1. 在“config.json”中添加内核子系统。 + 路径：“vendor/MyVendorCompany/MyProduct/config.json” + + 修改如下： + + ``` + { + "subsystem": "kernel", # 添加内核子系统 + "components": [ + { + "component": "liteos_m", "features":[""] + } + ] + }, + ``` + +2. 开启/关闭内核特性。 + 轻量级系统的内核提供了一些特性，此步骤将指导如何查看、开启/关闭这些特性。 + + 内核特性：liteos_m提供了包括文件系统、backtrace在内的一系列内核特性开关。 + + 路径：“kernel/liteos_m/BUILD.gn” + + + ``` + declare_args() { + enable_ohos_kernel_liteos_m_cppsupport = true # cpp支持 + enable_ohos_kernel_liteos_m_cpup = true # cpu占用率支持 + enable_ohos_kernel_liteos_m_exchook = true # 异常处理支持 + enable_ohos_kernel_liteos_m_kal = true # kal接口支持 + enable_ohos_kernel_liteos_m_fs = true # 文件系统支持 + enable_ohos_kernel_liteos_m_backtrace = true # backtrace支持 + } + group("kernel") { + deps = [ + "components/bounds_checking_function:sec", + "kernel:kernel", + "utils:utils", + ] + if (enable_ohos_kernel_liteos_m_cppsupport == true) { + deps += [ "components/cppsupport:cppsupport" ] # 如果内核特性true，则会加入相应的代码进行编译 + } + …… + if (enable_ohos_kernel_liteos_m_kal == true) { + deps += [ "kal:kal" ] + } + } + ``` + + 特性：可以选择cmsis接口或者posix接口支持。 + + 路径：“kernel/liteos_m/kal/BUILD.gn” + + + ``` + declare_args() { + enable_ohos_kernel_liteos_m_cmsis = true # cmsis支持 + enable_ohos_kernel_liteos_m_posix = true # posix支持 + } + static_library("kal") { + sources = [ "kal.c" ] + if (enable_ohos_kernel_liteos_m_cmsis == true) { + deps += [ "cmsis/" ] # 如果cmsis enable，加入cmsis目录编译 + } + if (enable_ohos_kernel_liteos_m_posix == true) { + deps += [ "posix/" ] # 如果posix enable，加入posix目录编译 + } + } + ``` + + 特性：可以选择fatfs支持。 + + 路径：“kernel/liteos_m/components/fs/BUILD.gn” + + + ``` + declare_args() { + enable_ohos_kernel_liteos_m_fatfs = true # fatfs支持 + } + group("fs") { + deps = [] + if (enable_ohos_kernel_liteos_m_fatfs == true) { + deps += [ "fatfs:fatfs" ] + } + } + ``` + + > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** + > 内核特性开关可以在具体产品模组中配置。例如关闭fs和cppsupport特性 + > + > “vendor/MyVendorCompany/MyProduct/config.json” + > + > + > ``` + > "subsystem": "kernel", + > "components": [ + > { + > "component": "liteos_m", + > "features":["enable_ohos_kernel_liteos_m_fs = false", + > "enable_ohos_kernel_liteos_m_cppsupport = false"] + > } + > ] + > } + > ``` diff --git a/zh-cn/device-dev/porting/porting-minichip-overview.md b/zh-cn/device-dev/porting/porting-minichip-overview.md new file mode 100644 index 0000000000000000000000000000000000000000..2b0ad4f6134ff6db5ae706409705a9fa70a5bff3 --- /dev/null +++ b/zh-cn/device-dev/porting/porting-minichip-overview.md @@ -0,0 +1,50 @@ +# 概述 + + +本文档从芯片适配的端到端视角，为芯片/模组制造商提供基于OpenHarmony的芯片适配指导。典型的芯片架构，例如cortex-m、risc-v系列都可以按照本文档进行适配移植。 + + +## 约束与限制 + +本文档适用于OpenHarmony LTS 3.0.1及之前版本的轻量系统的适配。 + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 本文仅对OpenHarmony移植适配过程中需要关注的文件和配置项进行介绍，其他文件以及配置项开发者无需关注，故不作详细介绍。 + + +## 适配流程 + + 主要开展基于伙伴硬件平台面向OpenHarmony系统的移植适配工作，具体细分为：移植准备、移植内核、移植子系统和移植验证四个环节，见表1芯片适配步骤。 + + **表1** 芯片适配步骤 + +| 步骤 | 介绍 | +| -------- | -------- | +| 移植准备 | 从OpenHarmony开源社区下载代码，并完成编译环境搭建，基于此初步熟悉和了解OpenHarmony的编译构建框架。 | +| 移植内核 | 将伙伴的SDK移植到OpenHarmony平台，同时根据芯片arch支持情况确认是否需要开展arch的适配工作。 | +| 移植子系统 | 开展包括启动子系统、文件子系统、安全子系统、通信子系统和外设驱动的移植。 | +| 移植验证 | 在适配完成之后使用OpenHarmony社区提供的兼容性测试套件对适配的工程进行基本接口的测试验证，同时伙伴需要使用自有测试能力对适配工程开展质量验证活动。 | + + + **图1** 业务总体流程  + + +  ![zh-cn_image_0000001378282213](figures/zh-cn_image_0000001378282213.png) + + +## 基本概念 + + **表2** 基本概念 + +| 名词 | 介绍 | +| -------- | -------- | +| 子系统 | 是一个逻辑概念，它由一个或多个具体的组件组成。OpenHarmony整体遵从分层设计，从下向上依次为：内核层、系统服务层、框架层和应用层。系统功能按照“系统 > 子系统 > 组件”逐级展开，在多设备部署场景下，支持根据实际需求裁剪某些非必要的子系统或组件。 | +| 部件 | 系统最小的可复用、可配置、可裁剪的功能单元。部件具备目录独立可并行开发、可独立编译、可独立测试的特征。 | +| hb | OpenHarmony的命令行工具，用来执行编译命令。 | +| DP平台 | Devicepartner缩写，即华为智能硬件合作伙伴平台，为生态合作伙伴提供产品开发、认证、发布等一站式服务的平台。 | +| IR平台 | Developers IssueReporter缩写，是由华为运营的、面向所有华为开发者用户的产品服务平台。 | +| HOBT | HiLink SDK OHOS Basic Test缩写，是HiLink SDK 接入 OpenHarmony的基础功能测试，检验HiLink SDK依赖的相关接口功能是否完善。 | +| Token | 伙伴从[合作伙伴平台](https://devicepartner.huawei.com/cn/)申请的设备身份凭据，每个设备唯一；需要在产线上逐个设备写入，用来标识设备是经过华为授权的。 | +| Kit Framework | Kit Framework是Kit的基础框架，包含了OpenHarmony的安全组件，不可裁剪。 | +| HiLink SDK | HarmonyOS Connect套件的一个关键组成部分，用于实现设备的联网，以及设备与HarmonyOS Connect云和智慧生活App的互联互通。 | +| kv | 键值对(key-value)，描述数据存储的格式。 | diff --git a/zh-cn/device-dev/porting/porting-minichip-prepare.md b/zh-cn/device-dev/porting/porting-minichip-prepare.md new file mode 100644 index 0000000000000000000000000000000000000000..2060fa754d05290ea298c675f1c03f0e6972dfea --- /dev/null +++ b/zh-cn/device-dev/porting/porting-minichip-prepare.md @@ -0,0 +1,215 @@ +# 移植准备 + + +由于OpenHarmony工程需要在Linux环境下进行编译，此章节将指导厂商搭建OpenHarmony的编译环境、获取OpenHarmony源码，并且创建厂商工作目录完成厂商芯片的编译框架适配。 + + +## 搭建编译环境 + +开展移植前请参考[开发环境准备](https://gitee.com/openharmony/docs/blob/master/zh-cn/device-dev/quick-start/quickstart-lite-env-setup.md)完成环境搭建工作。 + + +## 获取源码 + + +### 获取操作 + +请参考[获取源码](https://gitee.com/openharmony/docs/blob/master/zh-cn/device-dev/get-code/sourcecode-acquire.md)完成源码下载并进行编译。 + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 本文档仅适用于OpenHarmony LTS 3.0.1及之前版本，所以请获取对应版本的源码。 + + +### 目录介绍 + +OpenHarmony源码重要目录介绍见表1 OpenHarmony重要目录，其中device和vendor目录为芯片厂商和终端模组厂商工作区域（在[搭建编译框架](#搭建编译框架)部分详细介绍）。 + + **表1** OpenHarmony重要目录 + +| 目录 | 用途 | +| -------- | -------- | +| build | 编译框架所在目录。 | +| kernel/liteos_m | 内核所在的目录，其中arch目录描述支撑的内核架构。 | +| device | 芯片厂商适配目录，其中“config.gni”描述当前芯片使用的arch，工具链，编译链接选项等。 | +| vendor | 终端模组厂商适配目录，其中“config.json”描述需要集成的OpenHarmony子系统列表。 | +| utils | file，kv等相关的适配。 | + + +## 搭建编译框架 + +厂商开展移植工作时，需要在工程中按照公司名、芯片型号、开发板型号等创建工作目录，并且将所创目录加入到OpenHarmony的编译框架中，使厂商的工作目录能够参与编译，开发者可参照以下步骤进行操作。 + +1. 新增芯片厂商。 + 基于某款芯片进行OpenHarmony的适配，需要在device目录下创建芯片厂商目录，目录内文件描述内核类型，编译工具链，编译链接选项，内核配置选项等。 + + 创建目录规则：“device/{芯片厂商}/{芯片开发板}”。 + + 例：“device/MyDeviceCompany/MyBoard” + + ``` + device + ├── hisilicon # hisilicon芯片相关目录，创建目录时可供参考 + ├── MyDeviceCompany # MyDeviceCompany 芯片厂商 + │ └── MyBoard # MyBoard 芯片型号 + │ ├── BUILD.gn + │ ├── liteos_m + │ │ └── config.gni # 芯片工具链，编译链接选项 + │ └── target_config.h # 内核配置选项 + └── qemu # qemu相关 + ``` + + 编译脚本：将“device/MyDeviceCompany/MyBoard”下的文件添加到OpenHarmony编译框架中。 + + 路径：“device/MyDeviceCompany/MyBoard/BUILD.gn” + + + ``` + group("MyBoard") { #将此BUILD.gn文件加入解析 + print("MyDeviceCompany MyBoard is under developing.") + } + ``` + + 开发板编译配置：包括内核类型、工具链类型以及编译参数等内容（详见表2“config.gni”主要配置项）。 + + 路径：“device/MyDeviceCompany/MyBoard/liteos_m/config.gni” + + + ``` + # Kernel type, e.g. "linux", "liteos_a", "liteos_m". + kernel_type = "liteos_m" + + # Kernel version. + kernel_version = "" + + # Board CPU type, e.g. "cortex-a7", "riscv32". + board_cpu = "cortex-m4" + + # Board arch, e.g. "armv7-a", "rv32imac". + board_arch = "" + + # Toolchain name used for system compiling. + # E.g. gcc-arm-none-eabi, arm-linux-harmonyeabi-gcc, ohos-clang, riscv32-unknown-elf. + # Note: The default toolchain is "ohos-clang". It's not mandatory if you use the default toochain. + board_toolchain = "arm-none-eabi-gcc" + + # The toolchain path instatlled, it's not mandatory if you have added toolchian path to your ~/.bashrc. + board_toolchain_path = "" + + # Compiler prefix. + board_toolchain_prefix = "arm-none-eabi-" + + # Compiler type, "gcc" or "clang". + board_toolchain_type = "gcc" + + # Board related common compile flags. + board_cflags = [] + board_cxx_flags = board_cflags + board_ld_flags = [] + + # Board related headfiles search path. + board_include_dirs = [] + + # Board adapter dir for OHOS components. + board_adapter_dir ="" + ``` + + **表2** “config.gni”主要配置项 + + | 配置项 | 介绍 | + | -------- | -------- | + | kernel_type | 开发板使用的内核类型，例如：“liteos_a”,“liteos_m”,“linux”。 | + | kernel_version | 开发板使用的内核版本。 | + | board_cpu | 开发板CPU类型，例如：“cortex-m4”，“cortex-a7”，“riscv32”。 | + | board_arch | 开发芯片arch指令集, 例如：“armv7-a”。 | + | board_toolchain | 开发板自定义的编译工具链名称，例如：“gcc-arm-none-eabi”。若为空，则使用默认为ohos-clang。 | + | board_toolchain_path | 编译工具链路径，为空则默认使用环境变量中的工具链。 | + | board_toolchain_prefix | 编译工具链前缀，例如：“arm-none-eabi-”。 | + | board_toolchain_type | 编译工具链类型，目前支持gcc和clang。 | + | board_cflags | 开发板配置的c文件编译选项。 | + | board_cxx_flags | 开发板配置的cpp文件编译选项。 | + | board_ld_flags | 开发板配置的链接选项。 | + | board_include_dirs | 开发板配置的系统头文件路径列表。 | + | board_adapter_dir | 开发板适配文件路径。 | + +1. 新增模组终端厂商。 + 基于某款具备OpenHarmony能力的芯片进行模组终端开发，需要在vendor下创建模组厂商目录，目录内容主要是使用的OpenHarmony子系统能力。 + + 创建目录规则：“vendor/{产品模组厂商}/{产品模组名称}”。 + + 例：“vendor/MyVendorCompany/MyProduct” + + ``` + vendor + ├── hisilicon # hisilicon 产品相关目录，可供参考 + └── MyVendorCompany # MyVendorCompany 产品模组厂商 + └── MyProduct # 具体产品 + ├── BUILD.gn + └── config.json # 产品子系统列表 + ``` + + 编译脚本：将“vendor/MyVendorCompany/MyProduct/BUILD.gn”下的文件添加到OpenHarmony编译框架中。 + + 路径：“vendor/MyVendorCompany/MyProduct/BUILD.gn” + + + ``` + group("MyProduct") { + print("MyVendorCompnay MyProduct is under developing.") + } + ``` + + 产品配置信息：包括产品名、设备厂商、内核类型以及所添加的子系统列表等信息（详见表3）。 + + 路径：“vendor/MyVendorCompany/MyProduct/config.json” + + + ``` + { + "product_name": "MyProduct", + "ohos_version": "OpenHarmony 1.0", + "device_company": "MyDeviceCompany", + "board": "MyBoard", + "kernel_type": "liteos_m", + "kernel_version": "", + "subsystems": [ + { + "subsystem": "startup", + "components": [ + { "component": "bootstrap", "features":[] }, + { "component": "syspara_lite", "features": + [ + "enable_ohos_startup_syspara_lite_use_thirdparty_mbedtls = false" + ] + } + ] + } + ], + "vendor_adapter_dir": "", + "third_party_dir": "", + "product_adapter_dir": "//vendor/MyVendorCompany/MyProduct/hals", + } + ``` + + **表3** “config.json”文件配置项 + + | 配置项 | 介绍 | + | -------- | -------- | + | product_name | 产品名称，hb set时显示产品名称。 | + | ohos_version | OpenHarmony版本号，与实际版本保持一致即可。 | + | device_company | 芯片厂商名称，与device的二级目录名称一致。 | + | board | 开发板名称，与device的三级目录名称一致。 | + | kernel_type | 内核类型，应与开发板移植的OpenHarmony系统内核类型匹配。 | + | kernel_version | 内核版本号，与config.gni中kernel_version值匹配。 | + | subsystem | 产品选择的子系统，应为OS支持的子系统。子系统定义请见build/lite/components目录下的各子系统描述文件。 | + | components | 产品选择的某个子系统下的组件，子系统支持的组件详见build/lite/components/{子系统}.json文件。 | + | features | 产品配置的某个组件的特性，详见子系统源码目录对应的BUILD.gn文件。 | + | vendor_adapter_dir | 适配IOT外设，UtilsFile文件读写能力，一般指向device下目录。使用详见[文件子系统移植实例步骤2。](porting-minichip-subsys-filesystem.md#移植实例) | + | third_party_dir | 芯片厂自身三方软件目录，例如mbedtls，lwip等。如果使用OpenHarmony提供的三方软件，可暂时设空，也可参考hispark_pegasus的配置 。 | + | product_adapter_dir | 适配hal_token以及系统参数，一般指向vendor下目录。使用详见[启动恢复子系统移植实例步骤1。](porting-minichip-subsys-startup.md#移植实例) | + + > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** + > 1. 编译构建系统会对字段进行有效性检查，其中： + > + > - device_company，board，kernel_type，kernel_version应与芯片厂商配置匹配。 + > + > - subsystem，component应与“build/lite/components”下的部件描述匹配。 diff --git a/zh-cn/device-dev/porting/porting-minichip-subsys-communication.md b/zh-cn/device-dev/porting/porting-minichip-subsys-communication.md new file mode 100644 index 0000000000000000000000000000000000000000..fe6528653500ed2c28d19f9a84a9ecc7851d1c8b --- /dev/null +++ b/zh-cn/device-dev/porting/porting-minichip-subsys-communication.md @@ -0,0 +1,131 @@ +# 移植通信子系统 + + +通信子系统目前涉及Wi-Fi和蓝牙适配，厂商应当根据芯片自身情况进行适配。 + + +## 移植指导 + +Wi-Fi编译文件内容如下： + + 路径：“foundation/communication/wifi_lite/BUILD.gn” + +``` +group("wifi") { + deps = [ "$ohos_board_adapter_dir/hals/communication/wifi_lite/wifiservice:wifiservice" ] +} +``` + +从中可以看到厂商适配相关接口的.c文件存放目录应为“$ohos_board_adapter_dir/hals/communication/wifi_lite/wifiservice”，且该目录下BUILD.gn文件中的目标应为“wifiservice”。需要厂商适配的Wi-Fi接口见表1 、表2 和表3，蓝牙接口见表4和表5。 + + **表1** wifi_device.h + +| 接口 | 作用 | +| -------- | -------- | +| EnableWifi | 启用Wi-Fista模式。 | +| DisableWifi | 禁用Wi-Fi sta模式。 | +| IsWifiActive | 检查Wi-Fi sta模式是否启用。 | +| Scan | 扫描热点信息。 | +| GetScanInfoList | 获取所有扫描到的热点列表。 | +| AddDeviceConfig | 配置连接到的热点信息。 | +| GetDeviceConfigs | 获取配置连接到的热点信息。 | +| RemoveDevice | 删除指定的热点配置信息。 | +| ConnectTo | 接到指定的热点。 | +| Disconnect | 断开Wi-Fi连接。 | +| GetLinkedInfo | 获取热点连接信息。 | +| RegisterWifiEvent | 为指定的Wi-Fi事件注册回调。 | +| UnRegisterWifiEvent | 取消注册以前为指定Wi-Fi事件注册的回调。 | +| GetDeviceMacAddress | 获取设备的MAC地址。 | +| AdvanceScan | 根据指定参数启动Wi-Fi扫描。 | + + **表2** wifi_hotspot_config.h + +| 文件 | 接口 | 作用 | +| -------- | -------- | -------- | +| wifi_hotspot_config.h | SetBand | 设置该热点的频段。 | +| GetBand | 获取该热点的频段。 | + + **表3** wifi_hotspot.h + +| 接口 | 作用 | +| -------- | -------- | +| EnableHotspot | 启用Ap热点模式。 | +| DisableHotspot | 禁用Ap热点模式。 | +| SetHotspotConfig | 设置指定的热点配置。 | +| GetHotspotConfig | 获取指定的热点配置。 | +| IsHotspotActive | 检查Ap热点模式是否启用。 | +| GetStationList | 获取连接到此热点的一系列STA。 | +| GetSignalLevel | 获取指定接收信号强度指示器（RSSI）和频带指示的信号电平。 | +| DisassociateSta | 使用指定的MAC地址断开与STA的连接。 | +| AddTxPowerInfo | 将hotspot功率发送到beacon。 | + + **表4** ohos_bt_gatt.h + +| 接口 | 作用 | +| -------- | -------- | +| InitBtStack | 初始化蓝牙协议栈。 | +| EnableBtStack | 使能蓝牙协议栈。 | +| DisableBtStack | 禁用蓝牙协议栈。 | +| SetDeviceName | 设置蓝牙设备名称。 | +| BleSetAdvData | 设置广播数据。 | +| BleStartAdv | 开始广播。 | +| BleStartAdvEx | 传入构建好的广播数据，参数，开启蓝牙广播。 | +| BleStopAdv | 停止发送广播。 | +| BleUpdateAdv | 更新advertising参数。 | +| BleSetSecurityIoCap | 设置蓝牙的IO能力为NONE，配对方式为justworks。 | +| BleSetSecurityAuthReq | 设置蓝牙是否需要配对绑定。 | +| BleGattSecurityRsp | 响应安全连接请求。 | +| ReadBtMacAddr | 获取设备MAC地址。 | +| BleSetScanParameters | 设置扫描参数。 | +| BleStartScan | 开始扫描。 | +| BleStopScan | 停止扫描。 | +| BleGattRegisterCallbacks | 注册gap,GATT事件回调函数。 | + + **表5** ohos_bt_gatt_server.h + +| 接口 | 作用 | +| -------- | -------- | +| BleGattsRegister | 使用指定的应用程序UUID注册GATT服务器。 | +| BleGattsUnRegister | 断开GATT服务器与客户端的连接。 | +| BleGattsDisconnect | 断开GATT服务器与客户端的连接。 | +| BleGattsAddService | 添加了一个服务。 | +| BleGattsAddIncludedService | 将包含的服务添加到指定的服务。 | +| BleGattsAddCharacteristic | 向指定的服务添加特征。 | +| BleGattsAddDescriptor | 将描述符添加到指定的特征。 | +| BleGattsStartService | 启动一个服务。 | +| BleGattsStopService | 停止服务。 | +| BleGattsDeleteService | 删除一个服务。 | +| BleGattsClearServices | 清除所有服务。 | +| BleGattsSendResponse | 向接收到读取或写入请求的客户端发送响应。 | +| BleGattsSendIndication | 设备侧向APP发送蓝牙数据。 | +| BleGattsSetEncryption | 设置GATT连接的加密类型。 | +| BleGattsRegisterCallbacks | 注册GATT服务器回调。 | +| BleGattsStartServiceEx | 根据传入的服务列表，创建gatt服务。 | +| BleGattsStopServiceEx | 传入gatt服务句柄，停止gatt服务。 | + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 不同版本接口可能存在差异，需要根据当前版本的具体文件进行适配。 + + +## 适配实例 + +1. 在“config.json”中添加iot_hardware子系统。 + 路径：“vendor/MyVendorCompany/MyProduct/config.json” + + 修改如下： + + + ``` + { + subsystem": "communication", + components": [ + { "component": "wifi_lite", "features":[] } + ] + }, + ``` + +2. 添加适配文件。 + + 在“vendor/MyVendorCompany/MyProduct/config.json”文件中，通常将配置“ohos_board_adapter_dir”配置为 “//vendor/MyVendorCompany/MyProduct/adapter”。 + + 在“ohos_board_adapter_dir”目录下根据上述适配指导中提到的头文件，适配Wi-Fi、蓝牙接口。 diff --git a/zh-cn/device-dev/porting/porting-minichip-subsys-driver.md b/zh-cn/device-dev/porting/porting-minichip-subsys-driver.md new file mode 100644 index 0000000000000000000000000000000000000000..3388b6a9045e8f7a39b8e061b072c191376f752c --- /dev/null +++ b/zh-cn/device-dev/porting/porting-minichip-subsys-driver.md @@ -0,0 +1,115 @@ +# 移植外设驱动子系统 + + +外设驱动子系统提供OpenHarmony专有的外部设备操作接口。本模块提供设备操作接口有：FLASH, GPIO, I2C, PWM, UART, WATCHDOG等。 + + +OpenHarmony提供了两种驱动适配方式：使用外设驱动子系统、使用HDF驱动框架。由于轻量级系统的资源有限，这里建议使用IOT子系统方式。 + + +## 移植指导 + +厂商需要根据OpenHarmony提供的接口定义实现其功能，IOT子系统接口定义的头文件如下： + + +``` +base/iot_hardware/peripheral/ +├── BUILD.gn +└── interfaces + └── kits + ├── iot_errno.h + ├── iot_flash.h + ├── iot_gpio.h + ├── iot_i2c.h + ├── iot_pwm.h + ├── iot_uart.h + ├── iot_watchdog.h + ├── lowpower.h + └── reset.h +``` + +其中“base/iot_hardware/peripheral/BUILD.gn”文件如下： + + +``` +import("//build/lite/config/subsystem/lite_subsystem.gni") +import("//build/lite/ndk/ndk.gni") + +lite_subsystem("iothardware") { + subsystem_components = [ + "$ohos_vendor_adapter_dir/hals/iot_hardware/wifiiot_lite:hal_iothardware", + ] +} +if (ohos_kernel_type == "liteos_m") { + ndk_lib("iothardware_ndk") { + deps = [ + "$ohos_vendor_adapter_dir/hals/iot_hardware/wifiiot_lite:hal_iothardware", #依赖厂商的适配 + ] + head_files = [ "//base/iot_hardware/peripheral/interfaces/kits" ] + } +} +``` + +从中可以看到厂商适配相关接口的存放目录应为“$ohos_vendor_adapter_dir/hals/iot_hardware/wifiiot_lite”，且该目录下BUILD.gn文件中的目标应为hal_iothardware。 + + +## 移植实例 + +1. 在“config.json”中添加iot_hardware子系统。 + 路径：“vendor/MyVendorCompany/MyProduct/config.json” + + 修改如下： + + + ``` + { + subsystem": "iot_hardware", + components": [ + { "component": "iot_controller", "features":[] } + ] + }, + ``` + +2. 添加适配文件。 + + 在“vendor/MyVendorCompany/MyProduct/config.json”文件中，通常将配置“vendor_adapter_dir”配置为 “//device/MyDeviceCompany/MyBoard/adapter”。 + + 在“vendor_adapter_dir”目录下进行适配： + + + ``` + hals/iot_hardware/wifiiot_lite + ├── BUILD.gn + ├── iot_flash.c + ├── iot_gpio.c + ├── iot_i2c.c + ├── iot_lowpower.c + ├── iot_pwm.c + ├── iot_reset.c + ├── iot_uart.c + └── iot_watchdog.c + ``` + + 其中BUILD.gn内容如下： + + + ``` + static_library("hal_iothardware") { #目标名 + sources = [ #厂商适配的源文件 + "iot_watchdog.c", + "iot_reset.c", + "iot_flash.c", + "iot_i2c.c", + "iot_gpio.c", + "iot_pwm.c", + "iot_uart.c" + ] + include_dirs = [ ] + } + ``` + + 其中，“include_dirs”需要根据工程实际情况包含两个路径： + + - iot子系统的头文件路径 + + - 适配iot子系统所使用到的SDK的头文件路径 diff --git a/zh-cn/device-dev/porting/porting-minichip-subsys-filesystem.md b/zh-cn/device-dev/porting/porting-minichip-subsys-filesystem.md new file mode 100644 index 0000000000000000000000000000000000000000..fc2d572e5dfcdabbcb13f5235b2a35f9b71ced5d --- /dev/null +++ b/zh-cn/device-dev/porting/porting-minichip-subsys-filesystem.md @@ -0,0 +1,123 @@ +# 移植文件子系统 + + +utils部件可被各业务子系统及上层应用使用，依赖芯片文件系统实现，需要芯片平台提供文件打开、关闭、读写、获取大小等功能。 + + +## 移植指导 + +OpenHarmony文件系统需要适配如下HAL层接口： + + **表1** 文件打开或关闭 + +| **接口名** | **描述** | +| -------- | -------- | +| HalFileOpen | 文件打开或创建新文件。 | +| HalFileClose | 文件关闭。 | + + **表2** 文件操作 + +| **接口名** | **描述** | +| -------- | -------- | +| HalFileRead | 读文件。 | +| HalFileWrite | 写文件。 | +| HalFileDelete | 删除文件。 | +| HalFileStat | 获取文件属性。 | +| HalFileSeek | 文件查找。 | + + 厂商适配相关接口的实现，请参考OpenHarmony中file的接口和hal层适配接口的定义： + +``` +//utils/native/lite/file +├── BUILD.gn +└── src + └── file_impl_hal + └── file.c #file接口 +``` + + +``` +//utils/native/lite/hals +└── file +└── hal_file.h #hal层接口头文件 +``` + +其中BUILD.gn的内容如下： + + +``` +import("//build/lite/config/component/lite_component.gni") + +static_library("native_file") { + sources = [ + "src/file_impl_hal/file.c", + ] + include_dirs = [ + "//utils/native/lite/include", + "//utils/native/lite/hals/file", + ] + deps = ["$ohos_vendor_adapter_dir/hals/utils/file:hal_file_static"] #依赖厂商的适配 +} + +lite_component("file") { + features = [ + ":native_file", + ] +} +``` + +从中可以看到厂商适配相关接口的存放目录应为“$ohos_vendor_adapter_dir/hals/utils/file”，且该目录下BUILD.gn文件中的目标应为hal_file_static。 + +通常厂商可以采用下面三种方式适配hal层接口： + +1. 直接flash读写，模拟文件的操作。 + +2. 使用littlefs或者fatfs文件系统进行适配，littlefs或者fatfs都是轻量级文件系统适配简单，其中OpenHarmony的“//thirdparty”目录下已有fatfs可供参考。 + +3. 使用厂商已有的文件系统进行适配。 + + +## 移植实例 + +1. “config.json”添加文件系统。 + 路径：“vendor/MyVendorCompany/MyProduct/config.json” + + 修改如下： + + ``` + { + "subsystem": "utils", + "components": [ + { "component": "file", "features":[] }, + { "component": "kv_store", "features":[] }, + { "component": "os_dump", "features":[] } + ] + }, + ``` + +2. 添加适配文件。 + 在“vendor/MyVendorCompany/MyProduct/config.json”文件中，vendor_adapter_dir配置项通常进行如下配置： + + "vendor_adapter_dir": "//device/MyDeviceCompany/MyBoard/adapter"。 + + 在该目录下进行UtilsFile接口适配： + + + ``` + hals/utils/file + ├── BUILD.gn + └── src + └── hal_file.c + ``` + + 其中BUILD.gn内容如下： + + ``` + import("//build/lite/config/component/lite_component.gni") + static_library("hal_file_static") { #目标名 + sources = [ "src/hal_file.c" ] #厂商适配的源文件 + include_dirs = [ + "//utils/native/lite/hals/file", + ] + } + ``` diff --git a/zh-cn/device-dev/porting/porting-minichip-subsys-others.md b/zh-cn/device-dev/porting/porting-minichip-subsys-others.md new file mode 100644 index 0000000000000000000000000000000000000000..6f6393089084fb14244167f87f2854a5ab4adef2 --- /dev/null +++ b/zh-cn/device-dev/porting/porting-minichip-subsys-others.md @@ -0,0 +1,23 @@ +# 配置其他子系统 + + +除上述子系统之外，还有一些必要但是无需进行移植的子系统。如：分布式任务调度子系统、DFX子系统。 + + + 这些子系统添加方式比较简单，在“vendor/MyVendorCompany/MyProduct/config.json”文件中进行如下配置即可： + +``` +{ + "subsystem": "distributed_schedule", + "components": [ + { "component": "system_ability_manager", "features":[] } # 此处部件名不同版本可能有变化，请根据实际代码填写 + ] +}, +{ + "subsystem": "hiviewdfx", + "components": [ + { "component": "hilog_lite", "features":[] }, + { "component": "hievent_lite", "features":[] } + ] +}, +``` diff --git a/zh-cn/device-dev/porting/porting-minichip-subsys-overview.md b/zh-cn/device-dev/porting/porting-minichip-subsys-overview.md new file mode 100644 index 0000000000000000000000000000000000000000..a42474f82ed441079af1355072b0339137f588ba --- /dev/null +++ b/zh-cn/device-dev/porting/porting-minichip-subsys-overview.md @@ -0,0 +1,24 @@ +# 移植子系统概述 + + +OpenHarmony系统功能按照“系统 > 子系统 > 部件”逐级展开，支持根据实际需求裁剪某些非必要的部件（本文只对HarmonyOS Connect服务包所必需的子系统、部件进行介绍）。若想使用OpenHarmony系统的能力，需要对相应子系统进行适配。 + + +OpenHarmony芯片适配常见子系统列表如下（详见表1），需结合具体芯片再做增删减操作。 + + + **表1** OpenHarmony子系统 + +| 子系统 | 作用 | +| -------- | -------- | +| applications | 应用程序demo。可将应用相关源码存放在此目录下。 | +| kernel | 内核子系统。负责任务调度、内存管理等常见的内核功能。 | +| hiviewdfx | 可维可测子系统。提供日志相关功能。 | +| communication | 通信子系统。包含Wi-Fi，蓝牙功能。 | +| iot_hardware | IOT外设子系统。提供常见的外设接口，例如GPIO，I2C，SPI等。 | +| startup | 启动子系统。内核启动后运行的第一个子系统，负责在内核启动之后到应用启动之前的系统关键进程和服务的启动过程的功能。 | +| update | 升级子系统。用来支持OpenHarmony设备的OTA升级。 | +| utils | 公共基础库子系统。提供了一些常用的C、C++开发增强API。 | +| distributed_schedule | 分布式调度子系统。负责跨设备部件管理，提供访问和控制远程组件的能力，支持分布式场景下的应用协同。 | +| security | 安全子系统。包括系统安全、数据安全、应用安全等功能，为OpenHarmony提供有效保护应用和用户数据的能力。当前开源的功能，包括应用完整性保护、应用权限管理、设备认证、密钥管理服务、数据传输管控。 | +| test | 测试子系统。OpenHarmony为开发者提供了一套全面的自测试框架，开发者可根据测试需求开发相关测试用例，开发阶段提前发现缺陷，大幅提高代码质量。 | diff --git a/zh-cn/device-dev/porting/porting-minichip-subsys-security.md b/zh-cn/device-dev/porting/porting-minichip-subsys-security.md new file mode 100644 index 0000000000000000000000000000000000000000..961d2a0d0f94a006ca7dbc848c02294c6282bb86 --- /dev/null +++ b/zh-cn/device-dev/porting/porting-minichip-subsys-security.md @@ -0,0 +1,109 @@ +# 移植安全子系统 + + +安全子系统提供网络设备连接、认证鉴权等功能，依赖mbedtls实现硬件随机数以及联网功能。 + + +由于每个厂商芯片硬件与实现硬件随机数的方式不同，需要适配硬件随机数接口。 + + +## 移植指导 + +OpenHarmony提供了mbedtls的开源三方库，路径为“//third_party/mbedtls”。此库中提供了“mbedtls_platform_entropy_poll”、“mbedtls_hardclock_poll”、“mbedtls_havege_poll”、“mbedtls_hardware_poll”等几种产生随机数的方式。厂商需要根据芯片适配“mbedtls_hardware_poll”方式。 + + +## 移植实例 + +1. “config.json”添加文件系统。 + 路径：“vendor/MyVendorCompany/MyProduct/config.json” + + 修改如下： + + ``` + { + "subsystem": "security", + "components": [ + { "component": "hichainsdk", "features":[] }, + { "component": "huks", "features":[]} + ] + }, + ``` + +2. 配置宏，打开硬件随机数接口相关代码。 + 根据mbedtls的编译文件可以看出，配置宏的位置在"MBEDTLS_CONFIG_FILE=<../port/config/config_liteos_m.h>"文件中。 + + 路径：“third_party/mbedtls/BUILD.gn” + + + ``` + if (ohos_kernel_type == "liteos_m") { + defines += [ + "__unix__", + "MBEDTLS_CONFIG_FILE=<../port/config/config_liteos_m.h>", + ] + } + ``` + + 根据代码我们可以看出需要配置“MBEDTLS_NO_PLATFORM_ENTROPY”、“MBEDTLS_ENTROPY_HARDWARE_ALT”两个宏，才能编译硬件随机数的相关代码。 + + 路径：“third_party/mbedtls/library/entropy.c” + + + ``` + #if !defined(MBEDTLS_NO_DEFAULT_ENTROPY_SOURCES) + #if !defined(MBEDTLS_NO_PLATFORM_ENTROPY) + mbedtls_entropy_add_source( ctx, mbedtls_platform_entropy_poll, NULL, + MBEDTLS_ENTROPY_MIN_PLATFORM, + MBEDTLS_ENTROPY_SOURCE_STRONG ); + #endif + ...... + #if defined(MBEDTLS_ENTROPY_HARDWARE_ALT) + mbedtls_entropy_add_source( ctx, mbedtls_hardware_poll, NULL, + MBEDTLS_ENTROPY_MIN_HARDWARE, + MBEDTLS_ENTROPY_SOURCE_STRONG ); + #endif + ...... + #endif /* MBEDTLS_NO_DEFAULT_ENTROPY_SOURCES */ + } + ``` + +3. 适配硬件随机数接口 + 接口定义如下： + + 路径：“third_party/mbedtls/include/mbedtls/entropy_poll.h” + + + ``` + int mbedtls_hardware_poll( void *data,unsigned char *output, size_t len, size_t *olen ); + ``` + + + **表1** 安全子系统配置项 + +| 配置项 | 意义 | +| -------- | -------- | +| disable_huks_binary | 是否编译HUKS源码。
(1) 默认值： false，不编译HUKS源码。
(2) 其他值： true，编译HUKS源码。 | +| disable_authenticate | 是否需要裁剪hichain认证功能。
(1) 默认值： true，不裁剪。
(2) 其他值： false，裁剪hichain认证功能。 | +| huks_use_lite_storage | 是否采用轻量化存储方案。无文件系统、仅有flash存储的设备，可采用轻量化存储方案。
(1) 默认值： true，使用轻量化存储。
(2) 其他值： false，不使用轻量化存储。 | +| huks_use_hardware_root_key | 是否使用硬件根密钥。设备存在硬件根密钥能力时，需要根据自身能力适配硬件根密钥方案；HUKS提供的RKC方案仅为模拟实现。
(1) 默认值：false，默认值，默认无硬件根密钥。
(2) 其他值：true，设备具有硬件根密钥相关能力时，应自行适配。 | +| huks_config_file | 是否使用HUKS默认配置文件。
(1) 默认值：""：使用HUKS默认配置文件hks_config.h。
(2) 其他文件：产品可在HUKS支持能力集合中自行选择所要支持的特性。 | + + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 在添加安全子系统时，可直接通过配置feature来选择安全子系统特性。 +> +> +> ``` +> { +> "subsystem": "security", +> "components": [ +> { "component": "hichainsdk", "features":[] }, +> { "component": "huks", "features": +> [ +> "disable_huks_binary = false", +> "disable_authenticate = false" +> ] +> } +> ] +> }, +> ``` diff --git a/zh-cn/device-dev/porting/porting-minichip-subsys-startup.md b/zh-cn/device-dev/porting/porting-minichip-subsys-startup.md new file mode 100644 index 0000000000000000000000000000000000000000..3cf1ecc836385cd664687b226da988d0b3968054 --- /dev/null +++ b/zh-cn/device-dev/porting/porting-minichip-subsys-startup.md @@ -0,0 +1,154 @@ +# 移植启动恢复子系统 + + +启动恢复子系统负责在内核启动之后到应用启动之前的系统关键进程和服务的启动过程的功能。 + + +## 移植指导 + +针对轻量系统主要提供了各服务和功能的启动入口标识。在SAMGR启动时，会调用bootstrap标识的入口函数，并启动系统服务。 + +适配完成后，调用OHOS_SystemInit()接口，即可启动系统。 + +路径：“base/startup/bootstrap_lite/services/source/system_init.c” + + +``` +void OHOS_SystemInit(void) +{ + MODULE_INIT(bsp); //执行.zinitcall.bspX.init段中的函数 + MODULE_INIT(device); //执行.zinitcall.deviceX.init段中的函数 + MODULE_INIT(core); //执行.zinitcall.coreX.init段中的函数 + SYS_INIT(service); //执行.zinitcall.sys.serviceX.init段中的函数 + SYS_INIT(feature); //执行.zinitcall.sys.featureX.init段中的函数 + MODULE_INIT(run); //执行.zinitcall.runX.init段中的函数 + SAMGR_Bootstrap(); //SAMGR服务初始化 +} +``` + + +## 移植实例 + +1. 在“config.json”中添加启动子系统。 + 路径：“vendor/MyVendorCompany/MyProduct/config.json” + + 修改如下： + + + ``` + { + subsystem": "startup", + components": [ + { "component": "bootstrap_lite", "features":[] }, + { "component": "syspara_lite", "features":[] } + ] + }, + ``` + + 在startup子系统中有部分部件（如：syspara_lite等），会依赖“$ohos_product_adapter_dir/utils”中的模块。其中“ohos_product_adapter_dir”就是在config.json文件中配置的“product_adapter_dir”，我们通常配置其为“vendor/MyVendorCompany/MyProduct/hals”。 + +1. 添加zinitcall以及run定义。 + 在厂商ld链接脚本中.text段中，添加如下代码： + + + ``` + __zinitcall_bsp_start = .; + KEEP (*(.zinitcall.bsp0.init)) + KEEP (*(.zinitcall.bsp1.init)) + KEEP (*(.zinitcall.bsp2.init)) + KEEP (*(.zinitcall.bsp3.init)) + KEEP (*(.zinitcall.bsp4.init)) + __zinitcall_bsp_end = .; + __zinitcall_device_start = .; + KEEP (*(.zinitcall.device0.init)) + KEEP (*(.zinitcall.device1.init)) + KEEP (*(.zinitcall.device2.init)) + KEEP (*(.zinitcall.device3.init)) + KEEP (*(.zinitcall.device4.init)) + __zinitcall_device_end = .; + __zinitcall_core_start = .; + KEEP (*(.zinitcall.core0.init)) + KEEP (*(.zinitcall.core1.init)) + KEEP (*(.zinitcall.core2.init)) + KEEP (*(.zinitcall.core3.init)) + KEEP (*(.zinitcall.core4.init)) + __zinitcall_core_end = .; + __zinitcall_sys_service_start = .; + KEEP (*(.zinitcall.sys.service0.init)) + KEEP (*(.zinitcall.sys.service1.init)) + KEEP (*(.zinitcall.sys.service2.init)) + KEEP (*(.zinitcall.sys.service3.init)) + KEEP (*(.zinitcall.sys.service4.init)) + __zinitcall_sys_service_end = .; + __zinitcall_sys_feature_start = .; + KEEP (*(.zinitcall.sys.feature0.init)) + KEEP (*(.zinitcall.sys.feature1.init)) + KEEP (*(.zinitcall.sys.feature2.init)) + KEEP (*(.zinitcall.sys.feature3.init)) + KEEP (*(.zinitcall.sys.feature4.init)) + __zinitcall_sys_feature_end = .; + __zinitcall_run_start = .; + KEEP (*(.zinitcall.run0.init)) + KEEP (*(.zinitcall.run1.init)) + KEEP (*(.zinitcall.run2.init)) + KEEP (*(.zinitcall.run3.init)) + KEEP (*(.zinitcall.run4.init)) + __zinitcall_run_end = .; + __zinitcall_app_service_start = .; //SAMGR执行.zinitcall.app.serviceX.init段中的函数 + KEEP (*(.zinitcall.app.service0.init)) + KEEP (*(.zinitcall.app.service1.init)) + KEEP (*(.zinitcall.app.service2.init)) + KEEP (*(.zinitcall.app.service3.init)) + KEEP (*(.zinitcall.app.service4.init)) + __zinitcall_app_service_end = .; + __zinitcall_app_feature_start = .; //SAMGR执行.zinitcall.app.featureX.init段中的函数 + KEEP (*(.zinitcall.app.feature0.init)) + KEEP (*(.zinitcall.app.feature1.init)) + KEEP (*(.zinitcall.app.feature2.init)) + KEEP (*(.zinitcall.app.feature3.init)) + KEEP (*(.zinitcall.app.feature4.init)) + __zinitcall_app_feature_end = .; + __zinitcall_test_start = .; + KEEP (*(.zinitcall.test0.init)) + KEEP (*(.zinitcall.test1.init)) + KEEP (*(.zinitcall.test2.init)) + KEEP (*(.zinitcall.test3.init)) + KEEP (*(.zinitcall.test4.init)) + __zinitcall_test_end = .; + __zinitcall_exit_start = .; + KEEP (*(.zinitcall.exit0.init)) + KEEP (*(.zinitcall.exit1.init)) + KEEP (*(.zinitcall.exit2.init)) + KEEP (*(.zinitcall.exit3.init)) + KEEP (*(.zinitcall.exit4.init)) + __zinitcall_exit_end = .; + ``` + +1. 芯片SDK创建任务。 + 配置任务参数，系统启动后，启动任务，示例如下： + + + ``` + void mainTask(void) { + //厂商自定义功能 + OHOS_SystemInit(); //启动子系统初始化 + printf("MainTask running...\n"); + } + + void main(VOID) { + //硬件初始化，printf输出重定向到debug串口等 + if (LOS_KernelInit() == 0) { //ohos内核初始化 + task_init_param.usTaskPrio = 10; //任务优先级 + task_init_param.pcName = "mainTask"; //任务进程名 + task_init_param.pfnTaskEntry = (TSK_ENTRY_FUNC)mainTask; //任务入口函数 + task_init_param.uwStackSize = 8192; //任务栈大小 + LOS_TaskCreate(&tid, &task_init_param); //创建任务 + LOS_Start(); //启动任务 + } + else { + printf("[BUG] LOS_KernelInit fail\n"); + } + printf("[BUG] reach to unexpected code\n"); + while (1); + } + ``` diff --git a/zh-cn/device-dev/porting/porting-minichip-verification.md b/zh-cn/device-dev/porting/porting-minichip-verification.md new file mode 100644 index 0000000000000000000000000000000000000000..66f420e385c2986c8707892ee4971afce0584fa5 --- /dev/null +++ b/zh-cn/device-dev/porting/porting-minichip-verification.md @@ -0,0 +1,88 @@ +# 移植验证 + + +OpenHarmony芯片移植完成后，需要开展OpenHarmony兼容性测试以及芯片SDK功能性测试。除可获得测试认证之外，还可以在开发阶段提前发现缺陷，大幅提高代码质量。 + + +## OpenHarmony兼容性测试 + +OpenHarmony兼容性测试是XTS（OpenHarmony生态认证测试套件）之一，详见[OpenHarmony兼容性测试](https://gitee.com/openharmony/docs/blob/master/zh-cn/readme/XTS%E5%AD%90%E7%B3%BB%E7%BB%9F.md)。 + +1. 添加test子系统以及xts_acts部件。 + 在“vendor/xxx/xxx/config.json”文件中，添加如下代码： + + + ``` + { + "subsystem": "test", + "components": [ + { "component": "xts_acts", "features":[] }, + { "component": "xts_tools", "features":[] } + ] + } + ``` + +2. 链接XTS生成的.a库。 + 在链接选项中，需要链接生成于“out/MyBoard/MyProduct/libs”目录下的XTS的.a库，其库的名称格式为libmodule_ActsXxxTest.a，链接方式为"-lmodule_ActsXxxTest",示例代码如下： + + + ``` + "-Wl,--whole-archive", + ...... + "-lhctest", + "-lbootstrap", + "-lbroadcast", + "-lmodule_ActsBootstrapTest", + "-lmodule_ActsCMSISTest", + "-lmodule_ActsDfxFuncTest", + "-lmodule_ActsParameterTest", + "-lmodule_ActsSamgrTest", + "-lmodule_ActsSecurityDataTest", + ...... + "-Wl,--no-whole-archive", + ``` + +3. 根据测试报告调整代码。 + 将编译生成的文件烧录到开发板上，使用串口工具查看xts测试报告。如果出现"failed"的测试项，则需要整改代码。 + + 定位问题时，可在“test/xts/acts/build_lite/BUILD.gn”中，将不需要的测试项注释，以便调试。 + + + ``` + if (ohos_kernel_type == "liteos_m") { + all_features += [ + "//test/xts/acts/communication_lite/lwip_hal:ActsLwipTest", + "//test/xts/acts/communication_lite/softbus_hal:ActsSoftBusTest", + "//test/xts/acts/communication_lite/wifiservice_hal:ActsWifiServiceTest", + "//test/xts/acts/utils_lite/file_hal:ActsUtilsFileTest", + "//test/xts/acts/startup_lite/syspara_hal:ActsParameterTest", + "//test/xts/acts/iot_hardware_lite/iot_controller_hal:ActsWifiIotTest", + "//test/xts/acts/kernel_lite/kernelcmsis_hal:ActsCMSISTest", + "//test/xts/acts/utils_lite/kv_store_hal:ActsKvStoreTest", + "//test/xts/acts/security_lite/datahuks_hal:ActsSecurityDataTest", + "//test/xts/acts/hiviewdfx_lite/hilog_hal:ActsDfxFuncTest", + "//test/xts/acts/distributed_schedule_lite/samgr_hal:ActsSamgrTest", + "//test/xts/acts/update_lite/updater_hal:ActsUpdaterFuncTest", + "//test/xts/acts/startup_lite/bootstrap_hal:ActsBootstrapTest", + ] + } + ``` + +> ![icon-caution.gif](public_sys-resources/icon-caution.gif) **注意：** +> 1. XTS会在OHOS_SystemInit()调用之后，自行运行测试。 +> +> 2. 需要在"-Wl,--whole-archive"和"-Wl,--no-whole-archive"中间添加，否则链接不到。 +> +> 进行XTS测试时，必须链接以下静态库 +> +> +> ``` +> "-lhctest", +> "-lbootstrap", +> "-lbroadcast", +> ``` + + +## 厂商SDK功能性测试 + +芯片移植完成后需要客户验证SDK自身功能，例如Wi-Fi，蓝牙，OTA等基础能力是否正常。