[PATCH RFC v3 2/8] Documentation: add kcov-dataflow.rst

[Yunseong Kim]

Document the kcov_dataflow subsystem under Documentation/dev-tools/:

 - Prerequisites and the Kconfig options (KCOV_DATAFLOW_ARGS / _RET,
   NO_INLINE, INSTRUMENT_ALL) and the compiler they require.
 - Per-file (KCOV_DATAFLOW_<obj>.o := y) and whole-kernel instrumentation.
 - A worked collection example: open /sys/kernel/debug/kcov_dataflow,
   KCOV_DF_INIT_TRACK, mmap, KCOV_DF_ENABLE, run the workload, and walk the
   buffer.
 - The record layout: area[0] as the record-word count, the header word
   fields (sequence, type, value count, size, argument index), the PC with
   the KASLR offset removed, the traced pointer or comparison type, and the
   value words.
 - Safety properties and the ioctl interface reference.
 - Coexistence with KCOV, Rust module support, and the fork/child
   tracing pattern.

Add the ioctl 'd' numbers (KCOV_DF_INIT_TRACK and 100-103) to
Documentation/userspace-api/ioctl/ioctl-number.rst, link the new
file from the dev-tools index, and add the MAINTAINERS entries for
kernel/kcov_dataflow.c and include/uapi/linux/kcov_dataflow.h.

Signed-off-by: Yunseong Kim <yunseong.kim@xxxxxxxx>
---
 Documentation/dev-tools/index.rst                  |   1 +
 Documentation/dev-tools/kcov-dataflow.rst          | 449 +++++++++++++++++++++
 Documentation/userspace-api/ioctl/ioctl-number.rst |   2 +
 MAINTAINERS                                        |   2 +
 4 files changed, 454 insertions(+)

diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst
index 59cbb77b33ff4..541c58cc65ea5 100644
--- a/Documentation/dev-tools/index.rst
+++ b/Documentation/dev-tools/index.rst
@@ -24,6 +24,7 @@ Documentation/process/debugging/index.rst
    context-analysis
    sparse
    kcov
+   kcov-dataflow
    gcov
    kasan
    kmsan
