全志D1实战：在RISC-V开发板实现无依赖屏幕截图并存储到TF卡

你有没有遇到过这样的场景？
现场设备运行异常，用户报告“界面显示错乱”，但当你远程登录时一切已恢复正常。问题无法复现，日志中也找不到蛛丝马迹。此时，若能在问题发生的瞬间抓取一张屏幕截图，将对问题定位有极大的帮助。
在工业HMI（人机界面）产品的开发中，客户也常提出类似“行车记录仪”的需求——自动记录关键操作步骤的画面。
本文将解决一个在资源受限的嵌入式Linux系统中的实际问题：如何以最轻量的方式，实现“触发抓取 → 读取当前画面 → 编码成图片 → 存入存储介质”的完整流程。目标平台是基于全志D1芯片的实战派S3开发板，它搭载RISC-V架构处理器，运行嵌入式Linux并支持LVGL图形库。
整个方案不依赖X11、Wayland等高级图形服务器，直接面向最底层的帧缓冲（Framebuffer）操作，具有代码可移植性强、内存占用极低的优点。更重要的是，这是一个纯本地闭环处理的解决方案，无需网络参与。

从 /dev/fb0 开始：深入理解帧缓冲

很多开发者知道 /dev/fb0 是屏幕数据的来源，但对其工作机制、可访问时机及数据格式的细节却不甚了解。

Framebuffer 工作原理

你可以将Framebuffer理解为一个“共享显存”区域。GPU或显示控制器将最终渲染好的像素数据写入其中，而LCD驱动则按固定刷新率从中读取数据并送往显示屏。Linux内核通过 drivers/video/fbdev/core/fbmem.c 提供了一个统一的设备接口 /dev/fbX，使得用户空间的应用程序也能访问这块内存。

提示：/dev/fb0 并不总是主显示设备。在多显示器系统中可能存在fb1、fb2；此外，一些使用现代DRM/KMS图形框架的系统可能不再暴露传统的fb设备。因此，在开发前需要确认目标环境是否支持。

在实战派S3开发板上，默认的GUI输出直接通向了 fb0，这意味着我们可以通过 mmap() 系统调用映射这块内存，实现零拷贝的屏幕数据读取。

安全地获取屏幕原始数据

关键在于两个ioctl调用：

• FBIOGET_VSCREENINFO：获取可视区域信息（如分辨率、色深）。
• FBIOGET_FSCREENINFO：获取物理帧缓冲信息（如内存偏移量、长度）。

其中，struct fb_var_screeninfo 结构体中的字段尤为重要：

struct fb_var_screeninfo {
    __u32 xres;             // 可视区域宽度
    __u32 yres;             // 可视区域高度
    __u32 bits_per_pixel;   // 每像素位数（常见为16或32）
    ...
};

结合 mmap()，我们就能获得一个指向显存起始地址的指针。

但这里有一个关键陷阱：切勿轻易使用 O_RDWR 模式打开fb设备进行读写！
许多教程采用此方法，但在实际项目中，如果GUI线程正在向framebuffer写入数据，而你的截图线程也在同时进行读取或写入，极易引发竞争条件，导致画面撕裂甚至系统卡顿。
正确做法是：以只读模式打开，并使用 MAP_SHARED 标志进行映射。

fbfd = open("/dev/fb0", O_RDONLY);  // 关键！使用只读模式
// ... 获取屏幕信息
fbp = mmap(0, screensize, PROT_READ, MAP_SHARED, fbfd, 0);

这种方式既能确保捕获到最新的显示内容，又能避免干扰图形系统的正常绘制流程。

实战中的注意事项

1. 权限问题
   默认情况下，非root用户无法读取 /dev/fb0。解决方法包括：

   • 使用 sudo 运行程序。
   • 修改udev规则，将fb设备权限赋予特定用户组。
   • 使用 setcap cap_sys_admin+ep ./screenshot_app 为程序赋予相应能力。

2. 色彩格式识别
   实战派S3默认可能使用RGB565格式（每像素2字节），颜色排列为R5-G6-B5。这种格式节省空间，但需要转换才能生成标准图像。如果在LVGL配置中启用了 LV_COLOR_DEPTH=32，则会使用ARGB8888格式（每像素4字节），通常Alpha通道无效，提取时只需关注B、G、R三个分量。

3. 性能影响评估
   直接读取数MB的显存会短暂占用内存总线带宽。实测在全志D1上抓取一张800×480的图片，耗时约15~30ms（取决于内存频率）。若需高频截图（如每秒一次），建议将截图任务放在低优先级线程或空闲任务中执行。

