Merge "Update kernel header generation docs."
This commit is contained in:
Christopher Ferris
Gerrit Code Review
commit
b837767a63
@ -1,93 +1,47 @@
|
|||||||
Bionic comes with a set of 'clean' Linux kernel headers that can safely be
|
Bionic comes with a processed set of all of the uapi Linux kernel headers that
|
||||||
included by userland applications and libraries without fear of hideous
|
can safely be included by userland applications and libraries.
|
||||||
conflicts. for more information why this is needed, see the "RATIONALE"
|
|
||||||
section at the end of this document.
|
|
||||||
|
|
||||||
these clean headers are automatically generated by several scripts located
|
These clean headers are automatically generated by several scripts located
|
||||||
in the 'bionic/kernel/tools' directory, which process a set of original
|
in the 'bionic/kernel/tools' directory. The tools process the original
|
||||||
and unmodified kernel headers in order to get rid of many annoying
|
unmodified kernel headers in order to get rid of many annoying
|
||||||
declarations and constructs that usually result in compilation failure.
|
declarations and constructs that usually result in compilation failure.
|
||||||
|
|
||||||
the 'clean headers' only contain type and macro definitions, with the
|
The 'clean headers' only contain type and macro definitions, with the
|
||||||
exception of a couple static inline functions used for performance
|
exception of a couple static inline functions used for performance
|
||||||
reason (e.g. optimized CPU-specific byte-swapping routines)
|
reason (e.g. optimized CPU-specific byte-swapping routines).
|
||||||
|
|
||||||
they can be included from C++, or when compiling code in strict ANSI mode.
|
They can be included from C++, or when compiling code in strict ANSI mode.
|
||||||
they can be also included before or after any Bionic C library header.
|
They can be also included before or after any Bionic C library header.
|
||||||
|
|
||||||
the generation process works as follows:
|
Description of the directories involved in generating the parsed kernel headers:
|
||||||
|
|
||||||
* 'external/kernel-headers/original/'
|
* 'external/kernel-headers/original/'
|
||||||
contains a set of kernel headers as normally found in the 'include'
|
Contains the uapi kernel headers found in the android kernel. Note this
|
||||||
directory of a normal Linux kernel source tree. note that this should
|
also includes the header files that are generated by building the kernel
|
||||||
only contain the files that are really needed by Android (use
|
sources.
|
||||||
'find_headers.py' to find these automatically).
|
|
||||||
|
|
||||||
* 'bionic/libc/kernel/common'
|
* 'bionic/libc/kernel/uapi'
|
||||||
contains the non-arch-specific clean headers and directories
|
Contains the cleaned kernel headers and mirrors the directory structure
|
||||||
(e.g. linux, asm-generic and mtd)
|
in 'external/kernel-headers/original/uapi/'.
|
||||||
|
|
||||||
* 'bionic/libc/kernel/arch-arm/'
|
* 'bionic/libc/kernel/tools'
|
||||||
contains the ARM-specific directory tree of clean headers.
|
Contains various Python and shell scripts used to get and re-generate
|
||||||
|
the headers.
|
||||||
|
|
||||||
* 'bionic/libc/kernel/arch-arm/asm'
|
The tools to get/parse the headers:
|
||||||
contains the real ARM-specific headers
|
|
||||||
|
|
||||||
* 'bionic/libc/kernel/arch-x86'
|
* tools/generate_uapi_headers.sh
|
||||||
'bionic/libc/kernel/arch-x86/asm'
|
Checks out the android kernel and generates all uapi header files.
|
||||||
similarly contains all headers and symlinks to be used on x86
|
copies all the changed files into external/kernel-headers.
|
||||||
|
|
||||||
* 'bionic/libc/kernel/tools' contains various Python and shell scripts used
|
|
||||||
to manage and re-generate the headers
|
|
||||||
|
|
||||||
the tools you can use are:
|
|
||||||
|
|
||||||
* tools/find_users.py
|
|
||||||
scans a list of source files or directories and prints which ones do
|
|
||||||
include Linux headers.
|
|
||||||
|
|
||||||
* tools/find_headers.py
|
|
||||||
scans a list of source files or directories and recursively finds all
|
|
||||||
the original kernel headers they need.
|
|
||||||
|
|
||||||
* tools/clean_header.py
|
* tools/clean_header.py
|
||||||
prints the clean version of a given kernel header. with the -u option,
|
Prints the clean version of a given kernel header. With the -u option,
|
||||||
this will also update the corresponding clean header file if its
|
this will also update the corresponding clean header file if its
|
||||||
content has changed. you can also process more than one file with -u
|
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
|
Automatically update all clean headers from the content of
|
||||||
'external/kernel-headers/original'. this is the script you're likely going to
|
'external/kernel-headers/original'.
|
||||||
run whenever you update the original headers.
|
|
||||||
|
|
||||||
|
|
||||||
HOW TO BUILD BIONIC AND OTHER PROGRAMS WITH THE CLEAN HEADERS:
|
|
||||||
==============================================================
|
|
||||||
|
|
||||||
add bionic/kernel/common and bionic/kernel/arch-<yourarch> to your C
|
|
||||||
include path. that should be enough. Note that Bionic will not compile properly
|
|
||||||
if you don't.
|
|
||||||
|
|
||||||
|
|
||||||
HOW TO SUPPORT ANOTHER ARCHITECTURE:
|
|
||||||
====================================
|
|
||||||
|
|
||||||
see the content of tools/defaults.py, you will need to make a few updates
|
|
||||||
here:
|
|
||||||
|
|
||||||
- add a new item to the 'kernel_archs' list of supported architectures
|
|
||||||
|
|
||||||
- add a proper definition for 'kernel_known_<arch>_statics' with
|
|
||||||
relevant definitions.
|
|
||||||
|
|
||||||
- update 'kernel_known_statics' to map "<arch>" to
|
|
||||||
'kernel_known_<arch>_statics'
|
|
||||||
|
|
||||||
then, add the new architecture-specific headers to original/asm-<arch>.
|
|
||||||
(please ensure that these are really needed, e.g. with tools/find_headers.py)
|
|
||||||
|
|
||||||
finally, run tools/update_all.py
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
HOW TO UPDATE THE HEADERS WHEN NEEDED:
|
HOW TO UPDATE THE HEADERS WHEN NEEDED:
|
||||||
@ -99,81 +53,13 @@ IMPORTANT IMPORTANT:
|
|||||||
NOT BREAK THE KERNEL <-> USER ABI, FOR EXAMPLE BY CHANGING THE SIZE
|
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
|
OF A GIVEN TYPE. THIS TASK CANNOT BE EASILY AUTOMATED AT THE MOMENT
|
||||||
|
|
||||||
copy any updated kernel header into the corresponding location under
|
Grab the latest headers from the android kernel by running this command:
|
||||||
'bionic/kernel/original'.
|
|
||||||
|
|
||||||
for any new kernel header you want to add, first run tools/find_headers.py to be
|
bionic/kernel/tools/generate_uapi_headers.sh --download-kernel
|
||||||
sure that it is really needed by the Android sources. then add it to
|
|
||||||
'bionic/kernel/original'
|
|
||||||
|
|
||||||
then, run tools/update_all.py to re-run the auto-cleaning
|
Next, run this command to copy the parsed files to bionic/libc/kernel/uapi:
|
||||||
|
|
||||||
|
bionic/kernel/tools/update_all.py
|
||||||
|
|
||||||
|
After this, you will need to build/test the tree to make sure that these
|
||||||
HOW THE CLEANUP PROCESS WORKS:
|
changes do not introduce any errors.
|
||||||
==============================
|
|
||||||
|
|
||||||
this section describes the action performed by the cleanup program(s) when they
|
|
||||||
process the original kernel headers into clean ones:
|
|
||||||
|
|
||||||
1. Optimize well-known macros (e.g. __KERNEL__, __KERNEL_STRICT_NAMES)
|
|
||||||
|
|
||||||
this pass gets rid of everything that is guarded by a well-known macro
|
|
||||||
definition. this means that a block like
|
|
||||||
|
|
||||||
#ifdef __KERNEL__
|
|
||||||
....
|
|
||||||
#endif
|
|
||||||
|
|
||||||
will be totally omitted from the output. the optimizer is smart enough to
|
|
||||||
handle all complex C-preprocessor conditional expression appropriately.
|
|
||||||
this means that, for example:
|
|
||||||
|
|
||||||
#if defined(__KERNEL__) || defined(FOO)
|
|
||||||
...
|
|
||||||
#endif
|
|
||||||
|
|
||||||
will be transformed into:
|
|
||||||
|
|
||||||
#ifdef FOO
|
|
||||||
...
|
|
||||||
#endif
|
|
||||||
|
|
||||||
see tools/defaults.py for the list of well-known macros used in this pass,
|
|
||||||
in case you need to update it in the future.
|
|
||||||
|
|
||||||
note that this also remove any reference to a kernel-specific configuration
|
|
||||||
macro like CONFIG_FOO from the clean headers.
|
|
||||||
|
|
||||||
|
|
||||||
2. remove variable and function declarations:
|
|
||||||
|
|
||||||
this pass scans non-directive text and only keeps things that look like a
|
|
||||||
typedef/struct/union/enum declaration. this allows to get rid of any variable
|
|
||||||
or function declaration that should only be used within the kernel anyway
|
|
||||||
(and which normally *should* be guarded in a #ifdef __KERNEL__ ... #endif
|
|
||||||
block, if the kernel writers were not so messy)
|
|
||||||
|
|
||||||
there are however a few exceptions: it is seldom useful to keep the definition
|
|
||||||
of some static inline functions performing very simple operations. a good
|
|
||||||
example is the optimized 32-bit byte-swap function found in
|
|
||||||
arch-arm/asm/byteorder.h
|
|
||||||
|
|
||||||
the list of exceptions is in tools/defaults.py in case you need to update it
|
|
||||||
in the future.
|
|
||||||
|
|
||||||
note that we do *not* remove macro definitions, including these macro that
|
|
||||||
perform a call to one of these kernel-header functions, or even define other
|
|
||||||
functions. we consider it safe since userland applications have no business
|
|
||||||
using them anyway.
|
|
||||||
|
|
||||||
|
|
||||||
3. whitespace cleanup:
|
|
||||||
|
|
||||||
the final pass remove any comments and empty lines from the final headers.
|
|
||||||
|
|
||||||
|
|
||||||
4. add a standard disclaimer:
|
|
||||||
|
|
||||||
prepended to each generated header, contains a message like
|
|
||||||
"do not edit directly - file was auto-generated by ...."
|
|
||||||
|
|||||||
@ -1,5 +1,78 @@
|
|||||||
#!/usr/bin/env python
|
#!/usr/bin/env python
|
||||||
|
|
||||||
|
#------------------------------------------------------------------------------
|
||||||
|
# Description of the header clean process
|
||||||
|
#------------------------------------------------------------------------------
|
||||||
|
# Here is the list of actions performed by this script to clean the original
|
||||||
|
# kernel headers.
|
||||||
#
|
#
|
||||||
|
# 1. Optimize well-known macros (e.g. __KERNEL__, __KERNEL_STRICT_NAMES)
|
||||||
|
#
|
||||||
|
# This pass gets rid of everything that is guarded by a well-known macro
|
||||||
|
# definition. This means that a block like:
|
||||||
|
#
|
||||||
|
# #ifdef __KERNEL__
|
||||||
|
# ....
|
||||||
|
# #endif
|
||||||
|
#
|
||||||
|
# Will be totally omitted from the output. The optimizer is smart enough to
|
||||||
|
# handle all complex C-preprocessor conditional expression appropriately.
|
||||||
|
# This means that, for example:
|
||||||
|
#
|
||||||
|
# #if defined(__KERNEL__) || defined(FOO)
|
||||||
|
# ...
|
||||||
|
# #endif
|
||||||
|
#
|
||||||
|
# Will be transformed into:
|
||||||
|
#
|
||||||
|
# #ifdef FOO
|
||||||
|
# ...
|
||||||
|
# #endif
|
||||||
|
#
|
||||||
|
# See tools/defaults.py for the list of well-known macros used in this pass,
|
||||||
|
# in case you need to update it in the future.
|
||||||
|
#
|
||||||
|
# Note that this also removes any reference to a kernel-specific
|
||||||
|
# configuration macro like CONFIG_FOO from the clean headers.
|
||||||
|
#
|
||||||
|
#
|
||||||
|
# 2. Remove variable and function declarations:
|
||||||
|
#
|
||||||
|
# This pass scans non-directive text and only keeps things that look like a
|
||||||
|
# typedef/struct/union/enum declaration. This allows us to get rid of any
|
||||||
|
# variables or function declarations that should only be used within the
|
||||||
|
# kernel anyway (and which normally *should* be guarded by an #ifdef
|
||||||
|
# __KERNEL__ ... #endif block, if the kernel writers were not so messy).
|
||||||
|
#
|
||||||
|
# There are, however, a few exceptions: it is seldom useful to keep the
|
||||||
|
# definition of some static inline functions performing very simple
|
||||||
|
# operations. A good example is the optimized 32-bit byte-swap function
|
||||||
|
# found in:
|
||||||
|
#
|
||||||
|
# arch-arm/asm/byteorder.h
|
||||||
|
#
|
||||||
|
# The list of exceptions is in tools/defaults.py in case you need to update
|
||||||
|
# it in the future.
|
||||||
|
#
|
||||||
|
# Note that we do *not* remove macro definitions, including these macro that
|
||||||
|
# perform a call to one of these kernel-header functions, or even define other
|
||||||
|
# functions. We consider it safe since userland applications have no business
|
||||||
|
# using them anyway.
|
||||||
|
#
|
||||||
|
#
|
||||||
|
# 3. Whitespace cleanup:
|
||||||
|
#
|
||||||
|
# The final pass removes any comments and empty lines from the final headers.
|
||||||
|
#
|
||||||
|
#
|
||||||
|
# 4. Add a standard disclaimer:
|
||||||
|
#
|
||||||
|
# The message:
|
||||||
|
#
|
||||||
|
# /* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
|
||||||
|
#
|
||||||
|
# Is prepended to each generated header.
|
||||||
|
#------------------------------------------------------------------------------
|
||||||
|
|
||||||
import sys, cpp, kernel, glob, os, re, getopt
|
import sys, cpp, kernel, glob, os, re, getopt
|
||||||
from defaults import *
|
from defaults import *
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user