Gecko [ theprintave.ca ]

Name	Size	Permission	Date
atomic	[ DIR ]	drwxr-xr-x	2025-05-06 06:30
basic	[ DIR ]	drwxr-xr-x	2025-05-06 06:30
clang-tools	[ DIR ]	drwxr-xr-x	2025-05-06 06:30
coccinelle	[ DIR ]	drwxr-xr-x	2025-05-06 06:30
dtc	[ DIR ]	drwxr-xr-x	2025-05-06 06:30
dummy-tools	[ DIR ]	drwxr-xr-x	2025-05-06 06:30
gcc-plugins	[ DIR ]	drwxr-xr-x	2025-05-06 06:30
gdb	[ DIR ]	drwxr-xr-x	2025-05-06 06:30
genksyms	[ DIR ]	drwxr-xr-x	2025-05-06 06:30
kconfig	[ DIR ]	drwxr-xr-x	2025-05-06 06:30
ksymoops	[ DIR ]	drwxr-xr-x	2025-05-06 06:30
mod	[ DIR ]	drwxr-xr-x	2025-05-06 06:30
package	[ DIR ]	drwxr-xr-x	2025-05-06 06:30
selinux	[ DIR ]	drwxr-xr-x	2025-05-06 06:30
tracing	[ DIR ]	drwxr-xr-x	2025-05-06 06:30
.gitignore	214 B	-rw-r--r--	2024-03-10 20:38
Kbuild.include	10.1 KB	-rw-r--r--	2024-03-10 20:38
Kconfig.include	2.65 KB	-rw-r--r--	2025-04-15 13:08
Lindent	502 B	-rwxr-xr-x	2024-03-10 20:38
Makefile	1.87 KB	-rw-r--r--	2024-03-10 20:38
Makefile.asm-generic	1.82 KB	-rw-r--r--	2024-03-10 20:38
Makefile.btf	638 B	-rw-r--r--	2024-03-10 20:38
Makefile.build	17.2 KB	-rw-r--r--	2025-04-15 13:08
Makefile.clang	1.61 KB	-rw-r--r--	2024-03-10 20:38
Makefile.clean	1.87 KB	-rw-r--r--	2024-03-10 20:38
Makefile.compiler	2.74 KB	-rw-r--r--	2024-03-10 20:38
Makefile.debug	1.12 KB	-rw-r--r--	2024-03-10 20:38
Makefile.defconf	1.17 KB	-rw-r--r--	2024-03-10 20:38
Makefile.dtbinst	1.03 KB	-rw-r--r--	2025-04-15 13:08
Makefile.extrawarn	7.1 KB	-rw-r--r--	2025-04-15 13:08
Makefile.gcc-plugins	2.59 KB	-rw-r--r--	2024-03-10 20:38
Makefile.headersinst	2.88 KB	-rw-r--r--	2024-03-10 20:38
Makefile.host	5.91 KB	-rw-r--r--	2024-03-10 20:38
Makefile.kasan	2.45 KB	-rw-r--r--	2024-03-10 20:38
Makefile.kcov	333 B	-rw-r--r--	2024-03-10 20:38
Makefile.kcsan	1004 B	-rw-r--r--	2024-03-10 20:38
Makefile.kmsan	208 B	-rw-r--r--	2024-03-10 20:38
Makefile.lib	21.1 KB	-rw-r--r--	2025-04-15 13:08
Makefile.modfinal	2.63 KB	-rw-r--r--	2025-04-15 13:08
Makefile.modinst	4.02 KB	-rw-r--r--	2025-04-15 13:08
Makefile.modpost	4.69 KB	-rw-r--r--	2024-03-10 20:38
Makefile.package	8.73 KB	-rw-r--r--	2025-04-15 13:08
Makefile.randstruct	511 B	-rw-r--r--	2024-03-10 20:38
Makefile.ubsan	779 B	-rw-r--r--	2024-03-10 20:38
Makefile.userprogs	1.59 KB	-rw-r--r--	2024-03-10 20:38
Makefile.vdsoinst	1.15 KB	-rw-r--r--	2025-04-15 13:08
Makefile.vmlinux	1.48 KB	-rw-r--r--	2024-03-10 20:38
Makefile.vmlinux_o	3.27 KB	-rw-r--r--	2024-03-10 20:38
as-version.sh	2.03 KB	-rwxr-xr-x	2024-03-10 20:38
asn1_compiler.c	35.32 KB	-rw-r--r--	2024-03-10 20:38
bloat-o-meter	3.77 KB	-rwxr-xr-x	2024-03-10 20:38
bootgraph.pl	5.64 KB	-rwxr-xr-x	2024-03-10 20:38
bpf_doc.py	31.73 KB	-rwxr-xr-x	2025-04-15 13:08
cc-can-link.sh	166 B	-rwxr-xr-x	2024-03-10 20:38
cc-version.sh	1.36 KB	-rwxr-xr-x	2024-03-10 20:38
check-git	298 B	-rwxr-xr-x	2024-03-10 20:38
check-sysctl-docs	3.66 KB	-rwxr-xr-x	2024-03-10 20:38
check-uapi.sh	15.05 KB	-rwxr-xr-x	2024-03-10 20:38
check_extable.sh	4.93 KB	-rwxr-xr-x	2024-03-10 20:38
checkdeclares.pl	1.1 KB	-rwxr-xr-x	2024-03-10 20:38
checkincludes.pl	1.94 KB	-rwxr-xr-x	2024-03-10 20:38
checkkconfigsymbols.py	15.75 KB	-rwxr-xr-x	2024-03-10 20:38
checkpatch.pl	233.78 KB	-rwxr-xr-x	2025-04-15 13:08
checkstack.pl	5.96 KB	-rwxr-xr-x	2024-03-10 20:38
checksyscalls.sh	7.51 KB	-rwxr-xr-x	2024-03-10 20:38
checkversion.pl	2.16 KB	-rwxr-xr-x	2024-03-10 20:38
cleanfile	3.46 KB	-rwxr-xr-x	2024-03-10 20:38
cleanpatch	5.06 KB	-rwxr-xr-x	2024-03-10 20:38
coccicheck	7.9 KB	-rwxr-xr-x	2024-03-10 20:38
config	4.67 KB	-rwxr-xr-x	2024-03-10 20:38
const_structs.checkpatch	1.4 KB	-rw-r--r--	2024-03-10 20:38
decode_stacktrace.sh	7.58 KB	-rwxr-xr-x	2024-03-10 20:38
decodecode	4.86 KB	-rwxr-xr-x	2024-03-10 20:38
depmod.sh	697 B	-rwxr-xr-x	2024-03-10 20:38
dev-needs.sh	6.07 KB	-rwxr-xr-x	2024-03-10 20:38
diffconfig	4.12 KB	-rwxr-xr-x	2024-03-10 20:38
documentation-file-ref-check	5.67 KB	-rwxr-xr-x	2024-03-10 20:38
export_report.pl	4.5 KB	-rwxr-xr-x	2024-03-10 20:38
extract-ikconfig	1.74 KB	-rwxr-xr-x	2024-03-10 20:38
extract-module-sig.pl	3.66 KB	-rwxr-xr-x	2024-03-10 20:38
extract-sys-certs.pl	3.75 KB	-rwxr-xr-x	2024-03-10 20:38
extract-vmlinux	1.66 KB	-rwxr-xr-x	2024-03-10 20:38
extract_xc3028.pl	44.62 KB	-rwxr-xr-x	2024-03-10 20:38
faddr2line	8.63 KB	-rwxr-xr-x	2024-03-10 20:38
file-size.sh	86 B	-rwxr-xr-x	2024-03-10 20:38
find-unused-docs.sh	1.27 KB	-rwxr-xr-x	2024-03-10 20:38
gcc-x86_32-has-stack-protector.sh	405 B	-rwxr-xr-x	2025-04-15 13:08
gcc-x86_64-has-stack-protector.sh	195 B	-rwxr-xr-x	2025-04-15 13:08
gen-randstruct-seed.sh	228 B	-rwxr-xr-x	2024-03-10 20:38
generate_initcall_order.pl	5.95 KB	-rwxr-xr-x	2024-03-10 20:38
generate_rust_analyzer.py	4.8 KB	-rwxr-xr-x	2024-03-10 20:38
generate_rust_target.rs	5.58 KB	-rw-r--r--	2024-03-10 20:38
get_abi.pl	25.36 KB	-rwxr-xr-x	2024-03-10 20:38
get_dvb_firmware	24.54 KB	-rwxr-xr-x	2024-03-10 20:38
get_feat.pl	14.61 KB	-rwxr-xr-x	2024-03-10 20:38
get_maintainer.pl	67.63 KB	-rwxr-xr-x	2024-03-10 20:38
gfp-translate	2.08 KB	-rwxr-xr-x	2025-04-15 13:08
git.orderFile	564 B	-rw-r--r--	2024-03-10 20:38
head-object-list.txt	1.36 KB	-rw-r--r--	2024-03-10 20:38
headerdep.pl	3.5 KB	-rwxr-xr-x	2024-03-10 20:38
headers_install.sh	2.76 KB	-rwxr-xr-x	2024-03-10 20:38
insert-sys-cert.c	13.08 KB	-rw-r--r--	2025-04-15 13:08
install.sh	986 B	-rwxr-xr-x	2024-03-10 20:38
jobserver-exec	2.56 KB	-rwxr-xr-x	2024-03-10 20:38
kallsyms.c	17.75 KB	-rw-r--r--	2025-04-15 13:08
kernel-doc	77.13 KB	-rwxr-xr-x	2025-04-15 13:08
ld-version.sh	1.82 KB	-rwxr-xr-x	2025-04-15 13:08
leaking_addresses.pl	12.84 KB	-rwxr-xr-x	2024-03-10 20:38
link-vmlinux.sh	7.66 KB	-rwxr-xr-x	2025-04-15 13:08
makelst	808 B	-rwxr-xr-x	2024-03-10 20:38
markup_oops.pl	7.92 KB	-rwxr-xr-x	2024-03-10 20:38
min-tool-version.sh	630 B	-rwxr-xr-x	2025-04-15 13:08
misc-check	509 B	-rwxr-xr-x	2024-03-10 20:38
mkcompile_h	642 B	-rwxr-xr-x	2024-03-10 20:38
mksysmap	2.08 KB	-rwxr-xr-x	2025-04-15 13:08
mkuboot.sh	414 B	-rwxr-xr-x	2024-03-10 20:38
module.lds.S	1.43 KB	-rw-r--r--	2025-04-15 13:08
modules-check.sh	443 B	-rwxr-xr-x	2024-03-10 20:38
nsdeps	1.63 KB	-rw-r--r--	2024-03-10 20:38
objdiff	2.83 KB	-rwxr-xr-x	2024-03-10 20:38
objdump-func	848 B	-rwxr-xr-x	2024-03-10 20:38
orc_hash.sh	316 B	-rw-r--r--	2024-03-10 20:38
pahole-version.sh	269 B	-rwxr-xr-x	2024-03-10 20:38
parse-maintainers.pl	4.54 KB	-rwxr-xr-x	2024-03-10 20:38
patch-kernel	9.95 KB	-rwxr-xr-x	2024-03-10 20:38
profile2linkerlist.pl	414 B	-rwxr-xr-x	2024-03-10 20:38
prune-kernel	912 B	-rwxr-xr-x	2024-03-10 20:38
recordmcount.c	17.51 KB	-rw-r--r--	2024-03-10 20:38
recordmcount.h	19.37 KB	-rw-r--r--	2024-03-10 20:38
recordmcount.pl	17.34 KB	-rwxr-xr-x	2024-03-10 20:38
relocs_check.sh	717 B	-rwxr-xr-x	2024-03-10 20:38
remove-stale-files	1.29 KB	-rwxr-xr-x	2024-03-10 20:38
rust_is_available.sh	9.48 KB	-rwxr-xr-x	2025-04-15 13:08
rust_is_available_bindgen_libclang.h	91 B	-rw-r--r--	2024-03-10 20:38
rust_is_available_test.py	17.7 KB	-rwxr-xr-x	2024-03-10 20:38
rustdoc_test_builder.rs	3.25 KB	-rw-r--r--	2024-03-10 20:38
rustdoc_test_gen.rs	9.48 KB	-rw-r--r--	2024-03-10 20:38
setlocalversion	5.18 KB	-rwxr-xr-x	2025-04-15 13:08
show_delta	3.04 KB	-rwxr-xr-x	2024-03-10 20:38
sign-file.c	9.93 KB	-rw-r--r--	2024-03-10 20:38
sorttable.c	7.68 KB	-rw-r--r--	2024-03-10 20:38
sorttable.h	12.85 KB	-rw-r--r--	2024-03-10 20:38
spdxcheck-test.sh	284 B	-rw-r--r--	2024-03-10 20:38
spdxcheck.py	15.23 KB	-rwxr-xr-x	2024-03-10 20:38
spdxexclude	417 B	-rw-r--r--	2024-03-10 20:38
spelling.txt	34.18 KB	-rw-r--r--	2024-03-10 20:38
sphinx-pre-install	25.07 KB	-rwxr-xr-x	2024-03-10 20:38
split-man.pl	604 B	-rwxr-xr-x	2024-03-10 20:38
stackdelta	1.84 KB	-rwxr-xr-x	2024-03-10 20:38
stackusage	794 B	-rwxr-xr-x	2024-03-10 20:38
subarch.include	647 B	-rw-r--r--	2024-03-10 20:38
syscallhdr.sh	1.89 KB	-rwxr-xr-x	2024-03-10 20:38
syscallnr.sh	1.45 KB	-rwxr-xr-x	2024-03-10 20:38
syscalltbl.sh	1.82 KB	-rwxr-xr-x	2025-04-15 13:08
tags.sh	10.73 KB	-rwxr-xr-x	2024-03-10 20:38
test_fortify.sh	2.23 KB	-rw-r--r--	2024-03-10 20:38
tools-support-relr.sh	726 B	-rwxr-xr-x	2024-03-10 20:38
unifdef.c	34.8 KB	-rw-r--r--	2024-03-10 20:38
ver_linux	2.59 KB	-rwxr-xr-x	2024-03-10 20:38
xen-hypercalls.sh	386 B	-rwxr-xr-x	2024-03-10 20:38
xz_wrap.sh	516 B	-rwxr-xr-x	2024-03-10 20:38

