嵌入式 Linux 与 RTOS / 系统课时

用 ioctl 设计控制接口

用 ioctl 设计控制接口

当设备操作不是字节流,例如切换工作模式、读取状态或提交一组控制参数时,ioctl 比把控制字符串塞进 write 更合适。本节定义一组稳定的 UAPI 命令,完成用户态与内核态参数拷贝、错误返回和 32/64 位兼容处理,并用测试程序验证接口。

学习目标

  • 用 _IO、_IOR、_IOW、_IOWR 正确编码 ioctl 命令方向和参数大小。
  • 用固定宽度、无指针的数据结构设计可维护的用户态 ABI。
  • 在驱动中校验命令、拷贝参数并返回 -ENOTTY、-EFAULT 等明确错误码。

先把 ioctl 当成稳定 ABI

ioctl(fd, cmd, arg) 的关键不是“能传任意东西”,而是 cmd 和 arg 一旦被用户程序依赖,就形成用户态 ABI。命令号要有唯一 magic,参数结构要避免 long、裸指针和随编译器变化的布局;新增字段时还要考虑旧程序是否仍能工作。

ioctl 命令从用户态到驱动的控制路径

_IO 表示无数据参数,_IOR 表示驱动向用户返回数据,_IOW 表示用户向驱动提交数据,_IOWR 表示双向。方向宏不仅提高可读性,还会把参数大小编码进命令号,便于内核和调试工具判断 ABI。

定义共享的 UAPI 头文件

下面头文件同时给内核模块和用户程序包含。结构体只使用 __u32,因此在常见 32 位和 64 位 ABI 上布局一致;没有嵌入用户指针,也就不需要为指针宽度单独定义另一套结构。

c
#ifndef ANYSTACK_CTL_UAPI_H
#define ANYSTACK_CTL_UAPI_H

#include <linux/ioctl.h>
#include <linux/types.h>

#define ANYSTACK_IOC_MAGIC 'A'

/* UAPI 结构只放固定宽度值,避免跨 ABI 的 long/指针差异。 */
struct anystack_config {
    __u32 enabled;
    __u32 threshold;
};

struct anystack_status {
    __u32 enabled;
    __u32 threshold;
};

/* 每个命令号唯一,方向宏同时编码参数大小。 */
#define ANYSTACK_IOC_SET_CONFIG \
    _IOW(ANYSTACK_IOC_MAGIC, 0x01, struct anystack_config)
#define ANYSTACK_IOC_GET_STATUS \
    _IOR(ANYSTACK_IOC_MAGIC, 0x02, struct anystack_status)
#define ANYSTACK_IOC_RESET \
    _IO(ANYSTACK_IOC_MAGIC, 0x03)

#endif

预期结果

text
该头文件不产生运行时输出;内核模块与用户程序使用同一份命令号和结构体定义。

命令编号不要重复,也不要把 sizeof(arg) 传给 _IOW 等宏;第三个参数必须是数据类型本身。若未来扩展结构,优先保留已有字段含义并新增新命令或显式版本字段,而不是悄悄改变旧命令的结构大小。

在驱动中实现命令分派

为把重点放在控制接口上,下面使用 miscdevice 注册字符设备,它会自动分配次设备号并创建 /dev/anystack_ctl。驱动保存两个状态字段,并对用户输入做范围检查。

c
#include <linux/compat.h>
#include <linux/fs.h>
#include <linux/init.h>
#include <linux/miscdevice.h>
#include <linux/module.h>
#include <linux/mutex.h>
#include <linux/uaccess.h>

#include "anystack_ctl_uapi.h"

/* 示例状态代表真实驱动里的寄存器影子或控制缓存。 */
static DEFINE_MUTEX(state_lock);
static struct anystack_status state = {
    .enabled = 0,
    .threshold = 0,
};

static long anystack_ioctl(struct file *file,
                           unsigned int cmd,
                           unsigned long arg)
{
    struct anystack_config cfg;
    struct anystack_status snapshot;

    if (_IOC_TYPE(cmd) != ANYSTACK_IOC_MAGIC)
        return -ENOTTY;

    /* switch 对完整 cmd 匹配,也同时约束 number/direction/size。 */
    switch (cmd) {
    case ANYSTACK_IOC_SET_CONFIG:
        if (copy_from_user(&cfg, (void __user *)arg, sizeof(cfg)))
            return -EFAULT;
        if (cfg.enabled > 1 || cfg.threshold > 1000)
            return -ERANGE;

        mutex_lock(&state_lock);
        state.enabled = cfg.enabled;
        state.threshold = cfg.threshold;
        mutex_unlock(&state_lock);
        return 0;

    case ANYSTACK_IOC_GET_STATUS:
        mutex_lock(&state_lock);
        snapshot = state;
        mutex_unlock(&state_lock);

        /* 先在锁内取快照,再向用户空间拷贝,避免长时间持锁。 */

        if (copy_to_user((void __user *)arg,
                         &snapshot, sizeof(snapshot)))
            return -EFAULT;
        return 0;

    case ANYSTACK_IOC_RESET:
        mutex_lock(&state_lock);
        state.enabled = 0;
        state.threshold = 0;
        mutex_unlock(&state_lock);
        return 0;

    default:
        return -ENOTTY;
    }
}

