From: Mathieu Desnoyers Date: Tue, 1 Nov 2022 14:58:15 +0000 (-0400) Subject: Merge branch 'adah1972-improve-md' X-Git-Tag: v0.14.0~13 X-Git-Url: https://git.lttng.org/?p=userspace-rcu.git;a=commitdiff_plain;h=ed4c6ca597ff4211e1379a650403836fd59e9368;hp=8c677380d0f9241b9cd548082cf843c5111736d8 Merge branch 'adah1972-improve-md' Change-Id: I7904f3cee368428a21fdd84d07c395e232f5cfdb --- diff --git a/README.md b/README.md index 1e75589..cd24cc5 100644 --- 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 @@ -83,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 + - GCC 3.3 cannot match the "xchg" instruction on 32-bit x86 build. - See http://kerneltrap.org/node/7507 + See - 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. @@ -106,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 ) 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 @@ -163,8 +163,8 @@ There are multiple flavors of liburcu available: - `signal`, - `bp`. -The API members start with the prefix "urcu__", where - is the chosen flavor name. +The API members start with the prefix `urcu__`, where +`` is the chosen flavor name. ### Usage of `liburcu-memb` @@ -176,7 +176,7 @@ This is the preferred version of the library, in terms of grace-period detection speed, read-side speed and flexibility. Dynamically detects kernel support for `sys_membarrier()`. Falls back on `urcu-mb` scheme if support is not present, which has slower -read-side. Use the --disable-sys-membarrier-fallback configure option +read-side. Use the `--disable-sys-membarrier-fallback` configure option to disable the fall back, thus requiring `sys_membarrier()` to be available. This gives a small speedup when `sys_membarrier()` is supported by the kernel, and aborts in the library constructor if not @@ -382,11 +382,12 @@ By default the library is configured with internal debugging self-checks disabled. For always-on debugging self-checks: - ./configure --enable-rcu-debug + + ./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. @@ -413,7 +414,7 @@ theoretically yielding slightly better performance. By default the library is configured with extra debugging checks for lock-free hash table iterator traversal disabled. -Building liburcu with --enable-cds-lfht-iter-debug and rebuilding +Building liburcu with `--enable-cds-lfht-iter-debug` and rebuilding application to match the ABI change allows finding cases where the hash table iterator is re-purposed to be used on a different hash table while still being used to iterate on a hash table. @@ -445,9 +446,9 @@ 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 + - 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. + 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. @@ -459,7 +460,7 @@ Some possible work-arounds for this are: - Rebuild the application against Userspace RCU 0.11+. - - Rebuild the application with -fpic. + - Rebuild the application with `-fpic`. - Upgrade Userspace RCU to 0.13+ without installing 0.11 nor 0.12. diff --git a/doc/cds-api.md b/doc/cds-api.md index 5bc615e..3d313b7 100644 --- a/doc/cds-api.md +++ b/doc/cds-api.md @@ -33,12 +33,12 @@ Downside over `list.h`: lookup of tail in O(n). Doubly-linked list, with single pointer list head. Requires mutual exclusion on updates, allows RCU read traversals. Useful -for implementing hash tables. Downside over rculist.h: lookup of tail in O(n). +for implementing hash tables. Downside over `rculist.h`: lookup of tail in O(n). ### `urcu/wfstack.h` -Stack with wait-free push and wait-free pop_all. Both +Stack with wait-free push and wait-free pop\_all. Both blocking and non-blocking pop and traversal operations are provided. This stack does _not_ specifically rely on RCU. Various synchronization techniques can be used to deal with pop ABA. Those are detailed in the API. @@ -59,7 +59,7 @@ traversal (see API for details). ### `urcu/lfstack.h` -Stack with lock-free push, lock-free pop, wait-free pop_all, +Stack with lock-free push, lock-free pop, wait-free pop\_all, wait-free traversal. Various synchronization techniques can be used to deal with pop ABA. Those are detailed in the API. This stack does _not_ specifically rely on RCU. diff --git a/doc/solaris-build.md b/doc/solaris-build.md index a5bbdef..8baf305 100644 --- a/doc/solaris-build.md +++ b/doc/solaris-build.md @@ -20,7 +20,7 @@ And the following OpenCSW packages are required : * gsed * gmake * pkgconfig -* libglib2_dev +* libglib2\_dev * gcc4core ### Build diff --git a/doc/uatomic-api.md b/doc/uatomic-api.md index 9dd0c1c..0962399 100644 --- a/doc/uatomic-api.md +++ b/doc/uatomic-api.md @@ -27,7 +27,7 @@ API --- ```c -void uatomic_set(type *addr, type v) +void uatomic_set(type *addr, type v); ``` Atomically write `v` into `addr`. By "atomically", we mean that no @@ -36,7 +36,7 @@ effects of `uatomic_set()`. ```c -type uatomic_read(type *addr) +type uatomic_read(type *addr); ``` Atomically read `v` from `addr`. By "atomically", we mean that @@ -45,7 +45,7 @@ uatomic update. ```c -type uatomic_cmpxchg(type *addr, type old, type new) +type uatomic_cmpxchg(type *addr, type old, type new); ``` An atomic read-modify-write operation that performs this @@ -56,7 +56,7 @@ memory barrier before and after the atomic operation. ```c -type uatomic_xchg(type *addr, type new) +type uatomic_xchg(type *addr, type new); ``` An atomic read-modify-write operation that performs this sequence @@ -67,8 +67,8 @@ operation. ```c -type uatomic_add_return(type *addr, type v) -type uatomic_sub_return(type *addr, type v) +type uatomic_add_return(type *addr, type v); +type uatomic_sub_return(type *addr, type v); ``` An atomic read-modify-write operation that performs this @@ -79,8 +79,8 @@ operation. ```c -void uatomic_and(type *addr, type mask) -void uatomic_or(type *addr, type mask) +void uatomic_and(type *addr, type mask); +void uatomic_or(type *addr, type mask); ``` Atomically write the result of bitwise "and"/"or" between the @@ -95,8 +95,8 @@ atomic instructions implicitly supply the needed memory barriers. ```c -void uatomic_add(type *addr, type v) -void uatomic_sub(type *addr, type v) +void uatomic_add(type *addr, type v); +void uatomic_sub(type *addr, type v); ``` Atomically increment/decrement the content of `addr` by `v`. @@ -110,8 +110,8 @@ instructions implicitly supply the needed memory barriers. ```c -void uatomic_inc(type *addr) -void uatomic_dec(type *addr) +void uatomic_inc(type *addr); +void uatomic_dec(type *addr); ``` Atomically increment/decrement the content of `addr` by 1.