pkg/kfuzztest: add a golden tests for description generation

Author: Ethan Graham

pkg/kfuzztest/description_generation_test.go

@@ -0,0 +1,101 @@
+// Copyright 2025 syzkaller project authors. All rights reserved.
+// Use of this source code is governed by Apache 2 LICENSE that can be found in the LICENSE file.
+package kfuzztest
+
+import (
+	"fmt"
+	"os"
+	"path"
+	"testing"
+	"time"
+
+	"github.com/google/go-cmp/cmp"
+	"github.com/google/syzkaller/pkg/osutil"
+	"github.com/google/syzkaller/sys/targets"
+	"github.com/stretchr/testify/assert"
+)
+
+type testData struct {
+	dir  string
+	desc string
+}
+
+func TestBuildDescriptions(t *testing.T) {
+	testCases, err := readTestCases("./testdata")
+	assert.NoError(t, err)
+
+	target := targets.Get(targets.Linux, targets.AMD64)
+	for _, tc := range testCases {
+		runTest(t, target, tc)
+	}
+}
+
+// Tests that the description inferred from a compiled binary matches an
+// expected description.
+func runTest(t *testing.T, target *targets.Target, tc testData) {
+	// Compile the C binary containing the metadata.
+	cmd := flags(tc.dir)
+	out, err := osutil.RunCmd(time.Hour, "", target.CCompiler, cmd...)
+	assert.NoErrorf(t, err, "Failed to compile: %s", string(out))
+	// Cleanup the compiled binary.
+	defer func() {
+		out, err := osutil.RunCmd(time.Hour, "", "rm", path.Join(tc.dir, "bin"))
+		if err != nil {
+			assert.NoErrorf(t, err, "Failed to cleanup: %s", string(out))
+		}
+	}()
+
+	binaryPath := path.Join(tc.dir, "bin")
+	desc, err := ExtractDescription(binaryPath)
+	assert.NoError(t, err)
+
+	if diffDesc := cmp.Diff(tc.desc, desc); diffDesc != "" {
+		fmt.Print(diffDesc)
+		t.Fail()
+		return
+	}
+}
+
+func flags(testDir string) []string {
+	return []string{
+		"-g",
+		"-T",
+		path.Join(testDir, "..", "linker.ld"),
+		"-o",
+		path.Join(testDir, "bin"),
+		path.Join(testDir, "prog.c"),
+	}
+}
+
+func readTestCases(dir string) ([]testData, error) {
+	var testCases []testData
+	testDirs, err := os.ReadDir(dir)
+	if err != nil {
+		return nil, err
+	}
+
+	for _, subDir := range testDirs {
+		if !subDir.IsDir() {
+			continue
+		}
+		testData, err := readTestdata(path.Join(dir, subDir.Name()))
+		if err != nil {
+			return nil, err
+		}
+		testCases = append(testCases, testData)
+	}
+
+	return testCases, nil
+}
+
+func readTestdata(testDir string) (testData, error) {
+	content, err := os.ReadFile(path.Join(testDir, "desc.txt"))
+	if err != nil {
+		return testData{}, err
+	}
+
+	return testData{
+		dir:  testDir,
+		desc: string(content),
+	}, nil
+}

pkg/kfuzztest/testdata/.gitignore

@@ -0,0 +1 @@
+*bin

pkg/kfuzztest/testdata/1/desc.txt

@@ -0,0 +1,7 @@
+# This description was automatically generated with tools/kfuzztest-gen
+pkcs7_parse_message_arg {
+	data	ptr[in, array[int8]]
+	datalen	len[data, int64]
+}
+
+syz_kfuzztest_run$test_pkcs7_parse_message(name ptr[in, string["test_pkcs7_parse_message"]], data ptr[in, pkcs7_parse_message_arg], len bytesize[data]) (kfuzz_test)

pkg/kfuzztest/testdata/1/prog.c

@@ -0,0 +1,22 @@
+// Copyright 2025 syzkaller project authors. All rights reserved.
+// Use of this source code is governed by Apache 2 LICENSE that can be found in the LICENSE file.
+#include "../common.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+
+struct pkcs7_parse_message_arg {
+	const void *data;
+	size_t datalen;
+};
+
+DEFINE_FUZZ_TARGET(test_pkcs7_parse_message, struct pkcs7_parse_message_arg);
+/* Expect data != NULL. */
+DEFINE_CONSTRAINT(pkcs7_parse_message_arg, data, NULL, NULL, EXPECT_NE);
+/* Expect datalen == len(data). */
+DEFINE_ANNOTATION(pkcs7_parse_message_arg, datalen, data, ATTRIBUTE_LEN);
+
+/* Define a main function, otherwise the compiler complains. */
+int main(void)
+{
+}

pkg/kfuzztest/testdata/2/desc.txt

@@ -0,0 +1,15 @@
+# This description was automatically generated with tools/kfuzztest-gen
+bar {
+	a	int32
+	b	int32
+}
+
+foo {
+	b	ptr[inout, bar]
+	str	ptr[in, string]
+	data	ptr[in, array[int8]]
+	datalen	len[data, int64]
+	numbers	ptr[in, array[uint64_t]]
+}
+
+syz_kfuzztest_run$some_target(name ptr[in, string["some_target"]], data ptr[in, foo], len bytesize[data]) (kfuzz_test)

pkg/kfuzztest/testdata/2/prog.c

