uatomic/x86: Remove redundant memory barriers

[urcu.git] / README.md

diff --git a/README.md b/README.md
index cd24cc53ba0f3887d08c467be033f2e6af6f661d..d868ac491c50152662c25c4ffe48723f32f15cf7 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,3 +1,9 @@
+<!--
+SPDX-FileCopyrightText: 2023 EfficiOS Inc.
+
+SPDX-License-Identifier: CC-BY-4.0
+-->
+
 Userspace RCU Implementation
 ============================
 
@@ -51,12 +57,12 @@ Currently, the following architectures are supported:
   - hppa/PA-RISC
   - m68k
   - RISC-V
+  - LoongArch
 
 Tested on:
 
   - Linux all architectures
-  - FreeBSD 8.2/8.3/9.0/9.1/10.0 i386/amd64
-  - Solaris 10/11 i386
+  - FreeBSD 13 i386/amd64
   - Cygwin i386/amd64
   - MacOS amd64/arm64
 
@@ -65,18 +71,19 @@ Should also work on:
   - Android
   - NetBSD 5
   - OpenBSD
-  - Darwin
+  - Solaris
 
 (more testing needed before claiming support for these OS).
 
-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.
+Toolchain support
+-----------------
 
-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:
+The C compiler used needs to support at least C99. The C++ compiler used needs
+to support at least C++11. The oldest GCC version officialy supported and
+tested is 4.8.
+
+Older GCC versions might still work with the following exceptions:
 
   - GCC 3.3 and 3.4 have a bug that prevents them from generating volatile
     accesses to offsets in a TLS structure on 32-bit x86. These versions are
@@ -97,6 +104,10 @@ Clang version 3.0 (based on LLVM 3.0) is supported.
 Glibc >= 2.4 should work but the older version we test against is
 currently 2.17.
 
+
+Build system
+------------
+
 For developers using the Git tree:
 
 This source tree is based on the autotools suite from GNU to simplify
@@ -160,7 +171,6 @@ There are multiple flavors of liburcu available:
   - `memb`,
   - `qsbr`,
   - `mb`,
-  - `signal`,
   - `bp`.
 
 The API members start with the prefix `urcu_<flavor>_`, where
@@ -205,15 +215,6 @@ and reader sides. This results in faster grace-period detection, but
 results in slower reads.
 
 
-### Usage of `liburcu-signal`
-
-  1. `#include <urcu/urcu-signal.h>`
-  2. Link the application with `-lurcu-signal`
-
-Version of the library that requires a signal, typically `SIGUSR1`. Can
-be overridden with `-DSIGRCU` by modifying `Makefile.build.inc`.
-
-
 ### Usage of `liburcu-bp`
 
   1. `#include <urcu/urcu-bp.h>`
@@ -251,11 +252,19 @@ protected pointer.
 After, `urcu_<flavor>_synchronize_rcu()` must be called. When it
 returns, the old values are not in usage anymore.
 
+As an alternative to `urcu_<flavor>_synchronize_rcu()`,
+it is also possible to use the urcu polling mechanism to wait for a
+grace period to elapse. This can be done by using
+`urcu_<flavor>_start_poll_synchronize_rcu()`
+to start the grace period polling, and then invoke
+`urcu_<flavor>_poll_state_synchronize_rcu()`, which returns true if
+the grace period has completed, false otherwise.
+
 
 ### Usage of `liburcu-defer`
 
   - Follow instructions for either `liburcu-memb`, `liburcu-qsbr`,
-    `liburcu-mb`, `liburcu-signal`, or `liburcu-bp` above.
+    `liburcu-mb`, or `liburcu-bp` above.
     The `liburcu-defer` functionality is pulled into each of
     those library modules.
   - Provides `urcu_<flavor>_defer_rcu()` primitive to enqueue delayed
@@ -274,7 +283,7 @@ Its API is currently experimental. It may change in future library releases.
 ### Usage of `urcu-call-rcu`
 
   - Follow instructions for either `liburcu-memb`, `liburcu-qsbr`,
-    `liburcu-mb`, `liburcu-signal`, or `liburcu-bp` above.
+    `liburcu-mb`, or `liburcu-bp` above.
     The `urcu-call-rcu` functionality is pulled into each of
     those library modules.
   - Provides the `urcu_<flavor>_call_rcu()` primitive to enqueue delayed
@@ -292,13 +301,6 @@ Its API is currently experimental. It may change in future library releases.
 
 ### Being careful with signals
 
-The `liburcu-signal` library uses signals internally. The signal handler is
-registered with the `SA_RESTART` flag. However, these signals may cause
-some non-restartable system calls to fail with `errno = EINTR`. Care
-should be taken to restart system calls manually if they fail with this
-error. A list of non-restartable system calls may be found in
-`signal(7)`.
-
 Read-side critical sections are allowed in a signal handler,
 except those setup with `sigaltstack(2)`, with `liburcu-memb` and
 `liburcu-mb`. Be careful, however, to disable these signals
@@ -422,6 +424,10 @@ still being used to iterate on a hash table.
 This option alters the rculfhash ABI. Make sure to compile both library
 and application with matching configuration.
 
+### Usage of `--enable-compiler-atomic-builtins`
+
+Building liburcu with `--enable-compiler-atomic-builtins` implements the uatomic
+API with the compiler atomic builtins if supported.
 
 Make targets
 ------------
@@ -470,3 +476,18 @@ Contacts
 
 You can contact the maintainers on the following mailing list:
 `lttng-dev@lists.lttng.org`.
+
+IRC channel: [#lttng](irc://irc.oftc.net/lttng) on the OFTC network
+
+Bug tracker: [Userspace RCU bug tracker](https://bugs.lttng.org/projects/urcu)
+
+Code review: [_userspace-rcu_ project](https://review.lttng.org/q/project:userspace-rcu) on LTTng Review
+
+Continuous integration: [Userspace RCU](https://ci.lttng.org/view/Liburcu/) on LTTng's CI
+
+GitHub mirror: [urcu/userspace-rcu](https://github.com/urcu/userspace-rcu)
+
+Patches are principally submitted and reviewed on [LTTng Review](https://review.lttng.org),
+but may also be submitted to the [mailing list](mailto:lttng-dev@lists.lttng.org)
+with the subject prefix `PATCH urcu` or by pull request on the
+[GitHub mirror](https://github.com/urcu/userspace-rcu).