From adcb515bfcc5b32b2c627216b2c49e10125729c4 Mon Sep 17 00:00:00 2001 From: Elliott Hughes Date: Thu, 11 Apr 2019 13:38:25 -0700 Subject: [PATCH] Move kernel README files to Markdown. Test: N/A Change-Id: If987d8a24baf87adba20914896d29c94fc01cbfd --- libc/kernel/{README.TXT => README.md} | 39 ++++++++++--------- libc/kernel/android/{README.TXT => README.md} | 4 +- 2 files changed, 23 insertions(+), 20 deletions(-) rename libc/kernel/{README.TXT => README.md} (86%) rename libc/kernel/android/{README.TXT => README.md} (81%) diff --git a/libc/kernel/README.TXT b/libc/kernel/README.md similarity index 86% rename from libc/kernel/README.TXT rename to libc/kernel/README.md index 313dc0d0b..d31a6588e 100644 --- a/libc/kernel/README.TXT +++ b/libc/kernel/README.md @@ -1,11 +1,10 @@ -Bionic Kernel Header Files -========================== +# Bionic Kernel Header Files Bionic comes with a processed set of all of the uapi Linux kernel headers that can safely be included by userland applications and libraries. These clean headers are automatically generated by several scripts located -in the 'bionic/kernel/tools' directory. The tools process the original +in the `tools/` directory. The tools process the original unmodified kernel headers in order to get rid of many annoying declarations and constructs that usually result in compilation failure. @@ -18,36 +17,35 @@ They can be also included before or after any Bionic C library header. Description of the directories involved in generating the parsed kernel headers: - * 'external/kernel-headers/original/' + * `external/kernel-headers/original/` 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. - * 'bionic/libc/kernel/uapi' + * `bionic/libc/kernel/uapi/` Contains the cleaned kernel headers and mirrors the directory structure - in 'external/kernel-headers/original/uapi/'. + in `external/kernel-headers/original/uapi/`. - * 'bionic/libc/kernel/tools' + * `bionic/libc/kernel/tools/` Contains various Python and shell scripts used to get and re-generate the headers. The tools to get/parse the headers: - * tools/generate_uapi_headers.sh + * `tools/generate_uapi_headers.sh` Checks out the android kernel and generates all uapi header files. copies all the changed files into external/kernel-headers. - * tools/clean_header.py + * `tools/clean_header.py` Prints the clean version of a given kernel header. With the -u option, this will also update the corresponding clean header file if its content has changed. You can also process more than one file with -u. - * tools/update_all.py + * `tools/update_all.py` Automatically update all clean headers from the content of - 'external/kernel-headers/original'. + `external/kernel-headers/original/`. -How To Update The Headers -========================= +## How To Update The Headers IMPORTANT IMPORTANT: @@ -56,15 +54,17 @@ NOT BREAK THE KERNEL <-> USER ABI, FOR EXAMPLE BY CHANGING THE SIZE OF A GIVEN TYPE. THIS TASK CANNOT BE EASILY AUTOMATED AT THE MOMENT. Download the Linux kernel source code: - +``` > mkdir kernel_src > cd kernel_src kernel_src> git clone git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git +``` Then checkout the stable tag for the new kernel headers to import: - +``` kernel_src> cd linux-stable kernel_src/linux-stable> git checkout tags/vXXX +``` 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 @@ -72,16 +72,19 @@ to determine which directory to use as the destination directory. After running lunch, run this command to import the headers into the android source tree: - +``` bionic/libc/kernel/tools/generate_uapi_headers.sh --use-kernel-dir kernel_src +``` Next, run this command to copy the parsed files to bionic/libc/kernel/uapi: - +``` bionic/libc/kernel/tools/update_all.py +``` Finally, run this command to regenerate the syscalls list: - +``` bionic/libc/tools/gensyscalls.py +``` After this, you will need to build/test the tree to make sure that these changes do not introduce any errors. diff --git a/libc/kernel/android/README.TXT b/libc/kernel/android/README.md similarity index 81% rename from libc/kernel/android/README.TXT rename to libc/kernel/android/README.md index bc2efdee5..88062c0ec 100644 --- a/libc/kernel/android/README.TXT +++ b/libc/kernel/android/README.md @@ -2,7 +2,7 @@ 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. -None of these files will get updated automatically, and are frozen at their +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. @@ -12,6 +12,6 @@ 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. +These files are actually maintained in `external/kernel-headers/modified/scsi/`. Any modification should first be made there then copied into the scsi directory.