前言

在嵌入式 Linux 开发中，GPIO（通用输入输出口）是最基础也最常用的硬件资源，而 LED 驱动则是入门 GPIO 操作的经典案例。本文将以 “应用层通过 ioctl 接口控制 LED 亮灭” 为核心，由浅入深讲解驱动开发的完整流程 —— 从基础概念拆解到代码逐行解析，再到测试验证，全程通俗易懂，适合嵌入式 Linux 初学者上手实践。

本文配套代码已优化并可直接编译运行，涉及杂项设备注册、GPIO 寄存器操作、ioctl 命令交互等核心知识点，掌握后可快速迁移到其他 GPIO 外设开发中。

一、核心概念铺垫（先搞懂 “为什么这么做”）

在看代码前，先理清 3 个关键概念，避免后续一头雾水：

1.1 什么是 ioctl 接口？

ioctl（Input/Output Control）是 Linux 内核提供的 “设备控制专用接口”，专门用于实现应用层与驱动层的灵活交互。

• 相比 read/write 接口（只能传递数据流），ioctl 支持 “命令 + 数据” 的组合方式，适合控制类场景（如 LED 亮灭、电机启停等）。
• 本文中，应用层通过 ioctl 传递 “开灯 / 关灯命令” 和 “LED 编号”，驱动层解析命令后操作硬件。

1.2 ioctl 命令码的构成（32 位无符号整数）

命令码是应用层与驱动层的 “沟通协议”，必须严格遵循 Linux 内核规范，避免命令冲突。其 32 位结构拆解如下：

位范围	含义	核心宏定义
31~30	数据传输方向（无传输 / 读 / 写 / 读写）	__IOC_NONE/_IOC_READ/_IOC_WRITE/_IOWR
29~16	传递数据的字节数（0 表示无数据）	-
15~8	魔数（唯一 ASCII 字符，标识驱动，避免不同驱动命令冲突）	自定义（如本文的‘L’）
0~7	命令编号（同一驱动内的命令序号，0~255）	自定义（如 0 = 全亮、1 = 全灭）

内核提供的命令码合成宏（直接用，无需手动移位）：

• _IO(type, nr)：无数据传输的命令（如全亮 / 全灭 LED）
• _IOW(type, nr, size)：应用层向驱动层写数据（如指定 LED 编号）
• _IOR(type, nr, size)：应用层从驱动层读数据（如读取 LED 状态）
• _IOWR(type, nr, size)：读写双向传输（本文暂用不到）

1.3 应用层与驱动层的交互流程

（示意图：应用层调用 ioctl → 内核转发命令 → 驱动解析命令 → 操作 GPIO 硬件 → 返回结果）

流程拆解：

1. 应用层：打开 LED 设备文件 → 循环调用 ioctl 发送 “亮 / 灭” 命令 → 关闭设备。
2. 驱动层：注册设备 → 解析 ioctl 命令码（校验魔数、命令编号） → 读取应用层传递的 LED 编号 → 操作 GPIO 寄存器控制 LED → 返回执行结果。

二、开发环境与硬件说明

• 硬件平台：RK3399 开发板（LED_GREEN 接 GPIO0_B5，对应引脚编号 13）
• 内核版本：Linux 4.4+
• 开发工具：交叉编译器（arm-linux-gcc）、Makefile
• 核心硬件映射：
  • GPIO0 基地址：0xFF720000（物理地址）
  • 时钟控制寄存器基地址：0xFF750000（物理地址）
  • LED 引脚：GPIO0_B5（对应数据寄存器第 13 位）

三、分步实现：从命令定义到驱动落地

3.1 第一步：定义 ioctl 命令码（头文件 ioctl_cmd.h）

命令码是 “沟通协议”，需单独定义在头文件中，供应用层和驱动层共用，避免不一致。

c

运行

#ifndef __IOCTL_CMD__
#define __IOCTL_CMD__

#include <linux/ioctl.h>  // 包含内核ioctl宏定义

// 1. 定义魔数（唯一标识LED驱动，ASCII字符'L'）
#define IOC_CMD_LED_MAGIC       'L'

