Update kernel header generation docs.

Also move the description of the cleanup data to the cleanup script.

Bug: 15433575
Change-Id: I21e2cbbfab55da483af1bbe36bbe59126b518e3c

libc/kernel/tools/clean_header.py

@@ -1,5 +1,78 @@
 #!/usr/bin/env python
+
+#------------------------------------------------------------------------------
+# Description of the header clean process
+#------------------------------------------------------------------------------
+# Here is the list of actions performed by this script to clean the original
+# kernel headers.
 #
+# 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 removes 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 us to get rid of any
+#   variables or function declarations that should only be used within the
+#   kernel anyway (and which normally *should* be guarded by an #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 removes any comments and empty lines from the final headers.
+#
+#
+# 4. Add a standard disclaimer:
+#
+#   The message:
+#
+#   /* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
+#
+#   Is prepended to each generated header.
+#------------------------------------------------------------------------------
 
 import sys, cpp, kernel, glob, os, re, getopt
 from defaults import *