鸿蒙操作系统系列——Hi3516 OpenHarmony_release_v1.1.0 LTS版本led内核态驱动与用户态应用贯通篇

Hi3516 OpenHarmony_release_v1.1.0 LTS版本led内核态驱动与用户态应用贯通篇

此文档是针对 OpenHarmony 2021年4月10日发布的OpenHarmony_release_v1.1.0 LTS 版本分析。

1. 开发环境

1. HiSpark_AI_Hi3516D300开发板

2. 虚拟机安装Ubuntu18.04版本，参考https://device.harmonyos.com/cn/docs/start/introduce/oem_minitinier_environment_lin-0000001105407498搭好建开发环境。

2. 开发目标

在HiSpark_AI_Hi3516D300开发板上实现红外LED灯的亮灭控制，支持内核态驱动程序和用户态应用程序双向通信，实现用户态发送一个控制红外灯亮灭的消息到内核态，同时内核态返回灯的状态消息发送到用户态程序。

3. 开发准备

1）板卡级编译配置文件：device/hisilicon/hispark_taurus/sdk_liteos/config.gni

2）hi3516dv300驱动闭源lib库的路径在目录：device/hisilicon/drivers/libs/ohos/llvm/hi3516dv300

3）Hi3516开发板的红外灯的 IO 口编号为GPIO5_1。

4. 内核态开发

4.1 HDF简介

HDF（OpenHarmony Driver Foundation）驱动框架，为驱动开发者提供驱动框架能力，包括驱动加载、驱动服务管理和驱动消息机制。旨在构建统一的驱动架构平台，为驱动开发者提供更精准、更高效的开发环境，力求做到一次开发，多系统部署。

HDF框架以组件化的驱动模型作为核心设计思路，为开发者提供更精细化的驱动管理，让驱动开发和部署更加规范。HDF框架将一类设备驱动放在同一个host里面，驱动内部实现开发者也可以将驱动功能分层独立开发和部署，支持一个驱动多个node，HDF框架管理驱动模型如下图所示。

4.2 HDF实现

4.2.1 框架驱动实现

在vendor/huawei/hdf/sample/platform目录下新增led目录，新建如下文件夹和文件，其中include文件夹包含led_driver.h，src文件夹包含led_driver.c，led_driver.c文件实现HDF驱动框架代码。

主要代码如下。

#include "hdf_device_desc.h"    // HDF框架对驱动开放相关能力接口的头文件
#include "hdf_log.h"            // HDF框架提供的日志接口头文件
#include "device_resource_if.h" // HDF框架获取设备配置信息的接口头文件

//驱动对外提供的服务能力，将相关的服务接口绑定到HDF框架
int32_t HdfLedDriverBind(struct HdfDeviceObject *deviceObject)
{
    if (deviceObject == NULL)
    {
        HDF_LOGE("Led driver bind failed!");
        return HDF_ERR_INVALID_OBJECT;
    }
    static struct IDeviceIoService ledService = {
        .Dispatch = LedDriverDispatch,
    };
    deviceObject->service = (struct IDeviceIoService *)(&ledService);
    HDF_LOGD("Led driver bind success");
    return HDF_SUCCESS;
}

// 驱动自身业务初始的接口
int32_t HdfLedDriverInit(struct HdfDeviceObject *deviceObject)
{
    if (deviceObject == NULL)
    {
        HDF_LOGE("Led driver Init failed!");
        return HDF_ERR_INVALID_OBJECT;
    }
    HDF_LOGD("Led driver Init success");
    return HDF_SUCCESS;
}

// 驱动资源释放的接口
void HdfLedDriverRelease(struct HdfDeviceObject *deviceObject)
{
    if (deviceObject == NULL)
    {
        HDF_LOGE("Led driver release failed!");
        return;
    }

    HDF_LOGD("Led driver release success");
    return;
}

// 定义驱动入口的对象，必须为HdfDriverEntry（在hdf_device_desc.h中定义）类型的全局变量
struct HdfDriverEntry g_ledDriverEntry = {
    .moduleVersion = 1,
    .moduleName = "HDF_LED",
    .Bind = HdfLedDriverBind,
    .Init = HdfLedDriverInit,
    .Release = HdfLedDriverRelease,
};

