Version 0.12.5

[urcu.git] / README.md

diff --git a/README.md b/README.md
index 601703bdf6209af39c9e27e47a9d0c9d3e2d6b13..6ac06312a46cf58a92cbdcbfb6cc71fd1c3ce302 100644 (file)
--- a/README.md
+++ b/README.md
@@ -86,6 +86,8 @@ supported, with the following exceptions:
   - 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.
+  - Linux aarch64 depends on GCC 5.1 or better because prior versions
+    perform unsafe access to deallocated stack.
 
 Clang version 3.0 (based on LLVM 3.0) is supported.
 
@@ -224,10 +226,11 @@ be overridden with `-DSIGRCU` by modifying `Makefile.build.inc`.
 
 The BP library flavor stands for "bulletproof". It is specifically
 designed to help tracing library to hook on applications without
-requiring to modify these applications. `urcu_bp_init()`,
-`urcu_bp_register_thread()` and `urcu_bp_unregister_thread()` all become
-nops. The state is dealt with by the library internally at the expense
-of read-side and write-side performance.
+requiring to modify these applications. `urcu_bp_init()`, and
+`urcu_bp_unregister_thread()` all become nops, whereas calling
+`urcu_bp_register_thread()` becomes optional. The state is dealt with by
+the library internally at the expense of read-side and write-side
+performance.
 
 
 ### Initialization
@@ -387,7 +390,7 @@ For always-on debugging self-checks:
        ./configure --enable-rcu-debug
 
 For fine grained enabling of debugging self-checks, build
-urserspace-rcu with DEBUG_RCU defined and compile dependent
+userspace-rcu with DEBUG_RCU defined and compile dependent
 applications with DEBUG_RCU defined when necessary.
 
 Warning: Enabling this feature result in a performance penalty.
@@ -428,14 +431,42 @@ Make targets
 ------------
 
 In addition to the usual `make check` target, Userspace RCU features
-`make regtest` and `make bench` targets:
+`make regtest`, `make short_bench` and `make long_bench` targets:
 
   - `make check`: short tests, meant to be run when rebuilding or
     porting Userspace RCU.
   - `make regtest`: long (many hours) test, meant to be run when
     modifying Userspace RCU or porting it to a new architecture or
     operating system.
-  - `make bench`: long (many hours) benchmarks.
+  - `make short_bench`: short benchmarks, 3 seconds per test.
+  - `make long_bench`: long (many hours) benchmarks, 30 seconds per test.
+
+
+Known issues
+------------
+
+There is an application vs library compatibility issue between
+applications built using Userspace RCU 0.10 headers linked against
+Userspace RCU 0.11 or 0.12 shared objects. The problem occurs as
+follows:
+
+  - An application executable is built with _LGPL_SOURCE defined, includes
+    any of the Userspace RCU 0.10 urcu flavor headers, and is built
+    without the -fpic compiler option.
+
+  - The Userspace RCU 0.10 library shared objects are updated to 0.11
+    or 0.12 without rebuilding the application.
+
+  - The application will hang, typically when RCU grace period
+    (synchronize_rcu) is invoked.
+
+Some possible work-arounds for this are:
+
+  - Rebuild the application against Userspace RCU 0.11+.
+
+  - Rebuild the application with -fpic.
+
+  - Upgrade Userspace RCU to 0.13+ without installing 0.11 nor 0.12.
 
 
 Contacts