嵌入式 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、裸指针和随编译器变化的布局;新增字段时还要考虑旧程序是否仍能工作。

_IO 表示无数据参数,_IOR 表示驱动向用户返回数据,_IOW 表示用户向驱动提交数据,_IOWR 表示双向。方向宏不仅提高可读性,还会把参数大小编码进命令号,便于内核和调试工具判断 ABI。
定义共享的 UAPI 头文件
下面头文件同时给内核模块和用户程序包含。结构体只使用 __u32,因此在常见 32 位和 64 位 ABI 上布局一致;没有嵌入用户指针,也就不需要为指针宽度单独定义另一套结构。
#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预期结果
该头文件不产生运行时输出;内核模块与用户程序使用同一份命令号和结构体定义。命令编号不要重复,也不要把 sizeof(arg) 传给 _IOW 等宏;第三个参数必须是数据类型本身。若未来扩展结构,优先保留已有字段含义并新增新命令或显式版本字段,而不是悄悄改变旧命令的结构大小。
在驱动中实现命令分派
为把重点放在控制接口上,下面使用 miscdevice 注册字符设备,它会自动分配次设备号并创建 /dev/anystack_ctl。驱动保存两个状态字段,并对用户输入做范围检查。
#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");预期结果
模块加载成功后出现 /dev/anystack_ctl;SET_CONFIG 更新状态,GET_STATUS 返回快照,RESET 清零状态。copy_from_user 和 copy_to_user 的返回值是“未成功拷贝的字节数”,因此非零就应转成 -EFAULT,不能把这个字节数直接当系统调用错误码返回。未知 magic 或未知命令返回 -ENOTTY,参数值超出驱动约束时返回 -ERANGE,用户程序即可区分“命令不支持”和“参数不合法”。
用用户程序验证 ABI
测试程序先写入 enabled=1, threshold=42,读取状态,再执行 reset 并再次读取。假设头文件、驱动源码和测试程序位于同一目录,驱动已经按正常外部模块流程编译并加载。
#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;
}预期结果
编译并运行后,程序应先看到 enabled=1、threshold=42;执行 RESET 后两者都变为 0。编译并执行测试程序:
gcc -Wall -Wextra -O2 -o ioctl_test ioctl_test.c
sudo ./ioctl_test预期输出
enabled=1 threshold=42
enabled=0 threshold=0如果驱动返回 ENOTTY,先检查用户程序和内核模块是否包含同一版 UAPI 头文件,再检查 magic、命令编号和结构体大小。出现 EFAULT 通常表示传入了无效用户地址,或把整数值误当成结构体指针传递。
控制接口的维护边界
32 位用户程序运行在 64 位内核上时会走 compat_ioctl。本例结构不含指针且字段宽度固定,因此可把兼容层传来的用户指针转换后复用同一个处理函数;如果结构里包含指针、long 或依赖自然对齐的复杂字段,就必须定义兼容结构并逐字段转换,不能只做强制类型转换。
ioctl 适合低频、结构化的控制面,不适合持续数据流。批量采样数据优先用 read/write 或 mmap,事件通知可结合 poll,可枚举的通用属性应优先考虑 sysfs。把 ABI 的命令号、结构体布局、错误码和并发语义一开始就固定清楚,比后期为私有协议补兼容层成本更低。