linux distribution (ISO) for XRSH
Go to file
David Humphrey b1edf4b44f
Merge pull request #6 from wokwi/buildroot-2021
Update buildroot version to latest
2021-02-22 20:08:52 -05:00
bios Include BIOS files needed to boot from https://github.com/copy/v86/tree/master/bios 2019-02-12 17:01:07 -05:00
buildroot-v86 Buildroot 2021-02 (rc 2) 2021-02-19 16:21:48 +02:00
.dockerignore Initial commit, based on prev work in https://github.com/humphd/next 2019-02-06 19:26:34 -05:00
.gitignore Initial commit, based on prev work in https://github.com/humphd/next 2019-02-06 19:26:34 -05:00
Dockerfile Buildroot 2021-02 (rc 2) 2021-02-19 16:21:48 +02:00
LICENSE Initial commit, based on prev work in https://github.com/humphd/next 2019-02-06 19:26:34 -05:00
README.md Add build.sh script 2019-04-26 13:40:09 -04:00
build.sh Add build.sh script 2019-04-26 13:40:09 -04:00

README.md

Browser VM

A custom Buildroot config for a Linux x86 VM, meant to be run in the browser as part of browser-shell. The resulting Linux ISO is meant to be run under emulation in the browser via v86, and includes:

  • a custom Linux 4.15 kernel, which strips out many unnecessary drivers, modules, etc. and adds Plan 9 filesystem sharing
  • a root filesystem and Unix commands via BusyBox
  • an ISO-based bootloader (i.e., we create a "DVD" that is booted by v86)

Following the Buildroot customization docs we create a folder buildroot-v86/ with all the necessary config files, filesystem overlay, and scripts necessary to build our distribution.

Running via Docker

To build the Docker image use the build.sh script, or:

$ docker build -t buildroot .

And then to run the build:

$ docker run \
    --rm \
    --name build-v86 \
    -v $PWD/dist:/build \
    -v $PWD/buildroot-v86/:/buildroot-v86 \
    buildroot

NOTE: we define two volumes to allow the container to access the v86 config, and also to write the ISO once complete. In the above I've used $PWD, but you can use any absolute path.

When the build completes, an ISO file will be places in ./dist/v86-linux.iso in your source tree (i.e., outside the container).

If you need to re-configure things, instead of just running the build, do the following:

$ docker run \
    --rm \
    --name build-v86 \
    -v $PWD/dist:/build \
    -v $PWD/buildroot-v86/:/buildroot-v86 \
    -ti \
    --entrypoint "bash" \
    buildroot

Now in the resulting bash terminal, you can run make menuconfig and other make commands.

buildroot-v86/ Layout

We define a v86 buildroot "board" via the following files and directories:

+-- board/
    +-- v86
        +-- linux.config        # our custom Linux kernel config (make linux-menuconfig)
        +-- post_build.sh       # script to copy ISO file out of docker container
        +-- rootfs_overlay/     # overrides for files in the root filesystem
            +-- etc/
                +-- inittab     # we setup a ttyS0 console terminal to auto-login
                +-- fstab       # we auto-mount the Plan 9 Filer filesystem to /mnt
    +-- configs/
        +-- v86_defconfig       # our custom buildroot config (make menuconfig)
    +-- Config.in               # empty, but required https://buildroot.org/downloads/manual/manual.html#outside-br-custom
    +-- external.mk             # empty, but required https://buildroot.org/downloads/manual/manual.html#outside-br-custom
    +-- external.desc           # our v86 board config for make
    +-- build-v86.sh            # entrypoint for Docker to run our build

If you need or want to update these config files, do the following:

$ make BR2_EXTERNAL=/buildroot-v86 v86_defconfig
$ make menuconfig
...
$ make savedefconfig
$ make linux-menuconfig
...
$ make linux-savedefconfig

Configuration Notes

These are the options I set when configuring buildroot for v86. I'm only specifying the things I set.

$ cd buildroot-2018.02
$ make menucofing

Then follow these config steps in the buildroot config menu (NOTE: these docs may have drifted from the actual config in the source, so consult that first):

Target options

  • Target Architecture: i386
  • Target Architecture Variant: pentium mobile (Pentium with MMX, SSE)

Build options

  • Enable compiler cache (not strictly necessary, but helps with rebuilds)

Toolchain

  • C library: uLibc-ng (I'd like to experiment with musl too)

System configuration

  • remount root filesystem read-write during boot (I think this is unnecessary)
  • Root filesystem overlay directories: /build/overlay-fs (for etc/inittab)

Kernel

  • Linux Kernel: true
  • Defconfig name: i386
  • Kernel binary format: bzImage (vmlinux seemed to break on boot)

Target packages

Need to figure this out. I tried adding imagemagik, git, uemacs, but they are all adding too much size to the image.

Filesystem images

  • cpio the root filesystem (for use as an initial RAM filesystem)
  • initial RAM filesystem linked into the linux kernel (not sure I need this, trying without...)
  • iso image
    • Use initrd
  • tar the root filesystem Compression method (no compression)

Bootloaders

  • syslinux
    • install isolinux

Linux configuration

Now configure the Linux Kernel:

$ make linux-menuconfig

And set the following options to accomplish this:

CONFIG_NET_9P=y
CONFIG_NET_9P_VIRTIO=y
CONFIG_9P_FS=y
CONFIG_9P_FS_POSIX_ACL=y
CONFIG_PCI=y
CONFIG_VIRTIO_PCI=y
CONFIG_PCI=y
CONFIG_VIRTIO_PCI=y

Processor type and features

  • Processor family (Pentium-Pro) also tried Pentium M before.

Bus options (PCI, etc.)

  • PCI Debugging: true (I want to see what's happening with PCI errors, normally not needed)

Networking support

  • Plan 9 Resource Sharing Support (9P2000) (built into kernel * vs. M)
    • 9P Virtio Transport (* - make this is on, it won't exist if virtio is off)
    • Debug information (* - optional)

Device Drivers

  • Virtio drivers
    • PCI driver for virtio devices (built into kernel * vs. M)
      • Support for legacy virtio draft 0.9.X and older devices (New)
    • Platform bus driver for memory mapped virtio devices (* vs. M) - not sure I need this...
      • Memory mapped virtio devices parameter parsing - or this...

Filesystems

  • Caches

    • General filesystem local caching manager (*)
      • Filesystem caching on files (*)
  • Network File Systems

    • Plan 9 Resource Sharing Support (9P2000) (*)
      • Enable 9P client caching support
      • 9P Posic Access Control Lists

Now run make

When it finishes, the built image is in ./output/images.