Rename

// SPDX-License-Identifier: GPL-2.0

//! Generates KUnit tests from saved `rustdoc`-generated tests.
//!
//! KUnit passes a context (`struct kunit *`) to each test, which should be forwarded to the other
//! KUnit functions and macros.
//!
//! However, we want to keep this as an implementation detail because:
//!
//!   - Test code should not care about the implementation.
//!
//!   - Documentation looks worse if it needs to carry extra details unrelated to the piece
//!     being described.
//!
//!   - Test code should be able to define functions and call them, without having to carry
//!     the context.
//!
//!   - Later on, we may want to be able to test non-kernel code (e.g. `core`, `alloc` or
//!     third-party crates) which likely use the standard library `assert*!` macros.
//!
//! For this reason, instead of the passed context, `kunit_get_current_test()` is used instead
//! (i.e. `current->kunit_test`).
//!
//! Note that this means other threads/tasks potentially spawned by a given test, if failing, will
//! report the failure in the kernel log but will not fail the actual test. Saving the pointer in
//! e.g. a `static` per test does not fully solve the issue either, because currently KUnit does
//! not support assertions (only expectations) from other tasks. Thus leave that feature for
//! the future, which simplifies the code here too. We could also simply not allow `assert`s in
//! other tasks, but that seems overly constraining, and we do want to support them, eventually.