// 2. 定义命令（编号0~3，对应不同操作）
#define IOC_CMD_LED_ON_ALL      _IO(IOC_CMD_LED_MAGIC, 0)  // 所有LED亮（无数据传输）
#define IOC_CMD_LED_OFF_ALL     _IO(IOC_CMD_LED_MAGIC, 1)  // 所有LED灭（无数据传输）
#define IOC_CMD_ON_X            _IOW(IOC_CMD_LED_MAGIC, 2, int)  // 指定LED亮（传int型编号）
#define IOC_CMD_OFF_X           _IOW(IOC_CMD_LED_MAGIC, 3, int)  // 指定LED灭（传int型编号）

// 3. 命令编号范围（用于驱动层校验命令合法性）
#define IOC_CMD_LED_MIN_NR      0
#define IOC_CMD_LED_MAX_NR      3

#endif

关键说明：

• _IO(IOC_CMD_LED_MAGIC, 0)：无数据传输，32 位命令码的 31~30 位为 00。
• _IOW(..., int)：应用层向驱动层写 int 型数据（4 字节），31~30 位为 01，29~16 位为 4。

3.2 第二步：驱动层实现（led_drv.c）

驱动层核心是 “注册设备 + 解析 ioctl 命令 + 操作 GPIO”，采用 Linux 杂项设备（miscdevice）注册（无需手动分配设备号，开发更简单）。

3.2.1 驱动代码完整实现

c

运行

#include <linux/module.h>
#include <linux/init.h>
#include <linux/fs.h>
#include <linux/miscdevice.h>
#include <asm/uaccess.h>
#include <asm/io.h>
#include "ioctl_cmd.h"
#include <linux/device.h>
#include <linux/clk.h>

// 设备与硬件相关定义
#define DEV_NAME              "xyd-leds"        // 设备名（/dev/xyd-leds）
#define LED_NUM               1                 // LED数量（本文1个）
#define PMUCRU_BASE_ADDR      0xFF750000        // 时钟控制寄存器物理基地址
#define PMUCRU_CLKGATE_CON1   (cru_base_addr + 0x0104)  // GPIO0时钟使能寄存器
#define SIZE_64K              65536             // 地址映射大小（64K）
#define GPIO0_BASE_ADDR       0xFF720000        // GPIO0物理基地址
#define GPIO_SWPORTA_DR       (base_addr + 0x00)  // GPIO数据寄存器（控制输出值）
#define GPIO_SWPORTA_DDR      (base_addr + 0x04)  // GPIO方向寄存器（配置输入/输出）

// 虚拟地址指针（物理地址映射后使用）
void __iomem *base_addr     = NULL;  // GPIO0寄存器虚拟地址
void __iomem *cru_base_addr = NULL;  // 时钟寄存器虚拟地址

// 1. 时钟控制函数：开启/关闭GPIO0时钟
static void rk3399_ctrl_clk_en(int en) {
    u32 regv;
    regv = readl(PMUCRU_CLKGATE_CON1);  // 读取时钟寄存器值

    if (en) {  // 开启时钟
        if (regv & (1 << 3)) {          // 检查时钟是否已关闭
            regv |= 1 << (16 + 3);      // 解锁时钟控制位
            regv &= ~(1 << 3);          // 置0：开启GPIO0时钟
            writel(regv, PMUCRU_CLKGATE_CON1);  // 写回寄存器
        }
        return;
    }

    // 关闭时钟
    regv |= 1 << (16 + 3);
    regv |= 1 << 3;
    writel(regv, PMUCRU_CLKGATE_CON1);
}

// 2. LED亮灭控制函数：操作GPIO数据寄存器
static void rk3399_led_on_off(int led_nr, int en) {
    u32 regv;
    // 忽略led_nr（本文仅1个LED），多LED时需根据编号选择引脚
    regv = readl(GPIO_SWPORTA_DR);  // 读取当前GPIO输出值

    if (en) {  // 亮：对应引脚置1（GPIO0_B5 → 第13位）
        regv |= 1 << 13;
    } else {  // 灭：对应引脚置0
        regv &= ~(1 << 13);
    }
    writel(regv, GPIO_SWPORTA_DR);  // 写回数据寄存器
}

// 3. 文件操作接口：open（应用层打开设备时调用）
static int led_open(struct inode *pinode, struct file *pfile) {
    printk("LED device opened: %s\n", __FUNCTION__);
    return 0;
}