4. 合成器干扰
   如果系统使用了Weston、KMS/DRM等现代图形栈，/dev/fb0 中可能只是空白或固定背景。此时需要关闭合成器或启用“legacy fbdev”兼容模式才能正常捕获画面。

BMP编码：为何选择“古老”的格式？

你可能会问，为什么不直接保存原始数据，或者压缩成更节省空间的PNG/JPEG格式？
答案在于嵌入式开发的现实考量：简单即是正义。

我们来做一个简单的对比分析：

格式	是否需要第三方库	编码复杂度	解码便利性	典型体积（800×480）
RAW	否	极低	❌ 几乎无法直接查看	~737KB (RGB888)
BMP	否	低	✅ 系统原生支持	~921KB
PNG	是 (zlib/lodepng)	高	✅	~200~400KB
JPEG	是 (libjpeg)	很高	✅	~50~150KB

PNG和JPEG虽然体积小巧，但引入外部依赖意味着：

• 增加编译配置的复杂性。
• 占用更多的Flash和RAM空间。
• 出错概率上升（如压缩失败、内存溢出）。

而BMP格式的优势非常突出：

• 可完全手动构造文件头和像素数据流，无需外部库。
• 跨平台兼容性极佳，Windows/Linux/macOS均可直接预览。
• 内存占用可控，通常可以在栈上完成所有操作，无需动态分配。

对于调试工具和日志记录这类功能，BMP实现了真正的“开箱即用”。

BMP文件结构详解

一个标准的BMP文件主要由三部分组成：

1. 文件头（14字节）：包含魔数"BM"、文件总大小、像素数据偏移量等信息。
2. 信息头（BITMAPINFOHEADER，40字节）：描述图像的宽度、高度、位深、压缩方式等元信息。
3. 像素阵列：存储实际的图像数据，需要注意：
   • 像素颜色顺序为 BGR，而非RGB。
   • 每行数据的字节数必须4字节对齐，不足部分用零填充。
   • 行存储顺序是自底向上的，即图像文件中的第0行对应的是屏幕上最下面的一行。

最后一点尤其容易被忽略。Framebuffer中的数据通常是从上到下存储的，而BMP要求从下到上，因此编码时必须逆序扫描行。

自研BMP编码函数的设计思路

我们的目标是实现一个通用的编码函数：

int save_rgb_to_bmp(const char *filename,
                    const void *rgb_data,
                    int width, int height,
                    int input_bpp);

参数说明：

• filename: 输出文件的路径。
• rgb_data: 来自framebuffer的原始像素数据指针。
• width, height: 图像分辨率。
• input_bpp: 输入数据的位深度（16或32）。

函数将输出统一的 24位BGR格式的BMP文件，以确保最大的兼容性。

关键处理逻辑如下：

1. 计算输出文件每行的字节数和对齐后的字节数：

   int row_bytes = width * 3; // 每像素3字节（B, G, R）
   int row_padded = (row_bytes + 3) & (~3); // 对齐到4字节边界

2. 使用 #pragma pack(1) 防止结构体填充，并依次写入文件头和DIB信息头。
3. 逆序逐行写入像素数据并进行格式转换：

   for (int y = height - 1; y >= 0; y--) {
       const uint8_t *src = rgb_data + y * src_stride; // src_stride为输入数据每行字节数
       for (int x = 0; x < width; x++) {
           uint8_t r, g, b;
           if (input_bpp == 16) {
               // 解析RGB565格式
               uint16_t v = ((uint16_t*)src)[x];
               b = ((v << 3) & 0xf8) | ((v >> 2) & 0x7);
               g = ((v >> 3) & 0xfc) | ((v >> 8) & 0x3);
               r = ((v >> 8) & 0xf8) | ((v >> 13) & 0x7);
           } else { // 32-bit
               // 通常为ARGB8888或BGRA8888，假设为BGRA
               b = src[x*4 + 0];
               g = src[x*4 + 1];
               r = src[x*4 + 2];
               // 忽略Alpha通道 src[x*4 + 3]
           }
           fputc(b, fp);
           fputc(g, fp);
           fputc(r, fp);
       }
       // 写入行对齐的填充字节
       fwrite(padding, 1, row_padded - row_bytes, fp);
   }

4. 关闭文件并检查错误。

特别提醒：切勿假设输入数据的格式！
在开发中曾遇到一种情况：设备明明配置为RGB565，截图却出现颜色偏差。排查后发现是因为代码中硬编码按每像素3字节（RGB888）的方式解析。因此，健壮的做法是：根据从framebuffer查询到的 bits_per_pixel 信息，动态适配输入数据的解析方式。

TF卡存储：不仅仅是挂载

