Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
perf tools: Add tools/include/uapi/README
Write down the reason why we keep a copy of headers to the README file
instead of adding it to every commit messages.
Suggested-by: Jani Nikula <jani.nikula@linux.intel.com>
Original-by: Arnaldo Carvalho de Melo <acme@kernel.org>
Original-by: Ingo Molnar <mingo@kernel.org>
Signed-off-by: Namhyung Kim <namhyung@kernel.org>
+73
+73
tools/include/uapi/README
+73
tools/include/uapi/README
···
1
+
Why we want a copy of kernel headers in tools?
2
+
==============================================
3
+
4
+
There used to be no copies, with tools/ code using kernel headers
5
+
directly. From time to time tools/perf/ broke due to legitimate kernel
6
+
hacking. At some point Linus complained about such direct usage. Then we
7
+
adopted the current model.
8
+
9
+
The way these headers are used in perf are not restricted to just
10
+
including them to compile something.
11
+
12
+
There are sometimes used in scripts that convert defines into string
13
+
tables, etc, so some change may break one of these scripts, or new MSRs
14
+
may use some different #define pattern, etc.
15
+
16
+
E.g.:
17
+
18
+
$ ls -1 tools/perf/trace/beauty/*.sh | head -5
19
+
tools/perf/trace/beauty/arch_errno_names.sh
20
+
tools/perf/trace/beauty/drm_ioctl.sh
21
+
tools/perf/trace/beauty/fadvise.sh
22
+
tools/perf/trace/beauty/fsconfig.sh
23
+
tools/perf/trace/beauty/fsmount.sh
24
+
$
25
+
$ tools/perf/trace/beauty/fadvise.sh
26
+
static const char *fadvise_advices[] = {
27
+
[0] = "NORMAL",
28
+
[1] = "RANDOM",
29
+
[2] = "SEQUENTIAL",
30
+
[3] = "WILLNEED",
31
+
[4] = "DONTNEED",
32
+
[5] = "NOREUSE",
33
+
};
34
+
$
35
+
36
+
The tools/perf/check-headers.sh script, part of the tools/ build
37
+
process, points out changes in the original files.
38
+
39
+
So its important not to touch the copies in tools/ when doing changes in
40
+
the original kernel headers, that will be done later, when
41
+
check-headers.sh inform about the change to the perf tools hackers.
42
+
43
+
Another explanation from Ingo Molnar:
44
+
It's better than all the alternatives we tried so far:
45
+
46
+
- Symbolic links and direct #includes: this was the original approach but
47
+
was pushed back on from the kernel side, when tooling modified the
48
+
headers and broke them accidentally for kernel builds.
49
+
50
+
- Duplicate self-defined ABI headers like glibc: double the maintenance
51
+
burden, double the chance for mistakes, plus there's no tech-driven
52
+
notification mechanism to look at new kernel side changes.
53
+
54
+
What we are doing now is a third option:
55
+
56
+
- A software-enforced copy-on-write mechanism of kernel headers to
57
+
tooling, driven by non-fatal warnings on the tooling side build when
58
+
kernel headers get modified:
59
+
60
+
Warning: Kernel ABI header differences:
61
+
diff -u tools/include/uapi/drm/i915_drm.h include/uapi/drm/i915_drm.h
62
+
diff -u tools/include/uapi/linux/fs.h include/uapi/linux/fs.h
63
+
diff -u tools/include/uapi/linux/kvm.h include/uapi/linux/kvm.h
64
+
...
65
+
66
+
The tooling policy is to always pick up the kernel side headers as-is,
67
+
and integate them into the tooling build. The warnings above serve as a
68
+
notification to tooling maintainers that there's changes on the kernel
69
+
side.
70
+
71
+
We've been using this for many years now, and it might seem hacky, but
72
+
works surprisingly well.
73
+