4. 数据结构兼容性：核心结构体的字段增减与语义变化

在 Linux 内核版本演进过程中，struct file_operations、struct platform_driver 等核心数据结构频繁发生字段增减、参数类型变更或回调语义调整。驱动代码直接引用这些结构体时，若未针对目标内核版本做适配，轻则编译失败，重则运行时产生不可预期的行为。本章系统梳理常见核心结构体的版本差异，并给出系统化的排查与适配方法。

4.1 struct file_operations 的版本变迁

struct file_operations 是字符设备驱动的核心接口表。不同内核版本中，该结构体的字段数量、顺序和回调原型均有变化。以下表格列出主要版本间的关键差异：

以下 SVG 展示了 struct file_operations 在不同内核版本中的字段演化路径：

4.2 struct platform_driver 的兼容性要点

struct platform_driver 是平台设备驱动的标准接口。虽然其核心字段相对稳定，但 driver.pm 操作集、remove 回调的返回值语义、以及 probe 回调的调用时机在不同版本中存在细微差异。

以下 SVG 展示了 struct platform_driver 的结构体布局及版本差异：

4.3 其他核心结构体的版本差异

除了 file_operations 和 platform_driver，以下结构体在版本演进中也经历了重要变化：

4.4 系统化排查方法

针对核心数据结构兼容性，推荐以下排查流程：

1. 获取目标内核头文件：从目标内核源码中提取 include/linux/fs.h、include/linux/platform_device.h 等关键头文件。
2. 对比结构体定义：使用 diff 或 grep 对比当前驱动所依赖的字段在新旧版本中的存在性。
3. 检查回调签名：重点关注 probe、remove、open、ioctl 等回调的参数类型和返回值。
4. 验证语义变化：某些字段虽然名称未变，但语义已调整（如 unlocked_ioctl 在 2.6.36 后成为唯一 ioctl 入口）。
5. 使用版本宏隔离：在驱动代码中使用 #if LINUX_VERSION_CODE >= KERNEL_VERSION(5,19,0) 等宏进行条件编译。
6. 编译测试：在目标内核版本上执行完整编译，检查所有结构体赋值语句是否匹配。

以下 SVG 总结了数据结构兼容性排查的完整流程：

4.5 实战案例：file_operations 从 4.19 移植到 5.10

假设有一个字符设备驱动在 4.19 内核上正常工作，需要移植到 5.10。以下是 file_operations 的适配过程：

// 4.19 版本的原驱动代码
static const struct file_operations my_fops = {
    .owner          = THIS_MODULE,
    .open           = my_open,
    .release        = my_release,
    .read           = my_read,
    .write          = my_write,
    .unlocked_ioctl = my_ioctl,
    .compat_ioctl   = my_compat_ioctl,
};

// 5.10 版本需要检查以下变化：
// 1. read/write 是否被 read_iter/write_iter 替代？—— 否，仍可用
// 2. unlocked_ioctl 是否仍有效？—— 是，4.0+ 已稳定
// 3. compat_ioctl 是否需要？—— 是，64位兼容仍需
// 4. 是否有新增字段需要初始化？—— 建议显式初始化所有字段

// 5.10 适配后的代码（使用指定初始化器避免字段顺序依赖）
static const struct file_operations my_fops = {
    .owner          = THIS_MODULE,
    .open           = my_open,
    .release        = my_release,
    .read           = my_read,
    .write          = my_write,
    .unlocked_ioctl = my_ioctl,
    .compat_ioctl   = my_compat_ioctl,
    // 5.10 新增字段可保持 NULL，内核会使用默认行为
};

4.6 总结与检查清单

在进行数据结构兼容性排查时，请对照以下清单逐项确认：

• ✅ struct file_operations：检查 read_iter/write_iter、unlocked_ioctl、compat_ioctl、uring_cmd 等字段是否存在及签名正确。
• ✅ struct platform_driver：确认 probe 返回值语义、remove 返回值类型（int 或 void）、driver.pm 宏使用方式。
• ✅ struct device：检查 dma_mask、coherent_dma_mask 是否已正确设置。
• ✅ struct net_device_ops：确认 ndo_start_xmit、ndo_set_rx_mode、ndo_bpf 等回调是否存在。
• ✅ struct i2c_driver：确认 probe 或 probe_new 的签名与内核版本匹配。
• ✅ 使用 #if LINUX_VERSION_CODE 宏隔离版本差异，避免直接修改结构体定义。
• ✅ 在目标内核上执行完整编译，并使用 sparse 进行静态分析。