Porting mainline Linux to the HY300 consumer projector with Allwinner H713 SoC (ARM64 Cortex-A53, Mali-Midgard GPU).

• SoC: Allwinner H713 (ARM64 Cortex-A53, Mali-Midgard GPU)
• Target Device: HY300 consumer projector
• Architecture: aarch64 (64-bit ARM)
• Platform Family: sun50i (Allwinner H-series)

This project uses Nix flakes for reproducible development environments:

# Enter development shell nix develop # Or use direnv (recommended) direnv allow

• aarch64 cross-compilation toolchain
• sunxi-tools for FEL mode operations
• Firmware analysis tools (binwalk, hexdump, strings)
• Serial console tools (minicom, picocom)
• Device tree compiler and Android tools

• Extract and analyze factory ROM (update.img)
• Identify bootloader and DRAM parameters
• Extract device trees and partition layout
• Document hardware configuration
• Analyze factory DTB files for hardware mapping
• Correct previous analysis errors (GPU identification, etc.)

• Extract DRAM parameters from boot0.bin
• Configure U-Boot for H713 (using H6 base)
• Build SPL and U-Boot binaries
• Integrate custom DRAM parameters
• Test FEL mode boot (requires hardware access)
• Serial console access (requires hardware access)

• Complete DTB analysis and documentation
• Extract display.bin (MIPS co-processor firmware)
• Extract kernel and initramfs from Android partitions
• Analyze hardware-specific kernel modules
• Document additional drivers needed for mainline
• Complete MIPS co-processor integration analysis

• Device tree creation for mainline Linux (sun50i-h713-hy300.dts)
• All hardware components configured and documented
• MIPS co-processor integration with memory regions
• Mali-Midgard GPU support with operating points
• Projector-specific hardware configuration
• Device tree compilation verification (10.5KB DTB)
• Safe testing methodology with FEL recovery

• Comprehensive WiFi driver analysis (AIC8800 with 3 implementations)
• Mali GPU driver research (Panfrost vs proprietary options)
• MIPS co-processor firmware integration methodology
• Android kernel driver pattern analysis and documentation
• Projector-specific hardware driver requirements
• Complete driver integration roadmap with priorities
• Bootloader and MIPS co-processor complete analysis
• TSE database and panel configuration extraction

• Basic kernel module framework (drivers/misc/sunxi-mipsloader.c)
• Linux 6.16.7 API compatibility and compilation fixes
• Platform driver with device tree integration design
• Character device interface with IOCTL commands
• 40MB MIPS memory region management (0x4b100000)
• Register interface implementation (0x3061000 base)
• Task 019 Research (Option C): Complete ARM-MIPS communication protocol analysis
• HDMI Input Driver: V4L2 framework and hardware interface implementation
• MIPS Protocol Specifications: Complete implementation specs for 4 missing platform drivers
• Device tree integration: Complete kernel module compilation and validation
• Module loading framework: Ready for hardware testing

• NixOS VM Implementation: Complete VM system with Kodi and HY300 services
• Real Service Implementation: Python services replace shell script placeholders
• Service Architecture: Hardware/simulation mode separation
• Build System: Embedded service packages in flake.nix (resolved path issues)
• Cross-compilation: Both keystone and WiFi services building successfully
• VM Testing: Complete functionality validation in simulation mode
• Service Integration: Kodi + HY300 services working together
• Performance Validation: VM performance and stability testing
• Hardware Mode Preparation: Service transition from simulation to hardware
• Prometheus Metrics: All kernel drivers with comprehensive monitoring
• Kodi HDMI Integration: pvr.hdmi-input addon with channel management
• Task 019: Keystone parameter sysfs interface (panelparam) with MIPS integration
• Task 028: Panfrost GPU driver migration (open-source Mali replacement)
• Task 026: U-Boot and device tree completion verification

• Serial console setup and FEL mode recovery validation
• U-Boot bootloader testing via FEL mode
• Kernel module loading and MIPS co-processor testing
• Mainline device tree boot validation
• VM-tested software stack deployment to hardware
• Driver testing framework establishment
• WiFi and GPU driver hardware validation
• Projector hardware validation (motors, sensors, thermal)
• Complete hardware enablement testing

Phase IX Current: Hardware Testing and Validation - All software stack complete and ready for physical device deployment.

Phase VIII Completed (October 2025):

• Complete mainline Linux device tree with Panfrost GPU driver
• U-Boot bootloader with USB and HDMI support verified
• Full kernel module suite with Prometheus metrics
• NixOS VM system with Kodi and real Python services
• Keystone correction sysfs interface (panelparam)
• Complete software validation in simulation mode

