Wrap URLs in angle brackets

[userspace-rcu.git] / README.md

diff --git a/README.md b/README.md
index d39de22bdc6efcd9d343355df37772d02b20f4c8..38a76c29740a8286eabc92edb29b5eadc520b0a4 100644 (file)
--- a/README.md
+++ b/README.md
@@ -38,7 +38,7 @@ Architectures supported
 Currently, the following architectures are supported:
 
   - x86 (i386, i486, i586, i686)
-  - amd64 / x86_64
+  - amd64 / x86\_64
   - PowerPC 32/64
   - S390, S390x
   - ARM 32/64
@@ -72,6 +72,9 @@ Should also work on:
 Linux ARM depends on running a Linux kernel 2.6.15 or better, GCC 4.4 or
 better.
 
+The C compiler used needs to support at least C99. The C++ compiler used
+needs to support at least C++11.
+
 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:
 
@@ -80,12 +83,12 @@ supported, with the following exceptions:
     therefore not compatible with `liburcu` on x86 32-bit
     (i386, i486, i586, i686).
     The problem has been reported to the GCC community:
-    http://www.mail-archive.com/gcc-bugs@gcc.gnu.org/msg281255.html
+    <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
+    See <http://kerneltrap.org/node/7507>
   - 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.
+    <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.
 
@@ -103,7 +106,7 @@ compile the git repository tree :
   - GNU autotools (automake >=1.12, autoconf >=2.69)
     (make sure your system wide `automake` points to a recent version!)
   - GNU Libtool >=2.2
-    (for more information, go to http://www.gnu.org/software/autoconf/)
+    (for more information, go to <http://www.gnu.org/software/autoconf/>)
 
 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
@@ -160,8 +163,8 @@ There are multiple flavors of liburcu available:
   - `signal`,
   - `bp`.
 
-The API members start with the prefix "urcu_<flavor>_", where
-<flavor> is the chosen flavor name.
+The API members start with the prefix `urcu_<flavor>_`, where
+`<flavor>` is the chosen flavor name.
 
 
 ### Usage of `liburcu-memb`
@@ -382,8 +385,8 @@ For always-on debugging self-checks:
        ./configure --enable-rcu-debug
 
 For fine grained enabling of debugging self-checks, build
-userspace-rcu with DEBUG_RCU defined and compile dependent
-applications with DEBUG_RCU defined when necessary.
+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.
 
@@ -423,14 +426,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