4. fbdev ioctl 命令：核心控制接口详解

在 Linux Framebuffer 驱动体系中，用户空间程序通过 ioctl() 系统调用与内核驱动交互。这些 ioctl 命令是调试和配置 Framebuffer 设备的核心工具，涵盖了屏幕参数读取/设置、固定信息查询、以及电源管理（如屏幕空白）等关键操作。本章将深入剖析 FBIOGET_VSCREENINFO、FBIOPUT_VSCREENINFO、FBIOGET_FSCREENINFO 和 FBIOBLANK 这四个最常用的命令。

4.1 FBIOGET_VSCREENINFO：获取可变屏幕信息

该命令用于读取当前 Framebuffer 设备的可变参数，这些参数通常可以在运行时动态修改。它填充一个 struct fb_var_screeninfo 结构体，包含分辨率、位深、像素格式、时序等关键信息。

典型使用场景：调试工具 fbset 通过此命令读取当前显示模式并展示给用户。故障排查时，检查 bits_per_pixel 和 pixclock 是否与显示器 EDID 信息匹配，是解决“花屏”或“无信号”问题的第一步。

#include <linux/fb.h>
#include <sys/ioctl.h>
#include <fcntl.h>

int fd = open("/dev/fb0", O_RDWR);
struct fb_var_screeninfo varinfo;

if (ioctl(fd, FBIOGET_VSCREENINFO, &varinfo) == -1) {
    perror("FBIOGET_VSCREENINFO failed");
    return -1;
}

printf("Resolution: %dx%d, %d bpp\n",
       varinfo.xres, varinfo.yres, varinfo.bits_per_pixel);
printf("Virtual: %dx%d\n",
       varinfo.xres_virtual, varinfo.yres_virtual);
printf("Pixel clock: %d ps\n", varinfo.pixclock);

4.2 FBIOPUT_VSCREENINFO：设置可变屏幕信息

此命令允许应用程序修改 Framebuffer 的可变参数，从而实现分辨率切换、色彩深度调整、刷新率变更等操作。修改后，驱动会尝试重新配置硬件；如果参数无效，ioctl 将返回错误。

调试技巧：在设置新参数前，先调用 FBIOGET_VSCREENINFO 获取当前值，然后修改目标字段，最后调用 FBIOPUT_VSCREENINFO。如果失败，驱动通常会在内核日志（dmesg）中输出具体原因。

struct fb_var_screeninfo new_var;
// 先获取当前值作为基础
ioctl(fd, FBIOGET_VSCREENINFO, &new_var);

// 修改为目标分辨率
new_var.xres = 1024;
new_var.yres = 768;
new_var.bits_per_pixel = 32;

// 尝试应用新设置
if (ioctl(fd, FBIOPUT_VSCREENINFO, &new_var) == -1) {
    perror("FBIOPUT_VSCREENINFO failed");
    // 检查 dmesg 获取硬件限制信息
}

4.3 FBIOGET_FSCREENINFO：获取固定屏幕信息

该命令用于读取 Framebuffer 设备的固定属性，这些属性在驱动初始化时确定，通常不可修改。它填充 struct fb_fix_screeninfo 结构体，包含显存地址、行长度、内存类型等底层信息。

字段	类型	说明
smem_start	unsigned long	显存的物理起始地址（调试用，用户空间不可直接访问）
smem_len	__u32	显存总大小（字节），决定最大可支持的虚拟分辨率
line_length	__u32	一行像素占用的字节数（包含对齐填充）
type	__u32	Framebuffer 类型（如 FB_TYPE_PACKED_PIXELS）
visual	__u32	颜色模式（真彩色、伪彩色、直接彩色等）
accel	__u16	硬件加速类型（0 表示无加速）

调试价值：line_length 是计算帧缓冲区偏移的关键。例如，要访问第 y 行、第 x 列的像素，偏移量为 y * line_length + x * (bits_per_pixel / 8)。如果 smem_len 过小，即使 FBIOPUT_VSCREENINFO 设置了高分辨率，实际写入时也会越界导致崩溃。

struct fb_fix_screeninfo fixinfo;
if (ioctl(fd, FBIOGET_FSCREENINFO, &fixinfo) == -1) {
    perror("FBIOGET_FSCREENINFO failed");
    return -1;
}

printf("Framebuffer memory: %u bytes at 0x%lx\n",
       fixinfo.smem_len, fixinfo.smem_start);
printf("Line length: %u bytes\n", fixinfo.line_length);
printf("Visual mode: %u\n", fixinfo.visual);

