OmniNX/OmniNX-Installer-Payload
2
0 Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
14be4646d0667b4dfaf1354298fd4468cf141762
OmniNX-Installer-Payload/docs/INSTALLATION_PROCESS.md
T

10 KiB
Raw Blame History

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.

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. 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).
  • 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 View Git Blame Copy Permalink