[PATCH] kcov: update documentation on remote coverage collection

[Jann Horn]

Adjust the docs on remote coverage collection to reflect the changes made
in "kcov: refactor common handle ID into kcov_common_handle_id" and
"kcov: allow simultaneous KCOV_ENABLE/KCOV_REMOTE_ENABLE".

Suggested-by: Alexander Potapenko <gli...@google.com>
Signed-off-by: Jann Horn <ja...@google.com>
---
Documentation/dev-tools/kcov.rst | 5 +++++
1 file changed, 5 insertions(+)

diff --git a/Documentation/dev-tools/kcov.rst b/Documentation/dev-tools/kcov.rst
index 8127849d40f5..54a0baeb917a 100644
--- a/Documentation/dev-tools/kcov.rst
+++ b/Documentation/dev-tools/kcov.rst
@@ -246,6 +246,8 @@ KCOV supports collecting remote coverage from the following contexts:
2. Local kernel background tasks. These are spawned when a userspace process
interacts with some kernel interface and are usually killed when the process
exits (e.g. vhost workers).
+ This can be combined with another KCOV instance that is configured for normal
+ coverage collection.

3. Soft interrupts.

@@ -262,6 +264,9 @@ gets saved to the ``kcov_handle`` field in the current ``task_struct`` and
needs to be passed to the newly spawned local tasks via custom kernel code
modifications. Those tasks should in turn use the passed handle in their
``kcov_remote_start`` and ``kcov_remote_stop`` annotations.
+In the kernel, common handles are wrapped in a ``kcov_common_handle_id``, which
+consumes no space in builds without ``CONFIG_KCOV``; subsystems that integrate
+with this mechanism should not need to use any ``#ifdef CONFIG_KCOV`` or such.

KCOV follows a predefined format for both global and common handles. Each
handle is a ``u64`` integer. Currently, only the one top and the lower 4 bytes

---
base-commit: ab5fce87a778cb780a05984a2ca448f2b41aafbf
change-id: 20260519-kcov-docs-15feabfb10aa

--
Jann Horn <ja...@google.com>

[Alexander Potapenko]

On Tue, May 19, 2026 at 6:06 PM Jann Horn <ja...@google.com> wrote:
>
> Adjust the docs on remote coverage collection to reflect the changes made
> in "kcov: refactor common handle ID into kcov_common_handle_id" and
> "kcov: allow simultaneous KCOV_ENABLE/KCOV_REMOTE_ENABLE".
>
> Suggested-by: Alexander Potapenko <gli...@google.com>
> Signed-off-by: Jann Horn <ja...@google.com>

Reviewed-by: Alexander Potapenko <gli...@google.com>

[Andrey Konovalov]

On Tue, May 19, 2026 at 6:06 PM Jann Horn <ja...@google.com> wrote:
>

> Adjust the docs on remote coverage collection to reflect the changes made
> in "kcov: refactor common handle ID into kcov_common_handle_id" and
> "kcov: allow simultaneous KCOV_ENABLE/KCOV_REMOTE_ENABLE".
>
> Suggested-by: Alexander Potapenko <gli...@google.com>
> Signed-off-by: Jann Horn <ja...@google.com>

Hi Jann,

> ---
> Documentation/dev-tools/kcov.rst | 5 +++++
> 1 file changed, 5 insertions(+)
>
> diff --git a/Documentation/dev-tools/kcov.rst b/Documentation/dev-tools/kcov.rst
> index 8127849d40f5..54a0baeb917a 100644
> --- a/Documentation/dev-tools/kcov.rst
> +++ b/Documentation/dev-tools/kcov.rst
> @@ -246,6 +246,8 @@ KCOV supports collecting remote coverage from the following contexts:
> 2. Local kernel background tasks. These are spawned when a userspace process
> interacts with some kernel interface and are usually killed when the process
> exits (e.g. vhost workers).
> + This can be combined with another KCOV instance that is configured for normal
> + coverage collection.

But does your change only work for collecting coverage from these
local tasks, or from global ones as well? If the latter is allowed as
well, this sentence need to be moved.

[Jann Horn]

On Wed, May 20, 2026 at 7:51 PM Andrey Konovalov <andre...@gmail.com> wrote:
> On Tue, May 19, 2026 at 6:06 PM Jann Horn <ja...@google.com> wrote:
> > diff --git a/Documentation/dev-tools/kcov.rst b/Documentation/dev-tools/kcov.rst
> > index 8127849d40f5..54a0baeb917a 100644
> > --- a/Documentation/dev-tools/kcov.rst
> > +++ b/Documentation/dev-tools/kcov.rst
> > @@ -246,6 +246,8 @@ KCOV supports collecting remote coverage from the following contexts:
> > 2. Local kernel background tasks. These are spawned when a userspace process
> > interacts with some kernel interface and are usually killed when the process
> > exits (e.g. vhost workers).
> > + This can be combined with another KCOV instance that is configured for normal
> > + coverage collection.
>
> But does your change only work for collecting coverage from these
> local tasks, or from global ones as well? If the latter is allowed as
> well, this sentence need to be moved.

It also works for collecting global coverage. When I was writing this,
I figured that anyone wanting to collect global coverage would
probably be doing it from a separate task anyway; but yeah, you're
right, it makes more sense to move this note. I'll send a v2.

[Jann Horn]

Adjust the docs on remote coverage collection to reflect the changes made
in "kcov: refactor common handle ID into kcov_common_handle_id" and
"kcov: allow simultaneous KCOV_ENABLE/KCOV_REMOTE_ENABLE".

Suggested-by: Alexander Potapenko <gli...@google.com>
Signed-off-by: Jann Horn <ja...@google.com>

---
Changes in v2:
- move and reword sentence on simultaneous normal/remote collection (andreyknvl)
- Link to v1: https://lore.kernel.org/r/20260519-kcov-docs...@google.com
---
Documentation/dev-tools/kcov.rst | 6 ++++++
1 file changed, 6 insertions(+)

diff --git a/Documentation/dev-tools/kcov.rst b/Documentation/dev-tools/kcov.rst
index 8127849d40f5..1a739290c8ec 100644
--- a/Documentation/dev-tools/kcov.rst
+++ b/Documentation/dev-tools/kcov.rst
@@ -237,6 +237,9 @@ Both ``kcov_remote_start`` and ``kcov_remote_stop`` annotations and the
collection sections. The way a handle is used depends on the context where the
matching code section executes.

+A thread can use two separate KCOV instances to collect remote coverage and
+normal coverage at the same time.
+

KCOV supports collecting remote coverage from the following contexts:

1. Global kernel background tasks. These are the tasks that are spawned during
@@ -262,6 +265,9 @@ gets saved to the ``kcov_handle`` field in the current ``task_struct`` and