Package: kmax
The kmax tool suiteGetting startedInstalling the kmax tool suiteKicking the tiresUsingklocalizer --repairon patchesUsingkoverageUsingkismetAdditional documentationBugs foundCreditsThe kmax tool suiteGetting startedInstalling the kmax tool suiteInstall the requiste python tools (the kmax tool suite currently depends on python 3.8 or later), setup a python virtual environment (recommended), and finally install the tools from pip.sudo apt install -y python3 python3-pip python3-venv
python3 -m venv ~/env_kmax/
source ~/env_kmax/bin/activate
pip3 install kmaxInstructions to install from source can be found in theadvanced documentation.Kicking the tiresInstall dependencies for compiling Linux source, then download and enter the Linux source:sudo apt install -y flex bison bc libssl-dev libelf-dev
cd ~/
wget https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.16.tar.xz
tar -xvf linux-5.16.tar.xz
cd ~/linux-5.16/Runklocalizer --repairto modifyallnoconfigso that builds a given compilation unit:make ARCH=x86_64 allnoconfig
klocalizer --repair .config -o allnoconfig_repaired --include drivers/usb/storage/alauda.o
KCONFIG_CONFIG=allnoconfig_repaired make ARCH=x86_64 olddefconfig clean drivers/usb/storage/alauda.oYou should seeCC      drivers/usb/storage/alauda.oat the end of the build.Usingklocalizer --repairon patchesThis tool will automatically "fix" your .config file so that it builds the lines from a given patchfile (or any specific files or file:line pairs).  To use it, first installSuperC, whichklocalizerdepends on for finding#ifdefconstraints:sudo apt-get install -y libz3-java libjson-java sat4j unzip flex bison bc libssl-dev libelf-dev xz-utils lftp
wget -O - https://raw.githubusercontent.com/appleseedlab/superc/master/scripts/install.sh | bash
export COMPILER_INSTALL_PATH=$HOME/0day
export CLASSPATH=/usr/share/java/org.sat4j.core.jar:/usr/share/java/json-lib.jar:${HOME}/.local/share/superc/z3-4.8.12-x64-glibc-2.31/bin/com.microsoft.z3.jar:${HOME}/.local/share/superc/JavaBDD/javabdd-1.0b2.jar:${HOME}/.local/share/superc/xtc.jar:${HOME}/.local/share/superc/superc.jar:${CLASSPATH}
export PATH=${HOME}/.local/bin/:${PATH}Too see it in action, start with a clone of the linux repository and create a patch file:cd ~/
git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
cd ~/linux/
git checkout 6fc88c354f3af
git show > 6fc88c354f3af.diffNow try using repair to update allnoconfig, which doesn't build all lines from the patch.  After repair, the resulting configuration file builds the lines affected by the patch.  The last command builds the files affected by the patch, which would have failed with an unrepaired allnoconfig.make ARCH=x86_64 allnoconfig
klocalizer --repair .config -a x86_64 --include-mutex 6fc88c354f3af.diff
KCONFIG_CONFIG=0-x86_64.config make ARCH=x86_64 olddefconfig clean kernel/bpf/cgroup.o net/ipv4/af_inet.o net/ipv4/udp.o net/ipv6/af_inet6.o net/ipv6/udp.o
koverage --config 0-x86_64.config --arch x86_64 --check-patch 6fc88c354f3af.diff -o coverage_results.json
cat coverage_results.jsonWhen using--include-mutex, the generated configuration files are exported asNUM-ARCH.config, since several configuration files may be needed when patches contain mutually-exclusive lines.Usingklocalizer --save-dimacsandklocalizer --save-smtThis tool extracts a DIMACS or a SMT formula.
Therefore, execute the following commands in the root directory of your Linux kernel:klocalizer -a x86_64 --save-dimacs <Path>
klocalizer -a x86_64 --save-smt <Path>Note that<Path>should be replaced by the absolute path to the file, the formulae should be written to.
If you intend to use a Docker container, feel free to use the Dockerfile provided inAdvanced Usage.Usingkoveragekoveragechecks whether a Linux configuration file includes a set of source file:line pairs for compilation.  This following checks whether lines 256 and 261 ofkernel/fork.care included for compilation by Linux v5.16 allyesconfig.cd ~/linux-5.16/
make.cross ARCH=x86_64 allyesconfig
koverage --config .config --arch x86_64 --check kernel/fork.c:[259,261] -o coverage_results.json
make allnoconfig; klocalizer -v --repair .config --include kernel/fork.c:[259]; rm -rf koverage_files/; koverage -v -a x86_64 --config .config --check kernel/fork.c:[259] -o coverage.outThe coverage results are incoverage_results.json, which indicate that line 259 is included while 261 is excluded by allyesconfig, because the lines are under mutually-exclusive#ifdefbranches.Use--check-patch file.patchto check coverage of all source lines affected by a given patch.UsingkismetThis tool will check for unmet dependency bugs inKconfig specificationsdue to reverse dependencies overriding direct dependencies.Runkismeton the root of the Linux source tree.kismet --linux-ksrc="${HOME}/linux-5.16/" -a=x86_64Once finished (it can take about an hour on a commodity desktop), kismet will produce three outputs:A summary of the results inkismet_summary_x86_64.txtA list of results for eachselectconstruct inkismet_summary_x86_64.csv(UNMET_ALARMdenotes the buggy ones)A list of.configfiles meant to exercise each bug inkismet-test-cases/Technical details can be found in in thekismet documentationand thepublicationonkclauseandkismet.  The experimentreplication scriptcan be used to run kismet on all architectures' Kconfig specifications.Additional documentationAdvanced UsageBugs foundBugs Foundby our toolsCreditsThe main developers of this project have beenPaul Gazzillo(kextract,kclause,kmax,klocalizer),Necip Yildiran(kismet,krepair,koverage),Jeho Oh(kclause), andJulian Braha(koverage).Julia Lawallhas posed new applications and provided invaluable advice, feedback, and support.  Thanks to all the users who have contributed code and issues.  Special thanks to theIntel 0-dayteam for working toincludekismetinto the kernel test robotand for their valuable feedback.  This work is funded in part by the National Science Foundation under awardsCCF-1840934andCCF-1941816.