4. Weston 配置文件结构：weston.ini 核心配置项、核心模块加载、后端选择

Weston 合成器的所有运行时行为、显示参数、输入设备、后端类型以及模块扩展，几乎全部通过一个 INI 格式的文本文件 weston.ini 控制。理解这个文件的结构，是 RK 平台显示调试的第一步。本章将拆解 weston.ini 的段（Section）、键（Key）、值（Value）体系，并重点分析核心模块加载机制与后端选择策略。

调试提示：在 RK 平台开发阶段，建议始终使用 --config=/path/to/weston.ini 显式指定配置文件路径，避免系统默认路径下的缓存干扰。

4.1 weston.ini 整体结构概览

配置文件采用标准 INI 格式，由多个段（Section）组成，每个段以 [段名] 开头，内部包含若干 键=值 对。注释使用 # 或 ; 开头。

以下是一个针对 RK3566/RK3588 平台精简后的典型 weston.ini 骨架：

[core]
# 核心配置段
backend=drm-backend.so
modules=desktop-shell.so,ivi-shell.so
xwayland=true
idle-time=0

[shell]
# 桌面 shell 配置
background-color=0xff002244
locking=false
panel-position=top

[ivi-shell]
# ivi-shell 配置（用于多屏/多应用场景）
ivi-input-module=ivi-input-controller.so

[output]
# 输出设备配置
name=DSI-1
mode=1920x1080@60
transform=normal
scale=1

[output]
name=HDMI-A-1
mode=1920x1080@60
transform=normal
scale=1

[input-method]
# 输入法配置
path=/usr/lib/weston/libinput-backend.so

[libinput]
# libinput 设备配置
enable-tap=true
enable-dwt=true
关键点：段可以重复出现（如 [output]），每个同名段对应一个独立的输出设备或实例。解析器按顺序处理，后出现的同名段会追加到列表中。

4.2 核心配置段 [core] 详解

[core] 段是 Weston 启动的入口配置，决定了后端类型、模块加载策略、XWayland 支持等全局行为。下表列出了 RK 平台最常用的核心配置项：

配置项 值类型 说明 RK 平台推荐值
backend 字符串（.so 路径） 指定后端动态库，决定 Weston 如何与显示硬件交互 drm-backend.so
modules 逗号分隔的 .so 列表 启动时加载的模块列表，模块提供 shell、输入、协议扩展等功能 desktop-shell.so,ivi-shell.so
xwayland 布尔值（true/false） 是否启用 XWayland 兼容层，用于运行传统 X11 应用 true
idle-time 整数（秒） 空闲后进入屏幕节能模式的等待时间，0 表示禁用 0（开发调试时）
require-input 布尔值 是否要求至少一个输入设备存在才能启动 false（无触摸屏/鼠标时）
gbm-format 字符串 强制 GBM 表面格式，如 argb8888、xrgb8888 xrgb8888（减少 alpha 混合开销）
常见错误：在 RK 平台使用 backend=fbdev-backend.so 会导致无法启用 DRM 硬件叠加层（Planes），性能大幅下降。除非在极早期内核调试阶段，否则始终使用 drm-backend.so。

4.3 核心模块加载机制

Weston 采用模块化架构，核心功能（如窗口管理、输入处理、协议扩展）通过动态加载 .so 文件实现。modules 键指定了启动时加载的模块列表，模块加载顺序影响初始化流程。

模块加载流程如下：

  1. 解析 [core] 段：读取 modules 键，按逗号分割得到模块名列表。
  2. 路径搜索：在默认模块路径（通常是 /usr/lib/weston/）下查找对应的 .so 文件。
  3. dlopen 加载：使用 dlopen() 加载动态库，并调用模块的初始化函数（如 wet_module_init()）。
  4. 注册接口：模块向 Weston 核心注册 shell 接口、输入后端、协议扩展等。
  5. 初始化完成：所有模块加载成功后，Weston 进入事件循环。

下表列出了 RK 平台最常用的模块及其功能：

模块名 功能 依赖 RK 平台典型用途
desktop-shell.so 提供桌面窗口管理、面板、背景、锁定屏幕 无 通用 HMI、平板、单屏桌面
ivi-shell.so 提供 IVI（In-Vehicle Infotainment）表面布局管理，支持多屏独立控制 需要 ivi-layout.so 多屏异显、仪表盘、中控娱乐
fullscreen-shell.so 强制所有应用全屏，无窗口装饰 无 单应用信息亭、广告机
kiosk-shell.so 类似 fullscreen-shell，但支持多应用分屏 无 数字标牌、自助终端
libinput-backend.so 基于 libinput 的输入设备后端（触摸、鼠标、键盘） 无 所有需要输入交互的场景
ivi-input-controller.so IVI 输入控制器，将输入事件路由到指定表面 ivi-shell.so 多屏触摸输入隔离
模块加载顺序建议：在 RK 平台，建议将 desktop-shell.so 或 ivi-shell.so 放在模块列表最前面，确保 shell 接口在输入后端之前注册，避免输入事件路由失败。

