XPROC 框架应用层开发手册

一、 概述

​ XPROC 框架用于记录驱动/应用的运行状态、版本信息等参数。应用层开发者可以通过 UAPI 接口将业务模块注册到框架中，从而在 /proc/XPROC 节点下实时展示模块状态，便于系统维护和版权保护。

二、 发布包文件清单

发布版本包含以下文件，支持在交叉编译链下直接构建 ：

• 驱动文件：xproc.ko（核心驱动，需首先加载）

• 库文件：libxproc.a（应用层接口静态库）

• 头文件：

  xproc_data_type.h：核心数据结构与枚举定义

  xproc_driver_uapi.h：应用层接口定义

• 示例与构建：

  xproc_driver_sample.c：完整的参考代码

  Makefile / Makefile.param：工程构建配置文件

三、 数据结构定义

​ 开发者需在代码中包含 xproc_data_type.h。以下为核心枚举与结构体：

1. 模块类型 (xproc_module_type)

​ 用于定义被记录对象的属性：

typedef enum {
    MODULE_TYPE_KO = 0,     // 驱动类型
    MODULE_TYPE_LIB,        // 库类型
    MODULE_TYPE_APP,        // 程序/应用类型
    MODULE_TYPE_EXTERN      // 其他类型
} xproc_module_type;

2. 模块运行状态 (xproc_module_status)

​ 用于实时追踪模块的生命周期：

typedef enum {
    MODULE_STATUS_ACTIVE = 0,       // 模块处于活动状态
    MODULE_STATUS_INACTIVE,         // 模块处于非活动状态
    MODULE_STATUS_ERROR,            // 模块遇到错误
    MODULE_STATUS_LOADING,          // 模块正在加载
    MODULE_STATUS_UNLOADING,        // 模块正在卸载
    MODULE_STATUS_SUSPENDED,        // 模块被挂起
    MODULE_STATUS_TERMINATED,       // 模块被终止
    MODULE_STATUS_UNKNOWN           // 模块状态未知
} xproc_module_status;

3. 模块信息结构体 (xproc_module_info)

​ 注册和获取信息的核心载体：

typedef struct {
    char module_name[16];           // 模块名称（唯一标识）
    xproc_module_type module_type;  // 模块类型
    char module_version[8];         // 模块版本信息
    xproc_module_status module_status; // 模块运行状态
    char module_description[32];    // 模块描述信息
    char user_data[64];             // 模块私有数据（可存自定义参数）
    unsigned long long timestamp;    // 系统运行时间
    unsigned long long last_update;  // 最后更新时间
    unsigned long long run_time;     // 运行时间
    int priority;                   // 模块优先级
} xproc_module_info;

四、 应用层 API (UAPI) 说明

​ 所有应用层接口定义于 xproc_driver_uapi.h。调用前必须确保 xproc.ko 驱动已加载。

1. 基础控制接口

• 初始化设备节点： int xproc_device_init(void); 使用框架前必须调用，返回 0 表示成功。
• 去初始化设备节点： int xproc_device_exit(void); 程序退出前释放资源。
• 获取设备文件句柄： int xproc_device_get_fd(void); 获取底层 fd，常用于 select/poll 监听。

2. 模块管理接口

• 注册模块： int xproc_device_register_module(xproc_module_info *p_info); 向框架注册一个模块。若名称相同，则覆盖原有信息。
• 注销模块： int xproc_device_unregister_module(const char *name); 根据名称注销模块。
• 更新状态： int xproc_device_update_module_status(const char *name, xproc_module_status status); 仅更新模块的运行状态枚举值。

3. 数据交互接口

• 获取模块信息： int xproc_device_get_module_info(const char *name, xproc_module_info *p_info);
• 设置私有数据： int xproc_device_set_module_user_data(const char *name, const char *user_data, unsigned int data_size); 更新 xproc_module_info 中的 user_data 字段。
• 监听状态变更： int xproc_device_get_module_update(xproc_module_info *p_info); 配合 select/poll 使用。当有任何模块状态发生改变时，可通过此接口获取最新的变更信息。

4. 便捷接口 (Once 系列)

以下接口内部封装了 init 和 exit 操作，适合非频繁调用的简单场景：

• int xproc_device_register_module_once(xproc_module_info *p_info);
• int xproc_device_update_module_status_once(const char *name, xproc_module_status status);
• int xproc_device_get_module_info_once(const char *name, xproc_module_info *p_info);

五、 简易使用示例

1.驱动加载

2.Sample运行

3.应用层参考代码

​ 具体示例可参考xproc_driver_sample.c。

#include "xproc_driver_uapi.h"

int main() {
    xproc_module_info my_app = {0};

    // 1. 初始化
    if (xproc_device_init() < 0) return -1;

    // 2. 填充信息并注册
    strcpy(my_app.module_name, "VideoCodec");
    my_app.module_type = MODULE_TYPE_LIB;
    strcpy(my_app.module_version, "V1.2.0");
    my_app.module_status = MODULE_STATUS_ACTIVE;
    xproc_device_register_module(&my_app);

    // 3. 运行中更新状态
    // ...
    xproc_device_update_module_status("VideoCodec", MODULE_STATUS_SUSPENDED);

    // 4. 退出
    xproc_device_exit();
    return 0;
}

六、 编译与集成

框架采用 Makefile.param 进行环境配置，方便移植到不同的嵌入式平台 。

1. 配置交叉编译环境

在发布包的 Makefile.param 中修改以下变量以适配您的 SDK ：

# 示例配置 (HiSilicon SS928V100)
ARCH := arm64
CROSS_COMPILE := aarch64-mix210-linux-
KERNELDIR := /your/path/to/linux-kernel #未使用

2. 执行编译

在当前目录下直接执行 make 即可生成测试程序 ：

make

编译脚本会自动链接 libxproc.a 静态库并生成可执行文件 xproc_driver_sample 。

3. 运行

将编译生成的 xproc.ko 和应用拷贝到板端：

insmod xproc.ko
./xproc_driver_sample

七、后续更新

如后续有更新将在以下Gitee地址进行更新：

https://gitee.com/uncleroderick/XPROC_Release