KTF is a small and simple OS kernel, that enables writing low-level software tests for supported machine architectures (currently: x86-64).

• Machine architecture: x86-64, x86-32 in the baking
• SMP support with basic Per-CPU pages
• (very) Basic Physical Memory Management (PMM) and Virtual Memory Management (VMM)
• Very basic slab allocator
• Local APIC support
• Initial MP tables parsing
• Basic ACPI tables parsing
• Simple UART driver
• (very) Simple VGA driver

Some more features are in the making. Check out the issues.

The quick start is to run the following commands. The content of the file tests/test.c will be executed. Note, the last command will block.

Build a ktf.iso from scratch, in the docker container.

make clean
make docker:ktf.iso

Boot the resulting image:

make boot

You may need to install the following (unless you already have it):

• GRUB2 bootloader tools - grub2-common package (e.g. apt install grub2-common)
• ISO generation tools - xorriso, grub-pc-bin, and mtools package (e.g. apt install xorriso grub-pc-bin mtools)

• Native

make

• Docker

make docker:all

• Native

make ktf.iso

• Docker

make docker:ktf.iso

The make command generates the kernel64.bin multiboot-compatible ELF file, that you can directly boot with QEMU. The make ktf.iso command takes the kernel64.bin, places it in grub/boot/ directory hierarchy and generates a ktf.iso out of the grub/ (using grub/boot/grub/grub.cfg as a default GRUB config).

KTF builds and runs on Fedora, but you will need to tweak some of the commands. Create a Makeconf.local file with the following content (tested with Fedora 32):

DIST=$(shell grep NAME= /etc/os-release | cut -d= -f2)
ifeq ($(DIST),Fedora)
GRUB_FILE := grub2-file
GRUB_MKIMAGE := grub2-mkimage
GRUB_MODULES += normal
QEMU_BIN := qemu-kvm
DOCKER_MOUNT_OPTS := :Z
endif

Main Makefile has several targets that make booting KTF with QEMU easier. The Makefile detects if the host system is linux and enables KVM support if so. Default parameters for QEMU can be found in the Makefile under QEMU_PARAMS variable.

For booting run:

make boot

For debugging run:

make boot_debug

For debugging with gdb run:

make gdb

Use the following guest domain config example for booting KTF with Xen:

name="kernel64"
builder="hvm"
memory=1024

serial= [ 'file:/tmp/kernel.log', 'pty' ]

disk = [ '/home/user/ktf.iso,,hdc,cdrom' ]

on_reboot = "destroy"

vcpus=1

You need to generate a bootable ISO for this.

New tests can be added by adding a new function in a file in the tests folder. Each test signature must be the same as test_fn provided in test.h. Tests can be enabled in grub.cfg by adding the option with key tests and values the comma-separated list of function names, such as tests=test1,test2,unit_tests.

The style for this project is defined in .clang-format file in the main directory of this repository.

Use the following command to apply the style automatically to the file you modify:

clang-format -style=file -Werror -i MODIFIED_FILE

For more information refer to: https://clang.llvm.org/docs/ClangFormat.html

This project uses https://github.com/DoozyX/clang-format-lint-action action workflow to detect style mismatches automatically. For more information refer to: https://github.com/marketplace/actions/clang-format-lint

docker build -t clang-format-lint github.com/DoozyX/clang-format-lint-action

This has to be done only once.

make style

• first, download the one-line-scan base image

docker build -t one-line-scan \
    https://raw.githubusercontent.com/awslabs/one-line-scan/master/tools/Dockerfile

• create the KTF specific one-line-scan image, including necessary tools for building

 docker build -t ktf-one-line-scan \
    --build-arg USER_ID=$(id -u) \
    --build-arg GROUP_ID=$(id -g) \
    --build-arg USER=$USER \
    --file tools/docker/OnelineScanDockerfile .

This has to be done only once.

• per default, one-line-scan scans against the diff between HEAD and origin/mainline commit

make onelinescan

• Parts of the KTF project are inspired by and based on XTF project [1] developed by Andrew Cooper of Citrix.

[1] https://xenbits.xenproject.org/docs/xtf/

See CONTRIBUTING for more information.

Maintainers and users of KTF communicate in Slack. We set up a Slack workspace and we're actively sharing ideas, bugs and anything related to KTF there. Feel free to join us: Slack invite link

This project is licensed under the BSD 2-Clause License.