1Bionic comes with a processed set of all of the uapi Linux kernel headers that
2can safely be included by userland applications and libraries.
3
4These clean headers are automatically generated by several scripts located
5in the 'bionic/kernel/tools' directory. The tools process the original
6unmodified kernel headers in order to get rid of many annoying
7declarations and constructs that usually result in compilation failure.
8
9The 'clean headers' only contain type and macro definitions, with the
10exception of a couple static inline functions used for performance
11reason (e.g. optimized CPU-specific byte-swapping routines).
12
13They can be included from C++, or when compiling code in strict ANSI mode.
14They can be also included before or after any Bionic C library header.
15
16Description of the directories involved in generating the parsed kernel headers:
17
18  * 'external/kernel-headers/original/'
19    Contains the uapi kernel headers found in the android kernel. Note this
20    also includes the header files that are generated by building the kernel
21    sources.
22
23  * 'bionic/libc/kernel/uapi'
24    Contains the cleaned kernel headers and mirrors the directory structure
25    in 'external/kernel-headers/original/uapi/'.
26
27  * 'bionic/libc/kernel/tools'
28    Contains various Python and shell scripts used to get and re-generate
29    the headers.
30
31The tools to get/parse the headers:
32
33  * tools/generate_uapi_headers.sh
34    Checks out the android kernel and generates all uapi header files.
35    copies all the changed files into external/kernel-headers.
36
37  * tools/clean_header.py
38    Prints the clean version of a given kernel header. With the -u option,
39    this will also update the corresponding clean header file if its
40    content has changed. You can also process more than one file with -u.
41
42  * tools/update_all.py
43    Automatically update all clean headers from the content of
44    'external/kernel-headers/original'.
45
46
47HOW TO UPDATE THE HEADERS WHEN NEEDED:
48======================================
49
50IMPORTANT IMPORTANT:
51
52  WHEN UPDATING THE HEADERS, ALWAYS CHECK THAT THE NEW CLEAN HEADERS DO
53  NOT BREAK THE KERNEL <-> USER ABI, FOR EXAMPLE BY CHANGING THE SIZE
54  OF A GIVEN TYPE. THIS TASK CANNOT BE EASILY AUTOMATED AT THE MOMENT
55
56Grab the latest headers from the android kernel by running this command:
57
58  bionic/libc/kernel/tools/generate_uapi_headers.sh --download-kernel
59
60Next, run this command to copy the parsed files to bionic/libc/kernel/uapi:
61
62  bionic/libc/kernel/tools/update_all.py
63
64Finally, run this command to regenerate the syscalls list:
65
66  bionic/libc/tools/gensyscalls.py
67
68After this, you will need to build/test the tree to make sure that these
69changes do not introduce any errors.
70