update documentation

INSTALL

@@ -5,35 +5,68 @@ musl may be installed either as an alternate C library alongside the
 existing libraries on a system, or as the primary C library for a new
 or existing musl-based system.
 
-First, some prerequisites:
+This document covers the prerequisites and procedures for compiling
+and installation.
 
-- A C99 compiler with gcc-style inline assembly support, support for
-  weak aliases, and support for building stand-alone assembly files.
-  gcc 3.x and 4.x are known to work. pcc and LLVM/clang may work but
-  are untested, and pcc is known to have some bugs.
 
-- GNU make
 
-- Linux, preferably 2.6.22 or later. Older versions are known to have
-  serious bugs that will make some interfaces non-conformant, but if
-  you don't need threads or POSIX 2008 features, even 2.4 is probably
-  okay.
+==== Build Prerequisites ====
 
-- A supported CPU architecture (currently i386, x86_64, arm, or mips).
+The only build-time prerequisites for musl are GNU Make and a
+freestanding C99 compiler toolchain targeting the desired instruction
+set architecture and ABI, with support for gcc-style inline assembly,
+weak aliases, and stand-alone assembly source files.
 
-- If you want to use dynamic linking, it's recommended that you have
-  permissions to write to /lib and /etc. Otherwise your binaries will
-  have to use a nonstandard dynamic linker path.
+The system used to build musl does not need to be Linux-based, nor do
+the Linux kernel headers need to be available.
 
+If support for dynamic linking is desired, some further requriements
+are placed on the compiler and linker. In particular, the linker must
+support the -Bsymbolic-functions option.
 
+At present, GCC 4.6 or later is the recommended compiler for building
+musl. Any earlier version of GCC with full C99 support should also
+work, but may be subject to minor floating point conformance issues on
+i386 targets. Sufficiently recent versions of PCC and LLVM/clang are
+also believed to work, but have not been tested as heavily; prior to
+Fall 2012, both had known bugs that affected musl.
 
-== Option 1: Installing musl as an alternate C library ==
+
+
+=== Supported Targets ====
+
+musl can be built for the following CPU instruction set architecture
+and ABI combinations:
+
+- i386 (requires 387 math and 486 cmpxchg instructions)
+- x86_64
+- arm (EABI)
+- mips (o32 ABI, requires fpu or float emulation in kernel)
+- microblaze (requires a cpu with lwx/swx instructions)
+
+For architectures with both little- and big-endian options, both are
+supported unless otherwise noted.
+
+In general, musl assumes the availability of all Linux syscall
+interfaces available in Linux 2.6.0. Some programs that do not use
+threads or other modern functionality may be able to run on 2.4.x
+kernels. Other kernels (such as BSD) that provide a Linux-compatible
+syscall ABI should also work but have not been extensively tested.
+
+
+
+==== Option 1: Installing musl as an alternate C library ====
 
 In this setup, musl and any third-party libraries linked to musl will
 reside under an alternate prefix such as /usr/local/musl or /opt/musl.
 A wrapper script for gcc, called musl-gcc, can be used in place of gcc
 to compile and link programs and libraries against musl.
 
+(Note: There are not yet corresponding wrapper scripts for other
+compilers, so if you wish to compile and link against musl using
+another compiler, you are responsible for providing the correct
+options to override the default include and library search paths.)
+
 To install musl as an alternate libc, follow these steps:
 
 1. Configure musl's build with a command similar to:
@@ -92,7 +125,7 @@ source/build tree.
 
 
 
-== Option 2: Installing musl as the primary C library ==
+==== Option 2: Installing musl as the primary C library ====
 
 In this setup, you will need an existing compiler/toolchain. It
 shouldnt matter whether it was configured for glibc, uClibc, musl, or

README

@@ -8,7 +8,7 @@ musl is an alternative to glibc, eglibc, uClibc, dietlibc, and klibc.
 For reasons why one might prefer musl, please see the FAQ and libc
 comparison chart on the project website,
 
-    http://www.etalabs.net/musl/
+    http://www.musl-libc.org/
 
 For installation instructions, see the INSTALL file.
 
@@ -19,22 +19,23 @@ license status of code included in musl (standard MIT license).
 
 Greetings!
 
-With the 0.9.0 release, musl has reached a milestone in completeness
-and compatibility. All interfaces in ISO C99 and POSIX 2008 base exist
-in musl, along with a number of non-standardized interfaces based on
-GNU and BSD libraries and syscall interfaces for Linux-kernel-specific
-functions. Some interfaces lack obscure or rarely-used functionality
-needed for strict conformance, but the vast majority of interfaces go
-above and beyond the requirements for conformance, often promising
-success where other implementations can fail under resource exhaustion
-or other corner-case conditions.
-
-At this point, hundreds of packages have been successfully built
-against musl - either out-of-the-box or with minor patches to address
-portability errors - ranging from low-level system utilities and
-network daemons to major gui applications. Testing has been conducted
-using three separate test frameworks and numerous additional
-standalone test cases to verify the correctness of the implementation.
+The 0.9.x release series for musl features interface coverage for all
+interfaces defined in ISO C99 and POSIX 2008 base, along with a number
+of non-standardized interfaces for compatibility with Linux, BSD, and
+glibc functionality. As the release series progresses, we are
+gradually adding support for incomplete functionality in existing
+interfaces, additional functions that are deemed to be important due
+to their use in real-world software, and support for new library and
+language features in C11 such as thread-local storage, which is now
+supported on all targets. In addition, support for additional target
+cpu architectures is being added.
+
+The number of packages build successfully against musl - either
+out-of-the-box or with minor patches to address portability errors -
+has exceeded 5000 and is steadily growing. In addition to application
+compatibility testing, unit testing has been conducted using three
+separate test frameworks and numerous additional standalone test cases
+to verify the correctness of the implementation.
 
 Included with this package is a gcc wrapper script (musl-gcc) which
 allows you to build musl-linked programs using an existing gcc 3.x or