4.4 后端选择：drm-backend vs. fbdev-backend vs. headless-backend

后端（Backend）是 Weston 与底层显示硬件之间的抽象层。不同的后端决定了 Weston 如何分配缓冲区、如何提交画面、以及是否支持硬件叠加层。RK 平台主要涉及三种后端：

后端 底层接口 硬件叠加层支持 性能 适用场景
drm-backend.so DRM / KMS 是（支持 Planes、Blending） 高（零拷贝、Page Flip） 所有 RK 产品级显示（推荐）
fbdev-backend.so Linux FBDEV 否（仅单 Framebuffer） 低（CPU 合成、memcpy） 仅用于早期内核调试或无 DRM 驱动时
headless-backend.so 无物理显示（Pixman 渲染） 否 N/A（纯软件渲染） 自动化测试、远程渲染、无头服务器

在 RK 平台，drm-backend.so 是唯一能发挥 RK 芯片 VPU（Video Processing Unit）和显示控制器硬件叠加能力的后端。它通过 DRM 接口直接操作 KMS（Kernel Mode Setting），支持多个硬件 Plane 的独立缩放、旋转和混合。

性能对比数据：在 RK3588 平台上，使用 drm-backend.so 配合硬件 Plane 叠加 4 层 UI，GPU 负载仅为 5-8%；而使用 fbdev-backend.so 实现相同效果，GPU 负载高达 40-60%，且帧率不稳定。

4.5 后端选择与模块加载关系图

下图展示了 Weston 启动时，[core] 段如何驱动后端加载与模块初始化，以及它们之间的数据流关系：

Weston 启动：后端选择与模块加载流程 weston.ini [core] backend=xxx-backend.so modules=mod1.so,mod2.so dlopen(backend.so) dlopen(module.so) 循环 后端初始化：DRM KMS 创建输出、分配 CRTC/Planes 模块初始化：注册接口 Shell、输入、协议扩展 Weston 事件循环启动 合成、输入、模块回调 说明：后端必须先于模块初始化完成，因为模块（如 shell）需要查询后端提供的输出能力。 RK 平台推荐使用 drm-backend.so + desktop-shell.so 或 ivi-shell.so 组合。

4.6 输出设备配置 [output] 段

每个 [output] 段对应一个物理或虚拟显示输出。在 RK 平台，常见的输出名称包括 DSI-1（MIPI 屏）、HDMI-A-1（HDMI 输出）、DP-1（DisplayPort）等。输出名称由内核 DRM 驱动枚举，可通过 modetest 命令查看。

常用输出配置项：

配置项 值类型 说明 示例
name 字符串 输出设备名称，必须与 DRM 枚举名称一致 DSI-1
mode 字符串 分辨率@刷新率，或 preferred（使用 EDID 首选模式） 1920x1080@60
transform 字符串 画面旋转/翻转：normal、90、180、270、flipped 等 normal
scale 整数 缩放因子，1 为原始大小，2 为 2x 缩放（HiDPI） 1
background-color 十六进制 ARGB 输出背景色，格式 0xAARRGGBB 0xff002244
多屏配置技巧：在 RK 平台实现双屏异显时，需要为每个输出单独编写 [output] 段，并确保 name 与硬件连接一致。如果某个输出未在配置文件中列出，Weston 会使用内核提供的默认模式。

4.7 输入设备配置 [libinput] 段

[libinput] 段用于配置 libinput 输入后端的行为。在 RK 平台，触摸屏和遥控器是常见的输入设备，合理配置可以显著提升用户体验。

常用输入配置项：

配置项 值类型 说明 RK 平台推荐值
enable-tap 布尔值 启用触摸板点击模拟 true（触摸屏场景）
enable-dwt 布尔值 启用打字时禁用触摸板 true（带键盘设备）
calibration 字符串 触摸屏校准矩阵，6 个浮点数 根据实际校准工具生成
rotation 整数 触摸输入旋转角度（0/90/180/270） 与输出 transform 保持一致
触摸旋转对齐：当输出画面旋转（如 transform=90）时，必须同步设置 rotation=90，否则触摸坐标与显示画面不匹配，导致触摸位置偏移。

4.8 本章小结

  • weston.ini 是 Weston 合成器的唯一配置文件，采用 INI 格式，段可重复。
  • [core] 段决定后端类型（backend）和模块加载列表（modules），是配置的入口。
  • RK 平台始终使用 drm-backend.so 以发挥硬件叠加层性能，避免使用 fbdev-backend.so。
  • 模块加载顺序影响初始化流程，shell 模块应优先于输入模块加载。
  • [output] 段配置每个显示输出的分辨率、旋转和缩放，多屏异显需要多个同名段。
  • [libinput] 段配置触摸和输入设备，触摸旋转必须与输出旋转对齐。
← 上一章 📖 返回目录 下一章 →