A flexible BootLoader for PlayStation 2(TM) and PSX-DESR
Full original documentation is available on GitHub Pages:
This Repo is Forked from:
This Repo's ReadMe.md has been modified from its original version to reflect this fork's documentation.
As a result, it is recommended to familiarize yourself with this PS2BBLE documentation before continuing, even if you are familiar with PS2BBL.
A deterministic, configuration-driven bootloader for PlayStation 2(TM) (and supported builds for PSX-DESR) that:
- performs early system initialization (OSD facilities, core module loading, CDVD certification, etc.),
- can boot discs (PS1 / PS2 / DVD-Vide) via built-in commands,
- launches ELF executables from multiple storage devices using simple button bindings,
- supports embedded and/or runtime-loaded IRX driver stacks depending on the build.
PS2BBLE is designed to be recoverable: if your setup breaks but PS2BBLE still launches, you can enter an Emergency Mode and repeatedly attempt a known rescue ELF from USB.
Forked from @pcm720's PS2BBL fork of @israpps's PS2BBL, the parent projects of PS2BBLE, lightweight yet powerful bootloaders for PlayStation 2(TM) and PSX-DESR systems.
All intended performance and functions were targeted to preserve the existing PS2BBL features and performance, while enhancing and adding to the project as a whole.
Both perform early system initialization and launches ELF executables from multiple storage backends, supporting both embedded and runtime-loaded drivers.
Their boot processes are deterministic, with a clearly defined configuration search order and strict separation between boot-time and runtime-enabled devices.
- What PS2BBLE is
- Ways to use it
- Safety and recovery
- What you need
- Quick start
- How boot works
- Config file search order
- Configuration keys
- Launch keys (button bindings)
- Internal commands
- Devices and path formats
- Drivers: embedded vs runtime
- Example CONFIG.INI files
- Troubleshooting (panic-friendly)
- Compatibility notes
- Differences vs FreeMcBoot (practical)
- Build notes
- Credits and license
PS2BBLE is a bootloader. It reads one configuration file per boot, waits for controller input for a configured time window, and then runs the first valid launch entry for the pressed button (or runs AUTO if no button is pressed).
It does not merge configs, scan directories, or "guess" paths. Everything is driven by your config and the build's enabled features.
PS2BBL-family bootloaders are commonly used in these modes:
You boot PS2BBLE.ELF like any homebrew ELF from an existing entry point (uLaunchELF / wLaunchELF, OPL, FreeDVDBoot, modchip DEV1/DEV2, OpenTuna/FreeHDBoot flows, etc.).
Some distributions provide tooling or packaging to install the bootloader as an encrypted/system boot entry so it auto-starts without you manually launching the ELF each time. Depending on the platform and setup, this can be done via:
- a memory-card "system update / encrypted executable" style install, and/or
- a HDD-based boot path (where applicable to the environment and release packaging).
- KELFBinder by @israpps
Whether a given PS2BBLE release supports one-click install/auto-boot is determined by the release you ship (and its target hardware), not by this README alone.
If PS2BBLE still runs but your config/app paths are broken, hold:
R1 + START
PS2BBLE enters an endless loop and repeatedly tries:
mass:/RESCUE.ELF
mass is recommended to be a fat32 32kb clustered USB of any size equal to or less than 2TB
It is not required for normal operation, but it's strongly recommended to keep some known-good rescue app available so you can recover if things go wrong.
Typical choice:
- uLaunchELF / wLaunchELF copied as:
mass:/RESCUE.ELF
Any existing homebrew entry point works, for example:
- uLaunchELF / wLaunchELF
- OPL (Open PS2 Loader)
- FreeDVDBoot (disc entry point)
- modchip DEV1/DEV2 and similar
- OpenTuna / FreeHDBoot style entry points
- environment-specific loaders (examples seen in the ecosystem include YADE/MMCE-related flows, ATA/HDD loader flows, etc.)
(You do not need all of these. You just need one that works on your console.)
For USB (mass:) usage:
- Prefer FAT32
- Prefer MBR partitioning (not GPT) for maximum compatibility
- 32 KB cluster size is a common "safe default" for homebrew workflows
- For windows users, it is recommended to perform the format with rufus
- A MagicGate-capable memory card is strongly recommended for broad compatibility
- If you use MMCE device(s), follow the device's expected setup/official setup for your target build/variant
- Any PC text editor works, or
- uLaunchELF / wLaunchELF's built-in text editor can be used to create/edit the INI directly on-device
This is the simplest "beginner-safe" setup that works across the widest range of situations.
Place PS2BBLE.ELF on a device you can access from your entry point (USB or memory card).
PS2BBLE searches memory cards early and reliably. Create:
mc0:/SYS-CONF/PS2BBL.INI
Optionally (recommended for "global fallback"), duplicate the same file to or choose instead:
mc1:/SYS-CONF/PS2BBL.INI
Beginner rule (global fallback): PS2BBLE searches
mc1thenmc0. If you want a "works no matter which slot you use" feel, keep the same config on both cards or update the INI to mc?:/ instead of mc0:/ or mc1:/
This config keeps the boot window short and uses only always-available paths.
# Minimal safe PS2BBLE config
KEY_READ_WAIT_TIME=500
LOGO_DISPLAY=2
# AUTO fallback chain (tries in order)
LK_AUTO_E1=mc?:/BOOT/BOOT.ELF
LK_AUTO_E2=mc?:/BOOT/BOOT2.ELF(This minimal example intentionally does not require a USB rescue file. Add recovery later if you want it.)
- If you press nothing: after 500 ms, it runs the first found AUTO entry.
- If you want a recovery backdoor, see the next section and Emergency Mode.
At a high level:
- Initialize system basics and drivers (what's available depends on the build).
- Search for a configuration file in a fixed order.
- Parse known keys (
KEY=VALUE) and store launch mappings. - Wait for input for
KEY_READ_WAIT_TIME. - Launch the first valid entry for the pressed button; otherwise run AUTO.
Important practical point:
- Enabling some devices may happen after config parsing depending on build/driver availability, so a device may be usable for launching apps even if it couldn't provide the config for that boot pass.
PS2BBLE searches for one config file in the following order (first readable match wins):
CONFIG.INI(current working directory)mc1:/SYS-CONF/PS2BBL.INImc0:/SYS-CONF/PS2BBL.INImc?:/SYS-CONF/PSXBBL.INI(PSX / DESR builds)mmce1:/PS2BBL/PS2BBL.INI(when MMCE is enabled & available)mmce0:/PS2BBL/PS2BBL.INI(when MMCE is enabled & available)xfrom:/PS2BBL/CONFIG.INI(when XFROM is enabled & available)hdd0:__sysconf:pfs:/PS2BBL/CONFIG.INI(when HDD is enabled & available)massX:/PS2BBL/CONFIG.INI(MX4SIO mapping when enabled & available)mass:/PS2BBL/CONFIG.INI
- PS2: keep your primary config at
mc1:/SYS-CONF/PS2BBL.INIand optionally duplicate tomc0:/SYS-CONF/PS2BBL.INI; or just use mc?:/SYS-CONF/PS2BBL.INI - PSX-DESR builds: place a PSX-specific config at
mc?:/SYS-CONF/PSXBBL.INIwhen you want PSX-targeted behavior.
SKIP_PS2LOGO
Controls PS2 disc boot logo behavior (also affected by$CDVD_NO_PS2LOGO).KEY_READ_WAIT_TIME
Milliseconds to wait for button input before running AUTO.OSDHISTORY_READ
Enables OSD history reading (used by some builds for behavior/cosmetic decisions).EJECT_TRAY
Eject tray the first time an empty tray is detected.LOGO_DISPLAY0: no logo/info1: console info only2: logo + console info
HDD_ENABLE=1MX4SIO_ENABLE=1MMCE_ENABLE=1XFROM_ENABLE=1
LOAD_IRX_E#=<path>
Loads additional IRX modules during startup/parse time (useful for some setups).- This does not automatically guarantee a device becomes a config source for the same boot pass.
Launch keys map controller buttons to either:
- an ELF path, or
- an internal command (starts with
$).
LK_<BUTTON>_E#
<BUTTON>:
AUTO, SELECT, L3, R3, START, UP, RIGHT, DOWN, LEFT, L2, R2, L1, R1, TRIANGLE, CIRCLE, CROSS, SQUAREE#: entry index (useE1..E3for simple, reliable setups)
PS2BBLE checks entries in order (E1 -> E2 -> E3) until one works.
You can bind commands instead of ELF paths:
$CDVD
Boot disc, respecting the config's logo preference.$CDVD_NO_PS2LOGO
Boot disc forcing "skip PS2LOGO".
Example:
LK_CROSS_E1=$CDVD
LK_TRIANGLE_E1=$CDVD_NO_PS2LOGO$CREDITS- show credits/build info$OSDSYS- run OSDSYS with arguments intended to skip update flows and land in MC browser
(On PSX-DESR, OSDSYS menus differ; this may be useless there.)$RUNKELF:<KELFPATH>- run a KELF at<KELFPATH>$HDDCHECKER- HDD integrity/status checks (only when HDD support is enabled)
Common executable path formats:
mc0:/...- Memory Card slot 1mc1:/...- Memory Card slot 2mc?:/...- pseudo-device that searches both MC slotsmass:/...- USB storage mapped by USBMASSmassX:/...- MX4SIO SD mapping (when enabled)rom0:...- console ROM executables (e.g.,rom0:TESTMODE)hdd0:PARTITION:pfs:/path/to.elf- internal HDD PFS path
Example:
LK_SELECT_E1=rom0:TESTMODE
LK_AUTO_E1=hdd0:__sysconf:pfs:/PS2BBL/BOOT.ELFPS2BBLE can be built with driver stacks that are:
Drivers are built into the ELF, reducing dependency on external IRX files (helpful if storage contents are lost or corrupted).
Drivers are loaded from storage at boot. In these builds, keep required IRX files available on the memory card.
Typical external IRX lookup order:
mc0:/SYS-CONF/<IRX>mc1:/SYS-CONF/<IRX>mc?:/SYS-CONF/<IRX>
KEY_READ_WAIT_TIME=500
LOGO_DISPLAY=2
LK_AUTO_E1=mc?:/BOOT/BOOT.ELF
LK_AUTO_E2=mc?:/BOOT/BOOT2.ELFKEY_READ_WAIT_TIME=500
LOGO_DISPLAY=2
LK_AUTO_E1=mc?:/BOOT/BOOT.ELF
LK_AUTO_E2=mc?:/BOOT/BOOT2.ELF
LK_AUTO_E3=mass:/RESCUE.ELFAnd keep a rescue app at:
mass:/RESCUE.ELF
KEY_READ_WAIT_TIME=500
LOGO_DISPLAY=2
SKIP_PS2LOGO=0
LK_AUTO_E1=mc?:/BOOT/BOOT.ELF
LK_CROSS_E1=$CDVD
LK_TRIANGLE_E1=$CDVD_NO_PS2LOGO# Boot behavior
SKIP_PS2LOGO=0
EJECT_TRAY=1
OSDHISTORY_READ=1
KEY_READ_WAIT_TIME=4000
LOGO_DISPLAY=2
# Optional: load extra IRX
LOAD_IRX_E1=mass:/PS2BBL/EXAMPLE.IRX
# AUTO chain
LK_AUTO_E1=mc?:/APPS/OPNPS2LD.ELF
LK_AUTO_E2=mc?:/OPL/OPNPS2LD.ELF
LK_AUTO_E3=mass:/OPNPS2LD.ELF
# System & disc
LK_SELECT_E1=rom0:TESTMODE
LK_START_E1=$OSDSYS
LK_CROSS_E1=$CDVD
LK_TRIANGLE_E1=$CDVD_NO_PS2LOGO- Emergency Mode: hold R1 + START
If you have a rescue ELF atmass:/RESCUE.ELF, PS2BBLE will repeatedly attempt it. - Put your config on memory card:
mc1:/SYS-CONF/PS2BBL.INI(optionally duplicate tomc0:). - Check your paths carefully:
A single typo will cause an entry to fail and fall through to the next entry. - If using runtime drivers:
Ensure required IRX files exist undermc0:/SYS-CONF/.
Usually means one of:
- your build does not include that feature,
- the device isn't enabled/initialized successfully,
- required IRX files are missing (runtime builds).
Start with a working MC-only config, then add one device at a time.
Upstream PS2BBL documentation reports broad compatibility across many retail PS2 models and PSX-DESR variants, with special notes for:
- very early Japanese models requiring kernel patch updates,
- some late SCPH-900xx situations where "system update" constraints can affect auto-boot style installs.
If you publish releases targeting specific hardware/variants (PS2 retail vs PSX-DESR vs Namco System 2x6), include a release note that states:
- the target,
- supported devices,
- and what install/auto-boot modes are included (if any).
PS2BBL-family bootloaders are commonly used as an alternative to FreeMcBoot because they:
- emphasize deterministic config-driven boot behavior,
- provide disc-boot commands and emergency recovery loops,
- offer builds with embedded drivers (reducing dependency on external files),
- can be friendlier to some modchip environments (depending on setup/build) by avoiding certain OSDSYS patching approaches used elsewhere.
Both ecosystems are valuable; choose what best matches your hardware and goals.
Building requires a working ps2sdk toolchain in PATH.
Typical build:
makecl commonly builds multiple variants by enumerating feature flags (embedded vs runtime drivers, device support, chainload modes, etc.). Compatibility note: "normal" builds embed IRX for selected devices, and MMCE + MX4SIO embedded modes are mutually exclusive. Automated prerelease artifacts omit MMCE+MX4SIO combinations accordingly.
- OSD initialization libraries and related work: @SP193
- Original PS2BBL creator: @israpps (El_isra)
- Fork lineage and contributions: @pcm720, plus community contributors
- License: GNU General Public License v3.0 (see
LICENSE)