Error Handling and Recovery

Relevant source files

The following files were used as context for generating this wiki page:

• safe64.sh
• README.md
• .gitignore
• LICENSE
• scripts/rollback.sh (Referenced conceptually via script logic)

Introduction

The safe64switch utility implements a preemptive error handling and recovery strategy designed to protect the system configuration during the transition from a 32-bit to a 64-bit kernel on Raspberry Pi hardware. The primary objective is to ensure that modifications to critical system files are reversible and that the execution environment is validated before any changes are applied.

The system relies on Shell-level error trapping and manual configuration backups to prevent persistent system corruption. By verifying the hardware environment and creating a restorable state of /boot/config.txt, the utility minimizes the risk of rendering the device unbootable.
Sources: README.md:1-10, safe64.sh:1-5

Execution Environment Validation

Before performing any system modifications, the script performs a hardware validation check. This serves as the first line of defense against execution on unsupported architectures, which could lead to critical system errors or improper kernel configurations.

Hardware Verification Logic

The script inspects the device tree model to confirm it is running on a Raspberry Pi. If this check fails, the script triggers an immediate exit to prevent further execution.

The diagram above illustrates the initial validation gate that prevents the script from running on non-Pi hardware.
Sources: safe64.sh:11-15

Immediate Failure Management

The utility utilizes standard Shell error handling directives to ensure that if any command within the sequence fails, the entire process terminates immediately. This prevents a "cascading failure" scenario where subsequent commands might operate on partially modified or corrupt files.

Mechanism	Command	Purpose
Exit on Error	set -e	Terminates script execution if any command returns a non-zero exit status.
Hardware Check	grep -q ... /proc/...	Validates environment and exits with code 1 on failure.
Idempotency	grep -qxF	Checks for existing configuration before appending to avoid duplicate entries.

Sources: safe64.sh:6, safe64.sh:13-15, safe64.sh:30

State Recovery and Backups

A core component of the "Safe" aspect of safe64switch is the creation of a recovery point. Before the arm_64bit kernel parameter or performance settings are modified, the current system configuration is duplicated.

Configuration Backup

The script performs a direct copy of the primary configuration file:

• Source: /boot/config.txt
• Backup Destination: /boot/config.txt.bak

This backup allows for manual recovery by renaming the .bak file if the system fails to boot after the 64-bit kernel is enabled.
Sources: README.md:8, safe64.sh:18-19

Configuration Integrity

To avoid corrupting the config.txt file through redundant entries, the script employs conditional logic. This ensures that the recovery state remains clean and manageable.

Idempotent Updates

The script checks for the existence of specific strings before appending new configuration lines. This prevents the accumulation of duplicate flags which could lead to unpredictable boot behavior.

The sequence diagram shows the logic used to maintain file integrity during the update process.
Sources: safe64.sh:22-30

Summary of Recovery Steps

In the event of an error during execution or a failure to boot post-execution, the following recovery path is established:

1. Script Failure: The set -e directive stops the script, leaving the system in its last known good state or with a completed .bak file.
2. Hardware Incompatibility: The script terminates before any file modifications occur.
3. Boot Failure: The user can restore the system using the /boot/config.txt.bak file created during the backup phase.

Sources: safe64.sh:6-19, README.md:12-16