认为简单地执行 mount /dev/mmcblk0p1 /mnt/tf 就能写入？实际情况要复杂得多。
TF卡作为一种可移动存储介质，存在诸多不确定性：

• 卡是否已插入？
• 卡是否处于只读状态？
• 文件系统是否已损坏？
• 写入过程中用户拔出卡怎么办？
  这些都是嵌入式产品在真实使用环境中会遇到的挑战，而非理论问题。

如何检测TF卡是否就绪？

最直接的方法是轮询设备节点是否存在：

int is_tf_card_present() {
    return access("/dev/mmcblk0p1", F_OK) == 0;
}

但这种方式效率不高。更高效的方式是监听内核uevent事件：

# 查看输入设备事件（部分系统）
cat /proc/bus/input/devices | grep -i sd
# 或直接监听udev的mmc子系统事件
udevadm monitor --subsystem-match=mmc

不过，对于大多数应用场景，采用定时检测的策略（例如每5秒检查一次）已经足够。

安全挂载策略

直接调用 system("mount ...") 虽然快捷，但存在一些隐患：

• Shell注入风险（如果路径或参数包含特殊字符）。
• 无法精确获取和解析错误码。
• 依赖Busybox或util-linux中的mount命令是否存在。
  在生产环境中，推荐使用 mount() 系统调用：

  
  #include <sys/mount.h>

int safe_mount_tf() {
struct stat st;
if (stat("/mnt/tf", &st) != 0) {
mkdir("/mnt/tf", 0755);
}
// 使用 mount 系统调用
if (mount("/dev/mmcblk0p1", "/mnt/tf", "vfat", MS_NOATIME, NULL) < 0) {
perror("Mount failed");
return -1;
}
return 0;
}

参数说明：
*   `"vfat"`：文件系统类型（对应FAT32）。
*   `MS_NOATIME`：禁止更新文件的访问时间，可以减少不必要的写入操作，延长TF卡寿命。
*   `NULL`：额外的挂载选项字符串，例如可传入 `"iocharset=utf8"` 以支持中文文件名。

> **为何选择FAT32而非ext4？**
> 尽管ext4在稳定性、大文件支持和权限管理方面更胜一筹，但FAT32的跨平台兼容性是无与伦比的：
> *   Windows可即插即用。
> *   Linux和macOS原生支持。
> *   许多工控上位机软件仅识别FAT分区。
> 鉴于我们的需求只是存储尺寸有限的截图文件，FAT32是完全满足要求的。

