Documentation/driver-api/ioctl.rst

Source file repositories/reference/linux-study-clean/Documentation/driver-api/ioctl.rst

File Facts

System
Linux kernel
Corpus path
Documentation/driver-api/ioctl.rst
Extension
.rst
Size
10606 bytes
Lines
254
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

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
=====================

Annotation

Implementation Notes