// 调用HDF_INIT将驱动入口注册到HDF框架中，在加载驱动时HDF框架会先调用Bind函数,再调用Init函数加载该驱动，当Init调用异常时，HDF框架会调用Release释放驱动资源并退出。
HDF_INIT(g_ledDriverEntry);

4.2.2 驱动编译

在vendor/huawei/hdf/sample/platform/led目录下新增Makefile文件。

include $(LITEOSTOPDIR)/config.mk
include $(LITEOSTOPDIR)/../../drivers/adapter/khdf/liteos/lite.mk

MODULE_NAME := hdf_led

LOCAL_CFLAGS += $(HDF_INCLUDE)

LOCAL_SRCS += src/led_driver.c \

LOCAL_INCLUDE := ./include
LOCAL_CFLAGS += -fstack-protector-strong

include $(HDF_DRIVER)

4.2.3 链接到内核镜像

修改device/hisilicon/drivers/lite.mk 文件新增以下内容。

ifeq ($(LOSCFG_DRIVERS_HDF_PLATFORM_LED), y)
        LITEOS_BASELIB += -lhdf_led
        LIB_SUBDIRS    += $(LITEOS_SOURCE_ROOT)/vendor/huawei/hdf/sample/platform/led
endif

4.2.4 驱动配置

驱动配置包含两部分，HDF框架定义的驱动设备描述和驱动的私有配置信息。

（1）驱动设备配置

需要修改device/hisilicon/hispark_taurus/sdk_liteos/config/device_info/device_info.hcs文件，新增以下内容。其中，moduleName、serviceName和deviceMatchAttr 都比较重要，分布链接到源码的不同位置，我这里都分开命名，便于理解，设备级配置信息也需要同步修改，在文件vendor/hisilicon/hispark_taurus/config/device_info/device_info.hcs里面同步以下信息。

device_led :: device {              // led设备节点
    device0 :: deviceNode {         // led驱动的DeviceNode节点
    policy = 2;                     // policy字段是驱动服务发布的策略，在驱动服务管理章节有详细介绍
    priority = 40;                  // 驱动启动优先级（0-200），值越大优先级越低，建议默认配100，优先级相同则不保证device的加载顺序
    permission = 0644;              // 驱动创建设备节点权限
    moduleName = "HDF_LED";         // 驱动名称，该字段的值必须和驱动入口结构的moduleName值一致
    serviceName = "led_service";    // 驱动对外发布服务的名称，必须唯一
    deviceMatchAttr = "led_config"; // 驱动私有数据匹配的关键字，必须和驱动私有数据配置表中的match_attr值相等
    }
}

（2）驱动私有配置信息

如果驱动有私有配置，可以添加一个驱动的配置文件，填写驱动的配置信息，HDF框架在加载驱动的时候，会将对应的配置信息获取并保存在HdfDeviceObject 的property里面传递给驱动。在device/hisilicon/hispark_taurus/sdk_liteos/config/led目录新增led_config.hcs文件，内容如下。

root{
    LedDriverConfig {
        led_version = 1;
        match_attr = "led_config";   //该字段的值必须和device_info.hcs中的deviceMatchAttr值一致
    }
}

4.2.5 板级配置

配置信息定义之后，需要将该配置文件添加到板级配置入口文件device/hisilicon/hispark_taurus/sdk_liteos/config/hdf.hcs。

#include "led/led_config.hcs"

4.3 驱动消息机制实现

当用户态应用程序和内核态驱动程序需要交互数据时，可以使用HDF框架的消息机制来实现。消息通信机制可以在用户态和内核态之间架起桥梁，这为我们之后的APP与底层驱动提供了双向通信的能力。本案例在用户态发送一个控制红外灯亮灭的消息到内核态，同时内核态返回灯的状态消息发送到用户态程序。

实现内核态的消息服务接口，编辑 led_driver.c, 实现服务基类成员IDeviceIoService中的Dispatch方法。收到用户态发来的命令后，操作红外LED设备，然后将返回值通过reply传回，最后将收到的命令回传给用户态程序。

