linux-kernel - Re: [PATCH v2 03/11] kcov: elaborate on using the shared buffer

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <CACT4Y+Z=G0PBvMk=5MgLAC3LjKOHvCpMqtnw6PLey3SxeUa5gQ@mail.gmail.com>
Date: Wed, 9 Jul 2025 15:12:22 +0200
From: Dmitry Vyukov <dvyukov@...gle.com>
To: Alexander Potapenko <glider@...gle.com>
Cc: quic_jiangenj@...cinc.com, linux-kernel@...r.kernel.org, 
	kasan-dev@...glegroups.com, Aleksandr Nogikh <nogikh@...gle.com>, 
	Andrey Konovalov <andreyknvl@...il.com>, Borislav Petkov <bp@...en8.de>, 
	Dave Hansen <dave.hansen@...ux.intel.com>, Ingo Molnar <mingo@...hat.com>, 
	Josh Poimboeuf <jpoimboe@...nel.org>, Marco Elver <elver@...gle.com>, 
	Peter Zijlstra <peterz@...radead.org>, Thomas Gleixner <tglx@...utronix.de>
Subject: Re: [PATCH v2 03/11] kcov: elaborate on using the shared buffer

On Thu, 26 Jun 2025 at 15:42, Alexander Potapenko <glider@...gle.com> wrote:
>
> Add a paragraph about the shared buffer usage to kcov.rst.
>
> Signed-off-by: Alexander Potapenko <glider@...gle.com>
> ---
> Change-Id: Ia47ef7c3fcc74789fe57a6e1d93e29a42dbc0a97
> ---
>  Documentation/dev-tools/kcov.rst | 55 ++++++++++++++++++++++++++++++++
>  1 file changed, 55 insertions(+)
>
> diff --git a/Documentation/dev-tools/kcov.rst b/Documentation/dev-tools/kcov.rst
> index 6611434e2dd24..abf3ad2e784e8 100644
> --- a/Documentation/dev-tools/kcov.rst
> +++ b/Documentation/dev-tools/kcov.rst
> @@ -137,6 +137,61 @@ mmaps coverage buffer, and then forks child processes in a loop. The child
>  processes only need to enable coverage (it gets disabled automatically when
>  a thread exits).
>
> +Shared buffer for coverage collection
> +-------------------------------------
> +KCOV employs a shared memory buffer as a central mechanism for efficient and
> +direct transfer of code coverage information between the kernel and userspace
> +applications.
> +
> +Calling ``ioctl(fd, KCOV_INIT_TRACE, size)`` initializes coverage collection for
> +the current thread associated with the file descriptor ``fd``. The buffer
> +allocated will hold ``size`` unsigned long values, as interpreted by the kernel.
> +Notably, even in a 32-bit userspace program on a 64-bit kernel, each entry will
> +occupy 64 bits.
> +
> +Following initialization, the actual shared memory buffer is created using::
> +
> +    mmap(NULL, size * sizeof(unsigned long), PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0)
> +
> +The size of this memory mapping, calculated as ``size * sizeof(unsigned long)``,
> +must be a multiple of ``PAGE_SIZE``.
> +
> +This buffer is then shared between the kernel and the userspace. The first
> +element of the buffer contains the number of PCs stored in it.
> +Both the userspace and the kernel may write to the shared buffer, so to avoid
> +race conditions each userspace thread should only update its own buffer.
> +
> +Normally the shared buffer is used as follows::
> +
> +              Userspace                                         Kernel
> +    -----------------------------------------+-------------------------------------------
> +    ioctl(fd, KCOV_INIT_TRACE, size)         |
> +                                             |    Initialize coverage for current thread
> +    mmap(..., MAP_SHARED, fd, 0)             |
> +                                             |    Allocate the buffer, initialize it
> +                                             |    with zeroes
> +    ioctl(fd, KCOV_ENABLE, KCOV_TRACE_PC)    |
> +                                             |    Enable PC collection for current thread
> +                                             |    starting at buffer[1] (KCOV_ENABLE will
> +                                             |    already write some coverage)
> +    Atomically write 0 to buffer[0] to       |
> +    reset the coverage                       |
> +                                             |
> +    Execute some syscall(s)                  |
> +                                             |    Write new coverage starting at
> +                                             |    buffer[1]
> +    Atomically read buffer[0] to get the     |
> +    total coverage size at this point in     |
> +    time                                     |
> +                                             |
> +    ioctl(fd, KCOV_DISABLE, 0)               |
> +                                             |    Write some more coverage for ioctl(),
> +                                             |    then disable PC collection for current
> +                                             |    thread
> +    Safely read and process the coverage     |
> +    up to the buffer[0] value saved above    |
> +
> +
>  Comparison operands collection
>  ------------------------------

Reviewed-by: Dmitry Vyukov <dvyukov@...gle.com>