From 9e133ff96e332bbb878f2fa068604d66a3a0e6b3 Mon Sep 17 00:00:00 2001 From: duxbbo Date: Tue, 29 Jun 2021 02:51:58 +0000 Subject: [PATCH] add porting guide for standard system Signed-off-by: duxbbo Change-Id: Ia89c75ccdc9d22a04d17a41d89e04f9d5ab18c63 --- zh-cn/device-dev/porting/Readme-CN.md | 54 +-- .../porting/lite_system_port_guide.md | 27 ++ .../porting/standard_system_portting_guide.md | 349 ++++++++++++++++++ zh-cn/readme.md | 2 - 4 files changed, 403 insertions(+), 29 deletions(-) mode change 100755 => 100644 zh-cn/device-dev/porting/Readme-CN.md create mode 100755 zh-cn/device-dev/porting/lite_system_port_guide.md create mode 100644 zh-cn/device-dev/porting/standard_system_portting_guide.md diff --git a/zh-cn/device-dev/porting/Readme-CN.md b/zh-cn/device-dev/porting/Readme-CN.md old mode 100755 new mode 100644 index 0dca00c895f..8cb49296233 --- a/zh-cn/device-dev/porting/Readme-CN.md +++ b/zh-cn/device-dev/porting/Readme-CN.md @@ -1,27 +1,27 @@ -# 移植指南 - -- [三方库移植指导](三方库移植指导.md) - - [概述](概述.md) - - [CMake方式组织编译的库移植](CMake方式组织编译的库移植.md) - - [Makefile方式组织编译的库移植](Makefile方式组织编译的库移植.md) - -- [三方芯片移植指导](三方芯片移植指导.md) - - [移植准备](移植准备.md) - - [移植须知](移植须知.md) - - [编译构建适配流程](编译构建适配流程.md) - - - [内核移植](内核移植.md) - - [移植概述](移植概述.md) - - [内核基础适配](内核基础适配.md) - - [内核移植验证](内核移植验证.md) - - - [板级系统移植](板级系统移植.md) - - [移植概述](移植概述-0.md) - - [板级驱动适配](板级驱动适配.md) - - [HAL层实现](HAL层实现.md) - - [系统组件调用](系统组件调用.md) - - [三方组件适配](三方组件适配.md) - - [XTS认证](XTS认证.md) - - - [常见问题](常见问题.md) - + +# 开发板移植 +目前OpenHarmony已经成立了SIG组[sig-devboard](https://gitee.com/openharmony/community/blob/master/sig/sig-devboard/sig_devboard_cn.md)。该SIG组以支持更多第三方开发板为目标，提供开发板移植的支撑。 + +在了解开发板移植前，我们需要先了解一下OpenHarmony对设备的分类。不同设备类型的移植方法会有较大差异 + +| 设备类型| 硬件要求| 支持的内核| 能力| +|------|------|------|------| +|轻量系统类设备|内存>128KB | LiteOS-M| 只支持原生应用| +|小型系统类设备|内存>1MB、有MMU|LiteOS-A、Linux| 只支持原生应用| +|标准系统类设备|内存>128MB、有MMU|Linux| 支持原生应用 和 Android应用| + +# 1. 代码准备 + +目前OpenHarmony已经为各厂家创建了仓库并在openharmony-sig中进行孵化。参与孵化仓开发，需要使用如下方法初始化和下载代码。 + +```shell +repo init -u https://gitee.com/openharmony-sig/manifest.git -b master --no-repo-verify +``` + +其他下载步骤与主线相同。 + +# 2. 开始移植你的开发板 + +- [轻量级系统](lite_system_port_guide.md) +- [标准系统](standard_system_portting_guide.md) + diff --git a/zh-cn/device-dev/porting/lite_system_port_guide.md b/zh-cn/device-dev/porting/lite_system_port_guide.md new file mode 100755 index 00000000000..0dca00c895f --- /dev/null +++ b/zh-cn/device-dev/porting/lite_system_port_guide.md @@ -0,0 +1,27 @@ +# 移植指南 + +- [三方库移植指导](三方库移植指导.md) + - [概述](概述.md) + - [CMake方式组织编译的库移植](CMake方式组织编译的库移植.md) + - [Makefile方式组织编译的库移植](Makefile方式组织编译的库移植.md) + +- [三方芯片移植指导](三方芯片移植指导.md) + - [移植准备](移植准备.md) + - [移植须知](移植须知.md) + - [编译构建适配流程](编译构建适配流程.md) + + - [内核移植](内核移植.md) + - [移植概述](移植概述.md) + - [内核基础适配](内核基础适配.md) + - [内核移植验证](内核移植验证.md) + + - [板级系统移植](板级系统移植.md) + - [移植概述](移植概述-0.md) + - [板级驱动适配](板级驱动适配.md) + - [HAL层实现](HAL层实现.md) + - [系统组件调用](系统组件调用.md) + - [三方组件适配](三方组件适配.md) + - [XTS认证](XTS认证.md) + + - [常见问题](常见问题.md) + diff --git a/zh-cn/device-dev/porting/standard_system_portting_guide.md b/zh-cn/device-dev/porting/standard_system_portting_guide.md new file mode 100644 index 00000000000..bb2fbf5fe63 --- /dev/null +++ b/zh-cn/device-dev/porting/standard_system_portting_guide.md @@ -0,0 +1,349 @@ +# 移植标准系统开发板 + + + + + +- [定义你的开发板](#定义你的开发板) + - [1. 定义你的SOC](#1-定义你的soc) + - [2. 定义你的产品](#2-定义你的产品) + - [3. 效果小节](#3-效果小节) +- [内核移植](#内核移植) + - [1. 为SOC添加内核构建的子系统](#1-为soc添加内核构建的子系统) + - [2. 编译内核](#2-编译内核) + - [3. 效果小节](#3-效果小节-1) +- [HDF驱动移植](#hdf驱动移植) + - [1. LCD](#1-lcd) + - [2. 触摸屏](#2-触摸屏) + - [3. WiFi](#3-wifi) + + + + +## 定义你的开发板 + +### 1. 定义你的SOC + +在这一步我们将在productdefine\common\device目录下创建以SOC名字命名的json文件，并指定CPU的架构。 + +如我们要移植一个叫MySOC的SOC，这个SOC采用32位ARM内核 +我们配置如下 + +productdefine\common\device\MySOC.json +```json +{ + "target_os": "ohos", + "target_cpu": "arm" +} +``` +根据实际情况，这里的target_cpu也可能是arm64 、riscv、 x86 ... + +### 2. 定义你的产品 + +这一步，我们需要在productdefine\common\products目录下创建以产品名命名的json文件。用于描述产品所使用的SOC 以及 所需的子系统。 + + +如我们移植一个叫MyProduct的开发板，这个开发板使用MySOC SOC。 我们配置如下 +`productdefine\common\products\MyProduct.json` +```json +{ + "product_name": "MyProduct", + "product_vendor_name" : "MyVendor", + "product_device": "MySOC", + "version": "2.0", + "type": "standard", + "parts":{ + "ace:ace_engine_standard":{}, + "ace:napi":{}, + ... + "xts:phone_tests":{} + } +} + +``` +主要的配置内容包括： + +1. `product_device`：配置所使用的SOC +2. `type`： 配置系统的级别， 这里直接standard即可 +3. `parts`: 系统需要启用的子系统。子系统可以简单理解位一块独立构建的功能块。 + +已定义的子系统可以在`build/subsystem_config.json`中找到。当然你也可以定制子系统。 + +这里建议先拷贝3516dv300 开发板的配置文件，删除掉 hisilicon_products 这个子系统。这个子系统为3516dv3000 SOC编译内核，显然不适合我们的MySOC SOC。 + +### 3. 效果小节 + +至此，你可以使用如下命令，启动你产品的构建了 + +`./build.sh --product-name MyProduct ` + +构建完成后，可以在如下目录看到构建出来的OpenHarmony镜像文件 + +`out/ohos-arm-release/packages/phone/images` + +## 内核移植 + +这一步我们需要移植Linux内核，让Linux内核可以成功运行起来。 + +### 1. 为SOC添加内核构建的子系统 + +修改文件 `build/subsystem_config.json` 增加一个子系统. 如我们这里的MySOC + +这里假定我们的我们SOC的厂商是 `MySOCVendor`，配置如下： + +```json + "MySOCVendor_products": { + "project": "hmf/MySOCVendor_products", + "path": "device/MySOCVendor/MySOC/build", + "name": "MySOCVendor_products", + "dir": "device/MySOCVendor" + }, +``` + +其中path标识了这个subsystem构建的根目录。这个我们很快就会用到 + +我们还需要再修改定义产品的配置文件`productdefine\common\products\MyProduct.json`。将刚刚定义的子系统加入到产品中 + +### 2. 编译内核 + +在上一节定义subsystem的时候，定义了构建的路径，即`device/MySOCVendor/MySOC/build`。我们这一节需要在这个目录创建构建脚本，告诉构建系统，内核如何构建。 + +目前OpenHarmony源码中提供了Linux 4.19的内核，归档在`/kernel/linux-4.19`。请尽可能使用这个内核。 +每个SOC必然需要对内核做一些修改或扩展，建议采用补丁的方式。 + +建议的目录结构 +``` +├── build +│   ├── kernel +│   │ ├── linux +│   │ ├──standard_patch_for_4_19.patch +│   ├── BUILD.gn +``` +BUILD.gn是subsystem构建的唯一入口。 + +期望的构建结果 + +| 文件 | 文件说明| +|------|------| +|$root_build_dir/packages/phone/images/uImage| 内核镜像| +|$root_build_dir/packages/phone/images/uboot | bootloader镜像| + +### 3. 效果小节 + +至此已经生成了完整的OpenHarmony镜像 + +## HDF驱动移植 + +### 1. LCD +HDF为LCD设计了驱动模型。支持一块新的LCD，需要我们编写一个驱动，在驱动中生成模型的实例，并完成注册。 + +这些LCD的驱动被放置在`drivers/framework/model/display/driver/panel`目录中。 + +- 创建Panel驱动 + +在驱动的Init方法中，需要调用RegisterPanel接口注册模型实例。如: +```C +int32_t XXXInit(struct HdfDeviceObject *object) +{ + struct PanelData *panel = CreateYourPanel(); + + // 注册 + if (RegisterPanel(panel) != HDF_SUCCESS) { + HDF_LOGE("%s: RegisterPanel failed", __func__); + return HDF_FAILURE; + } + return HDF_SUCCESS; +} + +struct HdfDriverEntry g_xxxxDevEntry = { + .moduleVersion = 1, + .moduleName = "LCD_XXXX", + .Init = XXXInit, +}; + +HDF_INIT(g_xxxxDevEntry); +``` + +- 配置加载panel驱动 +产品的所有设备信息被定义在文件`vendor/vendor_name/product_name/config/device_info/device_info.hcs`中。修改该文件，在display的host中，名为device_lcd的device中增加配置。 +注意：moduleName 要与panal驱动中的moduleName相同。 + +```hcs +root { + ... + display :: host { + device_lcd :: device { + deviceN :: deviceNode { + policy = 0; + priority = 100; + preload = 2; + moduleName = "LCD_XXXX"; + } + } + } +} +``` + +更详细的驱动开发指导，请参考 [LCD](https://gitee.com/openharmony/docs/blob/master/zh-cn/device-dev/driver/LCD.md) + +### 2. 触摸屏 +本节描述如何移植触摸屏驱动。触摸屏的驱动被放置在drivers\framework\model\input\driver\touchscreen目录中。移植触摸屏驱动主要工作是向系统注册ChipDevice模型实例。 + +- 创建触摸屏器件驱动 + +在目录中创建名为touch_ic_name.c的文件。代码模板如下： + +```C +#include "hdf_touch.h" + +static int32_t HdfXXXXChipInit(struct HdfDeviceObject *device) +{ + ChipDevice *tpImpl = CreateXXXXTpImpl(); + if(RegisterChipDevice(tpImpl) != HDF_SUCCESS) { + ReleaseXXXXTpImpl(tpImpl); + return HDF_FAILURE; + } + return HDF_SUCCESS; +} + +struct HdfDriverEntry g_touchXXXXChipEntry = { + .moduleVersion = 1, + .moduleName = "HDF_TOUCH_XXXX", + .Init = HdfXXXXChipInit, +}; + +HDF_INIT(g_touchXXXXChipEntry); +``` + +其中ChipDevice中要提供若干方法 +| 方法| 实现说明| +|------|------| +|int32_t (*Init)(ChipDevice *device)| 实现器件初始化| +|int32_t (*Detect)(ChipDevice *device)| 实现器件探测| +|int32_t (*Suspend)(ChipDevice *device)| 实现器件休眠| +|int32_t (*Resume)(ChipDevice *device)| 实现器件唤醒| +|int32_t (*DataHandle)(ChipDevice *device)| 需要实现从器件读取数据，将触摸点数据填写入device->driver->frameData中| +|int32_t (*UpdateFirmware)(ChipDevice *device)| 实现固件升级| + +- 配置产品，加载器件驱动 + +产品的所有设备信息被定义在文件`vendor/vendor_name/product_name/config/device_info/device_info.hcs`中。修改该文件，在名为input的host中，名为device_touch_chip的device中增加配置。 +注意：moduleName 要与触摸屏驱动中的moduleName相同。 + +```hcs + deviceN :: deviceNode { + policy = 0; + priority = 130; + preload = 0; + permission = 0660; + moduleName = "HDF_TOUCH_XXXX"; + deviceMatchAttr = "touch_XXXX_configs"; + } +``` + +更详细的驱动开发指导，请参考 [TOUCHSCREEN](https://gitee.com/openharmony/docs/blob/master/zh-cn/device-dev/driver/TOUCHSCREEN.md) + + +### 3. WiFi + +![tu](./HDF_WIFI.PNG) + +WiFi驱动分为两部分，一部分负责管理WIFI设备，另一个部分负责处理WIFI流量。HDF WLAN分别为这两部分做了抽象。目前支持SDIO接口的WIFI芯片 + +主要需要实现的接口有: + +| 接口| 定义头文件| 说明| +|------|------|------| +| HdfChipDriverFactory| drivers\framework\include\wifi\hdf_wlan_chipdriver_manager.h| ChipDriver的Factory，用于支持一个芯片多个WIFI端口| +| HdfChipDriver | drivers\framework\include\wifi\wifi_module.h| 每个WIFI端口对应一个HdfChipDriver，用来管理一个特定的WIFI端口| +|NetDeviceInterFace| drivers\framework\include\wifi\net_device.h| 与协议栈之间的接口，如发送数据、设置网络接口状态等| + +建议适配按如下步骤操作： + +1. 创建Hdf驱动 +建议将代码放置在`/device/vendor_name/peripheral/wifi/chip_name/` + +```C +static int32_t HdfWlanHisiChipDriverInit(struct HdfDeviceObject *device) { + static struct HdfChipDriverFactory factory = CreateChipDriverFactory(); + struct HdfChipDriverManager *driverMgr = HdfWlanGetChipDriverMgr(); + if (driverMgr->RegChipDriver(&factory) != HDF_SUCCESS) { + HDF_LOGE("%s fail: driverMgr is NULL!", __func__); + return HDF_FAILURE; + } + return HDF_SUCCESS; +} + +struct HdfDriverEntry g_hdfXXXChipEntry = { + .moduleVersion = 1, + .Init = HdfWlanXXXChipDriverInit, + .Release = HdfWlanXXXChipRelease, + .moduleName = "HDF_WIFI_CHIP_XXX" +}; + +HDF_INIT(g_hdfXXXChipEntry); +``` + +在CreateChipDriverFactory中，我们需要创建一个HdfChipDriverFactory +| 接口| 说明| +|------|------| +|const char *driverName| 当前driverName | +|int32_t (*InitChip)(struct HdfWlanDevice *device)| 初始化芯片| +|int32_t (*DeinitChip)(struct HdfWlanDevice *device)| 去初始化芯片| +|void (*ReleaseFactory)(struct HdfChipDriverFactory *factory)| 释放HdfChipDriverFactory对象| +|struct HdfChipDriver *(*Build)(struct HdfWlanDevice *device, uint8_t ifIndex)|创建一个HdfChipDriver；输入参数中，device是设备信息，ifIndex是当前创建的接口在这个芯片中的序号| +|void (*Release)(struct HdfChipDriver *chipDriver)| 释放chipDriver +|uint8_t (*GetMaxIFCount)(struct HdfChipDriverFactory *factory)| 获取当前芯片支持的最大接口数| + +HdfChipDriver需要实现的接口有 + +|接口| 说明| +|------|------| +|int32_t (*init)(struct HdfChipDriver *chipDriver, NetDevice *netDev)| 初始化当前网络接口，这里需要向netDev提供接口NetDeviceInterFace| +|int32_t (*deinit)(struct HdfChipDriver *chipDriver, NetDevice *netDev)| 去初始化当前网络接口| +|struct HdfMac80211BaseOps *ops| WIFI基础能力接口集| +|struct HdfMac80211STAOps *staOps| 支持STA模式所需的接口集| +|struct HdfMac80211APOps *apOps| 支持AP模式所需要的接口集| + + + +2. 编写配置文件，描述驱动支持的设备 +在产品配置目录下创建芯片的配置文件vendor/vendor_name/product_name/config/wifi/wlan_chip_chip_name.hcs + +注意： 路径中的vendor_name、product_name、chip_name请替换成实际名称 +```hcs +root { + wlan_config { + chip_name :& chipList { + chip_name :: chipInst { + match_attr = "hdf_wlan_chips_chip_name"; /* 这是配置匹配属性，用于提供驱动的配置根 */ + driverName = "driverName"; /* 需要与HdfChipDriverFactory中的driverName相同*/ + sdio { + vendorId = 0x0296; + deviceId = [0x5347]; + } + } + } + } +} +``` + +3. 编写配置文件，加载驱动 + +产品的所有设备信息被定义在文件`vendor/vendor_name/product_name/config/device_info/device_info.hcs`中。修改该文件，在名为network的host中，名为device_wlan_chips的device中增加配置。 +注意：moduleName 要与触摸屏驱动中的moduleName相同。 + +```hcs + deviceN :: deviceNode { + policy = 0; + preload = 2; + moduleName = "HDF_WLAN_CHIPS"; + deviceMatchAttr = "hdf_wlan_chips_chip_name"; + serviceName = "driverName"; + } +``` + +4. 构建驱动 +参考平台驱动，修改mk文件。让驱动参与内核构建 + +更多详细的开发手册，请参考[WLAN开发](https://gitee.com/openharmony/docs/blob/master/zh-cn/device-dev/driver/WLAN.md) diff --git a/zh-cn/readme.md b/zh-cn/readme.md index 7a117bfee0f..e9419c9d40b 100644 --- a/zh-cn/readme.md +++ b/zh-cn/readme.md @@ -45,8 +45,6 @@ - [外设驱动](device-dev/guide/外设驱动开发示例.md) - porting：[移植适配](device-dev/porting/Readme-CN.md) - - [三方芯片移植指导](device-dev/porting/三方芯片移植指导.md) - - [三方库移植指导](device-dev/porting/三方库移植指导.md) - bundles：[组件开发](device-dev/bundles/Readme-CN.md) - [组件开发规范](device-dev/bundles/组件开发规范.md) -- Gitee