docs: move process, debug.ini and preserve.ini docs to docs/
This commit is contained in:
1 parent
f2230c79a7
commit
14be4646d0
5 files changed
+28
-27
No files matched your search
@@ -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).
|
||||
@@ -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.
|
||||
@@ -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`).
|
||||
Reference in new issue
Block a user