Fix Markdown issues

[urcu.git] / README.md

diff --git a/README.md b/README.md
index 8dfd5e96a62ab2cc048e54e26a111bcc7b357894..f75af605db88de89e8ac6bd3d26358ff1cf5766c 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
@@ -58,7 +58,7 @@ Tested on:
   - FreeBSD 8.2/8.3/9.0/9.1/10.0 i386/amd64
   - Solaris 10/11 i386
   - Cygwin i386/amd64
-  - MacOSX amd64
+  - MacOS amd64/arm64
 
 Should also work on:
 
@@ -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:
 
@@ -91,16 +94,8 @@ supported, with the following exceptions:
 
 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
+Glibc >= 2.4 should work but the older version we test against is
+currently 2.17.
 
 For developers using the Git tree:
 
@@ -108,7 +103,7 @@ This source tree is based on the autotools suite from GNU to simplify
 portability. Here are some things you should have on your system in order to
 compile the git repository tree :
 
-  - GNU autotools (automake >=1.10, autoconf >=2.50, autoheader >=2.50)
+  - 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/)
@@ -168,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`
@@ -390,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.
 
@@ -431,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