diff --git a/README.md b/README.md index d620638..3ff0da9 100644 --- a/README.md +++ b/README.md @@ -1,339 +1,284 @@ -
-

- - PS2BBLE Logo - -

- -

- A flexible BootLoader for PlayStation 2™ and PSX-DESR -

- -[![Codacy Badge](https://app.codacy.com/project/badge/Grade/8a5773aa30cf4aca97550ec8053908d6)]( -https://app.codacy.com/gh/NathanNeurotic/PlayStation2-Basic-BootLoader-Extended/dashboard -) -[![CI](https://github.com/NathanNeurotic/PlayStation2-Basic-BootLoader-Extended/actions/workflows/cl.yml/badge.svg?branch=main)]( -https://github.com/NathanNeurotic/PlayStation2-Basic-BootLoader-Extended/actions/workflows/cl.yml -) -[![GitHub all releases](https://img.shields.io/github/downloads/NathanNeurotic/PlayStation2-Basic-BootLoader-Extended/total?logo=GitHub&logoColor=white)](https://github.com/NathanNeurotic/PlayStation2-Basic-BootLoader-Extended/releases/) +# PS2BBLE (PlayStation 2 Basic BootLoader — Extended) +A small bootloader that reads **one configuration file per boot** and launches ELF (**executable**) programs based on button bindings or an AUTO (default) fallback. It searches known config locations in a fixed order and uses the **first** readable file it finds, when that file is reachable on the currently available devices.【F:src/main.c†L33-L45】【F:src/main.c†L632-L653】 ---- - -## Overview +**Documentation accuracy:** This README reflects the current source code and cl workflow configuration. If code changes, update this document to match the new behavior.【F:src/main.c†L33-L965】【F:.github/workflows/cl.yml†L1-L211】 -PS2BBL is a lightweight yet powerful bootloader for **PlayStation 2™** and **PSX-DESR** systems. -It performs early system initialization and launches ELF executables from multiple storage backends, supporting both **embedded** and **runtime-loaded** drivers. +--- -The boot process is deterministic, with a clearly defined configuration search order and strict separation between **boot-time** and **runtime-enabled** devices. +## Table of contents + +1. [What This Project Is](#what-this-project-is) +2. [What It’s Not](#what-its-not) +3. [Safety & Risk](#safety--risk) +4. [Glossary](#glossary) +5. [How Boot Works (Simplified)](#how-boot-works-simplified) +6. [What PS2BBLE Does During Boot (Verified Flow)](#what-ps2bble-does-during-boot-verified-flow) +7. [Storage/Devices (Verified)](#storagedevices-verified) +8. [Quick Start (I just want to use it)](#quick-start-i-just-want-to-use-it) +9. [Step-by-Step Setup](#step-by-step-setup) +10. [Configuration](#configuration) +11. [Advanced: Drivers (Embedded vs Runtime)](#advanced-drivers-embedded-vs-runtime) +12. [Build (Optional / Advanced)](#build-optional--advanced) +13. [Troubleshooting (Panic-Friendly Checklist)](#troubleshooting-panic-friendly-checklist) +14. [FAQ](#faq) +15. [Credits / Disclaimer / Legal](#credits--disclaimer--legal) --- -## Documentation +## What This Project Is -Full original documentation is available on GitHub Pages: -👉 https://israpps.github.io/PlayStation2-Basic-BootLoader/ +PS2BBLE is a bootloader that: -This Repo is Forked from: +- **Searches for one config file** at boot, using a fixed path order, and uses the first match **that can be read on the devices that are available at that time**.【F:src/main.c†L33-L45】【F:src/main.c†L632-L653】 +- **Parses known INI (configuration) keys** and applies boot options and button bindings.【F:src/main.c†L679-L767】 +- **Launches ELF executables** when a bound button is pressed, or uses AUTO after the wait timeout.【F:src/main.c†L921-L965】 -👉 https://github.com/pcm720/PlayStation2-Basic-BootLoader +--- -This Repo's ReadMe.md has been modified from its original version to reflect this fork's documentation. +## What It’s Not -As a result, it is recommended to familiarize yourself with this PS2BBLE documentation before continuing, even if you are familiar with PS2BBL. +- It is **not** confirmed in this fork to provide PSX-DESR-specific behavior. The code supports a PSX build flag, but DESR-specific guarantees are not proven here.【F:Makefile†L30-L31】【F:src/main.c†L229-L231】 +- It does **not** guarantee device availability at boot beyond what the build and runtime IRX loading allows. If a device is missing or IRX files are absent, behavior depends on runtime conditions.【F:src/main.c†L485-L629】【F:src/main.c†L1308-L1363】 --- -## Configuration Model (Read This First) - -PS2BBL reads **one primary configuration file per boot**. +## Safety & Risk -Some storage devices (HDD, MX4SIO, MMCE, XFROM) may not exist at boot time and can only be enabled *after* the initial configuration is parsed. -These devices **cannot provide the CONFIG.INI used for the same boot pass**. +PS2BBLE loads and runs ELFs from your configured paths. This is powerful, but it also means: -Configuration sources therefore fall into two categories: +- A wrong path or missing file results in **“not found”** behavior rather than a crash loop, and it will continue to other entries or AUTO as coded.【F:src/main.c†L921-L965】 +- **Emergency mode** exists: holding **R1 + START** triggers a loop that repeatedly tries `mass:/RESCUE.ELF`.【F:src/main.c†L612-L616】【F:src/main.c†L982-L993】 -1. **Always-available sources** (checked immediately) -2. **Conditionally-available sources** (checked only after device initialization) - -The search order below reflects this behavior explicitly. +**WARNING:** If your USB drive or memory card paths are wrong, the bootloader won’t find your ELFs. Keep a known-good `mass:/RESCUE.ELF` available if you rely on emergency mode.【F:src/main.c†L982-L993】 --- -## Configuration File Search Order -**(Activated sources only — first match wins)** - -### Phase 1 — Always available - -1. `CONFIG.INI` in the current working directory -2. `mc1:/SYS-CONF/PS2BBL.INI` -3. `mc0:/SYS-CONF/PS2BBL.INI` -4. `mc?:/SYS-CONF/PSXBBL.INI` *(PSX builds only)* - -### Phase 2 — Conditionally available +## Glossary -5. `mmce1:/PS2BBL/PS2BBL.INI` -6. `mmce0:/PS2BBL/PS2BBL.INI` - *(after MMCE driver initialization)* +- **ELF**: Executable file format used for PS2 homebrew (e.g., `BOOT.ELF`). +- **IOP**: Input/Output Processor (the PS2 coprocessor that runs IRX modules). +- **IRX**: IOP module (driver) loaded by the bootloader (e.g., USB or storage drivers).【F:src/main.c†L1149-L1193】 +- **INI**: Simple `NAME=VALUE` text configuration file parsed by the bootloader.【F:src/util.c†L65-L115】 +- **mc0 / mc1**: Memory card slots 0 and 1. +- **mass:** USB storage device path. +- **massX:** Placeholder that is resolved to `mass0:`–`mass4:` when MX4SIO is in use.【F:src/main.c†L1120-L1124】 +- **mmce0 / mmce1**: Memory card emulation devices (when MMCE is enabled).【F:src/main.c†L315-L360】 +- **xfrom:** External flash device path (when XFROM is enabled).【F:src/main.c†L367-L389】 -7. `xfrom:/PS2BBL/CONFIG.INI` - *(after XFROM is enabled)* - -8. `hdd0:__sysconf:pfs:/PS2BBL/CONFIG.INI` - *(after HDD stack initialization)* +--- -9. `massX:/PS2BBL/CONFIG.INI` - *(after MX4SIO initialization)* +## How Boot Works (Simplified) -10. `mass:/PS2BBL/CONFIG.INI` +1. Initialize core systems and drivers. +2. Search for a configuration file in the fixed order and stop at the first match **that can be read on available devices**.【F:src/main.c†L33-L45】【F:src/main.c†L632-L653】 +3. Parse known keys and apply settings, including button bindings.【F:src/main.c†L679-L767】 +4. Wait for button input for the configured timeout, then run bound ELFs or AUTO.【F:src/main.c†L921-L965】 --- -## Built-In Defaults (No Config Found) +## What PS2BBLE Does During Boot (Verified Flow) -If no configuration file is located, PS2BBL uses internal defaults. +This is the actual flow from the main program: -### Button → Launch Mapping +- Initializes IOP, file I/O, and core modules. +- Loads USB drivers (embedded or external depending on build).【F:src/main.c†L1149-L1193】 +- Optionally enables additional device drivers if compiled in and available.【F:src/main.c†L485-L520】 +- Loads OSD data, applies config, and sets video output parameters.【F:src/main.c†L542-L600】 +- Searches for `CONFIG.INI` in the fixed path order and parses recognized keys if the file is reachable on available devices.【F:src/main.c†L33-L45】【F:src/main.c†L632-L767】 +- Waits for button input, then loads the first existing ELF for that button; otherwise runs AUTO.【F:src/main.c†L921-L965】 -**AUTO** -- `mc?:/BOOT/BOOT.ELF` -- `mc?:/BOOT/BOOT2.ELF` -- `mass:/RESCUE.ELF` +**NOTE:** Some devices may be enabled before config parsing depending on build flags and runtime driver availability, which affects whether those devices can supply the config file on that boot.【F:src/main.c†L485-L629】【F:src/main.c†L1308-L1363】 -**SELECT** -- `mass:/PS2BBL/L2[1].ELF` -- `mass:/PS2BBL/L2[2].ELF` -- `mass:/PS2BBL/L2[3].ELF` +--- -**L3** -- `mass:/PS2BBL/R2[1].ELF` -- `mass:/PS2BBL/R2[2].ELF` -- `mass:/PS2BBL/R2[3].ELF` +## Storage/Devices (Verified) -**R3** -- `mc?:/OPL/OPNPS2LD.ELF` -- `mc?:/APPS/OPNPS2LD/ELF` -- `mass:/PS2BBL/OPNPS2LD.ELF` +These storage backends exist in code and are used as config sources or execution paths when the device and its drivers are available: -**START** -- `mass:/RESCUE.ELF` -- `mc?:/BOOT/BOOT2.ELF` -- `mc?:/APPS/ULE.ELF` +- **CWD**: `CONFIG.INI` in the current working directory.【F:src/main.c†L33-L45】 +- **Memory cards**: `mc0:` and `mc1:` (including `mc?:` auto-slot selection).【F:src/main.c†L33-L45】【F:src/main.c†L1086-L1094】 +- **USB mass storage**: `mass:` (always checked) and `massX:` (MX4SIO mode).【F:src/main.c†L33-L45】【F:src/main.c†L1120-L1124】 +- **MMCE**: `mmce0:` / `mmce1:` when enabled by build/runtime.【F:src/main.c†L315-L360】 +- **XFROM**: `xfrom:` when enabled by build/runtime.【F:src/main.c†L367-L389】 +- **HDD**: `hdd0:__sysconf:pfs:/...` when HDD support is available.【F:src/main.c†L33-L45】【F:src/main.c†L1370-L1433】 --- -## Runtime Configuration Keys - -These keys are parsed **only from the primary CONFIG.INI**. +## Quick Start (I just want to use it) -They activate devices *after* configuration parsing has completed. +This path assumes you already have a built PS2BBLE ELF. -### Runtime Device Enablement +1. **Copy PS2BBLE ELF** to a location you can boot (e.g., memory card or USB). + **What you should see:** Your launcher or file browser shows the PS2BBLE ELF where you copied it. +2. **Create a config file** in one of the default locations, for example: + - `mc0:/SYS-CONF/PS2BBL.INI` + - `mass:/PS2BBL/CONFIG.INI` + **What you should see:** The file exists in that exact path (case-sensitive on some tools). +3. **Add at least one AUTO entry** (example below). + **What you should see:** The config file contains lines like `LK_AUTO_E1=...`. +4. Boot PS2BBLE and let AUTO run after the timeout, or press a bound button. + **What you should see:** If the ELF exists, you should see a “Loading ” message before it launches.【F:src/main.c†L921-L965】 -- `HDD_ENABLE=1` - Enables the HDD stack after boot - *(requires `HDD_RUNTIME=1` build)* +**Recovery if it fails:** Hold **R1 + START** to enter emergency mode and attempt `mass:/RESCUE.ELF` repeatedly.【F:src/main.c†L612-L616】【F:src/main.c†L982-L993】 -- `MX4SIO_ENABLE=1` - Loads `mx4sio_bd.irx` and enables `massX:` - *(requires `MX4SIO` or `MX4SIO_RUNTIME`)* +Minimal example (AUTO only): -- `MMCE_ENABLE=1` - Loads `mmceman.irx` and enables `mmce0:/mmce1:` - *(requires `MMCE` or `MMCE_RUNTIME`)* - -- `XFROM_ENABLE=1` - Loads `xfromman.irx` and enables `xfrom:` - *(requires `XFROM` or `XFROM_RUNTIME`)* +``` +LK_AUTO_E1=mc0:/BOOT/BOOT.ELF +KEY_READ_WAIT_TIME=5000 +LOGO_DISPLAY=2 +``` -> ⚠️ These devices **cannot supply the current boot’s CONFIG.INI**. -> To use configuration files from them, chain-load PS2BBL again or perform a second config pass. +**TIP:** Keep a known-good rescue ELF at `mass:/RESCUE.ELF` so you can recover using **R1 + START** if needed.【F:src/main.c†L982-L993】 --- -### Extra IRX Loading +## Step-by-Step Setup -- `LOAD_IRX_E#=` - Loads additional IRX modules during config parsing. +1. **Pick a config location** from the fixed search order. For example: + - `mc0:/SYS-CONF/PS2BBL.INI` + - `mass:/PS2BBL/CONFIG.INI`【F:src/main.c†L33-L45】 + **What you should see:** The file is present in the exact path you chose. +2. **Create the config file** using `NAME=VALUE` entries (see [Configuration](#configuration)).【F:src/util.c†L65-L115】 + **What you should see:** Each line follows `KEY=VALUE` with no extra spaces around `=`. +3. **Add button bindings** using `LK_