4. FrameBuffer 用户态接口：/dev/fb* 设备节点、mmap 映射、ioctl 控制、fbset 工具使用

在 Linux 显示子系统中，FrameBuffer 驱动向用户空间暴露了一套经典的基于文件系统的接口。这套接口以 /dev/fb* 设备节点为核心，配合 mmap 内存映射、ioctl 控制命令以及 fbset 等用户态工具，构成了早期嵌入式图形栈的基础。理解这套接口是掌握显示驱动迁移的关键前提。

4.1 /dev/fb* 设备节点体系

系统启动后，FrameBuffer 驱动会注册多个设备节点，通常位于 /dev/ 目录下：

设备节点的创建由内核的 device_create() 或 misc_register() 机制完成。用户态程序通过 open("/dev/fb0", O_RDWR) 获取文件描述符，后续所有操作都基于该描述符进行。

4.2 mmap 内存映射：直接操作显存

mmap 是 FrameBuffer 用户态接口中最核心的操作。它允许应用程序将内核空间的显示缓冲区直接映射到用户空间虚拟地址，从而实现对显存的零拷贝访问。

4.2.1 mmap 调用原型与参数

#include <sys/mman.h>
#include <fcntl.h>
#include <unistd.h>

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

/* 获取屏幕参数（后续 ioctl 详解）*/
struct fb_var_screeninfo vinfo;
ioctl(fd, FBIOGET_VSCREENINFO, &vinfo);

/* 计算映射大小：屏幕总像素 × 每像素字节数 */
size_t screensize = vinfo.xres * vinfo.yres * vinfo.bits_per_pixel / 8;

/* 将显存映射到用户空间 */
char *fbp = (char *)mmap(NULL, screensize, PROT_READ | PROT_WRITE,
                         MAP_SHARED, fd, 0);
if (fbp == MAP_FAILED) {
    perror("mmap framebuffer");
    close(fd);
    return -1;
}

/* 现在可以直接通过 fbp 指针读写显存 */
/* 例如：将屏幕左上角像素设为红色 */
*(fbp + 0) = 0x00;     /* B */
*(fbp + 1) = 0x00;     /* G */
*(fbp + 2) = 0xFF;     /* R */
*(fbp + 3) = 0x00;     /* A (如果支持) */

/* 使用完毕后解除映射 */
munmap(fbp, screensize);
close(fd);

4.2.2 显存布局与像素操作

映射后的显存是一个线性缓冲区，像素按照从左到右、从上到下的顺序排列。常见的像素格式包括：

对于 RGB565 格式，设置像素 (x, y) 颜色的示例：

/* 假设 vinfo.bits_per_pixel == 16 */
int x = 100, y = 50;
int line_length = vinfo.xres * 2;  /* 每行字节数 */
unsigned short *pixel = (unsigned short *)(fbp + y * line_length + x * 2);
/* RGB565: 红色 0xF800, 绿色 0x07E0, 蓝色 0x001F */
*pixel = 0xF800;  /* 红色像素 */

4.3 ioctl 控制：查询与配置显示参数

ioctl 是 FrameBuffer 用户态接口中用于控制显示参数的核心系统调用。通过不同的命令码，应用程序可以查询和设置分辨率、颜色深度、刷新率、虚拟屏幕等参数。

4.3.1 核心 ioctl 命令码

4.3.2 关键数据结构详解

struct fb_var_screeninfo 是用户态最常打交道的结构体，定义在 <linux/fb.h> 中：

