1# Bionic Kernel Header Files
2
3Bionic comes with a processed set of all of the uapi Linux kernel headers that
4can safely be included by userland applications and libraries.
5
6These clean headers are automatically generated by several scripts located
7in the `tools/` directory. The tools process the original
8unmodified kernel headers in order to get rid of many annoying
9declarations and constructs that usually result in compilation failure.
10
11The 'clean headers' only contain type and macro definitions, with the
12exception of a couple static inline functions used for performance
13reason (e.g. optimized CPU-specific byte-swapping routines).
14
15They can be included from C++, or when compiling code in strict ANSI mode.
16They can be also included before or after any Bionic C library header.
17
18Description of the directories involved in generating the parsed kernel headers:
19
20  * `external/kernel-headers/original/uapi/`
21    Contains the uapi kernel headers found in the Android kernel. Note this
22    also includes the header files that are generated by building the kernel
23    sources.
24
25  * `external/kernel-headers/original/scsi/`
26    Contains copies of the kernel scsi header files. These where never
27    made into uapi files, but some user space code expects that these
28    headers are available.
29
30  * `external/kernel-headers/modified/scsi/`
31    Contains hand-modified versions of a few files from `original/scsi/`
32    that removes the kernel specific code from these files so they can
33    be used as uapi headers. The tools to process the kernel headers will
34    warn if any scsi header files have changed and require new versions
35    to be hand-modified.
36
37  * `bionic/libc/kernel/uapi/`
38    Contains the cleaned kernel headers and mirrors the directory structure
39    in `external/kernel-headers/original/uapi/`.
40
41  * `bionic/libc/kernel/tools/`
42    Contains various Python and shell scripts used to get and re-generate
43    the headers.
44
45The tools to get/parse the headers:
46
47  * `tools/generate_uapi_headers.sh`
48    Checks out the Android kernel and generates all uapi header files.
49    copies all the changed files into external/kernel-headers.
50
51  * `tools/clean_header.py`
52    Prints the clean version of a given kernel header. With the -u option,
53    this will also update the corresponding clean header file if its
54    content has changed. You can also process more than one file with -u.
55
56  * `tools/update_all.py`
57    Automatically update all clean headers from the content of
58    `external/kernel-headers/original/`.
59
60## How To Update The Headers
61
62IMPORTANT IMPORTANT:
63
64WHEN UPDATING THE HEADERS, ALWAYS CHECK THAT THE NEW CLEAN HEADERS DO
65NOT BREAK THE KERNEL <-> USER ABI, FOR EXAMPLE BY CHANGING THE SIZE
66OF A GIVEN TYPE. THIS TASK CANNOT BE EASILY AUTOMATED AT THE MOMENT.
67
68Download the Android mainline kernel source code:
69```
70  > mkdir kernel_src
71  > cd kernel_src
72  kernel_src> git clone https://android.googlesource.com/kernel/common/ -b android-mainline
73```
74
75The Android mainline kernel source has tags that indicate the kernel
76version to which they correspond. The format of a tag is
77android-mainline-XXX, where XXX is the kernel version. For example,
78android-mainline-5.10 corresponds to linux stable kernel 5.10. To check out
79a particular tag:
80```
81  kernel_src> cd common
82  kernel_src/common> git checkout tags/android-mainline-XXX
83```
84
85It is expected that a kernel update should only be performed on a valid tag.
86For testing purposes, it is possible that you can use the top of tree
87version, but never use that as the basis for importing new kernel headers.
88
89Before running the command to import the headers, make sure that you have
90done a lunch TARGET. The script uses a variable set by the lunch command
91to determine which directory to use as the destination directory.
92
93After running lunch, run this command to import the headers into the Android
94source tree if there is a kernel source tree already checked out:
95```
96  bionic/libc/kernel/tools/generate_uapi_headers.sh --use-kernel-dir kernel_src
97```
98
99Run this command to automatically download the latest version of the headers
100and import them if there is no checked out kernel source tree:
101```
102  # For testing only, not for use in production!
103  bionic/libc/kernel/tools/generate_uapi_headers.sh --download-kernel
104```
105
106Next, run this command to copy the parsed files to bionic/libc/kernel/uapi:
107```
108  bionic/libc/kernel/tools/update_all.py
109```
110
111After this, you will need to build/test the tree to make sure that these
112changes do not introduce any errors.
113