Tools

Purpose

tools/ ships userspace tools that are tightly coupled to the kernel: perf, bpftool, cpupower, turbostat, iio, gpio, lib/bpf (libbpf), the entire kernel selftest suite, KUnit, the BPF and KVM test harnesses, and many smaller utilities.

These are built and shipped from the kernel tree because they target kernel features (often UAPI not yet in glibc) and need to track kernel changes.

Top-level contents

tools/
├── arch/                # Per-arch userspace helpers
├── bpf/, lib/bpf/       # bpftool, libbpf
├── perf/                # perf(1)
├── testing/
│   ├── kunit/           # KUnit user-side runner
│   └── selftests/       # The big in-tree test suite (per-subsystem)
├── power/               # cpupower, x86/turbostat, x86/intel-speed-select
├── tracing/             # rtla, latency-collector
├── iio/                 # iio_event_monitor, iio_generic_buffer
├── memory-model/        # LKMM herd7 helpers
├── firmware/            # ihex2fw etc.
├── usb/, virtio/, vm/   # Tools for those subsystems
├── thermal/             # tmon
├── gpio/                # gpio-event-mon, gpio-watch
├── hv/                  # Hyper-V daemon helpers
├── mm/                  # page-types, slabinfo, thpcompact
├── verification/        # rv (runtime verification)
├── sched_ext/           # User-side helpers for sched_ext schedulers
├── tracing/             # latency-collector, rtla
├── lib/                 # Vendored or kernel-aware utility libraries (subcmd, traceevent, perf, bpf)
├── objtool/             # ORC unwind table generator + check tool used during the kernel build
├── workqueue/           # wq_dump, wq_monitor
└── ...

Notable subdirectories

tools/perf/

The largest single tool. Tracks every new kernel perf feature. Contains both a userspace counterpart and substantial parts of the perf event handling not exposed through libbpf. Built with make -C tools/perf.

tools/bpf/ and tools/lib/bpf/

bpftool (the swiss-army knife for inspecting and managing BPF programs/maps/links) and libbpf (the user-space library that loads BPF programs and resolves CO-RE relocations). libbpf is also released externally as a stand-alone library.

tools/testing/selftests/

The kselftest harness. Each subsystem has its own subdirectory with C/Python/shell tests. Standardized output (TAP). See How to contribute → Testing. Coverage:

• bpf/, kvm/, net/, mm/, cgroup/, clone3/, pidfd/, mount_setattr/, landlock/, seccomp/, futex/, iommu/, proc/, tdx/, damon/, livepatch/, arm64/, riscv/, x86/, powerpc/, kexec/, nolibc/, sgx/, vDSO/, ftrace/, rseq/, mqueue/, …

tools/testing/kunit/

The user-side runner for KUnit tests. tools/testing/kunit/kunit.py run builds and runs KUnit tests in UML or in QEMU.

tools/objtool/

Run during the kernel build to validate the call-graph and generate ORC unwind tables. Catches missing unreachable() annotations, unbalanced stack pushes, and similar low-level issues. See Documentation/dev-tools/objtool.rst.

tools/cpupower, tools/power/x86/turbostat, tools/power/x86/intel-speed-select

Userspace helpers for CPU frequency, idle states, and Intel SST. cpupower replaces the older cpufrequtils.

tools/lib/

Shared in-tree libraries: subcmd (a CLI sub-command framework), traceevent, bpf, perf, api. These are linked into the user-space tools above.

tools/include/

Kernel UAPI headers copied for use by tools (because make headers_install may not have been run on the host).

tools/sched_ext/

User-space framework for sched_ext schedulers — the "scheduler in BPF" loaders. Build a .bpf.o and load it via the helpers here.

tools/verification/rv/

Runtime verification — load monitors that observe the kernel and detect protocol violations.

Building

Each subdir has its own Makefile and is built independently:

make -C tools/perf
make -C tools/bpf/bpftool
make -C tools/testing/selftests TARGETS=bpf
make kselftest                            # Top-level shortcut

make tools/help (or make help after configure) lists more.

Integration points

• These tools depend on the running kernel's UAPI. Kernel and tools versions don't have to match exactly, but keeping them in sync is recommended.
• Tools that ship libraries (libbpf, libtraceevent) also have out-of-tree releases.
• Selftests are how the kernel community validates many features end-to-end.

Entry points for modification

• Adding a selftest: drop a directory under tools/testing/selftests/<subsys>/, write a C/shell test using kselftest_harness.h. Hook into the parent Makefile.
• Adding a feature to bpftool: tools/bpf/bpftool/.
• Adding a perf feature: tools/perf/.
• New libbpf API: tools/lib/bpf/. Stable ABI; coordinate with the libbpf maintainers.

Related pages

• How to contribute → Testing — running these.
• How to contribute → Tooling — checkpatch, sparse.
• Scripts — kernel build helpers (different from tools/).