📚 课程目录第3章开发环境准备

3. 开发环境准备：Linux内核版本要求、内核配置选项与模块编译

在开始使用ConfigFS配置复合USB Gadget设备之前，必须确保开发环境满足内核版本与配置要求。本章将详细说明最低内核版本、关键配置选项的启用方法，以及如何编译和安装内核模块。

3.1 Linux内核版本要求

ConfigFS框架从Linux内核3.11版本开始引入，并在此后的版本中持续完善。不同功能特性对内核版本的最低要求如下：

功能特性	最低内核版本	说明
基础ConfigFS框架	3.11	支持基本的USB Gadget配置
复合设备（多个功能）	3.19	支持同时绑定多个USB功能
UAC2（USB Audio Class 2）	4.4	支持高分辨率音频设备
UVC（USB Video Class）	4.7	支持视频采集设备
RNDIS（远程网络驱动接口规范）	4.14	支持Windows网络共享

推荐版本：建议使用Linux内核5.10 LTS或更高版本，以获得最稳定的ConfigFS支持和最新的功能补丁。

3.2 内核配置选项详解

要启用ConfigFS USB Gadget支持，必须在内核配置中开启以下关键选项。这些选项控制着USB设备控制器驱动、Gadget框架以及ConfigFS文件系统接口。

3.2.1 核心配置选项

配置选项	依赖关系	推荐设置	功能描述
`CONFIG_USB_GADGET`	无	y（编译进内核）	启用USB Gadget核心框架，所有USB设备模式功能的基础
`CONFIG_USB_CONFIGFS`	依赖 `CONFIG_USB_GADGET`	y 或 m	启用ConfigFS文件系统接口，允许通过用户空间配置Gadget
`CONFIG_USB_LIBCOMPOSITE`	依赖 `CONFIG_USB_GADGET`	y	提供复合设备库支持，用于构建多功能的USB设备

3.2.2 功能模块配置选项

根据目标设备类型，还需要启用对应的功能模块：

功能模块	配置选项	典型用途
串口（ACM）	`CONFIG_USB_CONFIGFS_ACM`	虚拟串口通信
大容量存储	`CONFIG_USB_CONFIGFS_MASS_STORAGE`	U盘模拟
以太网（ECM）	`CONFIG_USB_CONFIGFS_ECM`	USB网络共享
以太网（RNDIS）	`CONFIG_USB_CONFIGFS_RNDIS`	Windows网络共享
音频（UAC2）	`CONFIG_USB_CONFIGFS_UAC2`	USB声卡
视频（UVC）	`CONFIG_USB_CONFIGFS_UVC`	USB摄像头
人机交互（HID）	`CONFIG_USB_CONFIGFS_HID`	键盘、鼠标模拟

注意：如果选择编译为模块（m），请确保在系统启动时或使用ConfigFS之前加载对应的内核模块。使用 modprobe 命令手动加载，或将其添加到 /etc/modules 文件中实现自动加载。

3.3 内核配置与编译流程

以下流程图展示了从配置到安装内核模块的完整步骤：

3.4 编译与安装内核模块

以下是在标准Linux发行版上编译和安装内核模块的具体步骤：

3.4.1 配置内核

# 进入内核源码目录
cd /usr/src/linux

# 使用当前系统的配置文件作为基础
cp /boot/config-$(uname -r) .config

# 打开菜单配置界面
make menuconfig

在菜单配置界面中，依次进入以下路径启用选项：

Device Drivers  --->
  [*] USB support  --->
    <*>   USB Gadget Support  --->
      <*>   USB Gadget Functions (including configfs)  --->
        <*>   USB Gadget Functions (including configfs)
        <M>   Serial Gadget (with CDC ACM support)
        <M>   Ethernet Gadget (with CDC ECM support)
        <M>   Mass Storage Gadget
        <M>   Audio Gadget (UAC2)

  配置技巧：将不常用的功能模块编译为模块（M），可以减少内核体积，同时保持灵活性。核心框架（CONFIG_USB_GADGET、CONFIG_USB_CONFIGFS）建议编译进内核（Y），避免启动后手动加载。

3.4.2 编译内核与模块

# 编译内核和模块（使用所有CPU核心加速）
make -j$(nproc)

# 如果只需要编译模块（不重新编译内核）
make modules -j$(nproc)

3.4.3 安装模块

# 安装编译好的模块到系统目录
sudo make modules_install

# 更新模块依赖
sudo depmod -a

3.4.4 验证安装

# 检查USB Gadget相关模块是否可用
modinfo usb_f_acm
modinfo usb_f_ecm
modinfo usb_f_mass_storage

# 加载ConfigFS文件系统（如果编译为模块）
sudo modprobe libcomposite

# 检查ConfigFS是否挂载
mount | grep configfs

3.5 常见问题与排查

问题现象	可能原因	解决方案
`/sys/kernel/config/usb_gadget` 目录不存在	ConfigFS未挂载或内核未启用	执行 `sudo mount -t configfs none /sys/kernel/config`，检查内核配置
模块加载失败：`Unknown symbol`	内核版本与模块版本不匹配	重新编译模块，确保使用当前运行内核的源码
编译错误：`No rule to make target`	内核源码未正确配置	执行 `make olddefconfig` 生成默认配置
USB设备无法被主机识别	USB Gadget驱动未加载或硬件不支持	检查 `dmesg` 输出，确认UDC驱动已加载

快速验证：完成配置和编译后，可以使用以下命令快速验证ConfigFS是否正常工作：
ls /sys/kernel/config/usb_gadget/
如果该目录存在且可访问，说明ConfigFS框架已正确启用。