This was a slightly duff format for rst, make it use proper headings.

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

diff --git a/docs/user/main.rst b/docs/user/main.rst
index 9a1c60448c5..b8ff203c212 100644
--- a/docs/user/main.rst
+++ b/docs/user/main.rst
@@ -17,28 +17,34 @@ Features
 
 QEMU user space emulation has the following notable features:
 
-**System call translation:**
-   QEMU includes a generic system call translator. This means that the
-   parameters of the system calls can be converted to fix endianness and
-   32/64-bit mismatches between hosts and targets. IOCTLs can be
-   converted too.
-
-**POSIX signal handling:**
-   QEMU can redirect to the running program all signals coming from the
-   host (such as ``SIGALRM``), as well as synthesize signals from
-   virtual CPU exceptions (for example ``SIGFPE`` when the program
-   executes a division by zero).
-
-   QEMU relies on the host kernel to emulate most signal system calls,
-   for example to emulate the signal mask. On Linux, QEMU supports both
-   normal and real-time signals.
-
-**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.
+System call translation
+~~~~~~~~~~~~~~~~~~~~~~~
+
+QEMU includes a generic system call translator. This means that the
+parameters of the system calls can be converted to fix endianness
+and 32/64-bit mismatches between hosts and targets. IOCTLs can be
+converted too.
+
+POSIX signal handling
+~~~~~~~~~~~~~~~~~~~~~
+
+QEMU can redirect to the running program all signals coming from the
+host (such as ``SIGALRM``), as well as synthesize signals from
+virtual CPU exceptions (for example ``SIGFPE`` when the program
+executes a division by zero).
+
+QEMU relies on the host kernel to emulate most signal system calls,
+for example to emulate the signal mask. On Linux, QEMU supports both
+normal and real-time signals.
+
+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.
 
 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 7/24/25 00:59, Alex Bennée wrote:
> +Threading
> +~~~~~~~~~
> +
> +On Linux, QEMU can emulate the ``clone`` syscall and create a real
> +host thread (with a separate virtual CPU) for each emulated thread.


We might say something here about limited emulation of clone.
See CLONE_INVALID_THREAD_FLAGS.

> +Note that not all targets currently emulate atomic operations
> +correctly. x86 and Arm use a global lock in order to preserve their
> +semantics.

Wow, that's out of date.


r~

On 7/24/25 15:13, Richard Henderson wrote:
> On 7/24/25 00:59, Alex Bennée wrote:
>> +Threading
>> +~~~~~~~~~
>> +
>> +On Linux, QEMU can emulate the ``clone`` syscall and create a real
>> +host thread (with a separate virtual CPU) for each emulated thread.
> 
> 
> We might say something here about limited emulation of clone.
> See CLONE_INVALID_THREAD_FLAGS.
> 
>> +Note that not all targets currently emulate atomic operations
>> +correctly. x86 and Arm use a global lock in order to preserve their
>> +semantics.
> 
> Wow, that's out of date.

I should have waited until patch 5.  :-)

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>

r~

On Thu, Jul 24, 2025 at 2:02 PM Alex Bennée <alex.bennee@linaro.org> wrote:
>
> This was a slightly duff format for rst, make it use proper headings.
>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> ---
>  docs/user/main.rst | 50 ++++++++++++++++++++++++++--------------------
>  1 file changed, 28 insertions(+), 22 deletions(-)
>
> diff --git a/docs/user/main.rst b/docs/user/main.rst
> index 9a1c60448c5..b8ff203c212 100644
> --- a/docs/user/main.rst
> +++ b/docs/user/main.rst
> @@ -17,28 +17,34 @@ Features
>
>  QEMU user space emulation has the following notable features:
>
> -**System call translation:**
> -   QEMU includes a generic system call translator. This means that the
> -   parameters of the system calls can be converted to fix endianness and
> -   32/64-bit mismatches between hosts and targets. IOCTLs can be
> -   converted too.
> -
> -**POSIX signal handling:**
> -   QEMU can redirect to the running program all signals coming from the
> -   host (such as ``SIGALRM``), as well as synthesize signals from
> -   virtual CPU exceptions (for example ``SIGFPE`` when the program
> -   executes a division by zero).
> -
> -   QEMU relies on the host kernel to emulate most signal system calls,
> -   for example to emulate the signal mask. On Linux, QEMU supports both
> -   normal and real-time signals.
> -
> -**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.
> +System call translation
> +~~~~~~~~~~~~~~~~~~~~~~~
> +
> +QEMU includes a generic system call translator. This means that the
> +parameters of the system calls can be converted to fix endianness
> +and 32/64-bit mismatches between hosts and targets. IOCTLs can be
> +converted too.
> +
> +POSIX signal handling
> +~~~~~~~~~~~~~~~~~~~~~
> +
> +QEMU can redirect to the running program all signals coming from the
> +host (such as ``SIGALRM``), as well as synthesize signals from
> +virtual CPU exceptions (for example ``SIGFPE`` when the program
> +executes a division by zero).
> +
> +QEMU relies on the host kernel to emulate most signal system calls,
> +for example to emulate the signal mask. On Linux, QEMU supports both
> +normal and real-time signals.
> +
> +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.
>
>  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
>
>

Reviewed-by: Manos Pitsidianakis <manos.pitsidianakis@linaro.org>