Embedded ASCII Slot Machine

Embedded ASCII Slot Machine is a small (but easily extendable) collection of classic ASCII games running on top of a tiny linux kernel bundled into a single bootable iso for aarch64 and x86_64 architectures. The project was meant to be for fun and learning.

Tetris

Space Invaders

Snake

TL;DR

scripts/setupenv.sh                 # 1. Build docker build environments

scripts/build.sh                    # 2. Build iso image

scripts/aarch64/qemu_boot_iso.sh    # 3a. Boot iso image with qemu aarch64
scripts/x86_64/qemu_boot_iso.sh     # 3b. Boot iso image with qemu x86_64

Prerequisites

• Docker: Build environment is based on docker containers and docker's platform emulation capabilities.
• QEMU: Boot the iso within an emulated aarch64 or x86_64 machine

How to build

Automated build using GitHub Actions

• .github/workflows/CI.yml: Pushing on main branch triggers an automated build of the iso image.
• .github/workflows/Release.yml: Pushing a version tag triggers an automated release.

Manual build

Build docker build environments:

scripts/setupenv.sh

Trigger a full build using docker via scripts/build.sh. This may take a while as docker images need to be build first, including kernel git clone. Furthermore, build environments for non-compliant host architectures will be emulated by docker.

scripts/build.sh

Or bash into a specific build environment and make manually. The following example randomly chooses the aarch64 build environment for the build.

scripts/aarch64/buildenv_bash.sh    # bash into aarch64 build environment

make uki                            # build unified kernel image uki-aarch64
make isoimage                       # build iso image cdrom.iso which includes uki-aarch64 (and uki-86_64 if present)

How to play

QEMU

If out/cdrom.iso was built, run one of

scripts/aarch64/qemu_boot_iso.sh
scripts/x86_64/qemu_boot_iso.sh

Make sure EFI firmware is available at EFI/ first. Should be the case by default. Otherwise run:

scripts/efi_reinstall.sh

Real hardware

Put iso image on a USB stick or other bootable medium. Hardware must have UEFI (no BIOS supported) as it allows a framebuffer console using GOP/simpledrm w/o the need of a specific graphics driver in the kernel.

Project overview

Project outline

EmbeddedSlotMachine/
├── EFI/          # EFI firmware to boot iso with qemu
├── out/          # Build artifacts: cdrom.iso, uki-aarch64, uki-x86_64
├── rules/        # Additional make scripts
├── scripts/      # Convenience scripts to work with project
├── SlotMachine/  # C++ games collection "Slot Machine" as only user space binaries
├── Makefile      # Top-level make file (to be used within docker build environment)
├── config.mk     # Global build configuration
└── Dockerfile    # Dockerfile for aarch64/x86_64 build environemts

Build artifacts

Main build artifact is the bootable multi-arch iso image out/cdrom.iso. Kernel images are bundled with user space (=Slot Machine games collection) and command line arguments into one EFI executable file.

EmbeddedSlotMachine/out/
├── uki-aarch64    # Unified kernel image for aarch64
├── uki-x86_64     # Unified kernel image for x86_64
└── cdrom.iso      # Bootable (multi-arch) iso containing at least one kernel image

Scripts

Core functionallity is available via shell scripts. Scripts must be called from project root!

EmbeddedSlotMachine/scripts/
├── aarch64/                # aarch64 specific scripts
│   ├── buildenv_bash.sh    # Interactive shell into aarch64 build environment
│   └── qemu_boot_iso.sh    # Boot iso with qemu aarch64
├── x86_64/                 # x86_64 specific scripts
│   ├── buildenv_bash.sh    # Interactive shell into x86_64 build environment
│   └── qemu_boot_iso.sh    # Boot iso with qemu x86_64
├── build.sh                # Trigger full build
├── clean.sh                # Clean build artifacts in out/
├── efi_reinstall.sh        # Replace EFI/ with latest firmware from build environment
└── setupenv.sh             # Build docker build environments

How to add more games?

1. Copy & paste one of the existing games in SlotMachine/src folder
2. Adapt folder name and variables in config.mk. Build system will pick up the new folder automatically and add it to the collection.
3. Modify the C++ source code until your game is ready ;)