// Dispatch是用来处理用户态发下来的消息
int32_t LedDriverDispatch(struct HdfDeviceIoClient *client, int cmdCode, struct HdfSBuf *data, struct HdfSBuf *reply)
{
    int32_t result = HDF_FAILURE;

    if (client == NULL || client->device == NULL)
    {
        HDF_LOGE("Led driver device is NULL");
        return HDF_ERR_INVALID_OBJECT;
    }

    switch (cmdCode)
    {
	    case LED_WRITE_READ:
	    	//读取用户发过来的数据 
	        const char *recv = HdfSbufReadString(data);
	        if (recv != NULL)
	        {
	            HDF_LOGI("recv: %s", recv);
				if (strcmp(recv, "on") == 0)
				{
					LedControl(LED_LIGHT_ON);
					result = 1;
				}
				else if (strcmp(recv, "off") == 0)
				{
					LedControl(LED_LIGHT_OFF);
					result = 0;
				}
				else
				{
					HDF_LOGE("recv: %s invalid led mode", recv);
					result = -1;
				}
				
				//返回值通过reply回传
	            if (!HdfSbufWriteInt32(reply, result))
	            {
	                HDF_LOGE("replay is fail");
	            }
	            
	            //返回接收的数据发回给用户程序
	            return HdfDeviceSendEvent(client->device, cmdCode, data);
	        }
	        break;

	    default:
	        break;
    }
	
    return result;
}

修改 HdfLedDriverBind函数，将服务绑定到框架。

//驱动对外提供的服务能力，将相关的服务接口绑定到HDF框架
int32_t HdfLedDriverBind(struct HdfDeviceObject *deviceObject)
{
    if (deviceObject == NULL)
    {
        HDF_LOGE("Led driver bind failed!");
        return HDF_ERR_INVALID_OBJECT;
    }
    static struct IDeviceIoService ledService = {
        .Dispatch = LedDriverDispatch,
    };
    deviceObject->service = (struct IDeviceIoService *)(&ledService);
    HDF_LOGD("Led driver bind success");
    return HDF_SUCCESS;
}

4.4 业务代码实现

编辑 led_driver.c，实现业务逻辑控制代码。通过mode参数实现LED灯的亮灭功能。其中Hi3516DV300的控制器管理12组GPIO管脚，每组8个。GPIO号 = GPIO组索引(0~11)* 每组GPIO管脚数(8) + 组内偏移，GPIO5_1的GPIO号 = 5 * 8 +1 = 41。

static int32_t LedControl(int mode)
{
    int32_t ret;

    /* LED的GPIO管脚号 */
    uint16_t gpio = 5 * 8 + 1;  // 红外补光灯

    /* 将GPIO管脚配置为输出 */
    ret = GpioSetDir(gpio, GPIO_DIR_OUT);
    if (ret != 0)
    {
        HDF_LOGE("GpioSetDir: failed, ret %d\n", ret);
        return ret;
    }

	//点亮LED
    if (mode == LED_LIGHT_ON)
    {
        ret = GpioWrite(gpio, GPIO_VAL_HIGH);
    }
    else if (mode == LED_LIGHT_OFF) //关闭LED
    {
        ret = GpioWrite(gpio, GPIO_VAL_LOW);
    }
	else
    {
    	HDF_LOGE("LedControl: invalid led mode.\n");
		ret = -1;
	}
    	
    if (ret != 0)
    {
        HDF_LOGE("LedControl: failed, ret = %d\n", ret);
        return ret;
    }
	
    return ret;
}

4.5 配置KConfig

drivers/adapter/khdf/liteos/Kconfig添加LED相关的配置项控制编译。

config DRIVERS_HDF_PLATFORM_LED
    bool "Enable HDF platform led driver"
        default n
    depends on DRIVERS_HDF_PLATFORM
    help
      Answer Y to enable HDF platform led driver.

在kernel/liteos_a目录下输入make menuconfig配置KConfig文件，选择Driver->Enable HDF platform led driver选项。

系统编译配置文件：kernel/liteos_a/tools/build/config/hispark_taurus_clang.config，LiteOS内核对配置进行修改后需要将内核配置的.config文件拷贝到上述路径下，命令如下：

cp .config  tools/build/config/debug/hispark_taurus_clang.config

因为hb build -f每次会从kernel/liteos_a/tools/build/config/hispark_taurus_clang.config拷贝一份默认的配置到kernel/litos_a目录下把之前的配置给覆盖掉。

5. 用户态开发

我们开始写个led测试程序通过消息机制来与内核态交互，新建applications/sample/camera/ledApp/my_led_app.c源文件。代码如下：