### 文件命名的技巧：兼顾唯一性与可读性
避免使用 `screenshot1.bmp`、`screenshot2.bmp` 这种简单的序列命名。
更好的做法是嵌入时间戳：
```c
char filename[256];
time_t t = time(NULL);
struct tm *tm = localtime(&t);
strftime(filename, sizeof(filename), "/mnt/tf/screenshot_%Y%m%d_%H%M%S.bmp", tm);

生成的文件名示例：/mnt/tf/screenshot_20250405_143022.bmp
这种命名的优点：

• 按文件名排序即按时间排序。
• 几乎不会重名（除非在同一秒内触发多次截图）。
• 人类可读，一眼就能知道截图的大致时间。
  进阶技巧：可以使用 mkstemp() 函数生成一个唯一的临时文件，完成写入后再通过 rename() 原子性地更改为最终文件名，这可以防止多进程/多线程环境下的写入冲突。

数据安全的最后防线：sync

这是最容易忽视但至关重要的一步！
Linux的I/O操作普遍采用了页缓存（Page Cache）机制，fwrite() 调用成功仅仅表示数据被写入了内核缓冲区，并不代表已经物理写入TF卡。如果此时发生断电，缓存中的数据就会丢失。
因此，每次成功保存文件后，务必执行同步操作：

sync(); // 强制将所有脏页写回所有挂载的文件系统
// 或者更精确地，仅同步刚写入的文件：
fsync(fileno(fp)); // 仅同步指定文件描述符对应的文件

你还可以通过检查 /proc/mounts 确认挂载选项是否包含 sync，或者在挂载时直接加上 sync 参数来强制所有写入均为同步操作（但会降低写入性能）。

整体工作流程与工程实践

现在，我们将所有模块串联起来，构建完整的截图流水线。

完整调用流程示例

void take_screenshot() {
    framebuffer_info_t fb;
    char filename[256];

    // 1. 初始化并映射framebuffer
    if (init_framebuffer(&fb) < 0) {
        printf("Failed to access framebuffer\n");
        return;
    }

    // 2. 生成带时间戳的文件名
    time_t t = time(NULL);
    struct tm *tm = localtime(&t);
    strftime(filename, sizeof(filename), "/mnt/tf/screenshot_%Y%m%d_%H%M%S.bmp", tm);

    // 3. 确保TF卡已挂载并可写
    if (access("/mnt/tf", W_OK) < 0) {
        if (mount_tf_card() < 0) {
            printf("TF card not available\n");
            uninit_framebuffer(&fb);
            return;
        }
    }

    // 4. 执行RGB数据到BMP文件的编码与保存
    if (save_rgb_to_bmp(filename, fb.fbp, fb.width, fb.height, fb.bpp) == 0) {
        printf("Screenshot saved: %s\n", filename);
    } else {
        printf("Save failed\n");
    }

    // 5. 强制刷新缓存，确保数据落盘
    sync();

    // 6. 释放资源（解除内存映射，关闭文件描述符）
    uninit_framebuffer(&fb);
}

这个流程简洁、清晰，并包含了必要的错误处理。

性能与资源优化建议

1. ROI（感兴趣区域）截图
   如果只关心屏幕的特定区域（如某个报警对话框），可以在编码阶段只处理该矩形范围内的像素，这能显著降低CPU处理开销和I/O负担。
2. 异步执行防止界面卡顿
   截图、编码、写卡这一系列操作可能需要数十毫秒，在实时性要求高的系统中可能影响UI响应。建议将整个流程封装在独立的线程中，或使用 fork() 创建子进程来处理。

   pid_t pid = fork();
   if (pid == 0) {
       // 子进程中执行截图任务
       take_screenshot();
       exit(0);
   }
   // 父进程立即返回，不阻塞主线程

3. 频率限制与去抖
   添加简单的防误触和限频逻辑，避免因连续触发而写爆存储卡。

   static time_t last_shot = 0;
   if (time(NULL) - last_shot < 2) return; // 至少间隔2秒
   last_shot = time(NULL);
   // 执行截图...

4. 日志文件管理
   当截图文件积累过多时，可以使用 tar 和 gzip 定期打包旧文件以节省空间。甚至可以设计“循环存储”机制，只保留最近N张图片。

实际应用场景与扩展思路

这套轻量级截图方案已在多个实际项目中成功应用。

应用场景示例

• 工业HMI操作审计：将截图功能绑定到关键按钮（如“参数设置确认”）的回调函数中。每次操作都自动保存当前界面，形成带时间戳的可视化操作日志，方便事后追溯与分析。
• 教学实验平台作业提交：为开发板增加一个“截图”物理按键。学生完成实验后按下按键，即可将运行结果界面直接保存到TF卡，替代了用手机拍照的不便，使作业提交格式统一规范。
• 远程技术支持与诊断：现场设备出现显示问题时，技术支持人员可指导用户通过特定操作触发截图并取出TF卡。一张实时的屏幕截图比用户的文字描述（如“那个红色按钮不见了”）要直观、准确得多。

未来可能的扩展方向

拥有了基础的图像采集与存储能力后，还可以进一步扩展功能：

• 添加PNG压缩支持：集成 lodepng 这类单文件、无依赖的PNG编解码库，可将图片体积减小60%以上，更适合需要长期记录日志的系统。这涉及到对图片处理库的集成与优化。
• 实现自动上传：在网络可用时，自动将新生成的截图通过FTP或HTTP POST方式上传到远程服务器，结合简单的Web服务，构建一个云端设备监控面板。
• 尝试生成简易视频：以固定时间间隔连续截图，并将一系列BMP文件打包成简单的AVI格式视频，实现低帧率的“录屏”功能，适用于记录缓慢变化的参数曲线或流程。
• 集成轻量级OCR：如果界面上有需要记录的数字或状态文本，可以集成轻量化的Tesseract引擎，从截图中提取文字信息，转换为结构化的文本日志，便于搜索和统计。

总结：嵌入式开发的务实哲学

回顾整个实现过程，我们没有追求复杂炫目的架构，也没有引入任何重量级的框架，而是紧紧围绕问题本质，选择了最直接、最可靠的路径：

用最简单的方法，解决最实际的问题。

• 没有使用OpenGL截图接口。
• 没有运行Wayland/Weston等合成器。
• 没有接入GStreamer等多媒体框架。

仅仅依靠对底层 /dev/fb0 的读取、手写的BMP编码器以及对TF卡的标准挂载操作，就构建出了一套稳定可靠的“设备视觉日志系统”。
这正是嵌入式开发的独特魅力所在：资源限制迫使你深入思考问题的本质，从而往往能催生出最简洁、最优雅的解决方案。
当下次面临类似的需求时，不妨先问自己一句：

“这个功能，能否在不引入新库、不增加新依赖、不改变现有系统架构的前提下实现？”
或许，答案就隐藏在那个简单的 /dev/fb0 设备文件中。