starred/BFpilot
1
0 Fork 0
mirror of https://github.com/ItsBlurf/BFpilot.git synced 2026-10-18 23:06:53 -05:00
Code Issues Packages Projects Releases 10 Wiki Activity

Release BFpilot v0.3

Browse Source
This commit is contained in:
ItsBlurf committed 2026-06-19 01:57:07 +00:00
1 parent bc2c0e284f
commit 43ada0e1ae
42 files changed
+1220 -2326
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/COMPATIBILITY_STRATEGY.md
+58 -135
View File
@@ -1,162 +1,99 @@
# BFpilot Compatibility Strategy
BFpilot now separates the stable file manager from the fragile launcher
installer path.
BFpilot now keeps the stable file manager and the fragile launcher installer as
separate payloads.
## Payload Roles
### `bfpilot.elf`
This is the main release payload. It is firmware-light and should be tested
first on every firmware and loader.
Main release payload. Test this first on every firmware and loader.
- Starts the HTTP file manager on port `5905`.
- Does not install a launcher tile.
- Does not include `src/app_installer.c`.
- Does not link `libSceAppInstUtil`.
- Does not depend on AppInstUtil, SystemService, UserService, or launcher-only
Sony libraries.
- Does not install or refresh a launcher tile.
- Does not include integrated launcher installer source.
- Does not link AppInstUtil.
- Does not depend on SystemService, UserService, AppInstUtil, or `kernel_sys`.
- Writes boot/runtime/crash diagnostics under `/data/BFpilot`.
Broad firmware support comes from avoiding imports that can fail before
`main()` on some loaders or firmware combinations.
### `bfpilot-debug.elf`
This is the same file-manager payload with extra debug notifications/logging.
It still avoids AppInstUtil and launcher installer code.
Use it when `bfpilot.elf` appears to do nothing. If the debug payload writes
`/data/BFpilot/boot.log`, it reached `main()`.
### `bfpilot-full.elf`
This build restores the 0.2.0-style integrated launcher flow for firmware and
loaders where that path worked.
- Starts BFpilot from the same file-manager process.
- Runs optional `sceNetCtlInit` and `sceUserServiceInitialize` resolution/init.
- Dynamically resolves AppInstUtil symbols instead of direct-linking
AppInstUtil.
- Attempts `/user/app/BFPL00001` install/refresh before the web server loop.
- Continues to the web server if launcher install fails.
Use this first when specifically testing home-screen tile install on firmware
11.6, because it is closest to the previous full build that installed there.
`main()` on some loader/firmware combinations.
### `bfpilot-launcher-installer.elf`
This optional payload installs or refreshes `/user/app/BFPL00001`.
Isolated optional payload for installing or refreshing `/user/app/BFPL00001`.
Run it only after `bfpilot.elf` works.
It is intentionally isolated from the file manager:
- Direct-links the working websrv-style installer dependency set:
`kernel_sys`, SystemService, UserService, and AppInstUtil.
- Initializes UserService.
- Temporarily sets authid `0x4801000000000013`.
- Validates/stages embedded `param.json` and `icon0.png`.
- Registers the tile through AppInst.
- Restores the original authid before exit.
- Logs to `/data/BFpilot/launcher-installer.log`.
- It direct-links AppInstUtil, matching the launcher-install pattern used by
websrv, Payload Manager, and ftpsrv.
- It also links `kernel_sys`, SystemService, and UserService, initializes
UserService, temporarily sets authid `0x4801000000000013`, and restores the
original authid after registration.
- It logs to `/data/BFpilot/launcher-installer.log`.
- It cannot break the file manager because it is not part of `bfpilot.elf`.
The tile target is:
If `bfpilot.elf` works but the launcher installer fails, the issue is the
AppInstUtil/launcher path, not the file manager.
```text
http://127.0.0.1:5905/
```
### `bfpilot-launcher-installer-safe.elf`
## Why The Split Exists
This diagnostic payload avoids direct AppInstUtil imports and checks whether
AppInstUtil is already reachable through runtime symbol lookup. It is not the
force install path. Use it after the direct installer gives no notification or
log.
Working PS5 launcher projects such as ps5 websrv, Payload Manager, and
elf-arsenal use the complete AppInst service/privilege composition. Partial
approaches are unreliable:
## Launcher/AppInst Findings
- AppInst-only direct imports can be rejected before `main()`.
- Runtime AppInst lookup can return unavailable on some environments.
- Loading AppInst without the matching service/authid context can fail before a
useful install result is produced.
The current probes separate three cases:
- `tests/installer_enter_probe.elf` writes a marker with safe imports only.
If this works, the loader can run ordinary BFpilot-shaped ELFs.
- `tests/installer_linkonly_appinst.elf` directly imports AppInstUtil but does
not call it. If this payload does not write its marker, the loader or
firmware rejected the ELF before `main()`.
- `tests/installer_runtime_resolve_appinst.elf` has safe imports only and then
checks whether `libSceAppInstUtil.sprx` is already loaded. If
`kernel_dynlib_handle` returns `0xffffffff`, AppInstUtil is not reachable
through the safe runtime path.
The AppInst-only direct probe can fail even when the complete websrv pattern
works. `tests/installer_websrv_pattern.elf` reproduces the full dependency and
privilege setup without registering a title. On the tested live PS5 it reached
`main()` and returned zero from AppInst initialization; the repaired isolated
installer then registered the tile successfully.
## Patterns Checked
`ps5-payload-dev/websrv`, Payload Manager by itsPLK, and elf-arsenal launcher
installers all use the same basic AppInst pattern:
- link `libSceAppInstUtil` directly;
- call `sceAppInstUtilInitialize()` directly;
- resolve only `sceAppInstUtilAppInstallTitleDir` by NID `Wudg3Xe3heE`;
- fall back to `sceAppInstUtilAppInstallAll()`.
That pattern can work in environments where direct AppInst imports are accepted,
but it can also fail before `main()` on loaders that reject or cannot satisfy
the import. BFpilot keeps this pattern out of `bfpilot.elf`.
Working payloads depend on a system authid before AppInst init can succeed on
newer firmware. BFpilot implements that only in the isolated launcher installer.
The stable file manager does not change authid and does not import launcher
services.
BFpilot keeps that risk out of the file manager. If the installer fails, the
file manager payload remains compatible and usable.
## Boot Marker
Every ELF calls:
Both release ELFs call:
```c
bfpilot_boot_marker(payload_name, build_mode);
```
as the first meaningful line in `main()`.
early in `main()`.
The marker:
- Prints `BFpilot BOOT: <payload_name> <build_mode> entered main`.
- Tries to create `/data/BFpilot`.
- Appends payload name, build mode, PID, and build version to
`/data/BFpilot/boot.log`.
- Attempts a notification titled `BFpilot BOOT`.
- Continues if notification fails.
- prints `BFpilot BOOT: <payload_name> <build_mode> entered main`
- creates `/data/BFpilot` if possible
- appends payload name, build mode, PID, and build version to
`/data/BFpilot/boot.log`
- attempts a notification titled `BFpilot BOOT`
- continues if notification fails
If no notification appears and no `/data/BFpilot/boot.log` entry exists, the
payload probably failed before `main()` or the loader rejected the ELF. If the
boot marker exists but the server does not start, the crash or hang is after
`main()`.
No notification and no boot-log entry usually means the loader rejected the ELF
or execution failed before `main()`. A boot marker without a working server or
installer result means the failure happened after `main()`.
## Reload Behavior
Startup is explicit:
`bfpilot.elf` startup is explicit:
1. Boot marker runs.
2. BFpilot checks whether the selected port already has an old BFpilot server.
3. If an old server is found, BFpilot notifies `BFpilot reload: old server detected`.
4. BFpilot asks the old server to shut down through `/api/control/shutdown`.
5. If shutdown succeeds, the new server starts.
6. If shutdown fails or a file job is busy, BFpilot notifies `BFpilot reload blocked`,
logs the exact reason to `/data/BFpilot/log.txt`, and exits cleanly.
3. If an old server is found, BFpilot asks it to shut down through
`/api/control/shutdown`.
4. If shutdown succeeds, the new server starts.
5. If shutdown fails or a file job is busy, BFpilot logs the reason and exits
cleanly.
This avoids the misleading case where reinjection looks like nothing happened.
## Alternate Port
The default web port is compile-time configurable with `BFPILOT_WEB_PORT`.
Runtime port override is supported:
The default web port is `5905`. A runtime alternate port can be passed as:
```text
--port 5906
```
Use this to test a new build while an old BFpilot instance is still running on
`5905`.
## Import Inspection
Run:
@@ -165,29 +102,15 @@ Run:
make inspect-imports
```
The target prints file size, dynamic libraries/imports, undefined symbols, and
SCE-related symbol/string hints for:
The target builds and checks only:
- `bfpilot.elf`
- `bfpilot-debug.elf`
- `bfpilot-full.elf`
- `bfpilot-launcher-installer.elf`
- `bfpilot-launcher-installer-safe.elf`
- `tests/hello_boot.elf`
- `tests/hello_http.elf`
- `tests/hello_notify.elf`
- `tests/installer_enter_probe.elf`
- `tests/installer_linkonly_appinst.elf`
- `tests/installer_runtime_resolve_appinst.elf`
It fails if `bfpilot.elf` or `bfpilot-debug.elf` contain:
It fails if `bfpilot.elf` contains launcher/AppInstUtil fingerprints or direct
launcher imports. It also fails if the installer is missing any required direct
dependency: `libkernel_sys.sprx`, `libSceSystemService.sprx`,
`libSceUserService.sprx`, or `libSceAppInstUtil.sprx`.
- `SceAppInstUtil`
- `sceAppInst`
- `app_installer`
- `BFPL00001`
Only installer/probe payloads may directly import AppInstUtil. The release
installer must additionally import `kernel_sys`, SystemService, and UserService.
The link-only test intentionally proves that an incomplete AppInst-only
composition can be rejected before `main()`.
The supported release build contains only the file manager payload and the
isolated launcher installer.