MIME-Version: 1.0
References: <0b5efd70e31bba7912cf9a6c951f0e76a8df27df.1677517724.git.andreyknvl@google.com>
 <CACT4Y+Z4GvK-XCbrLp8cuH-xHYsCdh1f0948ZgkU2D0apfGG5w@mail.gmail.com>
In-Reply-To: <CACT4Y+Z4GvK-XCbrLp8cuH-xHYsCdh1f0948ZgkU2D0apfGG5w@mail.gmail.com>
From:   Andrey Konovalov <andreyknvl@gmail.com>
Date:   Tue, 28 Feb 2023 21:01:01 +0100
Message-ID: <CA+fCnZdn+3LuzDP0f=kc9Pgt6i63cQbXieP1gJRYOS8WnVJKQA@mail.gmail.com>
Subject: Re: [PATCH] kcov: improve documentation
To:     Dmitry Vyukov <dvyukov@google.com>
Cc:     andrey.konovalov@linux.dev, Marco Elver <elver@google.com>,
        Alexander Potapenko <glider@google.com>,
        kasan-dev@googlegroups.com,
        Andrew Morton <akpm@linux-foundation.org>, linux-mm@kvack.org,
        linux-kernel@vger.kernel.org,
        Andrey Konovalov <andreyknvl@google.com>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
Precedence: bulk

On Tue, Feb 28, 2023 at 10:37=E2=80=AFAM Dmitry Vyukov <dvyukov@google.com>=
 wrote:
>
> On Mon, 27 Feb 2023 at 18:17, <andrey.konovalov@linux.dev> wrote:
> >
> > From: Andrey Konovalov <andreyknvl@google.com>
> >
> > Improve KCOV documentation:
> >
> > - Use KCOV instead of kcov, as the former is more widely-used.
> >
> > - Mention Clang in compiler requirements.
> >
> > - Use ``annotations`` for inline code.
> >
> > - Rework remote coverage collection documentation for better clarity.
> >
> > - Various smaller changes.
> >
> > Signed-off-by: Andrey Konovalov <andreyknvl@google.com>
> > ---
> >  Documentation/dev-tools/kcov.rst | 169 +++++++++++++++++++------------
> >  1 file changed, 102 insertions(+), 67 deletions(-)
> >
> > diff --git a/Documentation/dev-tools/kcov.rst b/Documentation/dev-tools=
/kcov.rst
> > index d83c9ab49427..a113a03a475f 100644
> > --- a/Documentation/dev-tools/kcov.rst
> > +++ b/Documentation/dev-tools/kcov.rst
> > @@ -1,42 +1,50 @@
> > -kcov: code coverage for fuzzing
> > +KCOV: code coverage for fuzzing
> >  =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D
> >
> > -kcov exposes kernel code coverage information in a form suitable for c=
overage-
> > -guided fuzzing (randomized testing). Coverage data of a running kernel=
 is
> > -exported via the "kcov" debugfs file. Coverage collection is enabled o=
n a task
> > -basis, and thus it can capture precise coverage of a single system cal=
l.
> > +KCOV collects and exposes kernel code coverage information in a form s=
uitable
> > +for coverage-guided fuzzing. Coverage data of a running kernel is expo=
rted via
> > +the ``kcov`` debugfs file. Coverage collection is enabled on a task ba=
sis, and
> > +thus KCOV can capture precise coverage of a single system call.
> >
> > -Note that kcov does not aim to collect as much coverage as possible. I=
t aims
> > -to collect more or less stable coverage that is function of syscall in=
puts.
> > -To achieve this goal it does not collect coverage in soft/hard interru=
pts
> > -and instrumentation of some inherently non-deterministic parts of kern=
el is
> > -disabled (e.g. scheduler, locking).
> > +Note that KCOV does not aim to collect as much coverage as possible. I=
t aims
> > +to collect more or less stable coverage that is a function of syscall =
inputs.
> > +To achieve this goal, it does not collect coverage in soft/hard interr=
upts
> > +(unless remove coverage collection is enabled, see below) and from som=
e
> > +inherently non-deterministic parts of the kernel (e.g. scheduler, lock=
ing).
> >
> > -kcov is also able to collect comparison operands from the instrumented=
 code
> > -(this feature currently requires that the kernel is compiled with clan=
g).
> > +Besides collecting code coverage, KCOV can also collect comparison ope=
rands.
> > +See the "Comparison operands collection" section for details.
> > +
> > +Besides collecting coverage data from syscall handlers, KCOV can also =
collect
> > +coverage for annotated parts of the kernel executing in background ker=
nel
> > +tasks or soft interrupts. See the "Remote coverage collection" section=
 for
> > +details.
> >
> >  Prerequisites
> >  -------------
> >
> > -Configure the kernel with::
> > +KCOV relies on compiler instrumentation and requires GCC 6.1.0 or late=
r
> > +or any Clang version supported by the kernel.
> >
> > -        CONFIG_KCOV=3Dy
> > +Collecting comparison operands is only supported with Clang.
>
> Are you sure?
> I see -fsanitize-coverage=3Dtrace-cmp in gcc sources and man page.

Right, supported too starting with version 8.

Will fix in v2.

> Otherwise looks good to me.

I'll add your Reviewed-by to v2 then.

Thank you!