On Mon, 28 Jul 2025 at 20:43, Soham Bagchi <soham.bagchi@xxxxxxxx> wrote:
>
> Updating the KCOV documentation to use a load-acquire
> operation for the first element of the shared memory
> buffer between kernel-space and user-space.
>
> The load-acquire pairs with the write memory barrier
> used in kcov_move_area()
>
> Signed-off-by: Soham Bagchi <soham.bagchi@xxxxxxxx>
> ---
> Documentation/dev-tools/kcov.rst | 7 ++++++-
> 1 file changed, 6 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/dev-tools/kcov.rst b/Documentation/dev-tools/kcov.rst
> index 6611434e2dd..46450fb46fe 100644
> --- a/Documentation/dev-tools/kcov.rst
> +++ b/Documentation/dev-tools/kcov.rst
> @@ -287,6 +287,11 @@ handle instance id.
> The following program demonstrates using KCOV to collect coverage from both
> local tasks spawned by the process and the global task that handles USB bus #1:
>
> +The user-space code for KCOV should also use an acquire to fetch the count
> +of coverage entries in the shared buffer. This acquire pairs with the
> +corresponding write memory barrier (smp_wmb()) on the kernel-side in
> +kcov_move_area().
> +
This new paragraph is misplaced.
You've added it after the "... handles USB bus #1:" part which clearly
should be right before the code (note the colon).
Why not add what you wrote here as a block-comment (similar in style
to comment above the sleep()) right above the __atomic_load_n below? I
think those details probably don't quite belong into the high level
text, but the detailed code example.
> .. code-block:: c
>
> /* Same includes and defines as above. */
> @@ -361,7 +366,7 @@ local tasks spawned by the process and the global task that handles USB bus #1:
> */
> sleep(2);
>
> - n = __atomic_load_n(&cover[0], __ATOMIC_RELAXED);
> + n = __atomic_load_n(&cover[0], __ATOMIC_ACQUIRE);
> for (i = 0; i < n; i++)
> printf("0x%lx\n", cover[i + 1]);
> if (ioctl(fd, KCOV_DISABLE, 0))
> --
> 2.34.1
>
