Skip to content

Latest commit

 

History

History
124 lines (101 loc) · 5.77 KB

README_zh-cn.md

File metadata and controls

124 lines (101 loc) · 5.77 KB

PFW（Parameter-Framework）

[English | 简体中文]

概述

Media Policy 通过 PFW 来构造路由、音频策略等各种状态。PFW 是一个基于配置文件和回调函数来构造状态机的通用框架。

  • 在 PFW 配置文件中，我们会定义状态机中有哪些状态，每个状态成立的条件，用于判断的变量。
  • 回调函数则构成了状态机的动作。

pfw 框架图

项目目录

.
├── context.c
├── criterion.c
├── dump.c
├── include
│   └── pfw.h
├── internal.h
├── Kconfig
├── Make.defs
├── Makefile
├── parser.c
├── README.md
├── README_zh-cn.md
├── sanitizer.c
├── system.c
├── test
│   ├── criteria.txt
│   ├── Makefile
│   ├── settings.pfw
│   └── test.c
└── vector.c

功能介绍

PFW 模块主要包含创建系统，修改变量等功能。

  • 创建系统：提供配置文件路径和插件来创建 pfw 系统，通过实现了 on_load/on_save 方法，可以让 PFW 系统具有读取和即时保存的功能。
  • 修改变量：pfw_setint 等方法提供修改单个变量值的接口。
  • 查询变量：查询单个变量的值，或者通过 dump 打印整个系统的状态。
  • 应用变化：把当前的变量取值应用到状态机上，如果发生了变化，便会根据配置文件中的逻辑调用相应的插件。
  • 订阅插件：通过名字订阅制定的插件，注册一个 callback 到插件中，这样在相应的插件被调用时，也会调用之前注册的 callback，从而通知到订阅者。

编写 PFW 配置文件

配置文件组成

PFW 配置文件由 criteria.txt 和 settings.pfw 两个文件组成：

  • criteria.txt：定义系统中的所有变量，以及变量之间的依赖关系。
  • settings.pfw：定义系统中的规则，以及状态之间的转移条件。

Criteria 语法

criteria.txt 文件中，每一行定义一个变量，每行 := 和 |= 右边表示一种语法展开的可能，格式为：

<类型> <变量名>:<值域>

类型变量的本质上都是 int32_t，但是取值会可以被解释为三种类型：

  • NumericalCriterion：数值型，即最原始的 int 型，取值范围是 INT32_MIN 到 INT32_MAX。
  • ExclusiveCriterion：枚举型，类似 C 语言的 enum，从 0 开始的若干个值被解释为有意义的字符串。
  • InclusiveCriterion：掩码型，从低位到高位的若干个 bit 被解释为有意义的字符串。

变量名：每个变量可以有一个或更多的名字，在读写变量时这些名字都绑定到同一个变量实体。

值域：

  • NumericalCriterion 的值域用一个或更多开区间表示。
  • ExclusiveCriterion 和 InclusiveCriterion 的值域则用一个或更多的字符串表示。

Criteria 文件编写示例

以 Audio policy 为例：

NumericalCriterion MediaVolume MusicVolume : [0,10] = 5
ExclusiveCriterion AudioMode               : normal phone
InclusiveCriterion AvailableDevices        : mic sco a2dp = mic
  • 媒体音量：数值型，取值范围是 0～10；初始值为 5。
  • 音频模式：枚举型，取值 0 对应 normal 模式，取值 1 对应 phone 模式；初始值默认为 0。
  • 可用设备：掩码型，取值 0 为空集，取值 1 表示 mic，取值 2 表示 sco，取值 3 表示 mic|sco，……，取值 7 表示 mic|sco|a2dp；初始便开启 mic。

Settings.pfw 语法

settings 文件由若干个 domain 组成，每个 domain 都代表一个状态机，这个配置文件通过缩进来区分层次结构，每个 tab 或者4个空格表示一级缩进，且 tab 和空格不能混用（与 python 相同）。

  • 每个状态机有若干个 conf，每个 conf 都代表一个状态。

  • 每个状态有条件和动作两部分，我们应用变量（criterion）时，会按顺序遍历所有状态，我们会进入首先满足条件的状态，如果进去了一个新的状态，就会执行其动作。

    domain: string
    conf: string
        <RULES>
        <ACTS>

  • RULES 部分是对 criterion 取值的约束，可以通过且和或递归地组合起来；不同种类的 criterion 约束使用不同的谓词。

  • ACTS 是一次或多次插件回调的执行。在 ACTS 中，若想参考 criterion 变量当前的值，而非一个定值，这种情况我们支持下面的语法：

    param%criterion%param

Settings 文件编写示例

以 Audio sco 节点控制为例，当 sco 可用，用户也需要时，会通过 FFmpegCommand 插件更新采样率，并打开 sco 输入输出节点：

domain: SCO
    conf: enable
        ALL
            UsingDevices Includes sco
            AvailableDevices Includes sco
        FFmpegCommand = sco,sample_rate,%HFPSampleRate%;sco,play,;
    conf: disable
        ALL
        FFmpegCommand = sco,pause,;

检查工具

在 pfw/test 目录下，我们配置了在 host 上使用的 Makefile，可以编译生成 test 命令行工具，可以在其中输入命令调试同一文件夹下的两个 .conf 配置文件，同时在开发 pfw 新功能时，也可以借此工具快速检查代码。

pfw/test$ make cc -o test ../system.c ../parser.c ../context.c ../vector.c ../sanitizer.c ../criterion.c test.c -Wall -Werror -O0 -g -I ../include -D CONFIG_LIB_PFW_DEBUG -fsanitize=address -fsanitize=leak
pfw/test$ ./test
pfw> dump         //打印dump信息
pfw> setint persist.media.MediaVolume 7     //设置MediaVolume的值为7