docs: move process, debug.ini and preserve.ini docs to docs/
This commit is contained in:
niklascfw committed
1 parent
f2230c79a7
commit
14be4646d0
5 files changed
+28
-27
No files matched your search
@@ -0,0 +1,259 @@
|
||||
# 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.
|
||||
|
||||
For **optional debug step skips** (`sd:/config/omninx/debug.ini`), see **[DEBUG_INI.md](DEBUG_INI.md)**.
|
||||
|
||||
## 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, `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`), 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.
|
||||
|
||||
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`.
|
||||
|
||||
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.
|
||||
|
||||
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_update.c` (`update_mode_install`), `fs.c` (`fs_move_tree`, `fs_move_file`)
|
||||
|
||||
Staging (`sd:/OmniNX <Variant>/`) and the target are on the same SD card, so files are **moved**, not copied:
|
||||
|
||||
| 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:/` |
|
||||
|
||||
- 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.
|
||||
|
||||
`manifest.ini` is part of the pack (`config/omninx/manifest.ini`) and arrives with `config/`.
|
||||
|
||||
### Step 3: Extras
|
||||
**Location**: `install.c` (`install_extras_post_copy`)
|
||||
|
||||
- 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.
|
||||
|
||||
### Step 4: Cleanup Staging Directory
|
||||
**Location**: `install_update.c` (`cleanup_staging_directory`), `install_clean.c` (`cleanup_other_staging_directories`)
|
||||
|
||||
- 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.
|
||||
|
||||
---
|
||||
|
||||
## 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 settings
|
||||
- **Source**: `sd:/switch/DBI/dbi.config` (file only, not the whole `DBI` tree)
|
||||
- **Destination**: `sd:/temp_backup/dbi.config`
|
||||
- Only if the source file exists
|
||||
|
||||
#### 34. Backup prod.keys
|
||||
- **Source**: `sd:/switch/prod.keys`
|
||||
- **Destination**: `sd:/temp_backup/prod.keys`
|
||||
- Only if source exists
|
||||
|
||||
---
|
||||
|
||||
### Step 2: Wipe (Selective Deletion)
|
||||
**Location**: `install_clean.c` (`clean_mode_wipe`), lists in `deletion_lists_clean.h`
|
||||
|
||||
- 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.
|
||||
|
||||
---
|
||||
|
||||
### Step 3: Restore User Data
|
||||
**Location**: `backup.c:55-95`
|
||||
|
||||
#### 39. Restore DBI settings
|
||||
- **Source**: `sd:/temp_backup/dbi.config`
|
||||
- **Destination**: `sd:/switch/DBI/dbi.config` (creates `sd:/switch/DBI/` if needed)
|
||||
- No longer copies the full `DBI` folder; old `.nro` cleanup is unnecessary
|
||||
|
||||
#### 40. Restore prod.keys
|
||||
- **Source**: `sd:/temp_backup/prod.keys`
|
||||
- **Destination**: `sd:/switch/prod.keys`
|
||||
|
||||
#### 41. Cleanup Backup Directory
|
||||
**Location**: `backup.c` (`cleanup_backup`)
|
||||
- Deletes `sd:/temp_backup/` directory after restoration
|
||||
|
||||
---
|
||||
|
||||
### Step 4: Install Files, Extras, Cleanup
|
||||
- **Same as Update Mode Steps 2-4**
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
- 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
|
||||
- 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 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`).
|
||||
|
||||
### 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**: Directory existence check for `sd:/OmniNX Standard|Light|OC/`; a menu is shown when several are present
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
### Update Mode Flow
|
||||
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 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 user data and user-installed homebrew are kept.
|
||||
Reference in new issue
Block a user