# lightbox

**Repository Path**: tianqinjing/lightbox

## Basic Information

- **Project Name**: lightbox
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2024-08-27
- **Last Updated**: 2024-08-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

Lightbox
=============================

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.

![Snapshot](https://raw.githubusercontent.com/kernel-cyrus/lightbox/master/snapshots/snapshot.png)

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)

Setup Environment
-----------------------------

**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
```

Download Lightbox
-----------------------------

```
git clone https://github.com/kernel-cyrus/lightbox.git
```

Build Linux Kernel
-----------------------------

**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
```

Build Android Common Kernel
-----------------------------

**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
```

Start Kernel
-----------------------------

**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"
```

Contact
-----------------------------

Author: Cyrus Huang

Github: <https://github.com/kernel-cyrus/lightbox>