== Step 0 — Backup (strongly recommended) ==
Before you begin:
# Backup your boot SD (FAT partition) contents (Emu68 files).
# Backup your Amiga system drive (or at least your Poseidon and DEVS/LIBS changes).
# If testing USB storage: test with a blank USB stick you don’t care about.
== Step 1 — Update Emu68 to 1.1 alpha.1 ==
# Download the correct Emu68 1.1 archive for your hardware from the Emu68 releases page.
# Extract the archive on your PC.
# Copy/replace the Emu68 boot files onto the **FAT(16/32) boot partition** of the SD card.
# Reinsert SD and boot Emu68.
‘'’Notes:”’
* Emu68 1.1 changes some package names (make sure you pick the correct one for your PiStorm family).
* Emu68 1.1 may require a newer VideoCore.card (see the Emu68 release notes in the release page).
== Step 2 — Confirm Poseidon 4.5 is installed ==
The xHCI driver is a **Poseidon v4.5** hardware driver.
# Open Trident (Poseidon preferences).
# Confirm Poseidon version is **4.5** (About/Version info).
# If you’re not on 4.5, install/update Poseidon first before proceeding.
== Step 3 — Install gic400.library (required) ==
# Download the latest **gic400.library** release from:
# https://github.com/rondoval/emu68-gic400-library/releases
# Copy **gic400.library** to:
#* ‘'’LIBS:”’
# Reboot your Amiga/Emu68 environment.
== Step 4 — Install xhci.device ==
# Download the latest **emu68-xhci-driver** release from:
# https://github.com/rondoval/emu68-xhci-driver/releases
# Extract the archive on your Amiga (or on PC and transfer the files over).
# Copy ‘'’xhci.device”’ to:
#* ‘'’DEVS:USBHardware/”’
# If the ‘'’DEVS:USBHardware”’ drawer does not exist, create it.
‘'’Why this location?”’
Poseidon hardware drivers are typically loaded from ‘'’DEVS:USBHardware”’ and referenced like:
DEVS:USBHardware/
== Step 5 — Add/Enable the xHCI controller in Trident ==
# Open ‘'’Trident”’ (Poseidon prefs).
# Go to the section for ‘'’Hardware”’ / ‘'’Host Controllers”’ (wording varies).
# Choose ‘'’Add”’ (or similar).
# When prompted for driver/device:
#* Select ‘'’xhci.device”’
#* Set ‘'’Unit”’ to ‘'’0′'’ (typical default)
# Save changes.
# Use Trident’s ‘'’Restart Poseidon”’ / ‘'’Restart stack”’ option if available, otherwise reboot.
== Step 6 — Test safely ==
Start with low-risk devices first:
# Plug in a simple USB2 HID device (mouse/keyboard via dongle).
# Check Trident’s device tree: you should see a root hub and attached devices.
# Only after HID works, test storage with:
#* A spare USB stick you don’t care about
#* Read-only tests first (list files, verify checksums if possible)
# If you try USB3:
#* Plug a USB3 device directly into a blue USB3 port on the Pi 4B (no hub)
#* Expect limitations (USB3 hubs not supported yet)
== Known limitations (as of driver v2.0) ==
* The driver is experimental and can corrupt data.
* USB3 (SuperSpeed) support is limited:
** Works only for some devices directly connected to Pi 4B USB3 ports
** USB3 hubs are not supported
* CM4 and the Pi 4 OTG port are not supported (per repo README).
== Troubleshooting ==
=== xhci.device doesn’t appear in Trident ===
* Confirm you copied it to: ‘'’DEVS:USBHardware/xhci.device”’
* Confirm you are running Poseidon **4.5**
* Reboot after copying (don’t rely on hot-reload at first)
=== Trident/Poseidon can’t open the driver or crashes ===
* Confirm **gic400.library** exists in ‘'’LIBS:”’
* Confirm you are running **Emu68 1.1 alpha.1** (or 1.0.99)
* Confirm you are using **Raspberry Pi 4B** (VL805 xHCI controller)
=== Devices enumerate but storage is flaky ===
* This is expected for an experimental driver.
* Use different USB sticks, avoid hubs, try USB2 devices first.
* Avoid write tests on anything important.
== References ==
* Emu68 releases and release notes:
https://github.com/michalsc/Emu68/releases
* emu68-xhci-driver:
https://github.com/rondoval/emu68-xhci-driver
* emu68-xhci-driver releases:
https://github.com/rondoval/emu68-xhci-driver/releases
* gic400.library:
https://github.com/rondoval/emu68-gic400-library
* gic400.library releases:
https://github.com/rondoval/emu68-gic400-library/releases