4. 开发环境搭建

嵌入式Linux USB Gadget驱动的开发与普通桌面环境有本质区别：目标硬件（ARM、RISC-V、MIPS等）资源有限，无法直接运行编译工具链和大型内核构建系统。因此，交叉编译是开发流程的基石。本章将系统讲解如何搭建一套完整的USB Gadget开发环境，涵盖工具链安装、内核源码管理、配置裁剪以及Gadget相关选项的启用。

4.1 交叉编译工具链的安装与验证

交叉编译工具链是一组运行在宿主机上、但生成目标平台机器码的编译器、链接器和库。选择工具链时需关注：目标架构、浮点ABI（soft/hard）、C库（glibc/uclibc/musl）以及内核头文件版本。

4.1.1 工具链获取方式对比

4.1.2 安装Linaro ARM工具链

# 下载Linaro 7.5.0 ARM硬浮点工具链（约200MB）
wget https://releases.linaro.org/components/toolchain/binaries/7.5-2019.12/arm-linux-gnueabihf/gcc-linaro-7.5.0-2019.12-x86_64_arm-linux-gnueabihf.tar.xz

# 解压到 /opt 目录
sudo tar -xvf gcc-linaro-7.5.0-2019.12-x86_64_arm-linux-gnueabihf.tar.xz -C /opt/

# 添加至系统PATH（建议写入 ~/.bashrc 永久生效）
export PATH=/opt/gcc-linaro-7.5.0-2019.12-x86_64_arm-linux-gnueabihf/bin:$PATH

# 验证安装
arm-linux-gnueabihf-gcc --version
# 输出示例：arm-linux-gnueabihf-gcc (Linaro GCC 7.5-2019.12) 7.5.0

4.1.3 工具链与内核编译的关系

内核编译需要工具链提供：汇编器（as）、编译器（gcc）、链接器（ld）以及模块工具（modpost）。USB Gadget驱动作为内核的一部分，其编译完全依赖内核构建系统，工具链仅提供底层二进制能力。

# 设置内核编译使用的交叉编译变量
export ARCH=arm
export CROSS_COMPILE=arm-linux-gnueabihf-
# 注意：CROSS_COMPILE 必须以连字符结尾

4.2 Linux内核源码获取与版本选择

USB Gadget子系统在Linux 4.x到6.x之间经历了多次重构：ConfigFS 成为主流、FunctionFS 接口稳定、UVC/UAC 功能增强。本课程选择 Linux 5.10 LTS 作为基线，兼顾稳定性和新特性。

4.2.1 获取内核源码

# 方式一：从kernel.org下载稳定版（推荐）
wget https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.10.209.tar.xz
tar -xvf linux-5.10.209.tar.xz
cd linux-5.10.209

# 方式二：使用git克隆（适合需要打补丁的场景）
git clone --depth 1 --branch v5.10 git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
cd linux

4.2.2 内核源码目录结构（Gadget相关）

理解源码布局有助于快速定位驱动文件和配置项：

4.3 内核配置：启用USB Gadget子系统

内核配置是搭建环境的核心环节。错误的配置会导致Gadget驱动无法编译、模块加载失败或功能不可用。以下配置基于 make menuconfig 图形界面，所有选项均可通过 .config 文件直接编辑。

4.3.1 USB Gadget核心配置

# 进入内核源码目录，加载默认配置（以ARM versatile为例）
make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- versatile_defconfig

# 启动图形配置界面
make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- menuconfig

在menuconfig中依次进入以下路径，启用关键选项：

4.3.2 UDC（USB Device Controller）驱动配置

UDC驱动是Gadget子系统的底层硬件抽象层。不同SoC集成不同的UDC IP核：

# 以DWC2为例，在menuconfig中配置：
# Device Drivers → USB support → DesignWare USB2 DRD Core Support
# 选择 [M] 或 [*]
# 并确保以下子选项开启：
#   - CONFIG_USB_DWC2_PERIPHERAL=y   (仅设备模式)
#   - CONFIG_USB_DWC2_HOST=n         (关闭主机模式，减少内存占用)

4.3.3 其他辅助配置

# 文件系统支持（ConfigFS需要）
CONFIG_CONFIGFS_FS=y

# 内核模块支持（若Gadget驱动编译为模块）
CONFIG_MODULES=y
CONFIG_MODULE_UNLOAD=y

# 调试文件系统（用于Gadget调试）
CONFIG_DEBUG_FS=y

# USB PHY支持（部分SoC需要）
CONFIG_USB_PHY=y
CONFIG_NOP_USB_XCEIV=y

4.4 内核编译与模块部署

配置完成后，执行编译并部署到目标板：

# 编译内核镜像和模块
make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- -j$(nproc) zImage
make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- -j$(nproc) modules

# 安装模块到临时目录（假设目标板rootfs挂载在 /mnt/rootfs）
make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- \
     INSTALL_MOD_PATH=/mnt/rootfs modules_install

# 确认Gadget模块已生成
find /mnt/rootfs/lib/modules/5.10.209/ -name "*gadget*"
# 预期输出包含：usb_f_mass_storage.ko, usb_f_acm.ko, usb_f_hid.ko, libcomposite.ko 等

4.5 开发环境架构总览

下图展示了宿主机与目标板之间的开发环境关系，以及内核源码、工具链、配置系统之间的数据流：

4.6 常见问题与避坑指南

• 工具链版本不匹配：使用 arm-linux-gnueabihf-gcc --version 确认版本。GCC 8.x 以上编译内核时需添加 CONFIG_CC_OPTIMIZE_FOR_SIZE=y 避免链接错误。
• CONFIG_USB_GADGET 未生效：检查 .config 中是否有 CONFIG_USB_SUPPORT=y 前置依赖。USB Gadget 依赖于 USB 子系统总开关。
• 模块加载失败：Unknown symbol：确保 libcomposite.ko 先于功能模块加载。使用 modprobe libcomposite 自动处理依赖。
• ConfigFS 目录为空：确认内核编译时 CONFIG_CONFIGFS_FS=y 且已挂载：mount -t configfs none /sys/kernel/config。
• UDC 未注册：检查设备树中 USB 控制器状态是否为 okay，且 PHY 时钟已使能。执行 cat /sys/kernel/debug/usb/udc 查看注册情况。

4.7 环境验证清单

完成上述步骤后，使用以下清单逐项确认环境就绪：