@@ -0,0 +1,37 @@
+// Copyright 2025 syzkaller project authors. All rights reserved.
+// Use of this source code is governed by Apache 2 LICENSE that can be found in the LICENSE file.
+#include "../common.h"
+
+#include <stdlib.h>
+
+struct bar {
+	int a;
+	int b;
+};
+
+struct foo {
+	struct bar *b;
+	const char *str;
+	const char *data;
+	size_t datalen;
+	uint64_t *numbers;
+};
+
+DEFINE_FUZZ_TARGET(some_target, struct foo);
+/* Expect foo.bar != NULL. */
+DEFINE_CONSTRAINT(foo, bar, NULL, NULL, EXPECT_NE);
+/* Expect foo.str != NULL. */
+DEFINE_CONSTRAINT(foo, str, NULL, NULL, EXPECT_NE);
+/* Annotate foo.str as a string. */
+DEFINE_ANNOTATION(foo, str, , ATTRIBUTE_STRING);
+/* Expect foo.data != NULL. */
+DEFINE_CONSTRAINT(foo, data, NULL, NULL, EXPECT_NE);
+/* Annotate foo.datalen == len(foo.data). */
+DEFINE_ANNOTATION(foo, datalen, data, ATTRIBUTE_LEN);
+/* Annotate foo.numbers as an array. */
+DEFINE_ANNOTATION(foo, numbers, , ATTRIBUTE_ARRAY);
+
+/* Define a main function, otherwise the compiler complains. */
+int main(void)
+{
+}

pkg/kfuzztest/testdata/common.h

@@ -0,0 +1,81 @@
+// Copyright 2025 syzkaller project authors. All rights reserved.
+// Use of this source code is governed by Apache 2 LICENSE that can be found in the LICENSE file.
+
+// Common struct definitions that ressemble those sound in the kernel source
+// under /include/linux/kfuzztest.h. For testing purposes, it is only required
+// that these have the same sizes and emitted metadata as the kernel
+// definitions, and therefore there is no strict requirement that their fields
+// match one-to-one.
+#ifndef COMMON_H
+#define COMMON_H
+
+#include <stdint.h>
+
+struct kfuzztest_target {
+	const char *name;
+	const char *arg_type_name;
+	uintptr_t write_input_cb;
+} __attribute__((aligned(32)));
+
+enum kfuzztest_constraint_type {
+	EXPECT_EQ,
+	EXPECT_NE,
+	EXPECT_LT,
+	EXPECT_LE,
+	EXPECT_GT,
+	EXPECT_GE,
+	EXPECT_IN_RANGE,
+};
+
+struct kfuzztest_constraint {
+	const char *input_type;
+	const char *field_name;
+	uintptr_t value1;
+	uintptr_t value2;
+	enum kfuzztest_constraint_type type;
+} __attribute__((aligned(64)));
+
+enum kfuzztest_annotation_attribute : uint8_t {
+	ATTRIBUTE_LEN,
+	ATTRIBUTE_STRING,
+	ATTRIBUTE_ARRAY,
+};
+
+struct kfuzztest_annotation {
+	const char *input_type;
+	const char *field_name;
+	const char *linked_field_name;
+	enum kfuzztest_annotation_attribute attrib;
+} __attribute__((aligned(32)));
+
+#define DEFINE_FUZZ_TARGET(test_name, test_arg_type)                        \
+	struct kfuzztest_target __fuzz_test__##test_name                    \
+		__attribute__((section(".kfuzztest_target"), __used__)) = { \
+			.name = #test_name,                                 \
+			.arg_type_name = #test_arg_type,                    \
+		};                                                          \
+	/* Avoid the compiler optimizing out the struct definition. */      \
+	static test_arg_type arg;
+
+#define DEFINE_CONSTRAINT(arg_type, field, val1, val2, tpe)                  \
+	static struct kfuzztest_constraint __constraint_##arg_type##_##field \
+		__attribute__((section(".kfuzztest_constraint"),             \
+			       __used__)) = {                                \
+			.input_type = "struct " #arg_type,                   \
+			.field_name = #field,                                \
+			.value1 = (uintptr_t)val1,                           \
+			.value2 = (uintptr_t)val2,                           \
+			.type = tpe,                                         \
+		}
+
+#define DEFINE_ANNOTATION(arg_type, field, linked_field, attribute)          \
+	static struct kfuzztest_annotation __annotation_##arg_type##_##field \
+		__attribute__((section(".kfuzztest_annotation"),             \
+			       __used__)) = {                                \
+			.input_type = "struct " #arg_type,                   \
+			.field_name = #field,                                \
+			.linked_field_name = #linked_field,                  \
+			.attrib = attribute,                                 \
+		}
+
+#endif /* COMMON_H */

pkg/kfuzztest/testdata/linker.ld

@@ -0,0 +1,39 @@
+/* Copyright 2025 syzkaller project authors. All rights reserved. */
+/* Use of this source code is governed by Apache 2 LICENSE that can be found in the LICENSE file. */
+
+/* Defines a basic linkage script for building kernel-like KFuzzTest metadata into a binary. */
+PAGE_SIZE = 0x1000;
+
+PHDRS
+{
+    text PT_LOAD FLAGS(5); /* R, X */
+    data PT_LOAD FLAGS(6); /* R, W */
+}
+
+SECTIONS
+{
+    .text : { *(.text) } :text
+
+    .rodata : {
+        *(.rodata*)
+
+        . = ALIGN(PAGE_SIZE);
+        __kfuzztest_targets_start = .;
+        KEEP(*(.kfuzztest_target));
+        __kfuzztest_targets_end = .;
+
+        . = ALIGN(PAGE_SIZE);
+        __kfuzztest_constraints_start = .;
+        KEEP(*(.kfuzztest_constraint));
+        __kfuzztest_constraints_end = .;
+
+        . = ALIGN(PAGE_SIZE);
+        __kfuzztest_annotations_start = .;
+        KEEP(*(.kfuzztest_annotation));
+        __kfuzztest_annotations_end = .;
+
+    } :text
+
+    .data : { *(.data) } :data
+    .bss : { *(.bss) } :data
+}