Give a bit more background on "uapi headers".
Not everyone knows what these are, and we don't otherwise explain it.
Test: N/A
Change-Id: Ic28e4fd0f8584f5e808ab60f0c2e68dd0cf30088
diff --git a/README.md b/README.md
index 32dda04..e731e5f 100644
--- a/README.md
+++ b/README.md
@@ -85,12 +85,29 @@
# files written by us and files taken from BSD.
kernel/
- # The kernel uapi header files. These are scrubbed copies of the originals
- # in external/kernel-headers/. These files must not be edited directly. The
- # generate_uapi_headers.sh script should be used to go from a kernel tree to
- # external/kernel-headers/ --- this takes care of the architecture-specific
- # details. The update_all.py script should be used to regenerate bionic's
- # scrubbed headers from external/kernel-headers/.
+ # The kernel uapi header files. The "libc" headers that developers actually
+ # use are a mixture of headers provided by the C library itself (which,
+ # for bionic, are in bionic/libc/include/) and headers provided by the
+ # kernel. This is because ISO C and POSIX will say things like "there is
+ # a constant called PROT_NONE" or "there is a type called struct stat,
+ # and it contains a field called st_size", but they won't necessarily say
+ # what _value_ that constant has, or what _order_ the fields in a type
+ # are in. Those are left to individual kernels' ABIs. In an effort to --
+ # amongst other things, see https://lwn.net/Articles/507794/ for more
+ # background -- reduce copy & paste, the Linux kernel makes all the types
+ # and constants that make up the "userspace API" (uapi) available as
+ # headers separate from their internal-use headers (which contain all kinds
+ # of extra stuff that isn't available to userspace). We import the latest
+ # released kernel's uapi headers in external/kernel-headers/, but we don't
+ # use those headers directly in bionic. The bionic/libc/kernel/ directory
+ # contains scrubbed copies of the originals from external/kernel-headers/.
+ # The generate_uapi_headers.sh script should be used to go from a kernel
+ # tree to external/kernel-headers/ --- this takes care of the
+ # architecture-specific details. The update_all.py script should then be
+ # used to regenerate bionic's copy from external/kernel-headers/.
+ # The files in bionic must not be edited directly because any local changes
+ # will be overwritten by the next update. "Updating kernel header files"
+ # below has more information on this process.
private/
# These are private header files meant for use within bionic itself.