Include

Purpose

include/ holds the kernel's public headers — both the in-kernel API (consumed by drivers, filesystems, every other directory) and the user-space ABI (UAPI). It does not contain executable code, but it shapes more of the codebase than any other directory.

Top-level layout

include/
├── linux/         # In-kernel API: most kernel modules include from here
├── uapi/          # User-space facing types and constants (UAPI)
│   ├── linux/
│   ├── asm-generic/
│   ├── ...
├── asm-generic/   # Generic asm-* implementations; archs override what they need
├── net/           # Networking-specific in-kernel headers
├── drm/           # DRM (graphics) UAPI and in-kernel headers
├── crypto/        # Crypto API headers
├── sound/         # ALSA headers
├── scsi/          # SCSI headers
├── trace/         # Tracepoint definitions (TRACE_EVENT)
├── kvm/, ras/, soc/, target/, video/, vdso/, dt-bindings/, keys/, kunit/, math-emu/, misc/, pcmcia/, rdma/, xen/, media/, clocksource/, acpi/, …
└── …

Key directories

include/linux/

The in-kernel API. Most files here are headers like <linux/sched.h>, <linux/fs.h>, <linux/mm.h>, <linux/spinlock.h>. New kernel APIs are introduced by adding here.

include/uapi/

The user-space API. Headers here are exported as linux/... to user space — this is what glibc and musl consume. Examples:

• include/uapi/linux/io_uring.h — io_uring SQE/CQE format.
• include/uapi/linux/bpf.h — bpf syscall types.
• include/uapi/linux/socket.h — socket constants.
• include/uapi/linux/perf_event.h — perf_event types.

Changes here are scrutinized: this is the stable ABI Linus famously refuses to break.

include/asm-generic/

Generic implementations of asm/ headers. Each architecture has its own arch/<arch>/include/asm/ that overrides what it needs and pulls in asm-generic for the rest. Adding a new generic primitive often starts by writing the asm-generic version.

include/trace/events/

Tracepoint declarations using the TRACE_EVENT() macro. When you add a tracepoint, the declaration goes here, and the consumer side is trace_<name>(...) calls in code.

include/dt-bindings/

Constants used by device-tree source files, shared between Linux DTS and other consumers (U-Boot, hardware vendor docs).

include/drm/, include/sound/, include/scsi/, etc.

Subsystem-specific headers split out for readability.

Notable conventions

• Forward declarations are often used to keep header includes minimal.
• #ifdef __KERNEL__ guards have been mostly removed; UAPI vs. kernel-only is now controlled by directory placement (uapi/ vs not).
• __user, __kernel, __iomem annotations matter for sparse.
• Visibility: a function declared in include/linux/foo.h is generally callable from anywhere in the kernel; but per-subsystem internal headers (e.g. mm/internal.h, fs/internal.h) are private.

Integration points

Touched by every other directory. Best searched with grep -r '<linux/foo.h>' . to find consumers, or git grep "EXPORT_SYMBOL.*foo" for in-tree symbol exports.

Entry points for modification

• New kernel API: add <linux/foo.h>, declare the API, implement under the matching subsystem dir.
• New UAPI: add <uapi/linux/foo.h> and add to Kbuild to be exported. Coordinate with linux-api@.
• New tracepoint: add <trace/events/foo.h>.
• New device-tree binding: YAML schema under Documentation/devicetree/bindings/, constants under include/dt-bindings/.

Related pages

• Architecture support — arch/<arch>/include/asm/ overrides.
• Tools — tools/include/ mirrors UAPI for in-tree tools.
• Reference → Configuration — Kconfig and headers.