Version 0.7.17

[userspace-rcu.git] / README

diff --git a/README b/README
index ce25e3a3dabc8977f7a4dc5d4e391e5238e455fc..197d8a5573764c14892f9f7ff5bd329b824bbf74 100644 (file)
--- a/README
+++ b/README
@@ -25,11 +25,13 @@ BUILDING
 ARCHITECTURES SUPPORTED
 -----------------------
 
-Currently, x86 (i386, i486, i586, i686), x86 64-bit, PowerPC 32/64, S390, S390x,
-ARM, Alpha, ia64 and Sparcv9 32/64 are supported. Only tested on Linux so
-far, but should theoretically work on other operating systems.
+Currently, Linux x86 (i386, i486, i586, i686), x86 64-bit, PowerPC 32/64,
+S390, S390x, ARM, Alpha, ia64 and Sparcv9 32/64 are supported. Tested on
+Linux, FreeBSD 8.2/9.0, and Cygwin. Should also work on: Android, NetBSD 5,
+OpenBSD, Darwin (more testing needed before claiming support for these OS).
 
-ARM depends on running a Linux kernel 2.6.15 or better.
+Linux ARM depends on running a Linux kernel 2.6.15 or better, GCC 4.4 or
+better.
 
 The gcc compiler versions 3.3, 3.4, 4.0, 4.1, 4.2, 4.3, 4.4 and 4.5 are
 supported, with the following exceptions:
@@ -41,8 +43,18 @@ supported, with the following exceptions:
     http://www.mail-archive.com/gcc-bugs@gcc.gnu.org/msg281255.html
 - gcc 3.3 cannot match the "xchg" instruction on 32-bit x86 build.
   See: http://kerneltrap.org/node/7507
-- Alpha, ia64 and ARM architectures depend on 4.x gcc with atomic builtins
-  support.
+- Alpha, ia64 and ARM architectures depend on gcc 4.x with atomic builtins
+  support. For ARM this was introduced with gcc 4.4:
+    http://gcc.gnu.org/gcc-4.4/changes.html
+
+Clang version 3.0 (based on LLVM 3.0) is supported.
+
+Building on MacOS X (Darwin) requires a work-around for processor
+detection:
+  # 32-bit
+  ./configure --build=i686-apple-darwin11
+  # 64-bit
+  ./configure --build=x86_64-apple-darwin11
 
 For developers using the git tree:
 
@@ -59,6 +71,9 @@ If you get the tree from the repository, you will need to use the "bootstrap"
 script in the root of the tree. It calls all the GNU tools needed to prepare the
 tree configuration.
 
+Test scripts provided in the tests/ directory of the source tree depend
+on "bash" and the "seq" program.
+
 
 QUICK START GUIDE
 -----------------
@@ -171,7 +186,7 @@ Usage of urcu-call-rcu
          grace periods.  A number of additional functions are provided
          to manage the helper threads used by call_rcu(), but reasonable
          defaults are used if these additional functions are not invoked.
-         See API.txt for more details.
+         See rcu-api.txt in userspace-rcu documentation for more details.
 
 Being careful with signals
 
@@ -183,11 +198,12 @@ Being careful with signals
        signal(7). The liburcu-mb and liburcu-qsbr versions of the Userspace RCU
        library do not require any signal.
 
-       Read-side critical sections are allowed in a signal handler with
-       liburcu and liburcu-mb. Be careful, however, to disable these signals
+       Read-side critical sections are allowed in a signal handler,
+       except those setup with sigaltstack(2), with liburcu and
+       liburcu-mb. Be careful, however, to disable these signals
        between thread creation and calls to rcu_register_thread(), because a
-       signal handler nesting on an unregistered thread would not be allowed to
-       call rcu_read_lock().
+       signal handler nesting on an unregistered thread would not be
+       allowed to call rcu_read_lock().
 
        Read-side critical sections are _not_ allowed in a signal handler with
        liburcu-qsbr, unless signals are disabled explicitly around each
@@ -252,4 +268,24 @@ Interaction with fork()
        must invoke call_rcu_before_fork() before the fork() and
        call_rcu_after_fork_parent() after the fork().  The child
        process must invoke call_rcu_after_fork_child().
-       These three APIs are suitable for passing to pthread_atfork().
+       Even though these three APIs are suitable for passing to
+       pthread_atfork(), use of pthread_atfork() is *STRONGLY
+       DISCOURAGED* for programs calling the glibc memory allocator
+       (malloc(), calloc(), free(), ...) within call_rcu callbacks.
+       This is due to limitations in the way glibc memory allocator
+       handles calls to the memory allocator from concurrent threads
+       while the pthread_atfork() handlers are executing.
+       Combining e.g.:
+       * call to free() from callbacks executed within call_rcu worker
+         threads,
+       * executing call_rcu atfork handlers within the glibc pthread
+         atfork mechanism,
+       will sometimes trigger interesting process hangs. This usually
+       hangs on a memory allocator lock within glibc.
+
+Thread Local Storage (TLS)
+
+       Userspace RCU can fall back on pthread_getspecific() to emulate
+       TLS variables on systems where it is not available. This behavior
+       can be forced by specifying --disable-compiler-tls as configure
+       argument.