集成三方SDK

    三方SDK通常由静态库和适配代码构成。SDK的业务逻辑通过硬件模组工具链编译得到静态库libs，每款模组都有其对应的libs。SDK的南向API与OpenHarmony API的存在使用差异，该差异可通过adapter适配代码屏蔽，不同模组可共用一套adapter。

    基于以上特征，在OpenHarmony目录结构中，可以对三方SDK目录做如下划分。

    • 适配代码adapter，放置到./domains/iot/link/ 目录下，与模组解耦。
    • 业务库libs，放置到./vendor/hisi/hi3861/hi3861/3rd_sdk/ 目录下，与模组绑定。

    平台开发者在适配前，务必先依次完成以下步骤，下面以demolink SDK举例，进行介绍。

    1. 创建厂商目录，./domains/iot/link/demolink/、./vendor/hisi/hi3861/hi3861/3rd_sdk/demolink/ ，用于厂商隔离。
    2. 创建./domains/iot/link/demolink/BUILD.gn ，用于构建适配代码。
    3. 创建./vendor/hisi/hi3861/hi3861/3rd_sdk/demolink/libs/ 目录，用于存放业务库libs。

    构建业务libs

    平台SDK业务一般以静态库的形式提供，平台厂商在获取到OpenHarmony代码后，需要根据对应的硬件模组vendor，进行编译业务libs，并将编译结果放置在./vendor/hisi/hi3861/hi3861/3rd_sdk/demolink/libs/ 目录下。下面介绍业务libs的构建方法。

    OpenHarmony已规划用于编译业务libs的目录./domains/iot/link/libbuild/ ，该目录中包含./domains/iot/link/libbuild/BUILD.gn和./domains/iot/link/BUILD.gn文件，目录结构如下。

    2. └── domains
    3.     └── iot
    4.         └── link
    5.             ├── demolink
    6.             │   └── BUILD.gn
    7.             ├── libbuild
    8.             │   └── BUILD.gn
    9.             └── BUILD.gn

    平台开发者在构建libs前，务必先完成如下步骤。

    1. 在./domains/iot/link/libbuild/ 目录下放置业务源码文件，包括.c和.h文件。编译完成后清空目录下源码文件。

      1. .
      2. └── domains
      3.     └── iot
      4.         └── link
      5.             ├── demolink
      6.             │   ├── demosdk_adapter.c
      7.             │   ├── demosdk_adapter.h
      8.             │   └── BUILD.gn
      9.             ├── libbuild
      10.             │   ├── demosdk.c
      11.             │   ├── demosdk.h
      12.             │   └── BUILD.gn
      13.             └── BUILD.gn

    2. 适配./domains/iot/link/libbuild/BUILD.gn，在编译完成后还原该文件。

      在BUILD.gn中，sources为需要参与构建的源文件，include_dirs为依赖的头文件路径，构建的目标结果是生成静态库libdemosdk.a。

      1. static_library("demosdk") {
      2.     sources = [
      3.         "demosdk.c"
      4.     ]
      5.     include_dirs = [
      6.         "//domains/iot/link/libbuild",
      7.         "//domains/iot/link/demolink"
      8.     ]
      9. }

    3. 适配./domains/iot/link/BUILD.gn，在编译完成后还原该文件。

      1. import("//build/lite/config/subsystem/lite_subsystem.gni")
      2. import("//build/lite/config/component/lite_component.gni")
      3. lite_subsystem("iot") {
      4.     subsystem_components = [
      5.         ":link"
      6.     ]
      7. }
      8. lite_component("link") {
      9.     dependences = []
      10.     features = [
      11.         "libbuild:demosdk"
      12.     ]
      13. }

    完成以上3点后，需在代码根目录下执行命令python build.py wifiiot —target //domains/iot/link:iot，等待执行完成，检查./out/wifiiot/libs目录下是否生成了目标库文件。

    将库文件拷贝到./vendor/hisi/hi3861/hi3861/3rd_sdk/demolink/libs/ 目录下，并将./domains/iot/link/libbuild/ 目录中的.c和.h文件清除。

    代码编写

    平台SDK中使用的API通常与OpenHarmony API存在差异，无法直接使用，需要一层适配代码adapter进行中间转换。本节以./domains/iot/link/demolink/demosdk_adapter.c中的任务创建接口DemoSdkCreateTask举例，向开发者演示如何在OpenHarmony上编写适配代码。

    1. 查看待适配接口DemoSdkCreateTask的描述、参数、返回值。

    2. 查看OpenHarmony API接口文档，选取一个功能类似的接口，并比对参数及用法上的差异。例如本文选取osThreadNew ，通过和DemoSdkCreateTask接口比对，可以发现两接口依赖的参数基本一致，只是参数所归属的结构体不同。

      1. typedef struct {
      2.     const char                   *name;   ///< name of the thread
      3.     uint32_t                 attr_bits;   ///< attribute bits
      5.     uint32_t                   cb_size;   ///< size of provided memory for control block
      6.     void                   *stack_mem;    ///< memory for stack
      7.     uint32_t                stack_size;   ///< size of stack
      8.     osPriority_t              priority;   ///< initial thread priority (default: osPriorityNormal)
      9.     TZ_ModuleId_t            tz_module;   ///< TrustZone module identifier
      10.     uint32_t                  reserved;   ///< reserved (must be 0)
      11. } osThreadAttr_t;
      13. /// Create a thread and add it to Active Threads.
      14. /// \param[in]     func          thread function.
      15. /// \param[in]     argument      pointer that is passed to the thread function as start argument.
      16. /// \param[in]     attr          thread attributes; NULL: default values.
      17. /// \return thread ID for reference by other functions or NULL in case of error.
      18. osThreadId_t osThreadNew (osThreadFunc_t func, void *argument, const osThreadAttr_t *attr);

    3. 完成代码差异转换。

      1. int DemoSdkCreateTask(unsigned int *handle, const struct TaskPara *para)
      2. {
      3.     osThreadAttr_t attr = {0};
      4.     osThreadId_t threadId;
      5.     if (handle == 0 || para == 0) {
      6.         return DEMOSDK_ERR;
      7.     }
      8.     if (para->func == 0) {
      9.         return DEMOSDK_ERR;
      10.     }
      11.     if (para->name == 0) {
      12.         return DEMOSDK_ERR;
      13.     }
      14.     attr.name = para->name;
      15.     attr.priority = para->prio;
      16.     attr.stack_size = para->size;
      17.     threadId = osThreadNew((osThreadFunc_t)para->func, para->arg, &attr);
      18.     if (threadId == 0) {
      19.         printf("osThreadNew fail\n");
      20.         return DEMOSDK_ERR;
      21.     }
      22.     *(unsigned int *)handle = (unsigned int)threadId;
      23.     return DEMOSDK_OK;
      24. }

    开发者在完成代码适配后，还需要在adapter同级目录下新建BUILD.gn文件。该文件可在整包构建时，将适配代码编译成静态库，并链接到bin包中去。在./domains/iot/link/demolink/BUILD.gn中，sources中为需要参与构建的源文件，include_dirs中为依赖的头文件路径，构建目标结果是生产静态库libdemolinkadapter.a。

    1. import("//build/lite/config/component/lite_component.gni")
    2. static_library("demolinkadapter") {
    3.     sources = [
    4.         "demosdk_adapter.c"
    5.     ]
    6.         "//kernel/liteos-m/components/kal/include",
    7.         "//kernel/liteos-m/components/cmsis/2.0",
    8.         "//domains/iot/link/demolink"
    10. }

    修改./domains/iot/link/BUILD.gn文件，使./domain/iot/hilink/BUILD.gn参与到构建系统中。

    1. import("//build/lite/config/subsystem/lite_subsystem.gni")
    2. import("//build/lite/config/component/lite_component.gni")
    3. lite_subsystem("iot") {
    4.     subsystem_components = [
    5.         ":link"
    6.     ]
    7. }
    8. lite_component("link") {
    9.     version = "1.0.0"
    10.     dependences = []
    11.     features = [
    12.         "demolink:demolinkadapter"
    13.     ]
    14. }

    编写业务代码

    业务libs库和适配代码准备就绪后，还需要编写业务入口函数，调起三方SDK的业务入口。

    1. 目录创建

      开发者编写业务时，务必先在./applications/sample/wifi-iot/app/ 路径下新建一个目录（或一套目录结构），用于存放业务源码文件。

      例如：在app下新增业务目录demolink，并在其中创建业务入口代码helloworld.c和编译构建文件BUILD.gn，如下。

    2. 编写业务代码。

      在helloworld.c文件中编写业务入口函数DemoSdkMain，并调起demolink的业务DemoSdkEntry，最后通过SYS_RUN()调用入口函数完成业务启动。

      1. #include "hos_init.h"
      2. #include "demosdk.h"
      4. void DemoSdkMain(void)
      5. {
      6.     DemoSdkEntry();
      7. }
      9. SYS_RUN(DemoSdkMain);

    3. 编写构建脚本

      新增./applications/sample/wifi-iot/app/demolink/BUILD.gn文件，指定源码和头文件路径，编译输出静态库文件libexample_demolink.a。

      1. static_library("example_demolink") {
      2.     sources = [
      3.         "helloworld.c"
      4.     ]
      6.     include_dirs = [
      7.         "//utils/native/liteos/include",
      8.         "//vendor/hisi/wifi-iot/hi3861/3rd_sdk/demolink"
      9.     ]
      10. }

      修改./applications/sample/wifi-iot/app/BUILD.gn，使demolink参与编译。

      1. import("//build/lite/config/component/lite_component.gni")
      2. lite_component("app") {
      3.     features = [
      4.         "demolink:example_demolink"
      5.     ]
      6. }

    在代码根目录下，执行命令“python build.py wifiiot”编译输出版本包。最后启动运行，运行结果如图所示，与demolink预期相符。

    1. ready to OS start
    2. sdk ver:Hi3861V100R001C00SPC024 2020-08-05 16:30:00
    3. formatting spiffs...
    4. FileSystem mount ok.
    5. wifi init success!
    6. it is demosdk entry.
    7. it is demo biz: hello world.

    结束

    至此，三方SDK集成已介绍完毕。