BBeOS/docs/phases/PHASE_2_BOOTSTRAPPING.md

Phase 2: Bootstrapping a Minimal Linux System

🎯 Objectives

Achieve a working Linux shell booted on the BlackBerry Classic (Q20) with basic hardware access and development environment established.

📋 Detailed Tasks

2.1 Kernel Selection and Configuration

2.1.1 Kernel Source Selection

Options to Evaluate:

1. Mainline Linux: Latest stable kernel (6.x)
2. postmarketOS: Community-maintained mobile Linux
3. LineageOS: Android-based kernel tree
4. Qualcomm CAF: Code Aurora Forum kernel

Selection Criteria:

• MSM8960 support level
• Community maintenance
• Driver availability
• Security updates
• Documentation quality

Evaluation Tasks:

• Test mainline kernel MSM8960 support
• Compare postmarketOS vs LineageOS trees
• Assess Qualcomm CAF maintenance status
• Document missing features in each option
• Choose optimal kernel source

2.1.2 Kernel Configuration

Essential Configurations:

# Architecture
CONFIG_ARM=y
CONFIG_CPU_32v7=y
CONFIG_CPU_HAS_ASID=y

# MSM8960 specific
CONFIG_ARCH_MSM8960=y
CONFIG_MSM_SMD=y
CONFIG_MSM_SMD_PKG3=y

# Device tree
CONFIG_OF=y
CONFIG_DTC=y

# Essential subsystems
CONFIG_SERIAL_MSM=y
CONFIG_SERIAL_MSM_CONSOLE=y
CONFIG_USB_SUPPORT=y
CONFIG_USB_MSM_OTG=y

Configuration Tasks:

• Create base kernel configuration
• Enable MSM8960-specific drivers
• Configure device tree support
• Enable essential subsystems
• Optimize for size and performance

2.1.3 Device Tree Development

Device Tree Structure:

/ {
    model = "BlackBerry Classic Q20";
    compatible = "blackberry,q20", "qcom,msm8960";
    
    memory {
        device_type = "memory";
        reg = <0x00000000 0x80000000>; // 2GB
    };
    
    chosen {
        stdout-path = "serial0:115200n8";
    };
    
    soc {
        serial@16440000 {
            compatible = "qcom,msm-uartdm";
            reg = <0x16440000 0x1000>;
            interrupts = <0 154 0>;
            clocks = <&gcc 108>, <&gcc 109>;
            clock-names = "core", "iface";
        };
    };
};

Development Tasks:

• Create base device tree for Q20
• Add MSM8960 SoC nodes
• Configure memory and clocks
• Add essential peripherals
• Test device tree compilation

2.2 Root Filesystem Creation

2.2.1 Build System Selection

Options:

1. Buildroot: Lightweight, single-purpose
2. Yocto: Full-featured, complex
3. Debian: Standard distribution
4. Alpine: Minimal, security-focused

Selection Criteria:

• Build time requirements
• Package availability
• Customization flexibility
• Maintenance overhead
• Community support

Evaluation Tasks:

• Compare build times for each system
• Assess package availability
• Test customization capabilities
• Evaluate maintenance requirements
• Choose optimal build system

2.2.2 Minimal Root Filesystem

Essential Components:

# Core system
/bin/busybox
/bin/sh
/bin/init

# Development tools
/bin/dropbear    # SSH server
/bin/strace      # Debugging
/bin/gdb         # Debugger

# System utilities
/bin/mount
/bin/umount
/bin/reboot
/bin/poweroff

# Network tools
/bin/ifconfig
/bin/route
/bin/ping

Build Tasks:

• Configure build system for ARMv7
• Select essential packages
• Configure init system (systemd/OpenRC)
• Set up development tools
• Create minimal bootable image

2.2.3 Init System Configuration

Options:

1. systemd: Full-featured, complex
2. OpenRC: Lightweight, simple
3. BusyBox init: Minimal, basic
4. Custom init: Tailored for device

Configuration Tasks:

• Choose appropriate init system
• Configure boot sequence
• Set up service management
• Configure logging
• Test boot process

2.3 Boot Method Development

2.3.1 Bootloader Integration

Boot Methods to Investigate:

1. Fastboot: Standard Android boot method
2. kexec: Kernel-to-kernel boot
3. EDL Mode: Emergency Download Mode
4. Recovery Mode: Alternative boot path
5. Custom Bootloader: Modified boot sequence

Development Tasks:

• Test fastboot command availability
• Develop kexec boot method
• Research EDL mode entry
• Modify recovery boot sequence
• Create custom bootloader if needed

2.3.2 Boot Image Creation

Android Boot Image Format:

