요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
======================
ioctl based interfaces
======================
ioctl() is the most common way for applications to interface
with device drivers. It is flexible and easily extended by adding new
commands and can be passed through character devices, block devices as
well as sockets and other special file descriptors.
However, it is also very easy to get ioctl command definitions wrong,
and hard to fix them later without breaking existing applications,
so this documentation tries to help developers get it right.
Command number definitions
==========================
The command number, or request number, is the second argument passed to
the ioctl system call. While this can be any 32-bit number that uniquely
identifies an action for a particular driver, there are a number of
conventions around defining them.
``include/uapi/asm-generic/ioctl.h`` provides four macros for defining
ioctl commands that follow modern conventions: ``_IO``, ``_IOR``,
``_IOW``, and ``_IOWR``. These should be used for all new commands,
with the correct parameters:
_IO/_IOR/_IOW/_IOWR
The macro name specifies how the argument will be used. It may be a
pointer to data to be passed into the kernel (_IOW), out of the kernel
(_IOR), or both (_IOWR). _IO can indicate either commands with no
argument or those passing an integer value instead of a pointer.
It is recommended to only use _IO for commands without arguments,
and use pointers for passing data.
type
An 8-bit number, often a character literal, specific to a subsystem
or driver, and listed in Documentation/userspace-api/ioctl/ioctl-number.rst
nr
An 8-bit number identifying the specific command, unique for a give
value of 'type'
data_type
The name of the data type pointed to by the argument, the command number
encodes the ``sizeof(data_type)`` value in a 13-bit or 14-bit integer,
leading to a limit of 8191 bytes for the maximum size of the argument.
Note: do not pass sizeof(data_type) type into _IOR/_IOW/IOWR, as that
will lead to encoding sizeof(sizeof(data_type)), i.e. sizeof(size_t).
_IO does not have a data_type parameter.
Interface versions
==================
Some subsystems use version numbers in data structures to overload
commands with different interpretations of the argument.
This is generally a bad idea, since changes to existing commands tend
to break existing applications.
A better approach is to add a new ioctl command with a new number. The
old command still needs to be implemented in the kernel for compatibility,
but this can be a wrapper around the new implementation.
Return code
===========
ioctl commands can return negative error codes as documented in errno(3);
these get turned into errno values in user space. On success, the return
code should be zero. It is also possible but not recommended to return
a positive 'long' value.
When the ioctl callback is called with an unknown command number, the
handler returns either -ENOTTY or -ENOIOCTLCMD, which also results in
-ENOTTY being returned from the system call. Some subsystems return
-ENOSYS or -EINVAL here for historic reasons, but this is wrong.
Prior to Linux 5.5, compat_ioctl handlers were required to return
-ENOIOCTLCMD in order to use the fallback conversion into native
commands. As all subsystems are now responsible for handling compat
mode themselves, this is no longer needed, but it may be important to
consider when backporting bug fixes to older kernels.
Timestamps
==========
Traditionally, timestamps and timeout values are passed as ``struct
timespec`` or ``struct timeval``, but these are problematic because of
incompatible definitions of these structures in user space after the
move to 64-bit time_t.
The ``struct __kernel_timespec`` type can be used instead to be embedded
in other data structures when separate second/nanosecond values are
desired, or passed to user space directly. This is still not ideal though,
as the structure matches neither the kernel's timespec64 nor the user
space timespec exactly. The get_timespec64() and put_timespec64() helper
functions can be used to ensure that the layout remains compatible with
user space and the padding is treated correctly.
As it is cheap to convert seconds to nanoseconds, but the opposite
requires an expensive 64-bit division, a simple __u64 nanosecond value
can be simpler and more efficient.
Timeout values and timestamps should ideally use CLOCK_MONOTONIC time,
as returned by ktime_get_ns() or ktime_get_ts64(). Unlike
CLOCK_REALTIME, this makes the timestamps immune from jumping backwards
or forwards due to leap second adjustments and clock_settime() calls.
ktime_get_real_ns() can be used for CLOCK_REALTIME timestamps that
need to be persistent across a reboot or between multiple machines.
32-bit compat mode
==================
In order to support 32-bit user space running on a 64-bit machine, each
subsystem or driver that implements an ioctl callback handler must also
implement the corresponding compat_ioctl handler.
As long as all the rules for data structures are followed, this is as
easy as setting the .compat_ioctl pointer to a helper function such as
compat_ptr_ioctl() or blkdev_compat_ptr_ioctl().
compat_ptr()
------------
On the s390 architecture, 31-bit user space has ambiguous representations
for data pointers, with the upper bit being ignored. When running such
a process in compat mode, the compat_ptr() helper must be used to
clear the upper bit of a compat_uptr_t and turn it into a valid 64-bit
pointer. On other architectures, this macro only performs a cast to a
``void __user *`` pointer.
In an compat_ioctl() callback, the last argument is an unsigned long,
which can be interpreted as either a pointer or a scalar depending on
the command. If it is a scalar, then compat_ptr() must not be used, to
ensure that the 64-bit kernel behaves the same way as a 32-bit kernel
for arguments with the upper bit set.
The compat_ptr_ioctl() helper can be used in place of a custom
compat_ioctl file operation for drivers that only take arguments that
are pointers to compatible data structures.
Structure layout
----------------
Compatible data structures have the same layout on all architectures,
avoiding all problematic members:
* ``long`` and ``unsigned long`` are the size of a register, so
they can be either 32-bit or 64-bit wide and cannot be used in portable
data structures. Fixed-length replacements are ``__s32``, ``__u32``,
``__s64`` and ``__u64``.
* Pointers have the same problem, in addition to requiring the
use of compat_ptr(). The best workaround is to use ``__u64``
in place of pointers, which requires a cast to ``uintptr_t`` in user
space, and the use of u64_to_user_ptr() in the kernel to convert
it back into a user pointer.
* On the x86-32 (i386) architecture, the alignment of 64-bit variables
is only 32-bit, but they are naturally aligned on most other
architectures including x86-64. This means a structure like::
struct foo {
__u32 a;
__u64 b;
__u32 c;
};
has four bytes of padding between a and b on x86-64, plus another four
bytes of padding at the end, but no padding on i386, and it needs a
compat_ioctl conversion handler to translate between the two formats.
To avoid this problem, all structures should have their members
naturally aligned, or explicit reserved fields added in place of the
implicit padding. The ``pahole`` tool can be used for checking the
alignment.
* On ARM OABI user space, structures are padded to multiples of 32-bit,
making some structs incompatible with modern EABI kernels if they
do not end on a 32-bit boundary.
* On the m68k architecture, struct members are not guaranteed to have an
alignment greater than 16-bit, which is a problem when relying on
implicit padding.
* Bitfields and enums generally work as one would expect them to,
but some properties of them are implementation-defined, so it is better
to avoid them completely in ioctl interfaces.
* ``char`` members can be either signed or unsigned, depending on
the architecture, so the __u8 and __s8 types should be used for 8-bit
integer values, though char arrays are clearer for fixed-length strings.
Information leaks
=================
Uninitialized data must not be copied back to user space, as this can
cause an information leak, which can be used to defeat kernel address
space layout randomization (KASLR), helping in an attack.
For this reason (and for compat support) it is best to avoid any
implicit padding in data structures. Where there is implicit padding
in an existing structure, kernel drivers must be careful to fully
initialize an instance of the structure before copying it to user
space. This is usually done by calling memset() before assigning to
individual members.
Subsystem abstractions
======================
While some device drivers implement their own ioctl function, most
subsystems implement the same command for multiple drivers. Ideally the
subsystem has an .ioctl() handler that copies the arguments from and
to user space, passing them into subsystem specific callback functions
through normal kernel pointers.
This helps in various ways:
* Applications written for one driver are more likely to work for
another one in the same subsystem if there are no subtle differences
in the user space ABI.
* The complexity of user space access and data structure layout is done
in one place, reducing the potential for implementation bugs.
* It is more likely to be reviewed by experienced developers
that can spot problems in the interface when the ioctl is shared
between multiple drivers than when it is only used in a single driver.
Alternatives to ioctl
=====================
There are many cases in which ioctl is not the best solution for a
problem. Alternatives include:
* System calls are a better choice for a system-wide feature that
is not tied to a physical device or constrained by the file system
permissions of a character device node
* netlink is the preferred way of configuring any network related
objects through sockets.
* debugfs is used for ad-hoc interfaces for debugging functionality
that does not need to be exposed as a stable interface to applications.
* sysfs is a good way to expose the state of an in-kernel object
that is not tied to a file descriptor.
* configfs can be used for more complex configuration than sysfs
* A custom file system can provide extra flexibility with a simple
user interface but adds a lot of complexity to the implementation.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
ioctl interface 개요
1-13문서 제목은 `ioctl based interfaces`입니다. `ioctl()`은 application이 device driver와 interface하는 가장 흔한 방법입니다. New command를 추가해 유연하게 확장할 수 있고 character device, block device, socket와 다른 special file descriptor를 통해 전달할 수 있습니다.
하지만 ioctl command definition은 잘못 만들기 쉽고 existing application을 깨지 않고 나중에 고치기 어렵습니다. 이 문서는 처음부터 올바르게 정의하기 위한 지침입니다.
장점과 ABI 위험을 함께 보여 줍니다.
Command number 정의
14-50Command 또는 request number는 ioctl system call의 두 번째 argument입니다. 특정 driver action을 unique하게 식별하는 임의의 32-bit number일 수 있지만 convention을 따라야 합니다.
`include/uapi/asm-generic/ioctl.h`는 modern convention용 `_IO`, `_IOR`, `_IOW`, `_IOWR` macro를 제공합니다. `_IOW`는 userspace에서 kernel로 data input, `_IOR`은 kernel에서 output, `_IOWR`은 양방향 pointer data를 뜻합니다. `_IO`는 argument가 없거나 pointer 대신 integer를 전달하는 command를 나타낼 수 있지만 argument 없는 command에만 쓰고 data는 pointer로 전달하는 것이 권장됩니다.
`type`은 subsystem 또는 driver별 8-bit number이며 흔히 character literal입니다. 값은 `Documentation/userspace-api/ioctl/ioctl-number.rst`에 등록합니다. `nr`은 같은 `type` 안에서 specific command를 unique하게 식별하는 8-bit number입니다.
`data_type`은 argument가 가리키는 data type 이름입니다. Command number는 `sizeof(data_type)`을 13-bit 또는 14-bit integer로 encode하므로 argument 최대 크기는 8191 bytes입니다. `_IOR`, `_IOW`, `_IOWR`에 `sizeof(data_type)` 자체를 넘기면 `sizeof(sizeof(data_type))`, 즉 `sizeof(size_t)`가 encode되므로 절대 그렇게 하면 안 됩니다. `_IO`에는 data_type parameter가 없습니다.
Argument data direction과 권장 용도입니다.
type·nr·data_type의 폭과 제약입니다.
Interface version
51-64일부 subsystem은 data structure version number로 같은 command argument의 해석을 overload합니다. Existing command 변경은 existing application을 깨기 쉬우므로 일반적으로 나쁜 방법입니다.
더 나은 방법은 새 number의 ioctl command를 추가하는 것입니다. Compatibility를 위해 old command도 kernel에 남겨야 하지만 new implementation을 감싸는 wrapper로 만들 수 있습니다.
Existing command를 바꾸지 않고 새 command로 발전시킵니다.
Return code
65-83Ioctl command는 `errno(3)`에 문서화된 negative error code를 반환할 수 있고 userspace에서는 errno 값으로 변환됩니다. Success는 0이어야 합니다. Positive `long` 반환도 가능하지만 권장하지 않습니다.
Unknown command number를 받으면 handler는 `-ENOTTY` 또는 `-ENOIOCTLCMD`를 반환하며 system call 결과는 `-ENOTTY`입니다. 역사적으로 일부 subsystem이 `-ENOSYS`나 `-EINVAL`을 반환하지만 이는 잘못입니다.
Linux 5.5 전에는 compat_ioctl handler가 native command fallback conversion을 쓰기 위해 `-ENOIOCTLCMD`를 반환해야 했습니다. 이제 각 subsystem이 compat mode를 직접 처리하므로 필요 없지만 older kernel로 bug fix를 backport할 때 고려해야 합니다.
Success·known error·unknown command를 구분합니다.
Timestamp와 timeout
84-111전통적으로 timestamp와 timeout은 `struct timespec` 또는 `struct timeval`로 전달했지만 64-bit `time_t` 전환 뒤 userspace definition이 호환되지 않아 문제가 됩니다.
Separate seconds/nanoseconds가 필요하면 다른 structure에 `struct __kernel_timespec`을 embed하거나 userspace에 직접 전달할 수 있습니다. 다만 kernel `timespec64`와 userspace `timespec` 어느 쪽 layout과도 정확히 같지 않습니다. `get_timespec64()`와 `put_timespec64()` helper로 userspace layout compatibility와 padding 처리를 보장해야 합니다.
Seconds를 nanoseconds로 바꾸는 것은 싸지만 반대는 expensive 64-bit division이 필요하므로 단순한 `__u64` nanosecond 값이 더 간단하고 효율적일 수 있습니다.
Timeout과 timestamp는 이상적으로 `ktime_get_ns()` 또는 `ktime_get_ts64()`가 반환하는 `CLOCK_MONOTONIC`을 써야 합니다. `CLOCK_REALTIME`과 달리 leap second adjustment나 `clock_settime()` 때문에 앞뒤로 jump하지 않습니다. Reboot 사이 또는 여러 machine 사이에 지속되어야 하는 realtime timestamp에는 `ktime_get_real_ns()`를 사용할 수 있습니다.
Layout compatibility와 clock 선택을 정리했습니다.
32-bit compat mode와 compat_ptr
112-14264-bit machine에서 32-bit userspace를 지원하려면 ioctl callback을 구현한 subsystem·driver가 corresponding `compat_ioctl` handler도 구현해야 합니다. Data structure rule을 지키면 `.compat_ioctl` pointer를 `compat_ptr_ioctl()` 또는 `blkdev_compat_ptr_ioctl()` 같은 helper로 설정하면 됩니다.
s390에서 31-bit userspace data pointer는 upper bit가 무시되는 ambiguous representation입니다. Compat mode에서는 `compat_ptr()`로 `compat_uptr_t`의 upper bit를 clear해 valid 64-bit pointer로 바꿔야 합니다. 다른 architecture에서 이 macro는 `void __user *` cast만 수행합니다.
`compat_ioctl()` callback의 마지막 argument는 `unsigned long`이고 command에 따라 pointer 또는 scalar입니다. Scalar라면 upper bit가 설정된 argument에서 64-bit kernel이 32-bit kernel과 동일하게 동작하도록 `compat_ptr()`을 사용하면 안 됩니다.
Pointer와 compatible data structure만 argument로 받는 driver는 custom compat_ioctl file operation 대신 `compat_ptr_ioctl()` helper를 사용할 수 있습니다.
Pointer와 scalar를 구분한 올바른 conversion입니다.
Portable structure layout
143-194Compatible data structure는 모든 architecture에서 같은 layout이어야 하며 문제가 되는 member를 피해야 합니다. `long`과 `unsigned long`은 register 크기라 32-bit 또는 64-bit가 될 수 있으므로 portable structure에 쓰지 말고 `__s32`, `__u32`, `__s64`, `__u64`을 사용합니다.
Pointer도 폭 문제가 있고 compat_ptr가 필요합니다. Pointer 대신 `__u64`을 쓰고 userspace에서는 `uintptr_t`로 cast하며 kernel에서는 `u64_to_user_ptr()`로 user pointer로 변환하는 것이 가장 나은 workaround입니다.
x86-32에서 64-bit variable alignment는 32-bit이지만 x86-64를 포함한 대부분 architecture에서는 natural alignment입니다. 아래 structure는 x86-64에서 `a`와 `b` 사이 4-byte padding과 끝 4-byte padding이 있지만 i386에는 padding이 없어 compat conversion이 필요합니다.
struct foo {
__u32 a;
__u64 b;
__u32 c;
};문제를 피하려면 모든 member를 natural alignment에 맞추거나 implicit padding 위치에 explicit reserved field를 넣어야 합니다. `pahole`로 alignment를 확인할 수 있습니다.
ARM OABI userspace는 structure를 32-bit multiple로 pad하므로 32-bit boundary로 끝나지 않는 일부 struct는 modern EABI kernel과 호환되지 않습니다. m68k에서는 member가 16-bit보다 큰 alignment를 보장받지 못해 implicit padding 의존이 문제입니다.
Bitfield와 enum은 대개 예상대로 동작하지만 일부 property가 implementation-defined이므로 ioctl interface에서는 완전히 피하는 편이 낫습니다. `char` signedness도 architecture에 따라 달라지므로 8-bit integer에는 `__u8`, `__s8`을 쓰고 fixed-length string에는 char array가 더 명확합니다.
피해야 할 type과 대체 방법입니다.
대표 compat layout 차이입니다.
Information leak 방지
195-208Uninitialized data를 userspace로 copy하면 information leak이 발생하고 kernel address space layout randomization(KASLR)을 무력화해 attack을 도울 수 있습니다.
이 이유와 compat support 때문에 data structure의 implicit padding을 피하는 것이 좋습니다. Existing structure에 implicit padding이 있다면 userspace로 copy하기 전에 instance 전체를 초기화해야 합니다. 보통 individual member를 assign하기 전에 `memset()`을 호출합니다.
Kernel structure를 userspace로 copy하기 전 초기화 순서입니다.
Subsystem abstraction
209-230일부 device driver는 자체 ioctl function을 구현하지만 대부분 subsystem은 여러 driver에 같은 command를 구현합니다. 이상적으로 subsystem의 `.ioctl()` handler가 userspace argument를 copy in/out하고 normal kernel pointer로 subsystem-specific callback에 전달합니다.
이 방식은 한 driver용 application이 같은 subsystem의 다른 driver에서도 subtle userspace ABI 차이 없이 동작할 가능성을 높입니다. Userspace access와 structure layout complexity를 한 곳에서 처리해 implementation bug 가능성을 줄이고, 여러 driver가 공유하는 interface는 experienced developer에게 review될 가능성도 높습니다.
Userspace marshalling과 driver callback을 분리합니다.
ioctl 대안
231-253Ioctl이 최선이 아닌 경우가 많습니다. Physical device에 묶이지 않고 character device permission에 제한되지 않는 system-wide feature에는 system call이 낫습니다. Network object configuration은 socket 기반 netlink가 선호됩니다.
Stable application interface가 필요 없는 ad-hoc debugging에는 debugfs를 씁니다. File descriptor에 묶이지 않은 in-kernel object state 노출에는 sysfs, sysfs보다 복잡한 configuration에는 configfs를 사용할 수 있습니다. Custom filesystem은 단순한 userspace interface에 extra flexibility를 주지만 implementation complexity가 매우 큽니다.
Interface 성격에 맞는 kernel-userspace mechanism입니다.
요약과 해설
ioctl.rst:1-253ioctl ABI는 배포 뒤 수정하기 어려우므로 새 command number, fixed-width member, explicit padding, monotonic timestamp와 compat handler를 처음부터 설계해야 합니다. Subsystem 공통 handler로 userspace marshalling을 한 곳에 모으고 문제 성격에 따라 netlink·sysfs·configfs 같은 대안도 우선 검토합니다.