Code drop from //branches/cupcake/...@124589
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 @@
*'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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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.
-yeah, right....
+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.
+
+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 @@
- sometimes, the header is simply incorrect (e.g. it uses a type without
including the header that defines it before-hand)
+