am 57e55fe3: am fd152c31: Merge "Clean up some comments."

* commit '57e55fe3b32465023071a19e368d91f4804ade3b':
  Clean up some comments.
This commit is contained in:
Elliott Hughes 2013-10-01 11:14:27 -07:00 committed by Android Git Automerger
commit a08be021cc
4 changed files with 3 additions and 97 deletions

View File

@ -1,5 +1,4 @@
/* bionic/arch-arm/include/machine/kernel.h
**
/*
** Copyright 2006-2008, The Android Open Source Project
**
** Redistribution and use in source and binary forms, with or without

View File

@ -1,5 +1,4 @@
/* bionic/unistd/tcgetpgrp.c
**
/*
** Copyright 2006, The Android Open Source Project
**
** Redistribution and use in source and binary forms, with or without

View File

@ -1,5 +1,4 @@
/* bionic/unistd/tcsetpgrp.c
**
/*
** Copyright 2006, The Android Open Source Project
**
** Redistribution and use in source and binary forms, with or without

View File

@ -177,94 +177,3 @@ process the original kernel headers into clean ones:
prepended to each generated header, contains a message like
"do not edit directly - file was auto-generated by ...."
RATIONALE:
==========
OVERVIEW OF THE CURRENT KERNEL HEADER MESS:
-------------------------------------------
The original kernel headers are not easily usable from userland applications.
they contain many declarations and construct that will result in a compilation
failure or even worse, incorrect behaviour. for example:
- some headers try to define Posix types (e.g. size_t, ssize_t) that can
conflict with the corresponding definitions provided by your C library.
- some headers use constructs that cannot be compiled in ANSI C mode.
- some headers use constructs do not compile with C++ at all.
- some headers contain invalid "legacy" definitions for the benefit of old
C libraries (e.g. glibc5) but result in incorrect behaviour if used
directly.
e.g. gid_t being defined in <linux/types.h> as a 16-bit type while the
kernel uses 32-bit ids. this results in problems when getgroups() or
setgroups() are called, since they operate on gid_t arrays.
unfortunately, these headers are also the only source of some really extensive
constant and type definitions that are required by userland applications.
think any library/program that need to access ALSA, or Video4Linux, or
anything related to a specific device or Linux-specific system interface
(e.g. IOCTLS, etc...)
As a consequence, every Linux distribution provides a set of patched kernel
headers to be used by userland applications (which installs in
/usr/include/linux/, /usr/include/asm/, etc...). these are manually maintained
by distribution packagers, and generated either manually or with various
scripts. these headers are also tailored to GNU LibC and cannot be reused
easily by Bionic.
for a really long period, the kernel authors have stated that they don't want
to fix the problem, even when someone proposed a patch to start cleaning the
official headers. from their point of view this is purely a library author
problem.
fortunately, enlightnment happened, and the kernel now provides a way to
install a set of "user-friendly" headers that are generated from the official
ones by stripping the __KERNEL__ protected declarations.
unfortunately, this is not enough for Bionic because the result still contains
a few broken declarations that are difficult to route around. (see below for
a little bit of details).
we plan to be able to support these kernel-generated user-land headers in the
future, but the priority on this issue is very low.
WHAT WE DO:
-----------
so we're doomed to repeat the same effort than anyone else. the big difference
here is that we want to automate as much as possible the generation of the
clean headers to easily support additional architectures in the future,
and keep current with upstream changes in the header definitions with the
least possible hassle.
of course, this is only a race to the bottom. the kernel maintainers still
feel free to randomly break the structure of their headers (e.g. moving the
location of some files) occasionally, so we'll need to keep up with that by
updating our build script/original headers as these cases happen.
what we do is keep a set of "original" kernel headers, and process them
automatically to generate a set of "clean" headers that can be used from
userland and the C library.
note that the "original" headers can be tweaked a little to avoid some subtle
issues. for example:
- when the location of various USB-related headers changes in the kernel
source tree, we want to keep them at the same location in our generated
headers (there is no reason to break the userland API for something
like that).
- sometimes, we prefer to take certain things out of blocks guarded by a
#ifdef __KERNEL__ .. #endif. for example, on recent kernels <linux/wireless.h>
only includes <linux/if.h> when in kernel mode. we make it available to
userland as well since some code out there assumes that this is the case.
- sometimes, the header is simply incorrect (e.g. it uses a type without
including the header that defines it before-hand)