// 4. 核心接口：ioctl命令解析（重点！）
static long led_unlocked_ioctl(struct file *pfile, unsigned int cmd, unsigned long arg) {
    int led_nr = 0;
    int ret = 0;

    // 校验1：命令码的魔数是否匹配（防止调用错误驱动）
    if (_IOC_TYPE(cmd) != IOC_CMD_LED_MAGIC) {
        printk("ioctl magic number error!\n");
        return -EINVAL;  // 无效参数
    }

    // 校验2：命令编号是否在合法范围
    if (_IOC_NR(cmd) < IOC_CMD_LED_MIN_NR || _IOC_NR(cmd) > IOC_CMD_LED_MAX_NR) {
        printk("ioctl command number error!\n");
        return -EINVAL;
    }

    // 若命令需要传递数据（_IOW类型），从应用层读取LED编号
    if (_IOC_DIR(cmd) == _IOC_WRITE) {
        ret = copy_from_user(&led_nr, (void *)arg, _IOC_SIZE(cmd));
        if (ret < 0) {  // 数据拷贝失败
            printk("copy_from_user error!\n");
            return -EFAULT;
        }
        if (led_nr >= LED_NUM) {  // 校验LED编号合法性
            printk("LED number invalid!\n");
            return -EINVAL;
        }
    }

    // 解析命令，执行对应操作
    switch (cmd) {
        case IOC_CMD_LED_ON_ALL:
            rk3399_led_on_off(0, 1);  // 所有LED亮（仅1个）
            printk("All LEDs ON\n");
            break;
        case IOC_CMD_LED_OFF_ALL:
            rk3399_led_on_off(0, 0);  // 所有LED灭
            printk("All LEDs OFF\n");
            break;
        case IOC_CMD_ON_X:
            rk3399_led_on_off(led_nr, 1);  // 指定LED亮
            printk("LED %d ON\n", led_nr);
            break;
        case IOC_CMD_OFF_X:
            rk3399_led_on_off(led_nr, 0);  // 指定LED灭
            printk("LED %d OFF\n", led_nr);
            break;
        default:
            return -EINVAL;
    }

    return 0;
}

// 5. 文件操作集合（驱动层对外提供的接口）
static const struct file_operations led_fops = {
    .open           = led_open,
    .unlocked_ioctl = led_unlocked_ioctl,  // ioctl接口（Linux 2.6+推荐）
};

// 6. 杂项设备结构体（简化设备注册）
static struct miscdevice led_misc = {
    .minor = MISC_DYNAMIC_MINOR,  // 动态分配次设备号
    .name  = DEV_NAME,            // 设备名
    .fops  = &led_fops,           // 绑定文件操作集合
};

// 7. 驱动入口函数（模块加载时执行）
static int __init led_drv_init(void) {
    u32 regv;

    // 步骤1：物理地址映射为虚拟地址（内核不能直接操作物理地址）
    base_addr = ioremap(GPIO0_BASE_ADDR, SIZE_64K);
    cru_base_addr = ioremap(PMUCRU_BASE_ADDR, SIZE_64K);
    if (!base_addr || !cru_base_addr) {
        printk("ioremap failed!\n");
        return -ENOMEM;
    }

    // 步骤2：开启GPIO0时钟（硬件要求，否则GPIO不可用）
    rk3399_ctrl_clk_en(1);

    // 步骤3：配置GPIO0_B5为输出模式（方向寄存器对应位置1）
    regv = readl(GPIO_SWPORTA_DDR);
    regv |= 1 << 13;  // GPIO0_B5 → 第13位
    writel(regv, GPIO_SWPORTA_DDR);

    // 步骤4：初始状态：LED灭
    rk3399_led_on_off(0, 0);

    // 步骤5：注册杂项设备（自动创建/dev/xyd-leds）
    if (misc_register(&led_misc) < 0) {
        printk("misc_register failed!\n");
        iounmap(base_addr);  // 注册失败，释放地址映射
        iounmap(cru_base_addr);
        return -EFAULT;
    }

    printk("LED driver init success! /dev/%s created\n", DEV_NAME);
    return 0;
}

// 8. 驱动出口函数（模块卸载时执行）
static void __exit led_drv_exit(void) {
    // 步骤1：LED灭
    rk3399_led_on_off(0, 0);

    // 步骤2：关闭GPIO0时钟
    rk3399_ctrl_clk_en(0);

    // 步骤3：注销杂项设备
    misc_deregister(&led_misc);

    // 步骤4：释放虚拟地址映射
    iounmap(base_addr);
    iounmap(cru_base_addr);

    printk("LED driver exit success!\n");
}

