docs: move process, debug.ini and preserve.ini docs to docs/

This commit is contained in:
niklascfw committed 2026-11-12 23:10:21 +01:00
1 parent f2230c79a7
commit 14be4646d0
5 files changed
+28 -27

No files matched your search

+96
View File
@@ -0,0 +1,96 @@
# Debug configuration (`debug.ini`)
Optional file to **skip parts of the install** for testing (e.g. run only deletion and inspect the SD card). If the file is **missing**, the installer ignores debug entirely and runs the full flow.
## Location
```
sd:/config/omninx/debug.ini
```
Create the folder `sd:/config/omninx/` on the SD card if it does not exist. Same parent directory as `manifest.ini` and `config.ini`.
## Format
- Section name must be exactly **`[Debug]`** (case-sensitive in the parser).
- One key per line: `name=value`.
- **Enabling a skip:** set the value so it **starts** with one of: `1`, `t`, `T`, `y`, `Y`
Examples: `1`, `true`, `yes`, `True` — all enable that skip.
- **Disabling:** `0`, `false`, `no`, or omit the key.
## Parameters
### Clean install mode (`INSTALL_MODE_CLEAN`)
| Key | What is skipped |
|-----|-----------------|
| `skip_clean_backup` | Step 1 — backup of `sd:/switch/DBI/dbi.config`, `sd:/switch/prod.keys` to `sd:/temp_backup` |
| `skip_clean_wipe` | Step 2 — all cleanup from `deletion_lists_clean.h` (deletion / wipe) |
| `skip_clean_restore` | Step 3 — restore from `sd:/temp_backup` and post-restore paths (e.g. delete `sd:/switch/tinfoil/db`) |
| `skip_clean_install` | Step 4 — copy files from the OmniNX staging folder to the SD root |
| `skip_clean_staging_cleanup` | After install: do not remove the staging directory or other variant staging folders |
### Update mode (`INSTALL_MODE_UPDATE`)
| Key | What is skipped |
|-----|-----------------|
| `skip_update_cleanup` | Step 1 — selective deletion from `deletion_lists_update.h` |
| `skip_update_install` | Step 2 — copy from staging to SD |
| `skip_update_staging_cleanup` | End: do not remove staging / other variant folders |
| `skip_update_horizon_oc` | **OC variant only:** HorizonOC config backup before update, restore and cleanup after (entire HorizonOC update side path) |
### Both modes
| Key | What is skipped |
|-----|-----------------|
| `skip_hekate_8gb_post_copy` | After a successful copy: the optional `hekate_8GB` / RAM menu and related file moves (see `install_hekate_8gb_post_copy` in `install.c`) |
### Logging
| Key | Effect |
|-----|--------|
| `log` | Writes `sd:/config/omninx/install.log` with every deleted path, every copied file and the final result. Nothing is skipped. Slower on large packs; meant for test runs. |
## Behaviour
- On startup, if `debug.ini` exists and parses successfully, the payload prints a **DEBUG-MODUS** banner listing which skips are active.
- If the file is absent, unreadable, or has no `[Debug]` section, **no** skips apply — behaviour matches a release install.
- Skipping steps can leave the SD in an inconsistent state; this is **for developers/testers only**.
## Examples
### Wipe only (test deletion, no backup/restore/copy)
Inspect leftovers after the clean-install wipe, without backing up, restoring, installing, or cleaning staging:
```ini
[Debug]
skip_clean_backup=1
skip_clean_restore=1
skip_clean_install=1
skip_clean_staging_cleanup=1
skip_hekate_8gb_post_copy=1
```
Do **not** set `skip_clean_wipe` (leave unset or `0`).
### Update: deletion only
```ini
[Debug]
skip_update_install=1
skip_update_staging_cleanup=1
skip_hekate_8gb_post_copy=1
```
### OC update without touching HorizonOC backup/restore
```ini
[Debug]
skip_update_horizon_oc=1
```
## Implementation
- Parsed in `install.c`: `install_debug_load()`, `perform_installation()`.
- Uses the same INI parser as `config.ini` (`ini_parse` from BDK).
+259
View File
@@ -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.
+59
View File
@@ -0,0 +1,59 @@
# User preserve list (`preserve.ini`)
**Update mode only.** During OmniNX update cleanup (selective deletion), any path listed here with a truthy value is **not** deleted. Paths that would remove a preserved path (parent directory) are skipped as well.
- **File:** `sd:/config/omninx/preserve.ini`
- If missing or invalid, behavior is unchanged (full update deletion list applies).
## Format
Section **`[Preserve]`** (case-sensitive). Each line is **path as key**, **enable flag as value**:
```ini
[Preserve]
'sd:/ROMs'=1
sd:/switch/MyHomebrewFolder=0
sd:/backup/tools=1
```
### Path (key)
- Must start with **`sd:/`** (after optional quoting).
- **Optional** matching **single** or **double** quotes around the key are stripped (helps Ultrahand `set-ini-val` and readability).
- Trailing slashes are normalized away (except the volume root).
- **`sd:/` alone** is rejected (too broad).
- Minimum useful length after `sd:/` is enforced (at least one more character).
### Value (enable)
**On** if the value starts with `1`, `t`, `T`, `y`, or `Y` (e.g. `1`, `true`, `yes`). Anything else is **off** (path ignored).
### Limits
- Up to **96** preserved paths; longer keys truncated internally (~224 bytes per path).
- Duplicate paths after normalization are skipped.
- The list is allocated on the **heap** only while update cleanup runs (not a large static buffer in IPL IRAM), to avoid crowding hardware-adjacent memory used by Joy-Con UART and similar peripherals.
## Overlap rules
For each delete candidate from `deletion_lists_update.h`, deletion is skipped if it **overlaps** any enabled preserve path:
- Same path, or
- Delete target is **inside** a preserved tree (preserved path is a prefix), or
- Delete target is an **ancestor** of a preserved path (deleting it would remove the preserved data).
So preserving `sd:/ROMs` also blocks deleting `sd:/ROMs/title` if that were on the delete list, and blocks deleting `sd:/` if `sd:/ROMs` is preserved.
## Ultrahand
You can toggle entries with:
```text
set-ini-val sd:/config/omninx/preserve.ini Preserve 'sd:/ROMs' 1
```
and `0` to disable. Use the same quoted path in the key argument as in your INI.
## Clean install
**Not used** in clean install mode. `preserve.ini` is only read for **update** cleanup (`update_mode_cleanup`).