Fix the C library initialization to avoid calling static C++ constructors twice.

The problem was due to the fact that, in the case of dynamic executables,
the dynamic linker calls the DT_PREINIT_ARRAY, DT_INIT and DT_INIT_ARRAY
constructors when loading shared libraries and dynamic executables,
*before* calling the executable's entry point (i.e. arch-$ARCH/bionic/crtbegin_dynamic.c)
which in turns call __libc_init() in libc.so, as defined by bionic/libc_init_dynamic.c

The latter did call these constructors array again, mistakenly.

The patch also updates the documentation of many related functions.

Also adds a new section to linker/README.TXT explaining restrictions on
C library usage.

The patch has been tested on a Dream for stability issues with
proprietary blobs:

- H264 decoding works
- Camera + Video recording works
- GPS works
- Sensors work

The tests in system/extra/tests/bionic/libc/common/test_static_cpp_mutex.cpp has been
run and shows the static C++ constructor being called only once.

2 files changed, 30 insertions, 18 deletions

diff --git a/libc/arch-x86/bionic/crtbegin_dynamic.S b/libc/arch-x86/bionic/crtbegin_dynamic.S
index 3b47b18..b013641 100644
--- a/libc/arch-x86/bionic/crtbegin_dynamic.S
+++ b/libc/arch-x86/bionic/crtbegin_dynamic.S
@@ -29,25 +29,35 @@
 	.type _start, @function
 	.globl _start
 
-# this is the small startup code that is first run when
-# any executable that is statically-linked with Bionic
-# runs.
+# This is the small startup code that is called from
+# the dynamic linker to execute an executable once all
+# dependent shared libraries have been loaded and
+# initialized.
 #
-# it's purpose is to call __libc_init with appropriate
+# It's purpose is to call __libc_init as defined in
+# bionic/libc_init_dynamic.c with appropriate
 # arguments, which are:
 #
 #    - the address of the raw data block setup by the Linux
 #      kernel ELF loader
 #
-#    - address of an "onexit" function, not used on any
-#      platform supported by Bionic
+#    - address of an "onexit" function (not used on any
+#      platform supported by Bionic)
 #
 #    - address of the "main" function of the program. We
 #      can't hard-code it in the adr pseudo instruction
 #      so we use a tiny trampoline that will get relocated
 #      by the dynamic linker before this code runs
 #
-#    - address of the constructor list
+#    - address of the constructors table, i.e. a table
+#      that points to various initialization and
+#      finalization sections for the program.
+#
+# NOTE: This code is currently placed in shared libraries
+#       by the build system, but will be ignored.
+#
+#       On the other hand, the arrays defined below are
+#       required and will be parsed by the dynamic linker.
 #
 _start:	
         mov     %esp, %eax
diff --git a/libc/arch-x86/bionic/crtbegin_static.S b/libc/arch-x86/bionic/crtbegin_static.S
index eb4acee..a6c9ebf 100644
--- a/libc/arch-x86/bionic/crtbegin_static.S
+++ b/libc/arch-x86/bionic/crtbegin_static.S
@@ -29,25 +29,27 @@
 	.type _start, @function
 	.globl _start
 
-# this is the small startup code that is first run when
-# any executable that is statically-linked with Bionic
-# runs.
+# This is the small startup code that is first run when
+# any static executable runs. A static executable is one
+# that is started directly by the Linux kernel, not from
+# the dynamic linker, it thus cannot depend on any shared
+# library.
 #
-# it's purpose is to call __libc_init with appropriate
+# It's purpose is to call __libc_init as defined in
+# bionic/libc_init_static.c with appropriate
 # arguments, which are:
 #
 #    - the address of the raw data block setup by the Linux
 #      kernel ELF loader
 #
-#    - address of an "onexit" function, not used on any
-#      platform supported by Bionic
+#    - address of an "onexit" function (not used on any
+#      platform supported by Bionic).
 #
-#    - address of the "main" function of the program. We
-#      can't hard-code it in the adr pseudo instruction
-#      so we use a tiny trampoline that will get relocated
-#      by the dynamic linker before this code runs
+#    - address of the "main" function of the program.
 #
-#    - address of the constructor list
+#    - address of the constructors table, i.e. a table
+#      that points to various initialization and
+#      finalization sections for the program.
 #
 _start:	
         mov     %esp, %eax