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.
diff --git a/libc/private/bionic_preinit.h b/libc/private/bionic_preinit.h
new file mode 100644
index 0000000..b74a8b4
--- /dev/null
+++ b/libc/private/bionic_preinit.h
@@ -0,0 +1,76 @@
+/*
+ * Copyright (C) 2009 The Android Open Source Project
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *  * Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ *  * Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in
+ *    the documentation and/or other materials provided with the
+ *    distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+ * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+ * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+ * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+ * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
+ * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
+ * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+ * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ */
+
+#ifndef _BIONIC_PREINIT_H
+#define _BIONIC_PREINIT_H
+
+#include "pthread_internal.h"
+#include "bionic_tls.h"
+#include <asm/page.h>
+
+/* this function is used to perform a minimal initialization of the
+ * the C library. This must be performed before any other call to
+ * other functions, in either the dynamic linker's startup code
+ * or libc_init_static.c
+ *
+ * 'main_thread' and 'tls_area' must be persistent variables,
+ * which means they must be either global, or allocated in the
+ * main thread's stack frame and never, ever, freed before
+ * program exit.
+ *
+ * VERY IMPORTANT NOTE:
+ *
+ *   THIS IMPLEMENTATION SHOULD NOT USE GLOBAL VARIABLES.
+ *
+ *   The reason is the dynamic linker's tricky usage of C library
+ *   functions and later renaming of their symbols. See the
+ *   "C Library Usage Restriction" section in bionic/linker/README.TXT
+ *   for details.
+ */
+
+extern unsigned __get_sp(void);
+extern pid_t    gettid(void);
+
+static __inline__ void
+__libc_preinit( pthread_internal_t*  main_thread,
+                void*                tls_area[BIONIC_TLS_SLOTS] )
+{
+    pthread_attr_t  thread_attr;
+
+    /* Setup the main thread's information */
+    unsigned stacktop = (__get_sp() & ~(PAGE_SIZE - 1)) + PAGE_SIZE;
+    unsigned stacksize = 128 * 1024;
+    unsigned stackbottom = stacktop - stacksize;
+
+    pthread_attr_init(&thread_attr);
+    pthread_attr_setstack(&thread_attr, (void*)stackbottom, stacksize);
+    _init_thread(main_thread, gettid(), &thread_attr, (void*)stackbottom);
+    __init_tls(tls_area, main_thread);
+}
+
+#endif /* _BIONIC_INIT_H */
diff --git a/libc/private/pthread_internal.h b/libc/private/pthread_internal.h
new file mode 100644
index 0000000..eb4e80c
--- /dev/null
+++ b/libc/private/pthread_internal.h
@@ -0,0 +1,115 @@
+/*
+ * Copyright (C) 2008 The Android Open Source Project
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *  * Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ *  * Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in
+ *    the documentation and/or other materials provided with the
+ *    distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+ * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+ * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+ * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+ * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
+ * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
+ * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+ * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ */
+#ifndef _PTHREAD_INTERNAL_H_
+#define _PTHREAD_INTERNAL_H_
+
+#include <pthread.h>
+
+__BEGIN_DECLS
+
+typedef struct pthread_internal_t
+{
+    struct pthread_internal_t*  next;
+    struct pthread_internal_t** pref;
+    pthread_attr_t              attr;
+    pid_t                       kernel_id;
+    pthread_cond_t              join_cond;
+    int                         join_count;
+    void*                       return_value;
+    int                         intern;
+    __pthread_cleanup_t*        cleanup_stack;
+    void**                      tls;         /* thread-local storage area */
+} pthread_internal_t;
+
+extern void _init_thread(pthread_internal_t * thread, pid_t kernel_id, pthread_attr_t * attr, void * stack_base);
+
+/* needed by posix-timers.c */
+
+static __inline__ void timespec_add( struct timespec*  a, const struct timespec*  b )
+{
+    a->tv_sec  += b->tv_sec;
+    a->tv_nsec += b->tv_nsec;
+    if (a->tv_nsec >= 1000000000) {
+        a->tv_nsec -= 1000000000;
+        a->tv_sec  += 1;
+    }
+}
+
+static  __inline__ void timespec_sub( struct timespec*  a, const struct timespec*  b )
+{
+    a->tv_sec  -= b->tv_sec;
+    a->tv_nsec -= b->tv_nsec;
+    if (a->tv_nsec < 0) {
+        a->tv_nsec += 1000000000;
+        a->tv_sec  -= 1;
+    }
+}
+
+static  __inline__ void timespec_zero( struct timespec*  a )
+{
+    a->tv_sec = a->tv_nsec = 0;
+}
+
+static  __inline__ int timespec_is_zero( const struct timespec*  a )
+{
+    return (a->tv_sec == 0 && a->tv_nsec == 0);
+}
+
+static  __inline__ int timespec_cmp( const struct timespec*  a, const struct timespec*  b )
+{
+    if (a->tv_sec  < b->tv_sec)  return -1;
+    if (a->tv_sec  > b->tv_sec)  return +1;
+    if (a->tv_nsec < b->tv_nsec) return -1;
+    if (a->tv_nsec > b->tv_nsec) return +1;
+    return 0;
+}
+
+static  __inline__ int timespec_cmp0( const struct timespec*  a )
+{
+    if (a->tv_sec < 0) return -1;
+    if (a->tv_sec > 0) return +1;
+    if (a->tv_nsec < 0) return -1;
+    if (a->tv_nsec > 0) return +1;
+    return 0;
+}
+
+extern int  __pthread_cond_timedwait(pthread_cond_t*, 
+                                     pthread_mutex_t*,
+                                     const struct timespec*, 
+                                     clockid_t);
+
+extern int  __pthread_cond_timedwait_relative(pthread_cond_t*,
+                                              pthread_mutex_t*,
+                                              const struct timespec*);
+
+/* needed by fork.c */
+extern void __timer_table_start_stop(int  stop);
+
+__END_DECLS
+
+#endif /* _PTHREAD_INTERNAL_H_ */