Document known ABI issue in README.md

[userspace-rcu.git] / README.md

diff --git a/README.md b/README.md
index 601703bdf6209af39c9e27e47a9d0c9d3e2d6b13..b1a29906e002bf4fea5e8b702af69d9b343b7cd9 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.
   - 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.
 
 
 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
 
 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
 
 
 ### Initialization


@@ -387,7 +390,7 @@ For always-on debugging self-checks:
        ./configure --enable-rcu-debug
 
 For fine grained enabling of debugging self-checks, build
        ./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.
 applications with DEBUG_RCU defined when necessary.
 
 Warning: Enabling this feature result in a performance penalty.


@@ -438,6 +441,33 @@ In addition to the usual `make check` target, Userspace RCU features
   - `make bench`: long (many hours) benchmarks.
 
 
   - `make bench`: long (many hours) benchmarks.
 
 

+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
 --------
 
 Contacts
 --------