struct fb_var_screeninfo {
    __u32 xres;           /* 可见分辨率：宽度（像素） */
    __u32 yres;           /* 可见分辨率：高度（像素） */
    __u32 xres_virtual;   /* 虚拟分辨率：宽度（像素） */
    __u32 yres_virtual;   /* 虚拟分辨率：高度（像素） */
    __u32 xoffset;        /* 虚拟到可见的偏移：水平 */
    __u32 yoffset;        /* 虚拟到可见的偏移：垂直 */
    __u32 bits_per_pixel; /* 每像素位数：16/24/32 */
    __u32 grayscale;      /* 灰度标志：0=彩色，非0=灰度 */
    struct fb_bitfield red;    /* 红色通道位域 */
    struct fb_bitfield green;  /* 绿色通道位域 */
    struct fb_bitfield blue;   /* 蓝色通道位域 */
    struct fb_bitfield transp; /* 透明度通道位域 */
    __u32 nonstd;          /* 非标准格式标志 */
    __u32 activate;        /* 激活模式：立即/下次刷新 */
    __u32 height;          /* 屏幕物理高度（mm） */
    __u32 width;           /* 屏幕物理宽度（mm） */
    __u32 accel_flags;     /* 硬件加速标志（已废弃） */
    /* 时序参数 */
    __u32 pixclock;        /* 像素时钟（皮秒） */
    __u32 left_margin;     /* 行同步前沿 */
    __u32 right_margin;    /* 行同步后沿 */
    __u32 upper_margin;    /* 帧同步前沿 */
    __u32 lower_margin;    /* 帧同步后沿 */
    __u32 hsync_len;       /* 行同步脉冲长度 */
    __u32 vsync_len;       /* 帧同步脉冲长度 */
    __u32 sync;            /* 同步极性标志 */
    __u32 vmode;           /* 视频模式：隔行/逐行 */
    __u32 rotate;          /* 旋转角度 */
    __u32 reserved[5];     /* 保留字段 */
};

struct fb_fix_screeninfo 提供显存的固定属性：

struct fb_fix_screeninfo {
    char id[16];           /* 驱动名称字符串 */
    unsigned long smem_start;  /* 显存物理起始地址 */
    __u32 smem_len;        /* 显存总长度（字节） */
    __u32 type;            /* 显示类型：LCDC/PLASMA/VGA 等 */
    __u32 type_aux;        /* 辅助类型 */
    __u32 visual;          /* 颜色模式：真彩色/伪彩色/直接彩色 */
    __u16 xpanstep;        /* 水平 pan 步进 */
    __u16 ypanstep;        /* 垂直 pan 步进 */
    __u16 ywrapstep;       /* 垂直 wrap 步进 */
    __u32 line_length;     /* 一行显存的字节数（关键字段！） */
    unsigned long mmio_start; /* MMIO 区域物理地址 */
    __u32 mmio_len;        /* MMIO 区域长度 */
    __u32 accel;           /* 加速器类型 */
    __u16 capabilities;    /* 能力标志 */
    __u16 reserved[2];     /* 保留 */
};

4.3.3 设置分辨率示例

int set_resolution(int fd, int xres, int yres, int bpp) {
    struct fb_var_screeninfo vinfo;

    /* 先获取当前参数，再修改需要的字段 */
    if (ioctl(fd, FBIOGET_VSCREENINFO, &vinfo)) {
        perror("FBIOGET_VSCREENINFO");
        return -1;
    }

    vinfo.xres = xres;
    vinfo.yres = yres;
    vinfo.bits_per_pixel = bpp;

    /* 设置激活模式：立即生效 */
    vinfo.activate = FB_ACTIVATE_NOW;

    if (ioctl(fd, FBIOPUT_VSCREENINFO, &vinfo)) {
        perror("FBIOPUT_VSCREENINFO");
        return -1;
    }

    printf("分辨率已设置为 %dx%d %dbpp\n", xres, yres, bpp);
    return 0;
}

4.4 fbset 工具使用

fbset 是 Linux 系统中用于查询和配置 FrameBuffer 显示参数的标准命令行工具。它内部封装了 open、ioctl 等系统调用，是调试 FrameBuffer 驱动最常用的用户态工具。

4.4.1 常用命令

4.4.2 典型输出解读

$ fbset

mode "1024x768-60"
    # D: 65.003 MHz, H: 48.365 kHz, V: 60.006 Hz
    geometry 1024 768 1024 768 32
    timings 15384 160 24 29 3 136 6
    accel true
    rgba 8/16,8/8,8/0,8/24
endmode

输出字段解读：

• geometry：可见宽度 可见高度 虚拟宽度 虚拟高度 每像素位数
• timings：像素时钟(ps) 右边界 左边界 上边界 下边界 行同步 帧同步
• rgba：位数/偏移，例如 8/16 表示红色通道占 8 位，偏移 16 位
• accel：是否启用硬件加速

4.4.3 使用 fbset 调试驱动

4.5 用户态接口的局限与迁移动机

尽管 FrameBuffer 用户态接口简单易用，但在现代显示需求下暴露出明显不足：