#ifdef CONFIG_COMPAT
/* 固定宽度且无指针字段时,compat 路径可复用同一命令处理。 */
static long anystack_compat_ioctl(struct file *file,
                                  unsigned int cmd,
                                  unsigned long arg)
{
    return anystack_ioctl(file, cmd,
                          (unsigned long)compat_ptr(arg));
}
#endif

static const struct file_operations anystack_fops = {
    .owner = THIS_MODULE,
    .unlocked_ioctl = anystack_ioctl,
#ifdef CONFIG_COMPAT
    .compat_ioctl = anystack_compat_ioctl,
#endif
};

static struct miscdevice anystack_misc = {
    .minor = MISC_DYNAMIC_MINOR,
    .name = "anystack_ctl",
    .fops = &anystack_fops,
};

static int __init anystack_init(void)
{
    return misc_register(&anystack_misc);
}

static void __exit anystack_exit(void)
{
    misc_deregister(&anystack_misc);
}

module_init(anystack_init);
module_exit(anystack_exit);

MODULE_LICENSE("GPL");
MODULE_DESCRIPTION("Example ioctl control interface");

预期结果

text
模块加载成功后出现 /dev/anystack_ctl;SET_CONFIG 更新状态,GET_STATUS 返回快照,RESET 清零状态。

copy_from_user 和 copy_to_user 的返回值是“未成功拷贝的字节数”,因此非零就应转成 -EFAULT,不能把这个字节数直接当系统调用错误码返回。未知 magic 或未知命令返回 -ENOTTY,参数值超出驱动约束时返回 -ERANGE,用户程序即可区分“命令不支持”和“参数不合法”。

用用户程序验证 ABI

测试程序先写入 enabled=1, threshold=42,读取状态,再执行 reset 并再次读取。假设头文件、驱动源码和测试程序位于同一目录,驱动已经按正常外部模块流程编译并加载。

c
#include <errno.h>
#include <fcntl.h>
#include <stdio.h>
#include <string.h>
#include <sys/ioctl.h>
#include <unistd.h>

#include "anystack_ctl_uapi.h"

int main(void)
{
    int fd = open("/dev/anystack_ctl", O_RDWR);
    struct anystack_config cfg = {
        .enabled = 1,
        .threshold = 42,
    };
    struct anystack_status status;

    if (fd < 0) {
        perror("open");
        return 1;
    }

    /* 先写配置,再读取状态验证 SET_CONFIG。 */
    if (ioctl(fd, ANYSTACK_IOC_SET_CONFIG, &cfg) < 0) {
        fprintf(stderr, "SET_CONFIG: %s\n", strerror(errno));
        close(fd);
        return 1;
    }

    if (ioctl(fd, ANYSTACK_IOC_GET_STATUS, &status) < 0) {
        perror("GET_STATUS");
        close(fd);
        return 1;
    }
    printf("enabled=%u threshold=%u\n",
           status.enabled, status.threshold);

    /* RESET 不带数据参数,再次读取即可验证状态归零。 */
    if (ioctl(fd, ANYSTACK_IOC_RESET, 0) < 0) {
        perror("RESET");
        close(fd);
        return 1;
    }

    if (ioctl(fd, ANYSTACK_IOC_GET_STATUS, &status) < 0) {
        perror("GET_STATUS");
        close(fd);
        return 1;
    }
    printf("enabled=%u threshold=%u\n",
           status.enabled, status.threshold);

    close(fd);
    return 0;
}

预期结果

text
编译并运行后,程序应先看到 enabled=1、threshold=42;执行 RESET 后两者都变为 0。

编译并执行测试程序:

bash
gcc -Wall -Wextra -O2 -o ioctl_test ioctl_test.c
sudo ./ioctl_test

预期输出

text
enabled=1 threshold=42
enabled=0 threshold=0

如果驱动返回 ENOTTY,先检查用户程序和内核模块是否包含同一版 UAPI 头文件,再检查 magic、命令编号和结构体大小。出现 EFAULT 通常表示传入了无效用户地址,或把整数值误当成结构体指针传递。

控制接口的维护边界

32 位用户程序运行在 64 位内核上时会走 compat_ioctl。本例结构不含指针且字段宽度固定,因此可把兼容层传来的用户指针转换后复用同一个处理函数;如果结构里包含指针、long 或依赖自然对齐的复杂字段,就必须定义兼容结构并逐字段转换,不能只做强制类型转换。

ioctl 适合低频、结构化的控制面,不适合持续数据流。批量采样数据优先用 read/write 或 mmap,事件通知可结合 poll,可枚举的通用属性应优先考虑 sysfs。把 ABI 的命令号、结构体布局、错误码和并发语义一开始就固定清楚,比后期为私有协议补兼容层成本更低。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 ioctl 设计控制接口

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通