//设置回调函数，收到内核态发来的消息，打印信息
static int OnDevEventReceived(void *priv, uint32_t id, struct HdfSBuf *data)
{
    const char *string = HdfSbufReadString(data);
    if (string == NULL)
    {
        printf("fail to read string in event data\n");
        return HDF_FAILURE;
    }
    printf("%s received driver data: led %s\n", (char *)priv, string);

    return HDF_SUCCESS;
}

//先实现一个发送消息的函数SendEvent,发送字符串命令后,收回内核态reply中操作设备后的返回值,放入replyData中打印出来,操作成功返回0。
static int SendEvent(struct HdfIoService *serv, char *eventData)
{
    int ret = 0;
    struct HdfSBuf *data = HdfSBufObtainDefaultSize();
    if (data == NULL)
    {
        printf("fail to obtain sbuf data");
        return 1;
    }

    struct HdfSBuf *reply = HdfSBufObtainDefaultSize();
    if (reply == NULL)
    {
        printf("fail to obtain sbuf reply\n");
        ret = HDF_DEV_ERR_NO_MEMORY;
        goto out;
    }

    if (!HdfSbufWriteString(data, eventData))
    {
        printf("fail to write sbuf");
        ret = HDF_FAILURE;
        goto out;
    }

    ret = serv->dispatcher->Dispatch(&serv->object, LED_WRITE_READ, data, reply);
    if (ret != HDF_SUCCESS)
    {
        printf("fail to send service call\n");
        goto out;
    }

    int replyData = 0;
    if (!HdfSbufReadInt32(reply, &replyData))
    {
        printf("fail to get service call reply\n");
        ret = HDF_ERR_INVALID_OBJECT;
        goto out;
    }
    printf("Get reply is: %d\n", replyData);
out:
    HdfSBufRecycle(data);
    HdfSBufRecycle(reply);
    return ret;
}

//先获取led_service服务，通过服务名称，绑定到对应的驱动。然后设置监听，等待来自内核的消息。用户通过led on/off来控制红外LED灯的亮灭。
int main(int argc, char **argv)
{
	if (argc < 2)
	{
		printf("./ledApp [on/off]");
		return HDF_FAILURE;	
	}

    struct HdfIoService *serv = HdfIoServiceBind(LED_SERVICE);
    if (serv == NULL)
    {
        printf("fail to get service %s\n", LED_SERVICE);
        return HDF_FAILURE;
    }

    static struct HdfDevEventlistener listener = {
        .callBack = OnDevEventReceived,
        .priv = "ledApp"
    };

    if (HdfDeviceRegisterEventListener(serv, &listener) != HDF_SUCCESS)
    {
        printf("fail to register event listener\n");
        return HDF_FAILURE;
    }

    SendEvent(serv, argv[1]);

	sleep(2);  //延时2秒等待回应

    if (HdfDeviceUnregisterEventListener(serv, &listener))
    {
        printf("fail to  unregister listener\n");
        return HDF_FAILURE;
    }

    HdfIoServiceRecycle(serv);
    printf("exit!\n");

    return HDF_SUCCESS;
}

新建applications/sample/camera/ledApp/BUILD.gn,配置BUILD.gn

import("//build/lite/config/component/lite_component.gni")

executable("ledApp") {
  sources = [ "my_led_app.c" ]
  cflags = [ "-Wall" ]
  cflags_cc = cflags
  include_dirs = [
    "//drivers/framework/include/utils",
    "//drivers/adapter/khdf/liteos/osal/include",
    "//drivers/framework/ability/sbuf/include", 
    "//drivers/framework/core/shared/include",
    "//drivers/framework/core/host/include",
    "//drivers/framework/core/manager/include",
    "//drivers/framework/include/core",
    "//drivers/framework/include/utils",
    "//drivers/framework/utils/include",
    "//drivers/framework/include/osal",
  ]

  ldflags = [ "-lstdc++" ]
  ldflags += [ "-lpthread" ]
  ldflags += [ "-Wl,-rpath-link=$ohos_root_path/$root_out_dir" ]

  deps = [
    "//drivers/adapter/uhdf/manager:hdf_core",
    "//drivers/adapter/uhdf/posix:hdf_posix_osal",
  ]
  output_dir = "$root_out_dir/"
}

lite_component("led_app") {
  features = [
    ":ledApp",
  ]
}

