README.TXT
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