{"id":16320419,"url":"https://github.com/daniel-thompson/kgdbtest","last_synced_at":"2026-05-19T06:02:50.518Z","repository":{"id":151166344,"uuid":"107880249","full_name":"daniel-thompson/kgdbtest","owner":"daniel-thompson","description":"A collection of fully automated kernel tests that test aspects of the kernel that rely upon having access to a console","archived":false,"fork":false,"pushed_at":"2024-05-07T10:02:48.000Z","size":275,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-05-07T11:25:33.897Z","etag":null,"topics":["kdb","kgdb","linux","testing"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/daniel-thompson.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-10-22T15:52:01.000Z","updated_at":"2024-05-07T11:25:35.826Z","dependencies_parsed_at":null,"dependency_job_id":"2089e227-6715-49d3-b87f-9c638e972a40","html_url":"https://github.com/daniel-thompson/kgdbtest","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-thompson%2Fkgdbtest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-thompson%2Fkgdbtest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-thompson%2Fkgdbtest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-thompson%2Fkgdbtest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/daniel-thompson","download_url":"https://codeload.github.com/daniel-thompson/kgdbtest/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219865148,"owners_count":16555931,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["kdb","kgdb","linux","testing"],"created_at":"2024-10-10T22:44:16.437Z","updated_at":"2025-10-25T19:31:07.982Z","avatar_url":"https://github.com/daniel-thompson.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"kgdbtest - kernel console tests\n===============================\n\nCollection of fully automated kernel tests that test aspects of the\nkernel that rely upon having access to a console. In particular this\nallows us to test tools such as kgdb/kdb.\n\nkgdbtest is free software; you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation; either [version 2 of the\nLicense](LICENSE.md), or (at your option) any later version.\n\nPrerequisites\n-------------\n\nkgdbtest requires a few special command lines tools together with some\nadditional python libraries.\n\nOn Fedora systems these can be installed as follows:\n\n~~~\nsudo dnf install -y \\\n\tpython3 \\\n\tpython3-pexpect \\\n\tpython3-pytest \\\n\tsocat\n~~~\n\nLikewise on debian systems:\n\n~~~\nsudo apt install -y \\\n\tpython3 \\\n\tpython3-pexpect \\\n\tpython3-pytest \\\n\tsocat\n~~~\n\nBuildroot\n---------\n\nkgdbtest relies on buildroot filesystems, normally loaded as an\ninitramfs. kgdbtest includes .config files to regenerate the\nfilesystem from scratch. The Makefile also has a few convenience\nrules to help construct the filesystem.\n\n~~~\nARCH=arm make buildroot\nARCH=arm64 make buildroot\nARCH=mips make buildroot\nARCH=riscv make buildroot\nARCH=x86 make buildroot\n~~~\n\nkgdbtest is configured to use a known working buildroot tree but\ncan adopt a different tree is desired:\n\n~~~\nARCH=arm64 BUILDROOT=/path/to/buildroot/ make buildroot-config\nARCH=arm64 make buildroot-build buildroot-tidy\n~~~\n\n`buildroot-tidy` is a special rule, that saves diskspace by deleting\nfiles that are not needed to run kgdbtest.\n\nOnce `buildroot-config` has been run it is possible to run all buildroot\nrules directly from the build directory:\n\n~~~\nmake -C buildroot/arm64 menuconfig\n~~~\n\nChoosing a cross-toolset\n------------------------\n\nkgdbtest does not impose any additional requirements beyond the\nnormal kbuild toolset discovery variables such as `ARCH` and\n`CROSS_COMPILE`.\n\nIn general you should use whatever toolset you usually use for kernel\nbuilds as the basis for any kgdb testing that you undertake.\n\nIf you are working on an architecture for which you do not have a\ncross-compiler already installed then the buildroot tools for that\narchitecture can be used. For example:\n\n~~~\nARCH=arm\nCROSS_COMPILE=$PWD/buildroot/arm/host/bin/arm-linux-\nexport ARCH CROSS_COMPILE\n~~~\n\nRunning tests\n-------------\n\nkgdbtest currently relies upon external environment variables. These are\nset up automatically by the `Makefile`.\n\nAssuming `$KGDBTESTDIR` points to the directory where kgdbtest is\ninstalled, then from a pristine (or mrproper'ed) kernel source\ndirectory try:\n\n~~~\nmake -C $KGDBTESTDIR\n~~~\n\nThis will run the default `test` rule, which will scan kgdbtest for all \navailable tests and run them.\n\nThe Makefile behaviour can be made more verbose using `V=1` or `V=2`. At\nlevel 1 the names of each test case are displayed as the test is run.\nAt level 2 all stdio capture is disabled, meaning the pexpect output\nwill be displayed live as the test runs.\n\nThe set of tests can be restricted using `K=\u003ccondition\u003e`. A condition is\neither a sub-string to match in the test name or a python operator. For\nexample:\n\n~~~\nmake -C $KGDBTESTDIR V=2 K='kgdb and smoke'\n~~~\n\ngit bisect\n----------\n\nBy default kgdbtest will automatically configure and build the kernel\nunder test. This can be problematic for running automated git bisection\n(`git bisect run`) because git cannot easily distinguish between an\nuntestable kernel revision and a failed test.\n\nThere are multiple ways to work around this but one simple approach is\nto run the test suite twice, one with a \"smoke test\" job and the other\nto run real tests. If the smoke test fails we can return an error\ncode that causes the bisection to skip the selected version (without\nmarking it good or bad).\n\nFor example the following simple wrapper script allows kgdbtest to be\nused to manage a bisect.\n\n~~~ sh\n#\n# kgdbtest-wrapper.sh\n#\n# Help run kgdbtest from git bisect run. For example:\n#\n#   git bisect run kgdbtest-wrapper.sh K='kdb and tab_complete' V=2\n#\n\n# Run a basic nop test... skip this revision if this fails\nmake -C ../kgdbtest \"$@\" K='kdb and nop'\n[ 0 -ne $? ] \u0026\u0026 exit 125\n\n# Now run the test that was requested\nmake -C ../kgdbtest \"$@\"\n[ 0 -ne $? ] \u0026\u0026 exit 1\n~~~\n\nInteracting with the kernel debugger\n------------------------------------\n\nkgdbtest also provides a quick means to fire up a kernel and interact\nwith a kernel debugger. This is useful for ad-hoc experiments and to\ngather information to add new tests to kgdbtest itself.\n\nTo launch a kernel and interact with kdb try:\n\n~~~\nmake -C $KGDBTESTDIR interact\n~~~\n\nAlternatively if you wish to interact via kgdb try:\n\n~~~\nmake -C $KGDBTESTDIR interact K=kgdb\n~~~\n\nThis will launch the kernel (which will stop and wait for connection\nfrom remote gdb). In the scroll back buffer you should find a canned\ngdb command to run from another terminal. For example, for an arm64\nkernel the canned command will look like (and can easily be found by\nsearching for the `\u003e\u003e\u003e ` prefix:\n\n~~~\n...\n+ (cd mod-rootfs; find . | cpio -H newc -AoF ../rootfs.cpio)\n101159 blocks\n+ gzip -f rootfs.cpio\n\n\u003e\u003e\u003e (cd /home/drt/Development/Kernel/linux/build-arm64; aarch64-linux-gnu-gdb vmlinux -ex \"set pagination 0\" -ex \"target extended-remote |socat - UNIX:ttyS1.sock\")\n\n+| qemu-system-aarch64 -accel tcg,thread=multi  -M virt,gic_version=3 -cpu cortex-a57 -kernel arch/arm64/boot/Image -m 1G -smp 2 -nographic -monitor none -chardev stdio,id=mon,mux=on,signal=off -serial chardev:mon -chardev socket,id=ttyS1,path=ttyS1.sock,server,nowait -serial chardev:ttyS1 -initrd rootfs.cpio.gz -append \" console=ttyAMA0,115200 kgdboc=ttyAMA1 nokaslr kgdbwait\"\n[    0.000000] Booting Linux on physical CPU 0x0000000000 [0x411fd070]\n...\n~~~\n\nFinally the `nowait` keyword is also available and will prevent\n`kgdbwait` appearing on the kernel command line when the system\nboots:\n\n~~~\nmake -C $KGDBTESTDIR interact K='nowait'\nmake -C $KGDBTESTDIR interact K='kgdb nowait'\n~~~\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaniel-thompson%2Fkgdbtest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaniel-thompson%2Fkgdbtest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaniel-thompson%2Fkgdbtest/lists"}