在build/lite/components/applications.json文件新增如下内容。

{
    "component": "led_app",
    "description": "Led related samples.",
    "optional": "true",
    "dirs": [
    "applications/sample/camera/ledApp"
    ],
    "targets": [
    "//applications/sample/camera/ledApp:ledApp"
    ],
    "rom": "",
    "ram": "",
    "output": [],
    "adapted_kernel": [ "liteos_a" ],
    "features": [],
    "deps": {
    "components": [],
    "third_party": []
    }
},

6. 系统编译烧写

在系统根目录下执行hb build -f进行系统编译。

系统烧写可以采用TFTP简化烧写过程。

//更新内核
tftp 0x81000000 OHOS_Image.bin
mmc write 0x0 0x81000000 0x800 0x36c8

//更新根文件系统
tftp 0x81000000 rootfs_vfat.img
mmc write 0x0 0x81000000 0x5000 0x7fae

//更新用户数据空间
tftp 0x81000000 userfs_vfat.img
mmc write 0x0 0x81000000 0xf000 0x19000

7. 测试

测试结果符合设计目标。

OHOS # ./ledApp on
OHOS # Get reply is: 1
01-01 00:33:38.741 17 80 I 02500/led_driver: recv: on
ledApp received driver data: led on
exit!
01-01 00:33:40.742 17 81 I 02500/hdf_syscall_adapter: event listener task received exit event
01-01 00:33:40.742 17 81 I 02500/hdf_syscall_adapter: event listener task exit
      
OHOS # 
OHOS # 
OHOS # ./ledApp off
OHOS # Get reply is: 0
01-01 00:33:49.654 18 80 I 02500/led_driver: recv: off
ledApp received driver data: led off
exit!
01-01 00:33:51.654 18 81 I 02500/hdf_syscall_adapter: event listener task received exit event
01-01 00:33:51.654 18 81 I 02500/hdf_syscall_adapter: event listener task exit

8. 总结

驱动和应用开发涉及到文件和配置比较多，关系也比较纷繁，而且分散在各个目录，这里列出主要文件再梳理一下：

//应用主目录                                用户态
applications
|--sample
     |--camera
          |--ledApp
                |--BUILD.gn
                |--my_ledapp.c   //用户态主程序

//产品级主目录                                内核态
vender
|--huawei
     |--hdf
         |--sample
               |--platform
                      |--led
                           |--Makefile
                           |--src
                               |--led_driver.c 驱动实现文件
                           |--include
                               |--led_driver.h

//板卡级配置文件
drivers/adapter/khdf/liteos/Kconfig
device/hisilicon/drivers/lite.mk
device/hisilicon/hispark_taurus/sdk_liteos/config/device_info/device_info.hcs
device/hisilicon/hispark_taurus/sdk_liteos/config/hdf.hcs
device/hisilicon/hispark_taurus/sdk_liteos/config/led/led_config.hcs
//产品级配置文件
vendor/hisilicon/hispark_taurus/config.json
vendor/hisilicon/hispark_taurus/config/device_info/device_info.hcs
vendor/hisilicon/hispark_taurus/config/hdf.hcs
vendor/hisilicon/hispark_taurus/config/led/led_config.hcs
//应用级配置文件
build/lite/components/applications.json


大致上分三个部分：内核态、用户态和配置文件。

(1)  内核态
首先由led_driver.c生成名为led_service的服务，以g_ledDriverEntry结构注册到HCS框架。编译成hdf_led_driver驱动，通过device/hisilicon/drivers/lite.mk链接到内核镜像中。通过  HdfLedDriverBind函数将led_driver模块绑定到HDF框架，IDeviceIoService中的Dispatch方法来处理来自用户态消息。

(2)  用户态
用户态以HdfIoServiceBind通过服务名led_service来找到相应的驱动，用HdfSbufWriteString来发送消息，serv->dispatcher->Dispatch来接收返回值，通过HdfDeviceRegisterEventListener设置监听，来获取内核态主动发送的消息。

(3)驱动配置
以模块名led_driver找到注册到HCS框架的驱动程序,以服务名led_service暴露给用户态程序或内核态程序调用,以led_config链接驱动私有配置文件,最后通过配置文件来进行耦合，保证了灵活性。这种设计在分布式的场合中，会有比较大的便利性。