SHIAN OS – Android-first and Linux-first Tracks

This repo gives you two practical ways to get a simple, customizable, Linux-flavored mobile OS with a built-in terminal:

1. Android-first: a minimal Android-based ROM (LineageOS base) with preinstalled terminal and Linux tools
2. Linux-first: a postmarketOS (Alpine) setup with a mobile UI (Phosh/Plasma) and terminal

You can choose either path based on whether you need Android app compatibility (Android-first) or a pure Linux experience (Linux-first).

Quick start

Prereqs (host): Ubuntu 22.04+ recommended. Install Java 17, git, repo, build-essential, etc.

Android-first track

• scripts/android/init-and-sync.sh – initializes LineageOS sources
• scripts/android/build.sh – builds the ROM for your device
• android/product-template – a minimal product template to start from

Linux-first track (postmarketOS)

• pmos/README.md – setup guide
• scripts/pmos/init.sh – installs pmbootstrap
• scripts/pmos/flash.sh – flashes rootfs/kernel

Read docs/FLASHING.md before flashing any device.

Choose a path

Android-first (minimal ROM with Linux touch)

• Keep Android app compatibility
• Ship a terminal app (Termux or AOSP Terminal) by default
• Include core CLI tools (bash, nano/vim, busybox/toybox, openssh)
• Provide dotfiles (~/.bashrc, ~/.vimrc) for customization

Linux-first (postmarketOS)

• Full Linux (Alpine) with mobile shell (Phosh/Plasma/sxmo)
• Terminal and package manager (apk) out of the box
• Optional Waydroid for Android app support on supported devices

Next steps

1. Pick your device model and path.
2. For Android-first:
   • Run scripts/android/init-and-sync.sh
   • Create a device tree or use an existing one from LineageOS
   • Customize android/product-template to your product
   • Optionally add Termux via scripts/get-termux-prebuilt.sh
   • Build with scripts/android/build.sh
3. For Linux-first:
   • Follow pmos/README.md

Important

Replacing iOS on iPhone/iPad is not supported (locked boot chain). Android devices generally support custom ROMs subject to bootloader unlock and device support status.

SHIAN OS - A Simple Operating System

A personal OS development project built from scratch, starting with a simple bootloader and gradually evolving into a functional kernel.

Current Status: Milestone 5 - Process and Multitasking ✅

• ✅ BIOS bootloader that loads kernel from disk
• ✅ 16-bit to 32-bit mode transition
• ✅ Complete VGA text driver with colors and scrolling
• ✅ Printf-style formatted output
• ✅ Interrupt Descriptor Table (IDT) setup
• ✅ Programmable Interrupt Controller (PIC) configuration
• ✅ Keyboard driver with full US QWERTY layout
• ✅ Interactive shell with commands
• ✅ Dynamic memory allocation (kmalloc/kfree)
• ✅ Memory block management with coalescing
• ✅ Basic paging support (identity mapped)
• ✅ Preemptive multitasking with task scheduler
• ✅ Timer-driven task switching (100 Hz)
• ✅ Task creation, termination, and yielding
• ✅ Priority-based scheduling
• ✅ Task control blocks and state management
• ✅ QEMU testing setup for macOS (Apple Silicon)

Quick Start

1. Setup development environment: ```bash chmod +x scripts/setup-dev-environment.sh ./scripts/setup-dev-environment.sh ```

2. Build and run: ```bash make clean make make run ```

3. You should see: An interactive shell with multitasking capabilities!

Available Shell Commands

• help - Show available commands
• clear - Clear the screen
• info - Show system information
• colors - Demonstrate color capabilities
• memstat - Show memory usage statistics
• memtest - Test memory allocation and deallocation
• memblocks - Show detailed memory block information
• tasks - Show all running tasks and their states
• spawn - Create demo tasks to see multitasking in action
• yield - Yield CPU time to other tasks

Architecture

• Bootloader (boot/boot.asm): 16-bit BIOS bootloader, loads kernel from disk
• Kernel Entry (kernel/kernel_entry.asm): Transitions to 32-bit protected mode
• Interrupt Handling (kernel/interrupt.asm): Assembly interrupt handlers for timer and keyboard
• Kernel (kernel/kernel.c): Main kernel code in C
• VGA Driver (kernel/vga.c): Complete text mode driver with colors and scrolling
• Standard I/O (kernel/stdio.c): Printf and basic I/O functions
• IDT (kernel/idt.c): Interrupt Descriptor Table management
• PIC (kernel/pic.c): Programmable Interrupt Controller driver
• Keyboard (kernel/keyboard.c): Full keyboard driver with modifier keys
• Shell (kernel/shell.c): Interactive command-line interface
• Memory Management (kernel/memory.c): Heap allocation with block coalescing
• Paging (kernel/paging.c): Basic virtual memory support
• String Utils (kernel/string.c): Standard string manipulation functions
• Task Management (kernel/task.c): Multitasking with preemptive scheduling
• Timer (kernel/timer.c): System timer for task switching

Multitasking Features

• Preemptive Scheduling: Tasks are automatically switched every 10ms
• Priority-Based: Higher priority tasks get CPU time first
• Task States: READY, RUNNING, BLOCKED, TERMINATED
• Task Control Blocks: Full context saving for each task
• Cooperative Yielding: Tasks can voluntarily yield CPU time
• Demo Tasks: Built-in example tasks to demonstrate multitasking

Next Milestones

• Device Drivers (enhanced timer, more hardware support)
• Basic Filesystem Support (simple file operations)

Development Notes

• Tested on macOS (Apple Silicon) with QEMU
• Uses 32-bit x86 architecture for simplicity
• Timer runs at 100 Hz for smooth task switching
• Identity-mapped paging for first 4MB
• Each milestone builds on the previous one
• Focus on understanding, not perfection

Debugging

• Use make debug to run with GDB support
• Connect with: gdb -ex "target remote localhost:1234"
• Set breakpoints and step through code
• Use tasks command to monitor multitasking
• Use spawn to create demo tasks and watch them run

Happy OS hacking! 🚀