Bionic comes with a set of 'clean' Linux kernel headers that can safely be
included by userland applications and libraries without fear of hideous
conflicts. for more information why this is needed, see the "RATIONALE"
section at the end of this document.
these clean headers are automatically generated by several scripts located
in the 'bionic/kernel/tools' directory, which process a set of original
and unmodified kernel headers in order to get rid of many annoying
declarations and constructs that usually result in compilation failure.
the 'clean headers' only contain type and macro definitions, with the
exception of a couple static inline functions used for performance
reason (e.g. optimized CPU-specific byte-swapping routines)
they can be included from C++, or when compiling code in strict ANSI mode.
they can be also included before or after any Bionic C library header.
the generation process works as follows:
* 'external/kernel-headers/original/'
contains a set of kernel headers as normally found in the 'include'
directory of a normal Linux kernel source tree. note that this should
only contain the files that are really needed by Android (use
'find_headers.py' to find these automatically).
* 'bionic/libc/kernel/common'
contains the non-arch-specific clean headers and directories
(e.g. linux, asm-generic and mtd)
* 'bionic/libc/kernel/arch-arm/'
contains the ARM-specific directory tree of clean headers.
* 'bionic/libc/kernel/arch-arm/asm'
contains the real ARM-specific headers
* 'bionic/libc/kernel/arch-x86'
'bionic/libc/kernel/arch-x86/asm'
similarly contains all headers and symlinks to be used on x86
* 'bionic/libc/kernel/tools' contains various Python and shell scripts used
to manage and re-generate the headers
the tools you can use are:
* tools/find_users.py
scans a list of source files or directories and prints which ones do
include Linux headers.
* tools/find_headers.py
scans a list of source files or directories and recursively finds all
the original kernel headers they need.
* tools/clean_header.py
prints the clean version of a given kernel header. with the -u option,
this will also update the corresponding clean header file if its
content has changed. you can also process more than one file with -u
* tools/update_all.py
automatically update all clean headers from the content of
'external/kernel-headers/original'. this is the script you're likely going to
run whenever you update the original headers.
HOW TO BUILD BIONIC AND OTHER PROGRAMS WITH THE CLEAN HEADERS:
==============================================================
add bionic/kernel/common and bionic/kernel/arch-<yourarch> to your C
include path. that should be enough. Note that Bionic will not compile properly
if you don't.
HOW TO SUPPORT ANOTHER ARCHITECTURE:
====================================
see the content of tools/defaults.py, you will need to make a few updates
here:
- add a new item to the 'kernel_archs' list of supported architectures
- add a proper definition for 'kernel_known_<arch>_statics' with
relevant definitions.
- update 'kernel_known_statics' to map "<arch>" to
'kernel_known_<arch>_statics'
then, add the new architecture-specific headers to original/asm-<arch>.
(please ensure that these are really needed, e.g. with tools/find_headers.py)
finally, run tools/update_all.py
HOW TO UPDATE THE HEADERS WHEN NEEDED:
======================================
IMPORTANT IMPORTANT:
WHEN UPDATING THE HEADERS, ALWAYS CHECK THAT THE NEW CLEAN HEADERS DO
NOT BREAK THE KERNEL <-> USER ABI, FOR EXAMPLE BY CHANGING THE SIZE
OF A GIVEN TYPE. THIS TASK CANNOT BE EASILY AUTOMATED AT THE MOMENT
copy any updated kernel header into the corresponding location under
'bionic/kernel/original'.
for any new kernel header you want to add, first run tools/find_headers.py to be
sure that it is really needed by the Android sources. then add it to
'bionic/kernel/original'
then, run tools/update_all.py to re-run the auto-cleaning
HOW THE CLEANUP PROCESS WORKS:
==============================
this section describes the action performed by the cleanup program(s) when they
process the original kernel headers into clean ones:
1. Optimize well-known macros (e.g. __KERNEL__, __KERNEL_STRICT_NAMES)
this pass gets rid of everything that is guarded by a well-known macro
definition. this means that a block like
#ifdef __KERNEL__
....
#endif
will be totally omitted from the output. the optimizer is smart enough to
handle all complex C-preprocessor conditional expression appropriately.
this means that, for example:
#if defined(__KERNEL__) || defined(FOO)
...
#endif
will be transformed into:
#ifdef FOO
...
#endif
see tools/defaults.py for the list of well-known macros used in this pass,
in case you need to update it in the future.
note that this also remove any reference to a kernel-specific configuration
macro like CONFIG_FOO from the clean headers.
2. remove variable and function declarations:
this pass scans non-directive text and only keeps things that look like a
typedef/struct/union/enum declaration. this allows to get rid of any variable
or function declaration that should only be used within the kernel anyway
(and which normally *should* be guarded in a #ifdef __KERNEL__ ... #endif
block, if the kernel writers were not so messy)
there are however a few exceptions: it is seldom useful to keep the definition
of some static inline functions performing very simple operations. a good
example is the optimized 32-bit byte-swap function found in
arch-arm/asm/byteorder.h
the list of exceptions is in tools/defaults.py in case you need to update it
in the future.
note that we do *not* remove macro definitions, including these macro that
perform a call to one of these kernel-header functions, or even define other
functions. we consider it safe since userland applications have no business
using them anyway.
3. whitespace cleanup:
the final pass remove any comments and empty lines from the final headers.
4. add a standard disclaimer:
prepended to each generated header, contains a message like
"do not edit directly - file was auto-generated by ...."
b84926b95c