Update/clarify the kernel header docs slightly.
I'm not a huge fan of the libc/kernel/android/README.md file, and fear that no-one will ever see it, but exactly _where_ that information should go remains unclear, so I've left it for now.
Change-Id: I901fe6685904712d277ff32e4345ef27f7b8045d
diff --git a/README.md b/README.md
index 01598d3..3e57178 100644
--- a/README.md
+++ b/README.md
@@ -77,33 +77,13 @@
# See 'Adding system calls' later.
include/
- # The public header files on everyone's include path. These are a mixture of
- # files written by us and files taken from BSD.
-
kernel/
- # 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.
+ android/
+ uapi/
+ # The public header files on everyone's include path.
+ # These are a mixture of files written by us, files taken from BSD,
+ # and Linux kernel header files.
+ # See "Kernel header files" below for more on the last of those.
private/
# These are private header files meant for use within bionic itself.
@@ -371,18 +351,36 @@
When we switch to musl for the host libc, this should be less of a problem.
+## Kernel 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 reduce copy & paste (amongst other things;
+see https://lwn.net/Articles/507794/ for more background),
+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).
+
## Updating kernel header files
-As mentioned above, this is currently a two-step process:
-
- 1. Use generate_uapi_headers.sh to go from a Linux source tree to appropriate
- contents for external/kernel-headers/.
- 2. Run update_all.py to scrub those headers and import them into bionic.
-
Note that if you're actually just trying to expose device-specific headers to
-build your device drivers, you shouldn't modify bionic. Instead use
-`TARGET_DEVICE_KERNEL_HEADERS` and friends described in [config.mk](https://android.googlesource.com/platform/build/+/main/core/config.mk#186).
+build your device drivers, you shouldn't modify bionic/ or
+external/kernel-headers/.
+Instead use `TARGET_DEVICE_KERNEL_HEADERS` and friends described in
+[config.mk](https://android.googlesource.com/platform/build/+/main/core/config.mk#186).
+Otherwise, see
+[libc/kernel/README.md](https://android.googlesource.com/platform/bionic/+/main/libc/kernel/README.md)
+for details and instructions about how to get changes to
+external/kernel-headers/ mirrored in bionic/.
## Updating tzdata
diff --git a/libc/kernel/android/README.md b/libc/kernel/android/README.md
index 88062c0..a9da9a4 100644
--- a/libc/kernel/android/README.md
+++ b/libc/kernel/android/README.md
@@ -1,17 +1,11 @@
-The files under the uapi directory are android kernel uapi header files that
-exist in android kernels, but have not been upstreamed into the regular
-kernel.
+libc/kernel/android/uapi/linux/ contains header files that the kernel uapi
+headers depend upon but do not provide.
-None of these files are updated automatically, and are frozen at their
-current value.
-
-The files under the scsi directory are frozen copies of kernel scsi headers.
+libc/kernel/android/scsi/ contains frozen copies of kernel scsi headers.
Linux's scsi headers are a mix of userspace-facing and kernel-facing
declarations that can't be directly used by userspace. The glibc
maintainers manually copy-and-pasted these definitions into their own
scsi headers and haven't substantially updated them in 15 years. The
musl libc project has a similar set of definitions in its scsi headers.
-
-These files are actually maintained in `external/kernel-headers/modified/scsi/`.
-Any modification should first be made there then copied into the scsi
-directory.
+Our versions of these files are actually maintained in
+`external/kernel-headers/modified/scsi/`.