# Boot image structure
+------------------+
| Boot header      |
+------------------+
| Kernel           |
+------------------+
| Ramdisk          |
+------------------+
| Device tree      |
+------------------+

Creation Process:

• Compile kernel image
• Create initramfs
• Build device tree blob
• Package boot image
• Sign image if required

2.3.3 Boot Sequence Development

Boot Process:

1. Bootloader: Load and verify boot image
2. Kernel: Initialize hardware and mount rootfs
3. Init: Start system services
4. Shell: Provide user interface

Development Tasks:

• Configure bootloader parameters
• Set up kernel command line
• Configure init system
• Test complete boot sequence
• Debug boot issues

2.4 Hardware Access Development

2.4.1 Serial Console Access

UART Configuration:

# Kernel command line
console=ttyMSM0,115200n8

# Device tree node
serial@16440000 {
    compatible = "qcom,msm-uartdm";
    reg = <0x16440000 0x1000>;
    interrupts = <0 154 0>;
    clocks = <&gcc 108>, <&gcc 109>;
    clock-names = "core", "iface";
};

Setup Tasks:

• Configure UART driver
• Set up console output
• Test serial communication
• Configure USB serial bridge
• Document connection method

2.4.2 USB Access Development

USB Configuration:

# USB OTG support
CONFIG_USB_MSM_OTG=y
CONFIG_USB_GADGET=y
CONFIG_USB_G_SERIAL=y

# USB host support
CONFIG_USB_EHCI_HCD=y
CONFIG_USB_OHCI_HCD=y

Development Tasks:

• Configure USB OTG driver
• Set up USB gadget mode
• Enable USB serial bridge
• Test USB connectivity
• Configure USB networking

2.4.3 Network Access

Network Configuration:

# USB networking
CONFIG_USB_RNDIS=y
CONFIG_USB_CDC_ETHER=y

# Wi-Fi support (if available)
CONFIG_WLAN=y
CONFIG_ATH6KL=y

Setup Tasks:

• Configure USB networking
• Set up IP addressing
• Test network connectivity
• Configure SSH access
• Document network setup

2.5 Development Environment

2.5.1 Cross-Compilation Setup

Toolchain Requirements:

# ARMv7 cross-compiler
arm-linux-gnueabihf-gcc
arm-linux-gnueabihf-g++
arm-linux-gnueabihf-ld

# Build tools
make
cmake
autotools

# Device tree tools
dtc
dtc-utils

Setup Tasks:

• Install ARM cross-compiler
• Configure build environment
• Set up kernel build system
• Configure rootfs builder
• Test compilation process

2.5.2 Debug Environment

Debug Tools:

# Kernel debugging
CONFIG_KGDB=y
CONFIG_KGDB_SERIAL_CONSOLE=y

# User space debugging
strace
gdb
valgrind

# System monitoring
top
htop
iotop

Setup Tasks:

• Configure kernel debugging
• Set up GDB server
• Install debug tools
• Configure logging
• Test debug capabilities

2.5.3 Testing Framework

Testing Components:

• Unit Tests: Individual component testing
• Integration Tests: System-level testing
• Hardware Tests: Peripheral functionality
• Performance Tests: System performance
• Stress Tests: System stability

Framework Setup:

• Set up automated testing
• Configure test environment
• Create test scripts
• Set up continuous integration
• Document testing procedures

📊 Deliverables

2.6 Working Linux Shell

Requirements:

• Bootable Linux kernel
• Functional root filesystem
• Serial console access
• Basic command line interface
• Development tools available

2.7 Hardware Access Log

Documentation:

• Working vs non-working peripherals
• Driver status for each component
• Access methods for each interface
• Performance characteristics
• Known issues and limitations

2.8 Development Environment

Components:

• Cross-compilation toolchain
• Kernel build system
• Root filesystem builder
• Debug tools and utilities
• Testing framework

⏱️ Timeline

Week 1-2: Kernel selection and configuration Week 3-4: Root filesystem creation Week 5-6: Boot method development Week 7-8: Hardware access and development environment

Total Duration: 8 weeks (2 months)

🎯 Success Criteria

Phase 2 is successful when:

1. Linux kernel boots successfully on device
2. Serial console provides shell access
3. Basic hardware peripherals are accessible
4. Development environment is functional
5. Boot process is reliable and documented

🚨 Risk Mitigation

High-Risk Scenarios:

• Bootloader completely locked → Research alternative boot methods
• Kernel won't boot → Debug hardware initialization
• No serial access → Develop alternative debug methods
• Build system issues → Simplify or use alternative tools
• Hardware incompatibility → Identify and work around issues