4.4 FBIOBLANK：屏幕空白与唤醒控制

此命令用于控制显示器的电源管理状态，允许应用程序将屏幕置为空白（Blank）或恢复显示（Unblank）。它接受一个整数参数，表示空白模式。

宏定义	值	行为
FB_BLANK_UNBLANK	0	恢复屏幕显示，唤醒显示器
FB_BLANK_NORMAL	1	正常空白（通常关闭显示信号，但保持同步）
FB_BLANK_VSYNC_SUSPEND	2	暂停垂直同步（更深度的省电模式）
FB_BLANK_HSYNC_SUSPEND	3	暂停水平同步
FB_BLANK_POWERDOWN	4	完全关闭显示电源（最省电）

// 关闭屏幕（进入省电模式）
int blank_mode = FB_BLANK_POWERDOWN;
if (ioctl(fd, FBIOBLANK, blank_mode) == -1) {
    perror("FBIOBLANK POWERDOWN failed");
}

// 等待一段时间后唤醒
sleep(2);
blank_mode = FB_BLANK_UNBLANK;
if (ioctl(fd, FBIOBLANK, blank_mode) == -1) {
    perror("FBIOBLANK UNBLANK failed");
}

4.5 命令对比与调试优先级

在实际调试中，这四个命令的使用频率和目的各不相同。下表总结了它们的核心差异和典型应用场景。

命令	方向	数据结构	典型调试用途
FBIOGET_VSCREENINFO	读取	struct fb_var_screeninfo	检查当前分辨率、位深、时序参数是否正常
FBIOPUT_VSCREENINFO	写入	struct fb_var_screeninfo	尝试修复显示模式、切换分辨率、调整刷新率
FBIOGET_FSCREENINFO	读取	struct fb_fix_screeninfo	确认显存大小、行长度、硬件加速能力
FBIOBLANK	写入	int (空白模式)	测试屏幕电源管理、诊断唤醒失败问题

调试优先级建议：当遇到显示异常时，建议按以下顺序使用 ioctl 命令进行排查：

1. 先调用 FBIOGET_FSCREENINFO，确认显存和行长度是否合理。
2. 再调用 FBIOGET_VSCREENINFO，检查当前分辨率、位深和时序。
3. 如果参数异常，尝试用 FBIOPUT_VSCREENINFO 设置一个已知正确的模式。
4. 如果屏幕完全不亮，使用 FBIOBLANK 发送 FB_BLANK_UNBLANK 排除电源管理问题。

4.6 综合调试示例：使用 ioctl 诊断“黑屏”问题

假设系统启动后 Framebuffer 设备正常打开，但屏幕始终黑屏。以下是一个完整的 C 语言调试片段，展示如何组合使用上述 ioctl 命令进行诊断。

#include <stdio.h>
#include <fcntl.h>
#include <unistd.h>
#include <sys/ioctl.h>
#include <linux/fb.h>

int main() {
    int fd = open("/dev/fb0", O_RDWR);
    if (fd < 0) { perror("open"); return 1; }

    struct fb_fix_screeninfo fix;
    struct fb_var_screeninfo var;
    int blank;

    // 1. 检查固定信息
    if (ioctl(fd, FBIOGET_FSCREENINFO, &fix) == 0) {
        printf("FIX: smem_len=%u, line_length=%u\n",
               fix.smem_len, fix.line_length);
    } else {
        perror("FBIOGET_FSCREENINFO");
    }

    // 2. 检查可变信息
    if (ioctl(fd, FBIOGET_VSCREENINFO, &var) == 0) {
        printf("VAR: %dx%d, %d bpp, pixclock=%d\n",
               var.xres, var.yres, var.bits_per_pixel, var.pixclock);
    } else {
        perror("FBIOGET_VSCREENINFO");
    }

    // 3. 尝试唤醒屏幕（如果被空白）
    blank = FB_BLANK_UNBLANK;
    if (ioctl(fd, FBIOBLANK, blank) == 0) {
        printf("Screen unblanked successfully\n");
    } else {
        perror("FBIOBLANK UNBLANK");
    }

    // 4. 如果分辨率异常，尝试设置为标准模式
    if (var.xres != 1024 || var.yres != 768) {
        var.xres = 1024;
        var.yres = 768;
        var.bits_per_pixel = 32;
        if (ioctl(fd, FBIOPUT_VSCREENINFO, &var) == 0) {
            printf("Resolution set to 1024x768 @32bpp\n");
        } else {
            perror("FBIOPUT_VSCREENINFO");
        }
    }

    close(fd);
    return 0;
}