config: add documentation for managing kernel-headers

Change-Id: I6dc6ede4703cbe88c356656a1a6b86a4ffaafa3b
Signed-off-by: Dima Zavin <dima@android.com>

core/config.mk

@@ -151,12 +151,43 @@ include $(board_config_mk)
 TARGET_DEVICE_DIR := $(patsubst %/,%,$(dir $(board_config_mk)))
 board_config_mk :=
 
-# pull in device specific kernel headers. Files should be in
-# $(TARGET_DEVICE_DIR)/kernel-headers, e.g.
-# $(TARGET_DEVICE_DIR)/kernel-headers/linux/
-# $(TARGET_DEVICE_DIR)/kernel-headers/media/
-# $(TARGET_DEVICE_DIR)/kernel-headers/video/
-# etc.
+# The build system exposes several variables for where to find the kernel
+# headers:
+#   TARGET_DEVICE_KERNEL_HEADERS is automatically created for the current
+#       device being built. It is set as $(TARGET_DEVICE_DIR)/kernel-headers,
+#       e.g. device/samsung/tuna/kernel-headers. This directory is not
+#       explicitly set by anyone, the build system always adds this subdir.
+#
+#   TARGET_BOARD_KERNEL_HEADERS is specified by the BoardConfig.mk file
+#       to allow other directories to be included. This is useful if there's
+#       some common place where a few headers are being kept for a group
+#       of devices. For example, device/<vendor>/common/kernel-headers could
+#       contain some headers for several of <vendor>'s devices.
+#
+#   TARGET_PRODUCT_KERNEL_HEADERS is generated by the product inheritance
+#       graph. This allows architecture products to provide headers for the
+#       devices using that architecture. For example,
+#       hardware/ti/omap4xxx/omap4.mk will specify
+#       PRODUCT_VENDOR_KERNEL_HEADERS variable that specify where the omap4
+#       specific headers are, e.g. hardware/ti/omap4xxx/kernel-headers.
+#       The build system then combines all the values specified by all the
+#       PRODUCT_VENDOR_KERNEL_HEADERS directives in the product inheritance
+#       tree and then exports a TARGET_PRODUCT_KERNEL_HEADERS variable.
+#
+# The layout of subdirs in any of the kernel-headers dir should mirror the
+# layout of the kernel include/ directory. For example,
+#     device/samsung/tuna/kernel-headers/linux/,
+#     hardware/ti/omap4xxx/kernel-headers/media/,
+#     etc.
+#
+# NOTE: These directories MUST contain post-processed headers using the
+# bionic/libc/kernel/clean_header.py tool. Additionally, the original kernel
+# headers must also be checked in, but in a different subdirectory. By
+# convention, the originals should be checked into original-kernel-headers
+# directory of the same parent dir. For example,
+#     device/samsung/tuna/kernel-headers            <----- post-processed
+#     device/samsung/tuna/original-kernel-headers   <----- originals
+#
 TARGET_DEVICE_KERNEL_HEADERS := $(strip $(wildcard $(TARGET_DEVICE_DIR)/kernel-headers))
 
 define validate-kernel-headers