From 1df97d3a8677d76070a2f5dbfa33ff9ddb0433c9 Mon Sep 17 00:00:00 2001 From: niklascfw Date: Thu, 12 Nov 2026 22:59:46 +0100 Subject: [PATCH] docs: describe move-based install, new update list rules and logging --- INSTALLATION_PROCESS.md | 308 ++++++++-------------------------------- README.md | 13 +- 2 files changed, 66 insertions(+), 255 deletions(-) diff --git a/INSTALLATION_PROCESS.md b/INSTALLATION_PROCESS.md index 3c9b5cb..615668e 100644 --- a/INSTALLATION_PROCESS.md +++ b/INSTALLATION_PROCESS.md @@ -87,215 +87,54 @@ The OmniNX Installer Payload operates in two modes: ## Phase 3: Update Mode Execution -**Trigger**: `INSTALL_MODE_UPDATE` (OmniNX already installed) +**Trigger**: `INSTALL_MODE_UPDATE` (OmniNX already installed, `manifest.ini` has a valid `current_pack`) ### Step 1: Cleanup (Selective Deletion) -**Location**: `install_update.c` (`update_mode_cleanup`), `install.c` (`delete_path_lists_grouped`) +**Location**: `install_update.c` (`update_mode_cleanup`), `install.c` (`delete_path_lists_grouped`), lists in `deletion_lists_update.h` Before deletion, the payload reads optional **`sd:/config/omninx/preserve.ini`** (section `[Preserve]`). Paths enabled there are skipped, as are delete targets that would remove them (parent/child overlap). See **[PRESERVE_INI.md](PRESERVE_INI.md)**. Clean install does not use this file. -#### 10. Clean Atmosphere Subdirectories -**Location**: `install.c:325-327`, `deletion_lists.h:9-34` -Deletes 34 specific subdirectories: -- `atmosphere/config/` -- `atmosphere/crash_reports/` -- `atmosphere/exefs_patches/*` (various patch directories) -- `atmosphere/kip1/`, `atmosphere/kips/` -- `atmosphere/logs/` -- And more... +The update list only contains: +- paths the current pack ships (removed first so the new files replace them cleanly), +- components OmniNX used to ship and dropped (e.g. sys-ticon `00FF747765616BFF`), +- boot-relevant housekeeping: Atmosphere logs/reports, foreign `exefs_patches`/`kip` folders, legacy bootloader and root boot files, `themes/systemData`. -#### 11. Clean Atmosphere Root Directories (Title IDs) -**Location**: `install.c:330-331`, `deletion_lists.h:38-72` -Deletes 29 title ID directories: -- `atmosphere/0000000000534C56/` -- `atmosphere/0100000000000008/` -- `atmosphere/010000000000000D/` -- And 26 more title ID folders... +It deliberately does **not** contain apps, sysmodules or game title IDs a user can install on their own (e.g. through OmniNX Downloader). Those survive updates. Leftovers of other CFW packs are only removed by a clean install. `tools/audit_update_list.py ` checks the list against the pack history. -#### 12. Clean Atmosphere Contents Directories -**Location**: `install.c:333-334`, `deletion_lists.h:75-110` -Deletes 29 corresponding `atmosphere/contents/` title ID directories - -#### 13. Clean Atmosphere Files -**Location**: `install.c:336-337`, `deletion_lists.h:113-122` -Deletes 7 specific files: -- `atmosphere/config/exosphere.ini` -- `atmosphere/config/override_config.ini` -- `atmosphere/config/stratosphere.ini` -- `atmosphere/hbl.nsp` -- `atmosphere/package3` -- `atmosphere/reboot_payload.bin` -- `atmosphere/stratosphere.romfs` - -#### 14. Clean Bootloader Directories -**Location**: `install.c:340-343`, `deletion_lists.h:125-134` -Deletes 7 bootloader subdirectories: -- `bootloader/boot/` -- `bootloader/bootlogo/` -- `bootloader/ini2/` -- `bootloader/payloads/` -- `bootloader/reboot/` -- `bootloader/res/` -- `bootloader/sys/` - -#### 15. Clean Bootloader Files -**Location**: `install.c:345-346`, `deletion_lists.h:137-146` -Deletes 7 specific files: -- `bootloader/ArgonNX.bin` -- `bootloader/bootlogo.bmp` -- `bootloader/hekate_ipl.ini` -- `bootloader/nyx.ini` -- `bootloader/patches.ini` -- `bootloader/update.bin` -- `bootloader/ini/EmuMMC ohne Mods.ini` - -#### 16. Clean Config Directories -**Location**: `install.c:349-352`, `deletion_lists.h:149-160` -Deletes 8 config subdirectories: -- `config/aio-switch-updater/` -- `config/blue_pack_updater/` -- `config/kefir-updater/` -- `config/nx-hbmenu/` -- `config/quickntp/` -- `config/sys-con/` -- `config/sys-patch/` -- `config/uberhand/`, `config/ultrahand/` - -#### 17. Clean Switch Directories -**Location**: `install.c:355-358`, `deletion_lists.h:163-226` -Deletes 55+ switch application directories: -- `switch/.overlays/`, `switch/.packages/` -- `switch/aio-switch-updater/` -- `switch/DBI_810/`, `switch/DBI_810_DE/`, `switch/DBI_810_EN/` -- `switch/tinfoil/` -- `switch/EdiZon/`, `switch/JKSV/`, `switch/checkpoint/` -- And 40+ more application directories... - -#### 18. Clean Switch Files -**Location**: `install.c:360-361`, `deletion_lists.h:229-278` -Deletes 47+ NRO files and other files: -- `switch/tinfoil.nro` -- `switch/DBI.nro` -- `switch/DBI/DBI_810_*.nro` (various versions) -- `switch/daybreak.nro` -- And 40+ more files... - -#### 19. Clean Root Files -**Location**: `install.c:364-367`, `deletion_lists.h:281-295` -Deletes 12 root-level CFW files: -- `boot.dat`, `boot.ini` -- `exosphere.bin`, `exosphere.ini` -- `hbmenu.nro` -- `loader.bin`, `payload.bin` -- `update.bin`, `version` -- And more... - -#### 20. Clean Miscellaneous Directories -**Location**: `install.c:369-370`, `deletion_lists.h:298-309` -Deletes 9 miscellaneous directories: -- `argon/`, `games/`, `NSPs (Tools)/` -- `Patched Apps/`, `SaltySD/` -- `scripts/`, `tools/` -- `warmboot_mariko/` -- `switch/tinfoil/db/` - -#### 21. Clean Miscellaneous Files -**Location**: `install.c:372-373`, `deletion_lists.h:312-322` -Deletes 8 miscellaneous files: -- `fusee-primary.bin`, `fusee.bin` -- `SaltySD/*.elf` (various bootstrap files) - -#### 22. Cleanup Old Version Markers -**Location**: `install.c:308-318`, `deletion_lists.h:325-335` -Deletes legacy version marker files: -- `1.0.0l`, `1.0.0s`, `1.0.0oc` -- `1.4.0-pre`, `1.4.0-pre-c`, `1.4.0-pre-d` -- `1.4.1`, `1.5.0` - -**Note**: Each deletion operation checks if path exists before attempting deletion. +Deletion runs per group (`atmosphere/`, `bootloader/`, `config/`, `switch/`, root files) with one progress line each. Every entry is checked with a single `f_stat`; folders with more than 50 entries get their own progress line (detected with a probe that stops after 51 entries, not a full count). --- ### Step 2: File Installation -**Location**: `install.c:383-526` +**Location**: `install_update.c` (`update_mode_install`), `fs.c` (`fs_move_tree`, `fs_move_file`) -#### 23. Copy Atmosphere Directory -**Location**: `install.c:400-402` -- **Source**: `{staging}/atmosphere/` (e.g., `sd:/OmniNX Standard/atmosphere/`) -- **Destination**: `sd:/atmosphere/` -- **Progress**: Recursively counts all files/directories, displays percentage -- **Tracking**: Updates progress every 10 items or when percentage changes +Staging (`sd:/OmniNX /`) and the target are on the same SD card, so files are **moved**, not copied: -#### 24. Copy Bootloader Directory -**Location**: `install.c:404-406` -- **Source**: `{staging}/bootloader/` -- **Destination**: `sd:/bootloader/` -- Same progress tracking as above +| Folder | Notes | +|--------|-------| +| `atmosphere/`, `bootloader/`, `config/`, `switch/`, `themes/`, `warmboot_mariko/`, `hwtest/`, `extras/` | if present in the pack | +| `SaltySD/` | OC variant only | +| files at the pack root (`payload.bin`, `hbmenu.nro`, ...) | moved to `sd:/` | -#### 25. Copy Config Directory -**Location**: `install.c:408-410` -- **Source**: `{staging}/config/` -- **Destination**: `sd:/config/` -- Same progress tracking +- If the target folder does not exist yet, the whole folder is moved with one `f_rename`. +- If it exists, the pack folder is merged entry by entry: missing subfolders move in one step, files replace existing ones (read-only flag is cleared first). +- If a rename fails, that entry falls back to a copy (1 MB buffer, allocated once per run). +- The progress line counts processed entries (`Installiere: switch/ (n)`), so no extra pass over the tree is needed. -#### 26. Copy Switch Directory -**Location**: `install.c:412-414` -- **Source**: `{staging}/switch/` -- **Destination**: `sd:/switch/` -- Same progress tracking +`manifest.ini` is part of the pack (`config/omninx/manifest.ini`) and arrives with `config/`. -#### 27. Copy warmboot_mariko Directory -**Location**: `install.c:416-418` -- **Source**: `{staging}/warmboot_mariko/` -- **Destination**: `sd:/warmboot_mariko/` -- Only if directory exists in staging +### Step 3: Extras +**Location**: `install.c` (`install_extras_post_copy`) -#### 28. Copy SaltySD Directory (OC Variant Only) -**Location**: `install.c:421-425` -- **Source**: `{staging}/SaltySD/` -- **Destination**: `sd:/SaltySD/` -- **Condition**: Only copied if `variant == VARIANT_OC` -- **Note**: This is a large directory (~2500 files), so progress tracking is important +- RAM menu (4GB / 8GB) and Hekate / Atmosphere vs. Hekate-Pro / Atmosphere-Pro menu, unless `sd:/config/omninx/config.ini` already holds the choice. +- Hekate-Pro files are moved from `sd:/extras/hekate-ams-pro/` to `sd:/`; the 8GB payload is copied to `payload.bin` and `bootloader/update.bin`. +- `sd:/extras/` is deleted afterwards. -#### 29. Copy Root Files -**Location**: `install.c:428-466` -Copies individual files from staging root to SD root: -- `boot.dat` → `sd:/boot.dat` -- `boot.ini` → `sd:/boot.ini` -- `exosphere.ini` → `sd:/exosphere.ini` -- `hbmenu.nro` → `sd:/hbmenu.nro` -- `loader.bin` → `sd:/loader.bin` -- `payload.bin` → `sd:/payload.bin` +### Step 4: Cleanup Staging Directory +**Location**: `install_update.c` (`cleanup_staging_directory`), `install_clean.c` (`cleanup_other_staging_directories`) -Each file is only copied if it exists in staging. - -#### 30. Create manifest.ini -**Location**: `install.c:468-516` -Creates/overwrites `sd:/config/omninx/manifest.ini`: - -**Content Structure**: -```ini -[OmniNX] -current_pack={variant} # "Standard", "Light", or "OC" -version={VERSION} # e.g., "1.0.0" -update_channel={0|1|2} # light=0, oc=1, standard=2 -channel_pack={variant} # Same as current_pack -``` - -**Directory Creation**: Ensures `sd:/config/omninx/` exists before creating file. - ---- - -### Step 3: Cleanup Staging Directory -**Location**: `install.c:626-656` - -#### 31. Remove Staging Directory -**Location**: `install.c:634-652` -- Recursively deletes the entire staging directory: - - `sd:/OmniNX Standard/` OR - - `sd:/OmniNX Light/` OR - - `sd:/OmniNX OC/` -- **Error Handling**: Warns if deletion fails but continues (non-fatal) +- Deletes the staging folder of the installed variant (after the move it mostly contains empty folders) and any other `sd:/OmniNX /` folders. +- Failures are reported as a warning. --- @@ -321,26 +160,11 @@ channel_pack={variant} # Same as current_pack --- -### Step 2: Wipe Directories -**Location**: `install.c:543-602` +### Step 2: Wipe (Selective Deletion) +**Location**: `install_clean.c` (`clean_mode_wipe`), lists in `deletion_lists_clean.h` -#### 35. Delete Entire Directories -Recursively deletes (if they exist): -- `sd:/atmosphere/` (entire directory tree) -- `sd:/bootloader/` (entire directory tree) -- `sd:/config/` (entire directory tree) -- `sd:/switch/` (entire directory tree) - -#### 36. Delete Root Files -- Uses same deletion list as update mode (Step 19) -- Deletes `boot.dat`, `boot.ini`, `exosphere.ini`, etc. - -#### 37. Delete Miscellaneous Items -- Uses same deletion lists as update mode (Steps 20-21) -- Deletes `argon/`, `games/`, `SaltySD/`, etc. - -#### 38. Recreate Switch Directory -- Creates empty `sd:/switch/` directory for restoration +- Removes CFW folders and files of OmniNX and other packs from the clean list, including the whole `sd:/switch/` tree, `atmosphere/contents` overrides and legacy root files. +- Recreates an empty `sd:/switch/` for the restore step. --- @@ -362,17 +186,8 @@ Recursively deletes (if they exist): --- -### Step 4: Install Files -**Location**: `install.c:620-623` -- **Same as Update Mode Step 2** (Steps 23-30) -- Copies all directories and files from staging -- Creates `manifest.ini` - ---- - -### Step 5: Cleanup Staging -- **Same as Update Mode Step 3** (Step 31) -- Removes staging directory +### Step 4: Install Files, Extras, Cleanup +- **Same as Update Mode Steps 2-4** --- @@ -400,50 +215,45 @@ Recursively deletes (if they exist): ## Technical Details ### Progress Tracking -- **File Counting**: Recursively counts all files and directories before copy -- **Progress Updates**: Updates display every 10 items or when percentage changes +- One status line per operation, counting processed entries; no separate counting pass. +- Group deletion shows `Bereinige: [p%] (done/total)` over the list entries. - **Screen Management**: Automatically clears and reprints header when approaching bottom of screen ### Error Handling -- **Path Existence Checks**: Every operation checks if source exists before attempting -- **File System Errors**: Logged with descriptive error messages -- **Fallback Methods**: Some operations have fallback copy methods if primary fails -- **Non-Fatal Errors**: Staging directory cleanup failures are warned but don't abort installation +- Missing sources are skipped (`Ueberspringe: ... (nicht gefunden)`); a missing delete target counts as done. +- Failed moves fall back to copying per entry; remaining errors abort with source/target shown. +- Staging cleanup failures are warnings and do not abort the installation. -### File Copy Mechanism -- **Buffer Size**: 1MB (`FS_BUFFER_SIZE = 0x100000`) -- **Read/Write Verification**: Verifies bytes read/written match expected amounts -- **Attribute Preservation**: Copies file attributes (via `f_chmod`) -- **Recursive Copy**: Handles nested directory structures automatically +### File Operations (`fs.c`) +- `fs_delete_tree`, `fs_move_tree`, `fs_move_file`, `folder_copy`, `file_copy` share one path buffer per call (no `malloc` per entry) and visit each entry once. +- Copy buffer: 1MB, allocated on first use and freed after the run (`fs_release_buffers`). +- Copies verify read/written byte counts and keep file attributes (`f_chmod`). -### Memory Management -- **Dynamic Allocation**: Uses heap for file buffers and path strings -- **Cleanup**: Frees allocated memory after use -- **Stack Pivot**: Switches to dedicated stack area for payload execution +### Logging +- `debug.ini` `log=1` writes every deleted path, moved/copied entry and the result to `sd:/config/omninx/install.log` (see [DEBUG_INI.md](DEBUG_INI.md)). +- Formatting uses the BDK `s_vprintf`; newlib `printf` is not linked, which keeps the payload below the RCM size limit (the build fails above 126296 bytes). ### Detection Logic - **Installation Detection**: Based on `manifest.ini` file, not version marker files - **Variant Detection**: Parses `current_pack` from manifest INI format -- **Pack Detection**: Simple directory existence check (in priority order) +- **Pack Detection**: Directory existence check for `sd:/OmniNX Standard|Light|OC/`; a menu is shown when several are present --- ## Summary ### Update Mode Flow -1. Detect existing installation → Update mode -2. Selective cleanup (Steps 10-22) -3. Copy new files (Steps 23-30) -4. Create manifest (Step 30) -5. Cleanup staging (Step 31) +1. Existing OmniNX installation detected → Update mode +2. Selective cleanup from the update list (respects `preserve.ini`) +3. Move pack files into place +4. Extras (RAM / Hekate-Pro), remove `extras/` +5. Remove staging folders ### Clean Install Mode Flow -1. No installation detected → Clean install mode -2. Backup user data (Steps 32-35) -3. Full wipe (Steps 36-39) -4. Restore user data (Steps 40-43) -5. Copy new files (Steps 23-30) -6. Create manifest (Step 30) -7. Cleanup staging (Step 31) +1. No OmniNX installation detected → Clean install mode +2. Back up user data (DBI config, prod.keys, CyberFoil, Checkpoint) +3. Selective wipe from the clean list +4. Restore user data +5. Move pack files, extras, remove staging folders -**Result**: In both modes, the SD card ends up with a fresh OmniNX installation while preserving user data and savegames. +**Result**: In both modes the SD card ends up with a fresh OmniNX installation while user data and user-installed homebrew are kept. diff --git a/README.md b/README.md index cb138e0..843955f 100644 --- a/README.md +++ b/README.md @@ -108,12 +108,13 @@ Use hekate or another bootloader to launch the payload: 3. Detects which pack variant is on SD card 4. Determines installation mode (update vs clean) 5. Performs cleanup based on mode: - - **Update**: Selective deletion of specific paths - - **Clean**: Full wipe with backup/restore -6. Copies files from pack directory to SD root -7. Creates version marker file -8. Cleans up old version markers -9. Launches hekate (`sd:/bootloader/update.bin`) + - **Update**: Selective deletion of OmniNX-shipped paths (user-installed apps and sysmodules stay) + - **Clean**: Selective wipe with backup/restore of user data +6. Moves files from the pack directory to the SD root (same card, so no copying) +7. Applies extras (RAM / Hekate-Pro choice) and removes the pack directory +8. Launches hekate (`sd:/bootloader/update.bin`) + +Details: [INSTALLATION_PROCESS.md](INSTALLATION_PROCESS.md). Test runs can write a log via [`debug.ini`](DEBUG_INI.md) (`log=1`). ## Variant Support