From 571999ac49d28f28278317b99111cb35a413b886 Mon Sep 17 00:00:00 2001 From: Niklas080208 Date: Sat, 17 Jan 2026 19:42:39 +0100 Subject: [PATCH] Documented the Install process --- INSTALLATION_PROCESS.md | 460 ++++++++++++++++++++++++++++++++++++++++ README.md | 5 + 2 files changed, 465 insertions(+) create mode 100644 INSTALLATION_PROCESS.md diff --git a/INSTALLATION_PROCESS.md b/INSTALLATION_PROCESS.md new file mode 100644 index 0000000..f2276eb --- /dev/null +++ b/INSTALLATION_PROCESS.md @@ -0,0 +1,460 @@ +# OmniNX Installer - Installation Process Documentation + +This document provides a detailed, step-by-step breakdown of everything that is checked and done during the OmniNX installation/update process. + +## Overview + +The OmniNX Installer Payload operates in two modes: +- **Update Mode**: When OmniNX is already installed, performs selective cleanup +- **Clean Install Mode**: When no OmniNX is detected, performs full wipe with backup/restore + +--- + +## Phase 1: Initialization & Detection + +### Step 1: Hardware Initialization +**Location**: `main.c:185` +- Initialize hardware via `hw_init()` +- Pivot stack to `IPL_STACK_TOP` +- Initialize heap at `IPL_HEAP_START` + +### Step 2: Configuration Setup +**Location**: `main.c:190` +- Set default bootloader configuration: + - Autoboot: disabled + - Boot wait: 3 seconds + - Backlight: 100% + - SE keygen status: false + - Detect chip variant (T210B01 check) + - Check RCM patched status + +### Step 3: SD Card Mounting +**Location**: `main.c:193` +- Attempt to mount SD card filesystem +- **Error Handling**: If mount fails → reboot system (can't show error without display) + +### Step 4: System Initialization +**Location**: `main.c:198-211` +- Initialize Minerva memory controller (set to 800MHz) +- Initialize display and framebuffer (720x1280) +- Initialize graphics console +- Set display backlight to 100% +- Overclock BPMP (Boot and Power Management Processor) + +### Step 5: Installation Detection +**Location**: `main.c:216`, `version.c:127` +- Check for `sd:/config/omninx/manifest.ini` file +- If manifest exists: + - Parse manifest to extract `current_pack` value + - Determine variant: `standard`, `light`, or `oc` + - Read version information + - Set `is_installed = true` +- **Detection Method**: Reads INI file with `[OmniNX]` section containing `current_pack` key + +### Step 6: Pack Variant Detection +**Location**: `main.c:219`, `version.c:146` +- Check for staging directories (in order of priority): + 1. `sd:/OmniNX Standard/` + 2. `sd:/OmniNX Light/` + 3. `sd:/OmniNX OC/` +- **Error Handling**: If none found → display error message and wait for button input + +### Step 7: Installation Mode Determination +**Location**: `main.c:287` +- If `is_installed == true` → `INSTALL_MODE_UPDATE` +- If `is_installed == false` → `INSTALL_MODE_CLEAN` + +--- + +## Phase 2: User Confirmation + +### Step 8: Information Display +**Location**: `main.c:289-298` +- Display installation mode: "Update" or "Saubere Installation" (Clean Install) +- Display pack variant to install: "Standard", "Light", or "OC" +- Display current installation variant (if any) or "Keine" (None) + +### Step 9: User Input Wait +**Location**: `main.c:314-338` +- Wait for user confirmation via: + - **A button** on right Joy-Con, OR + - **Power button** +- Blocks until button is pressed (checks every 50ms) + +--- + +## Phase 3: Update Mode Execution + +**Trigger**: `INSTALL_MODE_UPDATE` (OmniNX already installed) + +### Step 1: Cleanup (Selective Deletion) +**Location**: `install.c:321-380` + +#### 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... + +#### 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... + +#### 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. + +--- + +### Step 2: File Installation +**Location**: `install.c:383-526` + +#### 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 + +#### 24. Copy Bootloader Directory +**Location**: `install.c:404-406` +- **Source**: `{staging}/bootloader/` +- **Destination**: `sd:/bootloader/` +- Same progress tracking as above + +#### 25. Copy Config Directory +**Location**: `install.c:408-410` +- **Source**: `{staging}/config/` +- **Destination**: `sd:/config/` +- Same progress tracking + +#### 26. Copy Switch Directory +**Location**: `install.c:412-414` +- **Source**: `{staging}/switch/` +- **Destination**: `sd:/switch/` +- Same progress tracking + +#### 27. Copy warmboot_mariko Directory +**Location**: `install.c:416-418` +- **Source**: `{staging}/warmboot_mariko/` +- **Destination**: `sd:/warmboot_mariko/` +- Only if directory exists in staging + +#### 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 + +#### 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` + +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) + +--- + +## Phase 4: Clean Install Mode Execution + +**Trigger**: `INSTALL_MODE_CLEAN` (No OmniNX detected) + +### Step 1: Backup User Data +**Location**: `backup.c:18-52` + +#### 32. Create Backup Directory +- Creates `sd:/temp_backup/` directory + +#### 33. Backup DBI +- **Source**: `sd:/switch/DBI/` +- **Destination**: `sd:/temp_backup/DBI/` +- Only if source exists + +#### 34. Backup Tinfoil +- **Source**: `sd:/switch/tinfoil/` +- **Destination**: `sd:/temp_backup/tinfoil/` +- Only if source exists + +#### 35. Backup prod.keys +- **Source**: `sd:/switch/prod.keys` +- **Destination**: `sd:/temp_backup/prod.keys` +- Only if source exists + +--- + +### Step 2: Wipe Directories +**Location**: `install.c:543-602` + +#### 36. 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) + +#### 37. Delete Root Files +- Uses same deletion list as update mode (Step 19) +- Deletes `boot.dat`, `boot.ini`, `exosphere.ini`, etc. + +#### 38. Delete Miscellaneous Items +- Uses same deletion lists as update mode (Steps 20-21) +- Deletes `argon/`, `games/`, `SaltySD/`, etc. + +#### 39. Recreate Switch Directory +- Creates empty `sd:/switch/` directory for restoration + +--- + +### Step 3: Restore User Data +**Location**: `backup.c:55-95` + +#### 40. Restore DBI +- **Source**: `sd:/temp_backup/DBI/` +- **Destination**: `sd:/switch/DBI/` +- **Cleanup**: After restoration, deletes old DBI NRO files: + - `sd:/switch/DBI/DBI_810_EN.nro` + - `sd:/switch/DBI/DBI_810_DE.nro` + - `sd:/switch/DBI/DBI_845_EN.nro` + - `sd:/switch/DBI/DBI_845_DE.nro` + - `sd:/switch/DBI/DBI.nro` + +#### 41. Restore Tinfoil +- **Source**: `sd:/temp_backup/tinfoil/` +- **Destination**: `sd:/switch/tinfoil/` +- **Cleanup**: After restoration, deletes `sd:/switch/tinfoil/tinfoil.nro` + +#### 42. Restore prod.keys +- **Source**: `sd:/temp_backup/prod.keys` +- **Destination**: `sd:/switch/prod.keys` + +#### 43. Cleanup Backup Directory +**Location**: `backup.c:98-103` +- Deletes `sd:/temp_backup/` directory after restoration + +--- + +### 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 + +--- + +## Phase 5: Completion & Launch + +### Step 44: Installation Summary +**Location**: `main.c:363-377` +- Display success message if `result == FR_OK && total_errors == 0` +- Display error count if errors occurred +- Show completion status + +### Step 45: Payload Launch Wait +**Location**: `main.c:382-454` +- Wait for A button or Power button +- Check if `sd:/bootloader/update.bin` exists +- If payload exists: + - Launch payload (relocates and executes) +- If payload doesn't exist: + - Display error message + - Wait for button again + - Reboot system + +--- + +## 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 +- **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 + +### 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 + +### 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 + +### 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) + +--- + +## 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) + +### 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) + +**Result**: In both modes, the SD card ends up with a fresh OmniNX installation while preserving user data and savegames. diff --git a/README.md b/README.md index 97505ba..20c0868 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,11 @@ Based on [HATS-Installer-Payload](https://github.com/sthetix/HATS-Installer-Payl - **Error Handling**: Detailed error reporting on screen - **Payload Chaining**: Automatically launch hekate after installation +## Documentation + +For detailed information about the installation process, see: +- **[INSTALLATION_PROCESS.md](INSTALLATION_PROCESS.md)** - Complete step-by-step breakdown of everything checked and done during installation/update + ## Installation Modes ### Update Mode (OmniNX Detected)