diff options
Diffstat (limited to 'libc/kernel/README.TXT')
| -rw-r--r-- | libc/kernel/README.TXT | 48 |
1 files changed, 28 insertions, 20 deletions
diff --git a/libc/kernel/README.TXT b/libc/kernel/README.TXT index da8c5d8..76dfa4d 100644 --- a/libc/kernel/README.TXT +++ b/libc/kernel/README.TXT @@ -30,10 +30,6 @@ the generation process works as follows: *'bionic/kernel/arch-arm/' contains the ARM-specific directory tree of clean headers. - * 'bionic/kernel/arch-arm/linux' - is really a symlink to '../common/linux'. ditto for the 'asm-generic' - and 'mtd' directories - * 'bionic/kernel/arch-arm/asm' contains the real ARM-specific headers @@ -59,9 +55,9 @@ the tools you can use are: content has changed. you can also process more than one file with -u * tools/update_all.py - automatically update <linux/_config.h> and all clean headers from - the content of 'bionic/kernel/original'. this is the script you're - likely going to run whenever you update the original headers. + automatically update all clean headers from the content of + 'bionic/kernel/original'. this is the script you're likely going to + run whenever you update the original headers. NOTE: if ANDROID_PRODUCT_OUT is defined in your environment, both 'clean_header.py' @@ -74,8 +70,9 @@ NOTE: HOW TO BUILD BIONIC AND OTHER PROGRAMS WITH THE CLEAN HEADERS: ============================================================== -simply add bionic/kernel/arch-<yourarch> to your C include path. that should -be enough. Note that Bionic will not compile properly if you don't. +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: @@ -158,12 +155,12 @@ process the original kernel headers into clean ones: 2. remove variable and function declarations: this pass scans non-directive text and only keeps things that look like a - typedef or struct declaration. this allows to get rid of any variable or - function declaration that should only be used within the kernel anyway + 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) - ther are however a few exceptions: it is seldom useful to keep the definition + 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 @@ -177,12 +174,12 @@ process the original kernel headers into clean ones: using them anyway. -4. whitespace cleanup: +3. whitespace cleanup: the final pass remove any comments and empty lines from the final headers. -5. add a standard disclaimer: +4. add a standard disclaimer: prepended to each generated header, contains a message like "do not edit directly - file was auto-generated by ...." @@ -209,8 +206,8 @@ failure or even worse, incorrect behaviour. for example: C libraries (e.g. glibc5) but result in incorrect behaviour if used directly. - e.g. gid_t being defined in <linux/types.h> as a 16-bit type while - __kernel_gid_t is 32-bit. this results in problems when getgroups() or + e.g. gid_t being defined in <linux/types.h> as a 16-bit type while the + kernel uses 32-bit ids. this results in problems when getgroups() or setgroups() are called, since they operate on gid_t arrays. unfortunately, these headers are also the only source of some really extensive @@ -226,11 +223,21 @@ by distribution packagers, and generated either manually or with various scripts. these headers are also tailored to GNU LibC and cannot be reused easily by Bionic. -the kernel authors have already stated that they don't want to fix the -problem, even when someone proposed a patch to start cleaning the official -headers. from their point of view this is purely a library author problem. +for a really long period, the kernel authors have stated that they don't want +to fix the problem, even when someone proposed a patch to start cleaning the +official headers. from their point of view this is purely a library author +problem. + +fortunately, enlightnment happened, and the kernel now provides a way to +install a set of "user-friendly" headers that are generated from the official +ones by stripping the __KERNEL__ protected declarations. -yeah, right.... +unfortunately, this is not enough for Bionic because the result still contains +a few broken declarations that are difficult to route around. (see below for +a little bit of details). + +we plan to be able to support these kernel-generated user-land headers in the +future, but the priority on this issue is very low. WHAT WE DO: @@ -266,3 +273,4 @@ issues. for example: - sometimes, the header is simply incorrect (e.g. it uses a type without including the header that defines it before-hand) + |