use std::{
    fs,
    fs::File,
    io::{BufWriter, Read, Write},
    path::{Path, PathBuf},
};

/// Find the real path to the original file based on the `file` portion of the test name.
///
/// `rustdoc` generated `file`s look like `sync_locked_by_rs`. Underscores (except the last one)
/// may represent an actual underscore in a directory/file, or a path separator. Thus the actual
/// file might be `sync_locked_by.rs`, `sync/locked_by.rs`, `sync_locked/by.rs` or
/// `sync/locked/by.rs`. This function walks the file system to determine which is the real one.
///
/// This does require that ambiguities do not exist, but that seems fair, especially since this is
/// all supposed to be temporary until `rustdoc` gives us proper metadata to build this. If such
/// ambiguities are detected, they are diagnosed and the script panics.
fn find_real_path<'a>(srctree: &Path, valid_paths: &'a mut Vec<PathBuf>, file: &str) -> &'a str {
    valid_paths.clear();

let potential_components: Vec<&str> = file.strip_suffix("_rs").unwrap().split('_').collect();

find_candidates(srctree, valid_paths, Path::new(""), &potential_components);
    fn find_candidates(
        srctree: &Path,
        valid_paths: &mut Vec<PathBuf>,
        prefix: &Path,
        potential_components: &[&str],
    ) {
        // The base case: check whether all the potential components left, joined by underscores,
        // is a file.
        let joined_potential_components = potential_components.join("_") + ".rs";
        if srctree
            .join("rust/kernel")
            .join(prefix)
            .join(&joined_potential_components)
            .is_file()
        {
            // Avoid `srctree` here in order to keep paths relative to it in the KTAP output.
            valid_paths.push(
                Path::new("rust/kernel")
                    .join(prefix)
                    .join(joined_potential_components),
            );
        }

// In addition, check whether each component prefix, joined by underscores, is a directory.
        // If not, there is no need to check for combinations with that prefix.
        for i in 1..potential_components.len() {
            let (components_prefix, components_rest) = potential_components.split_at(i);
            let prefix = prefix.join(components_prefix.join("_"));
            if srctree.join("rust/kernel").join(&prefix).is_dir() {
                find_candidates(srctree, valid_paths, &prefix, components_rest);
            }
        }
    }

