Update kernel update documentation.
Parts of the document have gone out of date, so update it.
Test: NA
Change-Id: Ia4bc534ca1cc9a538d5995126c541c2cd7029c57
diff --git a/libc/kernel/README.md b/libc/kernel/README.md
index 6db08d6..5f1c81d 100644
--- a/libc/kernel/README.md
+++ b/libc/kernel/README.md
@@ -17,11 +17,23 @@
Description of the directories involved in generating the parsed kernel headers:
- * `external/kernel-headers/original/`
- Contains the uapi kernel headers found in the android kernel. Note this
+ * `external/kernel-headers/original/uapi/`
+ Contains the uapi kernel headers found in the Android kernel. Note this
also includes the header files that are generated by building the kernel
sources.
+ * `external/kernel-headers/original/scsi/`
+ Contains copies of the kernel scsi header files. These where never
+ made into uapi files, but some user space code expects that these
+ headers are available.
+
+ * `external/kernel-headers/modified/scsi/`
+ Contains hand-modified versions of a few files from `original/scsi/`
+ that removes the kernel specific code from these files so they can
+ be used as uapi headers. The tools to process the kernel headers will
+ warn if any scsi header files have changed and require new versions
+ to be hand-modified.
+
* `bionic/libc/kernel/uapi/`
Contains the cleaned kernel headers and mirrors the directory structure
in `external/kernel-headers/original/uapi/`.
@@ -33,7 +45,7 @@
The tools to get/parse the headers:
* `tools/generate_uapi_headers.sh`
- Checks out the android kernel and generates all uapi header files.
+ Checks out the Android kernel and generates all uapi header files.
copies all the changed files into external/kernel-headers.
* `tools/clean_header.py`
@@ -60,19 +72,25 @@
kernel_src> git clone https://android.googlesource.com/kernel/common/ -b android-mainline
```
-For now, there are no tags, take the top of tree version. To find the
-version of the linux stable kernel headers the mainline source code is
-tracking, read the uapi/linux/version.h that is generated.
+The Android mainline kernel source has tags that indicate the kernel
+version to which they correspond. The format of a tag is
+android-mainline-XXX, where XXX is the kernel version. For example,
+android-mainline-5.10 corresponds to linux stable kernel 5.10. To check out
+a particular tag:
```
- kernel_src> cd linux-stable
- kernel_src/linux-stable> git checkout tags/vXXX
+ kernel_src> cd common
+ kernel_src/common> git checkout tags/android-mainline-XXX
```
+It is expected that a kernel update should only be performed on a valid tag.
+For testing purposes, it is possible that you can use the top of tree
+version, but never use that as the basis for importing new kernel headers.
+
Before running the command to import the headers, make sure that you have
done a lunch TARGET. The script uses a variable set by the lunch command
to determine which directory to use as the destination directory.
-After running lunch, run this command to import the headers into the android
+After running lunch, run this command to import the headers into the Android
source tree if there is a kernel source tree already checked out:
```
bionic/libc/kernel/tools/generate_uapi_headers.sh --use-kernel-dir kernel_src