diff --git a/Documentation/dev-tools/kcov-dataflow.rst b/Documentation/dev-tools/kcov-dataflow.rst
new file mode 100644
index 0000000000000..4c023032fea00
--- /dev/null
+++ b/Documentation/dev-tools/kcov-dataflow.rst
@@ -0,0 +1,449 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+KCOV-Dataflow: function argument and return value extraction
+=============================================================
+
+KCOV-Dataflow captures function arguments and return values, including
+automatic struct field decomposition, at instrumented kernel function
+boundaries. It provides per-task, lock-free ring buffers accessible via
+``mmap()``, enabling data-flow-aware fuzzing and post-mortem contract
+verification.
+
+Unlike KCOV's ``trace-pc`` which reports *which* code executed,
+KCOV-Dataflow reports *what values* were passed and returned. This is
+a completely separate device from ``/sys/kernel/debug/kcov``.
+
+Prerequisites
+-------------
+
+KCOV-Dataflow requires Clang/LLVM with the ``trace-args`` and
+``trace-ret`` SanitizerCoverage extensions. Standard (unpatched)
+compilers will not expose these Kconfig options.
+
+To enable KCOV-Dataflow, configure the kernel with::
+
+        CONFIG_KCOV=y
+        CONFIG_KCOV_DATAFLOW_ARGS=y
+        CONFIG_KCOV_DATAFLOW_RET=y
+
+Optional: instrument the entire kernel (significant overhead)::
+
+        CONFIG_KCOV_DATAFLOW_INSTRUMENT_ALL=y
+
+Coverage data becomes accessible once debugfs is mounted::
+
+        mount -t debugfs none /sys/kernel/debug
+
+Per-module instrumentation
+--------------------------
+
+To instrument a specific module, add to its Makefile::
+
+        KCOV_DATAFLOW_my_module.o := y
+
+For example, to instrument the Android binder driver::
+
+        # drivers/android/Makefile
+        KCOV_DATAFLOW_binder.o := y
+        KCOV_DATAFLOW_binder_alloc.o := y
+
+To instrument an entire directory, set the variable without a filename::
+
+        # fs/Makefile
+        KCOV_DATAFLOW := y
+
+The build system automatically adds the required compiler flags
+(``-fsanitize-coverage=trace-args,trace-ret``). Debug info is provided
+by ``CONFIG_DEBUG_INFO`` which is a Kconfig dependency.
+
+Data collection
+---------------
+
+The following program demonstrates how to collect function argument and
+return value data for a single syscall:
+
+.. code-block:: c
+
+    #include <stdio.h>
+    #include <stdint.h>
+    #include <stdlib.h>
+    #include <sys/types.h>
+    #include <sys/ioctl.h>
+    #include <sys/mman.h>
+    #include <unistd.h>
+    #include <fcntl.h>
+
+    #include <linux/kcov_dataflow.h>   /* ioctls, record layout, helpers */
+    #define BUF_SIZE            (1 << 20)  /* 1M words = 8MB */
+
+    int main(void)
+    {
+        int fd;
+        uint64_t *buf, n, i;
+
+        fd = open("/sys/kernel/debug/kcov_dataflow", O_RDWR);
+        if (fd == -1)
+            perror("open"), exit(1);
+
+        /* Allocate buffer (size in u64 words). */
+        if (ioctl(fd, KCOV_DF_INIT_TRACK, BUF_SIZE))
+            perror("ioctl(INIT)"), exit(1);
+
+        /* Map the buffer into user space. */
+        buf = (uint64_t *)mmap(NULL, BUF_SIZE * sizeof(uint64_t),
+                               PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
+        if (buf == MAP_FAILED)
+            perror("mmap"), exit(1);
+
+        /* Enable data-flow collection for this task. */
+        if (ioctl(fd, KCOV_DF_ENABLE, 0))
+            perror("ioctl(ENABLE)"), exit(1);
+
+        /* Reset counter. */
+        __atomic_store_n(&buf[0], 0, __ATOMIC_RELAXED);
+
+        /* === Trigger syscall(s) here === */
+        read(-1, NULL, 0);
+
+        /* Read how many words were written. */
+        n = __atomic_load_n(&buf[0], __ATOMIC_RELAXED);
+
+        /* Parse TLV records. */
+        i = 1;
+        while (i + KCOV_DF_RECORD_HDR_WORDS <= 1 + n) {
+            uint64_t hdr      = buf[i];
+            uint64_t pc       = buf[i + 1];   /* KASLR offset removed */
+            uint64_t ptr      = buf[i + 2];   /* traced pointer (ENTRY/RET) */
+            uint32_t type     = KCOV_DF_HDR_TYPE(hdr);
+            uint32_t num_vals = KCOV_DF_HDR_NVALS(hdr);
+            uint32_t seq      = KCOV_DF_HDR_SEQ(hdr);
+            uint32_t arg_idx  = KCOV_DF_HDR_ARGIDX(hdr);
+            uint32_t size     = KCOV_DF_HDR_SIZE(hdr);
+
+            if (!num_vals || (type != KCOV_DF_TYPE_ENTRY &&
+                              type != KCOV_DF_TYPE_RET &&
+                              type != KCOV_DF_TYPE_CMP)) {
+                i++;    /* garbage (e.g. reset mid-run): resync */
+                continue;
+            }
+            if (type != KCOV_DF_TYPE_CMP)
+                printf("[%s] seq=%u pc=0x%lx ptr=0x%lx arg_idx=%u size=%u val=0x%lx\n",
+                       type == KCOV_DF_TYPE_ENTRY ? "ENTRY" : "RET",
+                       seq, pc, ptr, arg_idx, size, buf[i + 3]);
+            i += KCOV_DF_RECORD_WORDS(num_vals);
+        }
+
+        if (ioctl(fd, KCOV_DF_DISABLE, 0))
+            perror("ioctl(DISABLE)"), exit(1);
+
+        munmap(buf, BUF_SIZE * sizeof(uint64_t));
+        close(fd);
+        return 0;
+    }
+
+Ring buffer format
+------------------
+
+The buffer is an array of ``u64`` words::
+
+        buf[0]: atomic counter -- total words written
+
+Each record occupies 3 + N words:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Offset
+     - Field
+     - Description
+   * - 0
+     - header
+     - bits[63:56] = arg_idx (0 for return), bits[55:48] = size in bytes
+       (clamped to 255), bits[47:32] = num_vals (>= 1),
+       bits[31:28] = type: ``KCOV_DF_TYPE_ENTRY`` (0xE),
+       ``KCOV_DF_TYPE_RET`` (0xF) or ``KCOV_DF_TYPE_CMP`` (0xC),
+       bits[23:0] = sequence number
+   * - 1
+     - pc
+     - Instrumented function address with the KASLR offset removed (same
+       as the PCs mainline kcov records), so it can be symbolized against
+       vmlinux; add the runtime offset back for ``/proc/kallsyms``
+   * - 2
+     - ptr / cmp_type
+     - ENTRY/RET: the full 64-bit traced pointer (may be NULL/ERR_PTR, in
+       which case the values are ``0xBADADD85``). CMP: the comparison
+       type, ``KCOV_CMP_SIZE()``/``KCOV_CMP_CONST`` bits from linux/kcov.h
+   * - 3..3+num_vals
+     - values
+     - Struct field values, a single scalar, or the two CMP operands
+
+``area[0]`` never exceeds the buffer size minus one and every counted word
+has been written, so a consumer that walks ``area[0]`` words never leaves
+its mapping. All of the above is defined in ``include/uapi/linux/kcov_dataflow.h``
+(``KCOV_DF_HDR_*()``, ``KCOV_DF_RECORD_WORDS()``).
+
+Magic values:
+
+- ``0xBADADD85``: field read failed (pointer was invalid/freed/poisoned)
+
+Safety
+------
+
+- Callbacks are ``notrace``, ``__no_sanitize_coverage``, ``noinline``
+  to prevent recursion.
+- All pointer reads use ``copy_from_kernel_nofault()`` -- survives
+  freed, poisoned, or unmapped memory.
+- An ``in_task()`` guard rejects calls from hardirq/softirq/NMI context,
+  preventing reentrant buffer corruption.
+- No ``printk`` or allocation in the data path.
+- When not enabled for a task, overhead is a single boolean check.
+
+Ioctl interface
+---------------
+
+.. list-table::
+   :header-rows: 1
+
+   * - Command
+     - Value
+     - Description
+   * - KCOV_DF_INIT_TRACK
+     - ``_IOR('d', 1, unsigned long)``
+     - Allocate buffer (size in u64 words)
+   * - KCOV_DF_ENABLE
+     - ``_IO('d', 100)``
+     - Start collection for current task
+   * - KCOV_DF_DISABLE
+     - ``_IO('d', 101)``
+     - Stop collection
+   * - KCOV_DF_REMOTE_ENABLE
+     - ``_IOW('d', 102, __u64)`` -- argument is a pointer to the handle
+     - Publish buffer for kworker/kthread remote capture
+   * - KCOV_DF_REMOTE_DISABLE
+     - ``_IO('d', 103)``
+     - Unpublish buffer from remote capture
+
+Compatibility
+-------------
+
+KCOV-Dataflow is completely independent from legacy KCOV:
+
+- Separate device: ``/sys/kernel/debug/kcov_dataflow``
+- Separate ioctl namespace (``'d'`` vs ``'c'``)
+- Separate per-task buffer
+- Both can be used simultaneously without interference
+- syzkaller and other KCOV users are unaffected
+
+Rust module support
+-------------------
+
+Rust kernel modules are instrumented natively through the build system.
+The ``KCOV_DATAFLOW_<module>.o := y`` mechanism works identically for
+Rust and C modules. The build system passes
+``-Cllvm-args=-sanitizer-coverage-trace-args`` and
+``-Cllvm-args=-sanitizer-coverage-trace-ret`` to rustc via
+``RUSTFLAGS_KCOV_DATAFLOW``.
+
+Example Makefile for a Rust module::
+
+        obj-m := my_rust_module.o
+        KCOV_DATAFLOW_my_rust_module.o := y
+
+Requires a rustc built against LLVM with trace-args/trace-ret support
+and ``CONFIG_RUST=y`` in the kernel config.
+
+Selftests
+---------
+
+Automated tests and visualization tools are in
+``tools/testing/selftests/kcov_dataflow/``::
+
+        # Automated ioctl interface test (TAP output):
+        make -C tools/testing/selftests/kcov_dataflow
+        vng --user root --exec \
+          tools/testing/selftests/kcov_dataflow/user_ioctl/user_ioctl
+
+        # Load a test module and view captured records:
+        make LLVM=1 CC=clang M=tools/testing/selftests/kcov_dataflow/eight_struct_args_c modules
+        vng --user root --exec \
+          "python3 tools/testing/selftests/kcov_dataflow/trigger-view.py \
+            eight_struct_args_c --ko \
+            tools/testing/selftests/kcov_dataflow/eight_struct_args_c/eight_struct_args_c.ko"
+
+        # Binderfs ioctl capture test (requires CONFIG_ANDROID_BINDER_IPC):
+        make -C tools/testing/selftests/kcov_dataflow/binderfs
+        vng --user root --exec \
+          tools/testing/selftests/kcov_dataflow/binderfs/binderfs_test
+
+See ``tools/testing/selftests/kcov_dataflow/README.rst`` for details.
+
+Tracing child processes
+-----------------------
+
+KCOV-Dataflow is per-task: after ``fork()``, the child does not inherit
+the enabled state. To trace child processes, re-enable on the inherited
+file descriptor in the child before ``exec()``. The ``mmap``'d buffer is
+shared (``MAP_SHARED``), so both parent and child write to the same ring
+buffer atomically.
+
+.. code-block:: c
+
+    #include <stdio.h>
+    #include <stdint.h>
+    #include <stdlib.h>
+    #include <sys/ioctl.h>
+    #include <sys/mman.h>
+    #include <sys/wait.h>
+    #include <unistd.h>
+    #include <fcntl.h>
+
+    #include <linux/kcov_dataflow.h>   /* ioctls, record layout, helpers */
+    #define BUF_SIZE            (1 << 20)
+
+    int main(int argc, char **argv)
+    {
+        int fd = open("/sys/kernel/debug/kcov_dataflow", O_RDWR);
+        ioctl(fd, KCOV_DF_INIT_TRACK, BUF_SIZE);
+        uint64_t *buf = mmap(NULL, BUF_SIZE * 8,
+                             PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
+
+        /* Enable for parent task. */
+        ioctl(fd, KCOV_DF_ENABLE, 0);
+        __atomic_store_n(&buf[0], 0, __ATOMIC_RELAXED);
+
+        pid_t pid = fork();
+        if (pid == 0) {
+            /*
+             * Child: re-enable on inherited fd.
+             * The shared mmap buffer receives records from both tasks.
+             */
+            ioctl(fd, KCOV_DF_ENABLE, 0);
+            execvp(argv[1], &argv[1]);
+            _exit(1);
+        }
+
+        waitpid(pid, NULL, 0);
+        ioctl(fd, KCOV_DF_DISABLE, 0);
+
+        uint64_t n = __atomic_load_n(&buf[0], __ATOMIC_RELAXED);
+        printf("Captured %lu words from parent + child\n", n);
+
+        munmap(buf, BUF_SIZE * 8);
+        close(fd);
+        return 0;
+    }
+
+Note: the child's ``ioctl(fd, KCOV_DF_ENABLE)`` will fail if the parent
+has not yet called ``KCOV_DF_DISABLE``, because only one task can be
+associated with a descriptor at a time. For true multi-process tracing,
+open a separate ``kcov_dataflow`` fd per child, or disable in the parent
+before the child enables (as shown above -- the parent is blocked in
+``waitpid`` so it generates no records during that time anyway).
+
+Remote tracing (kworker/kthread)
+--------------------------------
+
+To capture data from kernel threads (kworkers, kthreads) that are not
+direct descendants of user space, use the remote API:
+
+1. User space allocates and publishes a buffer with ``KCOV_DF_REMOTE_ENABLE``
+2. The kernel module calls ``kcov_df_remote_start()`` at work entry
+3. The kernel module calls ``kcov_df_remote_stop()`` at work exit
+4. User space reads the buffer and unpublishes with ``KCOV_DF_REMOTE_DISABLE``
+
+User space setup:
+
+.. code-block:: c
+
+    #include <stdio.h>
+    #include <stdint.h>
+    #include <sys/ioctl.h>
+    #include <sys/mman.h>
+    #include <unistd.h>
+    #include <fcntl.h>
+
+    #include <linux/kcov.h>            /* kcov_remote_handle() */
+    #include <linux/kcov_dataflow.h>
+    #define BUF_SIZE                (1 << 20)
+
+    int main(void)
+    {
+        int fd = open("/sys/kernel/debug/kcov_dataflow", O_RDWR);
+        ioctl(fd, KCOV_DF_INIT_TRACK, BUF_SIZE);
+        uint64_t *buf = mmap(NULL, BUF_SIZE * 8,
+                             PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
+        __atomic_store_n(&buf[0], 0, __ATOMIC_RELAXED);
+
+        /*
+         * Publish the buffer under a remote handle. The handle must be a
+         * valid kcov_remote_handle() encoding (KCOV_SUBSYSTEM_COMMON with a
+         * nonzero instance, or KCOV_SUBSYSTEM_USB) and is the value the
+         * kernel side passes to kcov_df_remote_start(); one handle per fd,
+         * and not while KCOV_DF_ENABLE is active on the same fd.
+         */
+        __u64 handle = kcov_remote_handle(KCOV_SUBSYSTEM_COMMON, 1);
+        if (ioctl(fd, KCOV_DF_REMOTE_ENABLE, &handle))
+            perror("ioctl(REMOTE_ENABLE)"), exit(1);
+
+        /* Trigger kworker activity (e.g., write to a file, ioctl). */
+        /* ... */
+        sleep(1);
+
+        /* Unpublish and read results. */
+        ioctl(fd, KCOV_DF_REMOTE_DISABLE, 0);
+
+        uint64_t n = __atomic_load_n(&buf[0], __ATOMIC_RELAXED);
+        printf("Captured %lu words from kworker\n", n);
+
+        munmap(buf, BUF_SIZE * 8);
+        close(fd);
+        return 0;
+    }
+
+Kernel module side (called from kworker context):
+
+.. code-block:: c
+
+    #include <linux/kcov.h>
+
+    void my_work_fn(struct work_struct *work)
+    {
+        kcov_df_remote_start();
+        /* ... instrumented code runs here ... */
+        kcov_df_remote_stop();
+    }
+
+Only one buffer can be published at a time. ``kcov_df_remote_start()``
+is a no-op if no buffer is published or if the current task already has
+dataflow enabled.
+
+Limitations
+-----------
+
+ABI argument mapping
+    The LLVM pass maps IR-level arguments to source-level parameters using
+    ``DILocalVariable`` debug records (``-g`` required). This correctly
+    handles hidden ``sret`` pointers, struct decomposition into multiple
+    registers, and C++ ``this`` pointers.
+
+    When debug info is absent or stripped, the pass falls back to positional
+    indexing which may misattribute arguments in functions with ABI-inserted
+    hidden parameters. The kernel is always built with ``-g``, so this
+    limitation does not apply to kernel use.
+
+Struct-by-value reassembly
+    When a small struct is passed by value and the ABI decomposes it into
+    multiple scalar registers (e.g., ``struct { int x; int y; }`` as two
+    ``i32`` values on x86_64), the pass reassembles the fragments into a
+    stack slot. The struct field offsets are preserved, but if a field was
+    entirely optimized away (no debug record), that slot contains zero.
+
+    In kernel code, structs are always passed by pointer, so this case
+    does not arise.
+
+Optimized builds
+    At ``-O2`` and above, LLVM may eliminate ``#dbg_value`` records for
+    arguments that are dead or fully inlined. Such arguments will emit a
+    trace with a null pointer (producing ``0xBADADD85`` in all field
+    positions), indicating the argument existed but its value was
+    unavailable at runtime.
diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst
index 2fc53093752d1..7864b2e7fb476 100644
--- a/Documentation/userspace-api/ioctl/ioctl-number.rst
+++ b/Documentation/userspace-api/ioctl/ioctl-number.rst
@@ -240,6 +240,8 @@ Code  Seq#    Include File                                             Comments
 'd'   00-FF  linux/char/drm/drm.h                                      conflict!
 'd'   02-40  pcmcia/ds.h                                               conflict!
 'd'   F0-FF  linux/digi1.h
+'d'   01     uapi/linux/kcov_dataflow.h                                conflict!
+'d'   64-67  uapi/linux/kcov_dataflow.h                                conflict!
 'e'   all    linux/digi1.h                                             conflict!
 'f'   00-1F  linux/ext2_fs.h                                           conflict!
 'f'   00-1F  linux/ext3_fs.h                                           conflict!
diff --git a/MAINTAINERS b/MAINTAINERS
index b91655b34f0ef..d79e04b108c1c 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -14092,7 +14092,9 @@ B:	https://bugzilla.kernel.org/buglist.cgi?component=Sanitizers&product=Memory%2
 F:	Documentation/dev-tools/kcov.rst
 F:	include/linux/kcov.h
 F:	include/uapi/linux/kcov.h
+F:	include/uapi/linux/kcov_dataflow.h
 F:	kernel/kcov.c
+F:	kernel/kcov_dataflow.c
 F:	scripts/Makefile.kcov
 
 KCSAN

-- 
2.47.3