https://www.kernel.org/doc/html/v6.6/driver-api/ioctl.html

ioctl基于接口

ioctl()是应用程序与设备驱动程序进行接口交互的最常见方式。它灵活且易于通过添加新命令进行扩展，并且可以通过字符设备、块设备以及套接字和其他特殊文件描述符进行传递。

然而，很容易错误地定义ioctl命令，并且很难在不破坏现有应用程序的情况下修复它们，因此本文档试图帮助开发人员正确使用它。

命令编号定义

命令编号或请求编号是传递给ioctl系统调用的第二个参数。虽然这可以是任何32位数字，用于唯一标识特定驱动程序的操作，但在定义它们时有一些约定。

include/uapi/asm-generic/ioctl.h提供了四个宏，用于定义遵循现代约定的ioctl命令：_IO、_IOR、_IOW和_IOWR。对于所有新命令，应使用这些宏，并使用正确的参数：

_IO/_IOR/_IOW/_IOWR

宏名称指定参数的使用方式。它可以是指向要传递到内核的数据的指针（_IOW），从内核传出的数据的指针（_IOR），或者两者都有的指针（_IOWR）。_IO可以表示没有参数的命令或传递整数值而不是指针的命令。建议仅对没有参数的命令使用_IO，并使用指针传递数据。
type

一个8位数字，通常是特定子系统或驱动程序的字符字面值，并在Ioctl Numbers中列出
nr

一个8位数字，用于标识特定命令，在给定'type'值的情况下是唯一的
data_type

参数指向的数据类型的名称，命令编号将sizeof(data_type)值编码为13位或14位整数，从而限制了参数的最大大小为8191字节。注意：不要将sizeof(data_type)类型传递给_IOR/_IOW/IOWR，因为这将导致编码sizeof(sizeof(data_type))，即sizeof(size_t)。_IO没有data_type参数。

接口版本

某些子系统在数据结构中使用版本号，以重载具有不同参数解释的命令。

这通常是一个不好的做法，因为更改现有命令往往会破坏现有应用程序。

更好的方法是添加一个具有新编号的新ioctl命令。为了兼容性，旧命令仍然需要在内核中实现，但可以将其包装在新实现的周围。

返回代码

ioctl命令可以返回负错误代码，如errno(3)中所述；这些错误代码在用户空间中转换为errno值。成功时，返回代码应为零。也可以返回正的'long'值，但不建议这样做。

当使用未知命令编号调用ioctl回调时，处理程序返回-ENOTTY或-ENOIOCTLCMD，这也导致从系统调用返回-ENOTTY。一些子系统在这里返回-ENOSYS或-EINVAL是出于历史原因，但这是错误的。

在Linux 5.5之前，compat_ioctl处理程序需要返回-ENOIOCTLCMD，以便使用回退转换为本机命令。由于现在所有子系统都负责处理兼容模式，因此不再需要这样做，但在将错误修复移植到旧内核时，考虑到这一点可能很重要。

时间戳

传统上，时间戳和超时值被传递为struct timespec或struct timeval，但由于64位time_t的移动后，这些结构在用户空间中的定义不兼容，因此存在问题。

当需要单独的秒/纳秒值时，可以使用struct __kernel_timespec类型嵌入到其他数据结构中，或直接传递给用户空间。然而，这仍然不是理想的解决方案，因为该结构既不匹配内核的timespec64，也不完全匹配用户空间的timespec。可以使用get_timespec64()和put_timespec64()辅助函数来确保布局与用户空间兼容，并正确处理填充。

由于将秒转换为纳秒很简单，但相反需要昂贵的64位除法，因此简单的__u64纳秒值可能更简单和更高效。

超时值和时间戳应理想地使用CLOCK_MONOTONIC时间，如ktime_get_ns()或ktime_get_ts64()所返回的那样。与CLOCK_REALTIME不同，这使得时间戳免受由于闰秒调整和clock_settime()调用而向前或向后跳动的影响。

对于需要在重启或多台机器之间持久存在的CLOCK_REALTIME时间戳，可以使用ktime_get_real_ns()。

32位兼容模式

为了支持在64位机器上运行的32位用户空间，每个实现ioctl回调处理程序的子系统或驱动程序也必须实现相应的compat_ioctl处理程序。

只要遵循数据结构的所有规则，这很容易，只需将.compat_ioctl指针设置为诸如compat_ptr_ioctl()或blkdev_compat_ptr_ioctl()之类的辅助函数即可。

compat_ptr()

在s390架构上，31位用户空间对于数据指针具有模糊的表示，忽略了最高位。在以compat模式运行此类进程时，必须使用compat_ptr()辅助函数来清除compat_uptr_t的最高位，并将其转换为有效的64位指针。在其他架构上，此宏仅执行到void __user *指针的转换。

在compat_ioctl()回调中，最后一个参数是一个unsigned long，可以根据命令将其解释为指针或标量。如果它是标量，则不能使用compat_ptr()，以确保64位内核对于带有设置了最高位的参数的行为与32位内核相同。

对于仅接受指向兼容数据结构的指针的驱动程序，可以使用compat_ptr_ioctl()辅助函数来替代自定义的compat_ioctl文件操作。

结构布局

兼容的数据结构在所有架构上具有相同的布局，避免了所有问题成员：

long和unsigned long的大小与寄存器相同，因此它们可以是32位或64位宽，并且不能用于可移植的数据结构。固定长度的替代类型是__s32、__u32、__s64和__u64。
指针也有同样的问题，除了需要使用compat_ptr()之外。最好的解决方法是在指针的位置使用__u64，这需要在用户空间中进行uintptr_t的转换，并在内核中使用u64_to_user_ptr()将其转换回用户指针。
在x86-32（i386）架构上，64位变量的对齐方式只有32位，但在包括x86-64在内的大多数其他架构上，它们是自然对齐的。这意味着在x86-64上，像这样的结构：
```
struct foo {
    __u32 a;
    __u64 b;
    __u32 c;
};
```
在a和b之间有4个字节的填充，在结尾处还有另外4个字节的填充，但在i386上没有填充，并且它需要一个compat_ioctl转换处理程序来在这两种格式之间进行转换。
为了避免这个问题，所有的结构都应该有自然对齐的成员，或者在隐式填充的位置添加显式保留字段。可以使用pahole工具来检查对齐情况。
在ARM OABI用户空间，结构被填充到32位的倍数，如果它们不以32位边界结束，这会导致一些结构与现代EABI内核不兼容。
在m68k架构上，结构成员不能保证具有大于16位的对齐方式，这在依赖隐式填充时会成为一个问题。
位字段和枚举通常按照预期工作，但它们的一些属性是实现定义的，因此最好完全避免在ioctl接口中使用它们。
char成员可以是有符号的或无符号的，这取决于架构，因此应该使用__u8和__s8类型来表示8位整数值，尽管对于固定长度的字符串，使用char数组更清晰。