Build, USB images and testbench start

This page documents the path where HarvTTP is built as an ELF, copied into the program USB image, combined with the data USB image and then started by the HarvOS boot ROM inside the processor testbench.

Project files

Path	Purpose
`software/user/harvttp/main.c`	HarvTTP HTTP, PHP worker, SQL loopback and HNET implementation.
`software/user/harvsql`	HarvSQL MySQL-compatible SQL service used by PHP tests.
`software/bootrom/harvos_usb_elf_bootrom.c`	Boot ROM, FAT/exFAT/YAML/ELF loading and bundle preparation.
`software/include/harvos_abi.h`	ABI, start parameters, MMIO addresses and HTTP bundle structures.
`rtl/harvos_soc.sv`	CPU, IMEM/DMEM, HNET, USB, HPS block bridge and loader integration.
`ports/php85`	HarvOS PHP 8.5/Zend SAPI, compatibility headers and build profiles.
`scripts/build_harvttp_php85_wsl.ps1`	Builds the PHP-enabled `harvttp.elf` through WSL and copies WordPress files when configured.
`scripts/build_harvsql.ps1`	Builds `harvsql.elf`, SQL config, seed files and data directories.
`scripts/start_harvttp_usb_boot_server.ps1`	Builds the testbench, boots HarvOS and prints the DHCP URL.

USB layout

# Program USB
/
  harvttp.elf
  harvsql.elf
  config/
    harvttp/
      harvttp.yaml
      wp-fast-overlay/
    harvsql/
      harvsql.yaml
      runtime.yaml
      seed/
      migrations/

# Data USB
/
  data/
    harvttp/
      webroot/
        index.php
        wp-login.php
        wp-admin/
        wp-includes/
        wp-content/
    harvsql/
      db/
        catalog.hsq

Build the PHP-enabled HarvTTP ELF

Run the command from the MiSTer template project root. The default module profile is wordpress-recommended. Set HARVOS_WORDPRESS_SOURCE to a local WordPress directory if the data web root should be populated from a full WordPress tree.

$env:HARVOS_WORDPRESS_SOURCE = "C:\Users\dennis\Downloads\wordpress"
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\build_php85_harvos_wsl.ps1 -ModuleProfile wordpress-recommended
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\build_harvttp_php85_wsl.ps1 -SkipPhp85Build

Build HarvSQL

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\build_harvsql.ps1

The script builds build/apps/harvsql.elf, copies it to the program USB directory, installs SQL runtime configuration and seed scripts and ensures release/data_usb/data/harvsql/db.

Build images and boot ROM

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\build_usb_elf_bootrom.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\build_usb_images.ps1

The boot ROM image contains the loader that runs after CPU reset. The USB images contain the service ELFs, YAML configuration, PHP files, WordPress files and SQL state directories.

Start the testbench

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\start_harvttp_usb_boot_server.ps1 -UsePhp85 $true -VerilatorThreads 4

The start script rebuilds the PHP-enabled HarvTTP path, builds HarvSQL, builds the boot ROM and USB images, compiles the Verilator harness, boots the processor and waits for DHCP. When DHCP completes, it prints a URL such as http://192.168.8.231/.

Browser checks

Request	Expected result
`GET /`	Static index or WordPress/front-controller output, depending on the data web root.
`GET /phpver.php`	PHP/Zend diagnostic output when the PHP-enabled ELF is active.
`GET /wpdiag.php`	WordPress-oriented PHP and HarvSQL diagnostics.
`GET /wp-login.php`	WordPress login path or the fast-overlay login page.
`GET /wp-full.php`	Full WordPress bootstrap path; this is the heaviest current request.
`GET /style.css`	`Content-Type: text/css` for static assets.
`GET /not-found`	`HTTP/1.0 404 Not Found`.

Stop the testbench

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\stop_harvttp_usb_boot_server.ps1

Troubleshooting

Symptom	Check
Browser timeout	Check the DHCP URL, packet bridge route, Npcap/TAP device and HNET link status.
`127.0.0.1` refuses the connection	Use the DHCP address unless a proxy or port forward was explicitly started.
`HarvTTP PHP worker queue full`	The request queue is saturated; inspect long-running PHP jobs and the `wp-full.php` bootstrap path.
SQL connection fails	Check `config/harvsql/runtime.yaml`, seed scripts and HarvSQL startup output.
Known static file returns 404	Confirm that the file exists in the preloaded bundle or the data web root and is below the configured size limit.
Boot hangs	Confirm that the program USB contains both ELFs and that the data USB contains `/data/harvttp` and `/data/harvsql`.