// 模块加载/卸载宏
module_init(led_drv_init);
module_exit(led_drv_exit);

// 许可证声明（GPL协议，必须添加，否则内核报错）
MODULE_LICENSE("GPL");
MODULE_DESCRIPTION("RK3399 GPIO LED Driver (ioctl)");
MODULE_AUTHOR("CSDN");

app.c

运行

#include <stdio.h>
#include <string.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <unistd.h>    //lseek
#include <sys/ioctl.h> //ioctl
#include "ioctl_cmd.h"
#define DEV_NAME "/dev/ioctl-leds"

int main(int argc,char *argv[])
{
  int fd;
  fd =open(DEV_NAME,O_RDWR);
  while(1)
  {
     ioctl(fd,IOC_CMD_ON_X,0);
     sleep(1);
     ioctl(fd,IOC_CMD_OFF_X,0);
     sleep(1);
}
	close(fd);
	return 0;
}

Makefile文件：执行命令make

# Makefile
obj-m += led_drv.o 
# 修正交叉编译工具链名称
CROSS_COMPILE ?= aarch64-linux-gnu-

# 内核源码目录（确保路径正确）
KDIR ?= /home/xyd/work/kernel-rockchip-nanopi4-linux-v4.4.y

# 当前目录
PWD := $(shell pwd)

# 编译规则
modules:
	@make ARCH=arm64 CROSS_COMPILE=$(CROSS_COMPILE) -C $(KDIR) M=$(PWD) modules
	aarch64-linux-gnu-gcc app.c -o app
clean:
	@make ARCH=arm64 CROSS_COMPILE=$(CROSS_COMPILE) -C $(KDIR) M=$(PWD) clean

3.2.2 驱动核心逻辑拆解

1. 地址映射（ioremap）：

   • 内核不能直接操作物理地址（如 0xFF720000），需通过ioremap映射为虚拟地址后使用。
   • 映射大小 64K，覆盖 GPIO0 和时钟控制寄存器的所有地址。

2. 时钟使能：

   • RK3399 芯片的 GPIO 外设默认时钟关闭，需先解锁时钟控制位，再开启时钟，否则 GPIO 操作无效。

3. GPIO 配置：

   • 方向寄存器（DDR）：置 1 表示输出模式，置 0 表示输入模式。
   • 数据寄存器（DR）：置 1 表示引脚输出高电平（LED 亮），置 0 表示低电平（LED 灭）。

4. ioctl 命令解析：

   • 先校验命令码的魔数和编号，避免非法命令。
   • 若命令需要数据（如指定 LED 编号），用copy_from_user从应用层读取数据（内核空间不能直接访问用户空间地址）。
   • 根据命令执行对应的 LED 亮灭操作。

3.3 第三步：应用层实现（led_app.c）

应用层通过ioctl函数向驱动发送命令，控制 LED 循环亮灭。

c

运行

#include <stdio.h>
#include <string.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <unistd.h>
#include <sys/ioctl.h>
#include "ioctl_cmd.h"

#define DEV_NAME "/dev/xyd-leds"  // 设备文件路径（与驱动定义一致）

int main(int argc, char *argv[]) {
    int fd;
    int led_nr = 0;  // LED编号（本文仅1个，为0）

    // 步骤1：打开设备文件（O_RDWR：读写模式）
    fd = open(DEV_NAME, O_RDWR);
    if (fd < 0) {
        perror("open device failed");
        return -1;
    }
    printf("Open /dev/xyd-leds success! fd = %d\n", fd);

    // 步骤2：循环控制LED亮灭（1秒切换一次）
    while (1) {
        // 发送“指定LED亮”命令（传递LED编号0）
        ioctl(fd, IOC_CMD_ON_X, &led_nr);
        printf("LED %d ON\n", led_nr);
        sleep(1);

        // 发送“指定LED灭”命令（传递LED编号0）
        ioctl(fd, IOC_CMD_OFF_X, &led_nr);
        printf("LED %d OFF\n", led_nr);
        sleep(1);
    }

    // 步骤3：关闭设备（循环中不会执行，需手动Ctrl+C终止）
    close(fd);
    return 0;
}

关键说明：

