Update kernel header generation docs.
Also move the description of the cleanup data to the cleanup script.
Bug: 15433575
Change-Id: I21e2cbbfab55da483af1bbe36bbe59126b518e3c
diff --git a/libc/kernel/tools/clean_header.py b/libc/kernel/tools/clean_header.py
index 238087b..6601817 100755
--- a/libc/kernel/tools/clean_header.py
+++ b/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 *