OmniNX/OmniNX-Installer-Payload
2
0 Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: describe move-based install, new update list rules and logging

Browse Source
This commit is contained in:
niklascfw committed 2026-11-12 22:59:46 +01:00
1 parent 5241cccbe9
commit 1df97d3a86
2 files changed
+66 -255
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

INSTALLATION_PROCESS.md
+59 -249
View File
@@ -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 <OmniNX repo>` 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 <Variant>/`) 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 <Variant>/` 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: <group> [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.