assert!(
        valid_paths.len() > 0,
        "No path candidates found. This is likely a bug in the build system, or some files went \
        away while compiling."
    );

if valid_paths.len() > 1 {
        eprintln!("Several path candidates found:");
        for path in valid_paths {
            eprintln!("    {path:?}");
        }
        panic!(
            "Several path candidates found, please resolve the ambiguity by renaming a file or \
            folder."
        );
    }

valid_paths[0].to_str().unwrap()
}

fn main() {
    let srctree = std::env::var("srctree").unwrap();
    let srctree = Path::new(&srctree);

let mut paths = fs::read_dir("rust/test/doctests/kernel")
        .unwrap()
        .map(|entry| entry.unwrap().path())
        .collect::<Vec<_>>();

// Sort paths.
    paths.sort();

let mut rust_tests = String::new();
    let mut c_test_declarations = String::new();
    let mut c_test_cases = String::new();
    let mut body = String::new();
    let mut last_file = String::new();
    let mut number = 0;
    let mut valid_paths: Vec<PathBuf> = Vec::new();
    let mut real_path: &str = "";
    for path in paths {
        // The `name` follows the `{file}_{line}_{number}` pattern (see description in
        // `scripts/rustdoc_test_builder.rs`). Discard the `number`.
        let name = path.file_name().unwrap().to_str().unwrap().to_string();

// Extract the `file` and the `line`, discarding the `number`.
        let (file, line) = name.rsplit_once('_').unwrap().0.rsplit_once('_').unwrap();

// Generate an ID sequence ("test number") for each one in the file.
        if file == last_file {
            number += 1;
        } else {
            number = 0;
            last_file = file.to_string();

// Figure out the real path, only once per file.
            real_path = find_real_path(srctree, &mut valid_paths, file);
        }

// Generate a KUnit name (i.e. test name and C symbol) for this test.
        //
        // We avoid the line number, like `rustdoc` does, to make things slightly more stable for
        // bisection purposes. However, to aid developers in mapping back what test failed, we will
        // print a diagnostics line in the KTAP report.
        let kunit_name = format!("rust_doctest_kernel_{file}_{number}");

// Read the test's text contents to dump it below.
        body.clear();
        File::open(path).unwrap().read_to_string(&mut body).unwrap();

// Calculate how many lines before `main` function (including the `main` function line).
        let body_offset = body
            .lines()
            .take_while(|line| !line.contains("fn main() {"))
            .count()
            + 1;

use std::fmt::Write;
        write!(
            rust_tests,
            r#"/// Generated `{name}` KUnit test case from a Rust documentation test.
#[no_mangle]
pub extern "C" fn {kunit_name}(__kunit_test: *mut kernel::bindings::kunit) {{
    /// Overrides the usual [`assert!`] macro with one that calls KUnit instead.
    #[allow(unused)]
    macro_rules! assert {{
        ($cond:expr $(,)?) => {{{{
            kernel::kunit_assert!("{kunit_name}", "{real_path}", __DOCTEST_ANCHOR - {line}, $cond);
        }}}}
    }}

/// Overrides the usual [`assert_eq!`] macro with one that calls KUnit instead.
    #[allow(unused)]
    macro_rules! assert_eq {{
        ($left:expr, $right:expr $(,)?) => {{{{
            kernel::kunit_assert_eq!("{kunit_name}", "{real_path}", __DOCTEST_ANCHOR - {line}, $left, $right);
        }}}}
    }}

// Many tests need the prelude, so provide it by default.
    #[allow(unused)]
    use kernel::prelude::*;

// Unconditionally print the location of the original doctest (i.e. rather than the location in
    // the generated file) so that developers can easily map the test back to the source code.
    //
    // This information is also printed when assertions fail, but this helps in the successful cases
    // when the user is running KUnit manually, or when passing `--raw_output` to `kunit.py`.
    //
    // This follows the syntax for declaring test metadata in the proposed KTAP v2 spec, which may
    // be used for the proposed KUnit test attributes API. Thus hopefully this will make migration
    // easier later on.
    kernel::kunit::info(format_args!("    # {kunit_name}.location: {real_path}:{line}\n"));

/// The anchor where the test code body starts.
    #[allow(unused)]
    static __DOCTEST_ANCHOR: i32 = core::line!() as i32 + {body_offset} + 1;
    {{
        {body}
        main();
    }}
}}

"#
        )
        .unwrap();

write!(c_test_declarations, "void {kunit_name}(struct kunit *);\n").unwrap();
        write!(c_test_cases, "    KUNIT_CASE({kunit_name}),\n").unwrap();
    }

let rust_tests = rust_tests.trim();
    let c_test_declarations = c_test_declarations.trim();
    let c_test_cases = c_test_cases.trim();

write!(
        BufWriter::new(File::create("rust/doctests_kernel_generated.rs").unwrap()),
        r#"//! `kernel` crate documentation tests.

const __LOG_PREFIX: &[u8] = b"rust_doctests_kernel\0";

{rust_tests}
"#
    )
    .unwrap();

write!(
        BufWriter::new(File::create("rust/doctests_kernel_generated_kunit.c").unwrap()),
        r#"/*
 * `kernel` crate documentation tests.
 */

#include <kunit/test.h>

{c_test_declarations}

static struct kunit_case test_cases[] = {{
    {c_test_cases}
    {{ }}
}};

static struct kunit_suite test_suite = {{
    .name = "rust_doctests_kernel",
    .test_cases = test_cases,
}};

kunit_test_suite(test_suite);

MODULE_LICENSE("GPL");
"#
    )
    .unwrap();
}