Re: [PATCH v2 RFC 5/7] kfuzztest: add ReST documentation

[Alexander Potapenko <glider@google.com>]

On Mon, Sep 1, 2025 at 6:43 PM Ethan Graham <ethan.w.s.graham@gmail.com> wrote:
>
> From: Ethan Graham <ethangraham@google.com>
>
> Add Documentation/dev-tools/kfuzztest.rst and reference it in the
> dev-tools index.
>
> Signed-off-by: Ethan Graham <ethangraham@google.com>
Acked-by: Alexander Potapenko <glider@google.com>

Some nits below.

> +Macros ``FUZZ_TEST``, `KFUZZTEST_EXPECT_*`` and ``KFUZZTEST_ANNOTATE_*`` embed

Nit: missing second backtick before KFUZZTEST_EXPECT_


> +Input Format
> +============
> +
> +KFuzzTest targets receive their inputs from userspace via a write to a dedicated
> +debugfs ``/sys/kernel/debug/kfuzztest/<test-name>/input``.

Nit: "debugfs file"?

> +- Padding and Poisoning: The space between the end of one region's data and the
> +  beginning of the next must be sufficient for padding. In KASAN builds,
> +  KFuzzTest poisons this unused padding, allowing for precise detection of
> +  out-of-bounds memory accesses between adjacent buffers. This padding should
> +  be at least ``KFUZZTEST_POISON_SIZE`` bytes as defined in
> +  `include/linux/kfuzztest.h``.

Nit: missing leading backtick.

> +
> +KFuzzTest Bridge Tool
> +=====================
> +
> +The kfuzztest-bridge program is a userspace utility that encodes a random byte

Nit: do we need backticks around kfuzztest-bridge?

> +This tool is intended to be simple, both in usage and implementation. Its
> +structure and DSL are sufficient for simpler use-cases. For more advanced
> +coverage-guided fuzzing it is recommended to use syzkaller which implements
> +deeper support for KFuzzTest targets.

Nit: please add a link to syzkaller.

> +
> +The textual format is a human-readable representation of the region-based binary
> +format used by KFuzzTest. It is described by the following grammar:
> +
> +.. code-block:: text
> +
> +       schema     ::= region ( ";" region )* [";"]
> +       region     ::= identifier "{" type+ "}"

Don't types need to be separated with spaces?

> +       type       ::= primitive | pointer | array | length | string
> +       primitive  ::= "u8" | "u16" | "u32" | "u64"
> +       pointer    ::= "ptr" "[" identifier "]"
> +       array      ::= "arr" "[" primitive "," integer "]"
> +       length     ::= "len" "[" identifier "," primitive "]"
> +       string     ::= "str" "[" integer "]"
> +       identifier ::= [a-zA-Z_][a-zA-Z1-9_]*
> +       integer    ::= [0-9]+
> +
> +Pointers must reference a named region. To fuzz a raw buffer, the buffer must be

Maybe insert a paragraph break between these two sentences?

> +.. code-block:: text
> +
> +       my_struct { ptr[buf] len[buf, u64] }; buf { arr[u8, n] };
> +
> +Where ``n`` is some integer value defining the size of the byte array inside of

s/Where/, where/ ?