^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) ======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) ioctl based interfaces
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) ioctl() is the most common way for applications to interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) with device drivers. It is flexible and easily extended by adding new
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) commands and can be passed through character devices, block devices as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) well as sockets and other special file descriptors.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) However, it is also very easy to get ioctl command definitions wrong,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) and hard to fix them later without breaking existing applications,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) so this documentation tries to help developers get it right.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) Command number definitions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) ==========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) The command number, or request number, is the second argument passed to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) the ioctl system call. While this can be any 32-bit number that uniquely
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) identifies an action for a particular driver, there are a number of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) conventions around defining them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) ``include/uapi/asm-generic/ioctl.h`` provides four macros for defining
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) ioctl commands that follow modern conventions: ``_IO``, ``_IOR``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) ``_IOW``, and ``_IOWR``. These should be used for all new commands,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) with the correct parameters:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) _IO/_IOR/_IOW/_IOWR
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) The macro name specifies how the argument will be used. It may be a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) pointer to data to be passed into the kernel (_IOW), out of the kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) (_IOR), or both (_IOWR). _IO can indicate either commands with no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) argument or those passing an integer value instead of a pointer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) It is recommended to only use _IO for commands without arguments,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) and use pointers for passing data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) type
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) An 8-bit number, often a character literal, specific to a subsystem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) or driver, and listed in :doc:`../userspace-api/ioctl/ioctl-number`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) nr
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) An 8-bit number identifying the specific command, unique for a give
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) value of 'type'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) data_type
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) The name of the data type pointed to by the argument, the command number
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) encodes the ``sizeof(data_type)`` value in a 13-bit or 14-bit integer,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) leading to a limit of 8191 bytes for the maximum size of the argument.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) Note: do not pass sizeof(data_type) type into _IOR/_IOW/IOWR, as that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) will lead to encoding sizeof(sizeof(data_type)), i.e. sizeof(size_t).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) _IO does not have a data_type parameter.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) Interface versions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) ==================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) Some subsystems use version numbers in data structures to overload
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) commands with different interpretations of the argument.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) This is generally a bad idea, since changes to existing commands tend
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) to break existing applications.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) A better approach is to add a new ioctl command with a new number. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) old command still needs to be implemented in the kernel for compatibility,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) but this can be a wrapper around the new implementation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) Return code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) ===========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) ioctl commands can return negative error codes as documented in errno(3);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) these get turned into errno values in user space. On success, the return
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) code should be zero. It is also possible but not recommended to return
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) a positive 'long' value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) When the ioctl callback is called with an unknown command number, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) handler returns either -ENOTTY or -ENOIOCTLCMD, which also results in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) -ENOTTY being returned from the system call. Some subsystems return
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) -ENOSYS or -EINVAL here for historic reasons, but this is wrong.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) Prior to Linux 5.5, compat_ioctl handlers were required to return
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) -ENOIOCTLCMD in order to use the fallback conversion into native
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) commands. As all subsystems are now responsible for handling compat
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) mode themselves, this is no longer needed, but it may be important to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) consider when backporting bug fixes to older kernels.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) Timestamps
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) ==========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) Traditionally, timestamps and timeout values are passed as ``struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) timespec`` or ``struct timeval``, but these are problematic because of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) incompatible definitions of these structures in user space after the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) move to 64-bit time_t.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) The ``struct __kernel_timespec`` type can be used instead to be embedded
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) in other data structures when separate second/nanosecond values are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) desired, or passed to user space directly. This is still not ideal though,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) as the structure matches neither the kernel's timespec64 nor the user
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) space timespec exactly. The get_timespec64() and put_timespec64() helper
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) functions can be used to ensure that the layout remains compatible with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) user space and the padding is treated correctly.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) As it is cheap to convert seconds to nanoseconds, but the opposite
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) requires an expensive 64-bit division, a simple __u64 nanosecond value
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) can be simpler and more efficient.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) Timeout values and timestamps should ideally use CLOCK_MONOTONIC time,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) as returned by ktime_get_ns() or ktime_get_ts64(). Unlike
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) CLOCK_REALTIME, this makes the timestamps immune from jumping backwards
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) or forwards due to leap second adjustments and clock_settime() calls.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) ktime_get_real_ns() can be used for CLOCK_REALTIME timestamps that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) need to be persistent across a reboot or between multiple machines.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) 32-bit compat mode
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) ==================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) In order to support 32-bit user space running on a 64-bit machine, each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) subsystem or driver that implements an ioctl callback handler must also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) implement the corresponding compat_ioctl handler.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) As long as all the rules for data structures are followed, this is as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) easy as setting the .compat_ioctl pointer to a helper function such as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) compat_ptr_ioctl() or blkdev_compat_ptr_ioctl().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) compat_ptr()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) ------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) On the s390 architecture, 31-bit user space has ambiguous representations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) for data pointers, with the upper bit being ignored. When running such
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) a process in compat mode, the compat_ptr() helper must be used to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) clear the upper bit of a compat_uptr_t and turn it into a valid 64-bit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) pointer. On other architectures, this macro only performs a cast to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) ``void __user *`` pointer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) In an compat_ioctl() callback, the last argument is an unsigned long,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) which can be interpreted as either a pointer or a scalar depending on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) the command. If it is a scalar, then compat_ptr() must not be used, to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) ensure that the 64-bit kernel behaves the same way as a 32-bit kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) for arguments with the upper bit set.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) The compat_ptr_ioctl() helper can be used in place of a custom
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) compat_ioctl file operation for drivers that only take arguments that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) are pointers to compatible data structures.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) Structure layout
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) ----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) Compatible data structures have the same layout on all architectures,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) avoiding all problematic members:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) * ``long`` and ``unsigned long`` are the size of a register, so
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) they can be either 32-bit or 64-bit wide and cannot be used in portable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) data structures. Fixed-length replacements are ``__s32``, ``__u32``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) ``__s64`` and ``__u64``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) * Pointers have the same problem, in addition to requiring the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) use of compat_ptr(). The best workaround is to use ``__u64``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) in place of pointers, which requires a cast to ``uintptr_t`` in user
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) space, and the use of u64_to_user_ptr() in the kernel to convert
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) it back into a user pointer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) * On the x86-32 (i386) architecture, the alignment of 64-bit variables
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) is only 32-bit, but they are naturally aligned on most other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) architectures including x86-64. This means a structure like::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) struct foo {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) __u32 a;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) __u64 b;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) __u32 c;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) has four bytes of padding between a and b on x86-64, plus another four
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) bytes of padding at the end, but no padding on i386, and it needs a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) compat_ioctl conversion handler to translate between the two formats.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) To avoid this problem, all structures should have their members
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) naturally aligned, or explicit reserved fields added in place of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) implicit padding. The ``pahole`` tool can be used for checking the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) alignment.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) * On ARM OABI user space, structures are padded to multiples of 32-bit,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) making some structs incompatible with modern EABI kernels if they
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) do not end on a 32-bit boundary.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) * On the m68k architecture, struct members are not guaranteed to have an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) alignment greater than 16-bit, which is a problem when relying on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) implicit padding.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) * Bitfields and enums generally work as one would expect them to,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) but some properties of them are implementation-defined, so it is better
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) to avoid them completely in ioctl interfaces.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) * ``char`` members can be either signed or unsigned, depending on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) the architecture, so the __u8 and __s8 types should be used for 8-bit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) integer values, though char arrays are clearer for fixed-length strings.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) Information leaks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) =================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) Uninitialized data must not be copied back to user space, as this can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) cause an information leak, which can be used to defeat kernel address
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) space layout randomization (KASLR), helping in an attack.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) For this reason (and for compat support) it is best to avoid any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) implicit padding in data structures. Where there is implicit padding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) in an existing structure, kernel drivers must be careful to fully
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) initialize an instance of the structure before copying it to user
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) space. This is usually done by calling memset() before assigning to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) individual members.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) Subsystem abstractions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) ======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) While some device drivers implement their own ioctl function, most
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) subsystems implement the same command for multiple drivers. Ideally the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) subsystem has an .ioctl() handler that copies the arguments from and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) to user space, passing them into subsystem specific callback functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) through normal kernel pointers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) This helps in various ways:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) * Applications written for one driver are more likely to work for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) another one in the same subsystem if there are no subtle differences
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) in the user space ABI.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) * The complexity of user space access and data structure layout is done
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) in one place, reducing the potential for implementation bugs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) * It is more likely to be reviewed by experienced developers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) that can spot problems in the interface when the ioctl is shared
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) between multiple drivers than when it is only used in a single driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) Alternatives to ioctl
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) =====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) There are many cases in which ioctl is not the best solution for a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) problem. Alternatives include:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) * System calls are a better choice for a system-wide feature that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) is not tied to a physical device or constrained by the file system
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) permissions of a character device node
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) * netlink is the preferred way of configuring any network related
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) objects through sockets.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) * debugfs is used for ad-hoc interfaces for debugging functionality
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) that does not need to be exposed as a stable interface to applications.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) * sysfs is a good way to expose the state of an in-kernel object
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) that is not tied to a file descriptor.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) * configfs can be used for more complex configuration than sysfs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) * A custom file system can provide extra flexibility with a simple
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) user interface but adds a lot of complexity to the implementation.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags