eliott/BBeOS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b748805c71e54352d4b545f6a4902058b47b4573
BBeOS/docs/PHASE_2_BOOTSTRAPPING.md

9.0 KiB
Raw Blame History

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