config: add documentation for managing kernel-headers
Change-Id: I6dc6ede4703cbe88c356656a1a6b86a4ffaafa3b
Signed-off-by: Dima Zavin <dima@android.com>
diff --git a/core/config.mk b/core/config.mk
index 8a5c96e..dabdfde 100644
--- a/core/config.mk
+++ b/core/config.mk
@@ -151,12 +151,43 @@
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