Lightbox is an aarch64 qemu based kernel running and debug environment for the linux kernel.
Everything is intergrated and configured ready to run.
You can start to run and debug the linux kernel from the very first assembly code just with the start-kernel.sh
script.
Both linux kernel and android common kernel are supported, and you can choose to use gdb-tui or ddd as the debugger's front-end.
The envionment include:
- prebuilt aarch64 qemu excutables (for x86 host)
- prebuilt aarch64 gdb with tui enabled (for x86 host)
- prebuilt aarch64 initramfs image
- support running with linux kernel
- support running with android common kernel
- support debug with gdb for aarch64
- support debug with ddd for aarch64
- support 9pfs share folder
Host environment tested:
- Intel x86 PC + Ubuntu 20.04 (OK)
- Raspberry Pi 4B + Ubuntu 22.04 (OK)
- Macbook M1 + UTM (virtual machine) + Ubuntu 20.04 (OK)
for x86 Host
To build arm64 linux kernel on x86 machine, you need install the cross-compiler:
sudo apt install gcc-aarch64-linux-gnu
gdb and qemu are already built as binaries. lightbox will just use the prebuild ones, and nothing else is needed.
for arm64 Host
When your host is arm64 (raspberry pi or macbook m1), you need install GDB and QEMU:
sudo apt install gdb
sudo apt install qemu qemu-system-arm
Install tmux
For better experience, lightbox will use tmux as default terminal when it is installed.
To install tmux:
sudo apt install tmux
When tmux is not installed, lightbox will use gnome as default termninal, you can also choose to use xfce4 or cli terminal seperately.
Install DDD
By default, lightbox use gdb as default debugger with tui. You can also choose to use ddd as debugger with gui.
To install ddd:
sudo apt install ddd
git clone https://github.com/kernel-cyrus/lightbox.git
Download linux kernel
git clone https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
Apply a patch
cd linux
git apply .../lightbox/patches/linux-mainline.patch
Build the kernel
ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- make lightbox_defconfig
ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- make Image scripts_gdb
Download android common kernel
repo init -u https://android.googlesource.com/kernel/manifest -b common-android-mainline
repo sync
Apply a patch
cd common
git apply .../lightbox/patches/android-mainline.patch
Build the kernel
BUILD_CONFIG=common/build.config.lightbox build/build.sh
Command Format
./start-kernel.sh
--kernel=<kernel dir> # kernel repo dir (REQUIRED)
--initrd=<initrd file path> # initrd file (OPTIONAL)
--with=<"gdb" or "ddd"> # use gdb or ddd as debugger (OPTIONAL)
--append=<kernel cmdline> # append extra cmdline (OPTIONAL)
--share=<share folder path> # host share folder (OPTIONAL)
--terminal=<terminal to use> # default: tmux (OPTIONAL)
# options: tmux / gnome / xfce4 / cli-qemu / cli-gdb
Run kernel with gdb
./start-kernel --kernel=<kernel_dir> --with=gdb
Run kernel with ddd
sudo apt install ddd
./start-kernel --kernel=<kernel_dir> --with=ddd
Run with your own initramfs image
./start-kernel --kernel=<kernel_dir> --initrd=<initramfs_file_path>
Customize kernel cmdline
./start-kernel --kernel=<kernel_dir> --append="earlycon"
Share host files
The default share folder is "./host-share", and it will be automatically mounted when guest os bootup.
You can also use a custom share folder:
./start-kernel --kernel=<kernel_dir> --share="./host-share"
Support for gnome and xfce4 terminals
When tmux is not installed, lightbox will use gnome as default terminal.
In some cases when your host os is not GNOME, you may choose to use xfce4 terminal:
./start-kernel --kernel=<kernel_dir> --terminal="xfce4"
Run in cli mode
For pure cli environment like ssh without desktop display, and also tmux is not installed, you can start qemu and gdb seperately.
Start qemu from one cli session:
./start-kernel --kernel=<kernel_dir> --terminal="cli-qemu"
And then start gdb in another cli session:
./start-kernel --kernel=<kernel_dir> --terminal="cli-gdb"
Author: Cyrus Huang