Key Achievements:

• Complete mainline Linux device tree (sun50i-h713-hy300.dts - 967 lines, 14KB DTB)
• U-Boot bootloader ready for testing (u-boot-sunxi-with-spl.bin - 732KB)
• Phase VII Complete: Full kernel module development with MIPS integration
• Phase VIII Complete: VM-validated software stack ready for hardware
• Keystone Interface: Factory-compatible panelparam sysfs interface
• Panfrost GPU: Open-source Mali-T720 driver fully integrated
• Real Service Architecture: Python services (keystone, WiFi) with hardware/simulation modes

Next Priority: Hardware deployment (Phase IX) - requires physical device access for serial console, FEL mode testing, and driver validation.

• firmware/ROM_ANALYSIS.md - Complete ROM analysis results
• docs/FACTORY_DTB_ANALYSIS.md - Detailed DTB hardware analysis
• docs/DTB_ANALYSIS_COMPARISON.md - Error corrections from previous analysis
• sun50i-h713-hy300.dts - Main deliverable: Complete mainline device tree (967 lines)
• drivers/misc/sunxi-mipsloader.c - COMPLETED: MIPS co-processor kernel module with keystone sysfs (905 lines)
• docs/ARM_MIPS_COMMUNICATION_PROTOCOL.md - BREAKTHROUGH: Complete ARM-MIPS protocol specifications
• docs/MIPS_HDMI_COMMAND_ANALYSIS.md - COMPLETED: Complete HDMI command set analysis
• docs/MISSING_DRIVERS_IMPLEMENTATION_SPEC.md - COMPLETED: Implementation specs for 4 platform drivers
• drivers/media/platform/sunxi/sunxi-tvcap.c - COMPLETED: V4L2 HDMI input capture driver (1,760 lines)
• nixos/ - COMPLETED: Complete NixOS VM system with Kodi and HY300 services
• nixos/BUILD.md - COMPLETED: VM implementation and Panfrost GPU integration
• nixos/VM-TESTING.md - COMPLETED: Complete VM testing guide and procedures
• docs/HY300_HARDWARE_ENABLEMENT_STATUS.md - Hardware component status matrix
• docs/HY300_TESTING_METHODOLOGY.md - Safe testing procedures with FEL recovery
• docs/HY300_SPECIFIC_HARDWARE.md - Projector-specific hardware documentation
• firmware/boot0.bin - Extracted bootloader with DRAM parameters
• docs/tasks/completed/ - All completed task documentation
• flake.nix - Development environment configuration

1. Task Management: Create numbered tasks in docs/tasks/, move to completed/ when done
2. Git Commits: Reference task numbers, atomic commits with descriptive messages
3. Documentation: Update analysis reports as discoveries are made
4. Testing: Use FEL mode for safe bootloader testing

• Serial Console: UART access via TX/RX/GND pads
• FEL Mode: USB recovery mode for bootloader testing
• Complete Backup: Full eMMC backup before modifications

• u-boot-sunxi-with-spl.bin - Complete U-Boot binary for H713 (732KB with USB+HDMI)
• sunxi-spl.bin - Secondary Program Loader (32 KB)
• u-boot.bin - Main U-Boot binary (638 KB)
• u-boot.dtb - Device tree blob for HY300 hardware
• sun50i-h713-hy300.dtb - Main deliverable: Mainline device tree blob (14KB from 967-line source)
• sunxi-mipsloader.ko - COMPLETED: MIPS co-processor kernel module (905 lines with keystone interface)
• hy300-vm - NEW: Complete NixOS VM with Kodi and HY300 services
• hy300-keystone-service - NEW: Real Python keystone motor control service
• hy300-wifi-service - NEW: Real Python WiFi management service

• Platform: sun50i-H6 (compatible with H713)
• DRAM: DDR3-1600 configuration extracted from boot0.bin
• Device Tree: Complete HY300 mainline configuration with all hardware support
• MIPS: Co-processor integration with 40.3MB memory region

• Hardware Access Required: Phase IX hardware validation requires physical serial console and FEL mode access for testing
• MIPS Co-processor: Custom driver complete with keystone sysfs interface (panelparam)
• Proprietary Components: WiFi (AIC8800) and some projection hardware may require reverse engineering
• GPU Driver: Panfrost open-source driver configured for Mali-T720 (Midgard gen 2)

This is a hardware porting project. All development should happen through the Nix environment and follow the established task management system.

See docs/instructions/README.md for detailed development guidelines.