• open(DEV_NAME, O_RDWR)：打开 /dev/xyd-leds 设备文件，返回文件描述符 fd（后续操作通过 fd 标识设备）。
• ioctl(fd, IOC_CMD_ON_X, &led_nr)：第三个参数是用户空间地址，传递 LED 编号（驱动层用copy_from_user读取）。
• 若要控制所有 LED，可替换为ioctl(fd, IOC_CMD_LED_ON_ALL, NULL)（无数据传递，第三个参数为 NULL）。

3.4 第四步：编写 Makefile（编译驱动模块）

驱动是内核模块，需用内核源码编译，Makefile 如下：

makefile

# 内核源码路径（需替换为你的RK3399内核源码路径）
KERNELDIR ?= /home/user/rk3399-linux-4.4.y
# 当前目录（驱动代码所在目录）
PWD := $(shell pwd)

# 编译目标：驱动模块led_drv.ko
obj-m += led_drv.o

# 编译规则
all:
    $(MAKE) -C $(KERNELDIR) M=$(PWD) modules

# 清理编译产物
clean:
    $(MAKE) -C $(KERNELDIR) M=$(PWD) clean

注意：

• KERNELDIR必须替换为你的开发板对应的内核源码路径（需提前编译过内核）。
• 编译命令：make（生成 led_drv.ko 驱动模块）。

四、测试验证步骤

4.1 编译与部署

1. 编译驱动：在驱动目录执行make，生成led_drv.ko。
2. 编译应用程序：用交叉编译器编译led_app.c：

   bash

   arm-linux-gcc led_app.c -o led_app
   

3. 部署文件：将led_drv.ko和led_app拷贝到开发板（如通过 TF 卡、SSH）。

4.2 运行测试

1. 加载驱动模块：

   bash

   insmod led_drv.ko
   

   • 查看驱动是否加载成功：lsmod | grep led_drv
   • 查看设备文件是否创建：ls /dev/xyd-leds（存在则说明注册成功）

2. 运行应用程序：

   bash

   ./led_app
   

3. 预期结果：

   • 应用程序输出 “LED 0 ON”“LED 0 OFF”，每秒切换一次。
   • 开发板上的 LED_GREEN 循环亮灭。
   • 查看内核打印信息：dmesg | grep LED（可看到驱动层的打印日志）。

4. 卸载驱动模块：

   bash

   rmmod led_drv

五、常见问题与优化建议

5.1 常见问题排查

1. 驱动加载失败（insmod 报错）：

   • 内核源码路径错误：检查 Makefile 中的KERNELDIR。
   • 内核版本不匹配：驱动需与开发板内核版本一致。
   • 缺少 GPL 声明：驱动代码必须添加MODULE_LICENSE("GPL")。

2. 应用层 open 设备失败（No such file or directory）：

   • 驱动未加载：重新执行insmod led_drv.ko。
   • 设备名不一致：检查应用层DEV_NAME与驱动DEV_NAME是否相同。

3. LED 不亮：

   • GPIO 引脚定义错误：核对开发板 LED 对应的 GPIO 引脚和寄存器地址。
   • 时钟未开启：检查rk3399_ctrl_clk_en函数的寄存器位是否正确。
   • 数据寄存器操作错误：确认引脚对应的寄存器位（本文是第 13 位）。

5.2 代码优化建议

1. 支持多个 LED：修改LED_NUM为实际数量，在rk3399_led_on_off中根据led_nr选择不同引脚。
2. 添加 LED 状态读取：实现_IOR类型命令，应用层可读取 LED 当前状态。
3. 错误处理增强：在驱动中增加更多异常判断（如地址映射失败、寄存器读写失败）。
4. 动态申请 GPIO：使用内核 GPIO 子系统（gpio_request、gpio_direction_output）替代直接操作寄存器，兼容性更好。

六、总结与扩展

本文通过 “命令码定义→驱动实现→应用开发→测试验证” 的完整流程，讲解了 Linux 下基于 ioctl 接口的 GPIO_LED 驱动开发。核心要点是：

• ioctl 命令码的规范定义（魔数、编号、数据方向）。
• 驱动层的核心流程：地址映射→时钟使能→GPIO 配置→命令解析。
• 应用层与驱动层的数据交互（copy_from_user）。

        这就是本文的全部内容，也感谢耐心看到这里的读者，我会持续更新，希望你能够多多关注，如果本文有帮组到你的话，还请三连加关注，你的支持就是我创作的最大动力！希望这份手册能帮你少走弯路，欢迎在评论区补充你的调试经验！