Potentially too many weasel words when describing atomic and memory
order issues.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
 docs/user/main.rst | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/docs/user/main.rst b/docs/user/main.rst
index 05de904225c..449acd4a324 100644
--- a/docs/user/main.rst
+++ b/docs/user/main.rst
@@ -46,9 +46,14 @@ Threading
 
 On Linux, QEMU can emulate the ``clone`` syscall and create a real
 host thread (with a separate virtual CPU) for each emulated thread.
-Note that not all targets currently emulate atomic operations
-correctly. x86 and Arm use a global lock in order to preserve their
-semantics.
+However as QEMU relies on the system libc to call ``clone`` on its
+behalf we are limit the flags accepted to those it uses. Specifically
+this means flags affecting namespaces (e.g. container runtimes) are
+not supported. QEMU guest can still be run inside containers though.
+
+While QEMU does its best to emulate atomic operations properly
+differences between the host and guest memory models can cause issues
+for software that makes assumptions about the memory model.
 
 QEMU was conceived so that ultimately it can emulate itself. Although it
 is not very useful, it is an important test to show the power of the
-- 
2.47.2

On Thu, Jul 24, 2025 at 2:02 PM Alex Bennée <alex.bennee@linaro.org> wrote:
>
> Potentially too many weasel words when describing atomic and memory
> order issues.
>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> ---
>  docs/user/main.rst | 11 ++++++++---
>  1 file changed, 8 insertions(+), 3 deletions(-)
>
> diff --git a/docs/user/main.rst b/docs/user/main.rst
> index 05de904225c..449acd4a324 100644
> --- a/docs/user/main.rst
> +++ b/docs/user/main.rst
> @@ -46,9 +46,14 @@ Threading
>
>  On Linux, QEMU can emulate the ``clone`` syscall and create a real
>  host thread (with a separate virtual CPU) for each emulated thread.
> -Note that not all targets currently emulate atomic operations
> -correctly. x86 and Arm use a global lock in order to preserve their
> -semantics.
> +However as QEMU relies on the system libc to call ``clone`` on its
> +behalf we are limit the flags accepted to those it uses. Specifically

s/we are limit/we limit

> +this means flags affecting namespaces (e.g. container runtimes) are
> +not supported. QEMU guest can still be run inside containers though.

QEMU guest? Maybe write "QEMU user-mode" instead?


> +
> +While QEMU does its best to emulate atomic operations properly
> +differences between the host and guest memory models can cause issues
> +for software that makes assumptions about the memory model.
>
>  QEMU was conceived so that ultimately it can emulate itself. Although it
>  is not very useful, it is an important test to show the power of the
> --
> 2.47.2
>
>


-- 
Manos Pitsidianakis
Emulation and Virtualization Engineer at Linaro Ltd