feat(core/emulator): report the exit kind and the boot args on exit [no changelog]
What changed, and why it matters
This commit changes only the Trezor software emulator (the desktop test version, not real hardware). It makes the emulator write its next-boot instructions to a file named trezor.bootargs and exit with specific numeric codes so automated tests can tell what happened. It does not change how real Trezor devices work, store secrets, or verify firmware. The file is only written, never automatically read back in. There is no indication this fixes or introduces a security vulnerability.
No security action required. Treat as a normal emulator/test-infrastructure improvement. If reviewing for defense in depth, confirm trezor.bootargs is written only under the emulator profile directory and is not parsed implicitly by the emulator on startup.
Security signals we found
New file write to host filesystem: trezor.bootargs in profile directory
Emulator-only code paths; real hardware behavior unchanged
Removal of RSOD screen on bootloader-to-firmware jump in emulator
Standardization of emulator exit codes for test harness consumption
No cryptographic, authentication, or firmware verification changes
Evidence from the diff
The patch refactors emulator shutdown paths in the Trezor Core Unix build. It introduces bootutils_emu_exit() and an emulator-only header that maps exit kinds to distinct process exit codes (2 quit, 3 reboot, 10 jump, 11 power off, 12 halt after RSOD, 1 usage). Before exiting, bootargs_persist() writes a fixed-size struct containing the current boot_command_t and raw boot_args_t to
Changed components
core/embed/io/power_manager/unix/power_manager.ccore/embed/projects/bootloader/emulator.ccore/embed/sys/startup/inc/sys/unix/bootutils_emu.hcore/embed/sys/startup/unix/bootutils.cInspect captured patch +160 / −25
### core/embed/io/power_manager/unix/power_manager.c
@@ -30,6 +30,8 @@
#include <stdlib.h>
#include "SDL3/SDL_events.h"
+#include <sys/bootargs.h>
+#include <sys/unix/bootutils_emu.h>
#include "../power_manager_poll.h"
typedef struct {
@@ -71,8 +73,9 @@ pm_status_t pm_init(bool inherit_state) {
void pm_deinit(void) { pm_poll_deinit(); }
pm_status_t pm_hibernate(void) {
- exit(1);
- return PM_OK;
+ // a cold start follows on the device, so no boot command is recorded
+ bootargs_set(BOOT_COMMAND_NONE, NULL, 0);
+ bootutils_emu_exit(BOOTUTILS_EMU_EXIT_POWER_OFF);
}
pm_status_t pm_suspend(wakeup_flags_t* wakeup_reason) {
@@ -81,7 +84,7 @@ pm_status_t pm_suspend(wakeup_flags_t* wakeup_reason) {
SDL_Event event;
while (SDL_WaitEvent(&event)) {
if (event.type == SDL_EVENT_QUIT) {
- exit(1);
+ exit(BOOTUTILS_EMU_EXIT_QUIT);
}
if (event.type == SDL_EVENT_KEY_DOWN || event.type == SDL_EVENT_KEY_UP) {
if (wakeup_reason != NULL) {
### core/embed/projects/bootloader/emulator.c
@@ -23,6 +23,8 @@
#include "emulator.h"
#include "rust_ui_common.h"
+#include <sys/unix/bootutils_emu.h>
+
LOG_DECLARE(emulator)
#undef FIRMWARE_START
@@ -44,7 +46,7 @@ bool storage_empty(const flash_area_t *area) {
}
void usage(void) {
- printf("Usage: ./build/bootloader/bootloader_emu [options]\n");
+ printf("Usage: bootloader-emu [options]\n");
printf("Options:\n");
printf(" -a disable animations\n");
printf(" -s stay in bootloader\n");
@@ -59,6 +61,16 @@ void usage(void) {
printf(" -l lock bootloader\n");
#endif
printf(" -h show this help\n");
+ printf("\n");
+ printf("On exit, the boot command for the next run is written to\n");
+ printf("trezor.bootargs in the profile directory. The exit code tells\n");
+ printf("how the run ended: %d reboot, %d jump to firmware, %d power off,\n",
+ BOOTUTILS_EMU_EXIT_REBOOT, BOOTUTILS_EMU_EXIT_JUMP,
+ BOOTUTILS_EMU_EXIT_POWER_OFF);
+ printf("%d halt after RSOD, %d closed by the user (no file written),\n",
+ BOOTUTILS_EMU_EXIT_HALT, BOOTUTILS_EMU_EXIT_QUIT);
+ printf("%d command line rejected (nothing ran).\n", BOOTUTILS_EMU_EXIT_USAGE);
+ printf("TREZOR_EMULATOR_FAST_EXIT=1 skips the delays before exiting.\n");
}
bool load_firmware(const char *filename, uint8_t *hash) {
@@ -118,15 +130,15 @@ bool preload_firmware_image(const char *filename) {
static bool sdl_event_filter(void *userdata, SDL_Event *event) {
switch (event->type) {
case SDL_EVENT_QUIT:
- exit(3);
+ exit(BOOTUTILS_EMU_EXIT_QUIT);
return false;
case SDL_EVENT_KEY_UP:
if (event->key.repeat) {
return false;
}
switch (event->key.key) {
case SDLK_ESCAPE:
- exit(3);
+ exit(BOOTUTILS_EMU_EXIT_QUIT);
return false;
case SDLK_S:
display_save("emu");
@@ -172,18 +184,18 @@ int main(int argc, char **argv) {
break;
case 'i': {
if (!preload_firmware_image(optarg)) {
- exit(1);
+ exit(BOOTUTILS_EMU_EXIT_USAGE);
}
} break;
case 'w': {
if (sectrue != flash_area_erase(&FIRMWARE_AREA, NULL)) {
- exit(1);
+ exit(BOOTUTILS_EMU_EXIT_USAGE);
}
} break;
case 'f': {
uint8_t hash[BLAKE2S_DIGEST_LENGTH];
if (!load_firmware(optarg, hash)) {
- exit(1);
+ exit(BOOTUTILS_EMU_EXIT_USAGE);
}
bootargs_set(BOOT_COMMAND_INSTALL_UPGRADE, hash, sizeof(hash));
} break;
@@ -195,7 +207,7 @@ int main(int argc, char **argv) {
#endif
default:
usage();
- exit(1);
+ exit(BOOTUTILS_EMU_EXIT_USAGE);
}
}
@@ -244,11 +256,12 @@ void jump_to_next_stage(uint32_t address, const startup_args_t *args) {
if (storage_is_erased) {
LOG_WARN("Storage was erased");
- error_shutdown_ex("BOOTLOADER EXIT", "Jumped to firmware",
- "STORAGE WAS ERASED");
} else {
LOG_WARN("Storage was retained");
- error_shutdown_ex("BOOTLOADER EXIT", "Jumped to firmware",
- "STORAGE WAS RETAINED");
}
+ LOG_WARN("Jumped to firmware");
+
+ // The next stage starts with a clean command, as on hardware
+ bootargs_set(BOOT_COMMAND_NONE, NULL, 0);
+ bootutils_emu_exit(BOOTUTILS_EMU_EXIT_JUMP);
}
### core/embed/sys/startup/inc/sys/unix/bootutils_emu.h
@@ -0,0 +1,57 @@
+/*
+ * This file is part of the Trezor project, https://trezor.io/
+ *
+ * Copyright (c) SatoshiLabs
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#pragma once
+
+#ifndef TREZOR_EMULATOR
+#error "emulator-only side-channel API"
+#endif
+
+// Emulator side-channel API of the startup module: how a run of the emulator
+// ends and how a test harness sets it up. Not part of the module API that the
+// firmware and the bootloader use.
+
+#include <trezor_types.h>
+
+// Process exit codes of the emulator. Every exit path maps to one of these
+// so that a test harness can tell them apart. The boot command and its
+// arguments are persisted to `trezor.bootargs` in the profile directory
+// before the process ends.
+typedef enum {
+ // The command line was rejected; nothing ran and no file is written.
+ BOOTUTILS_EMU_EXIT_USAGE = 1,
+ // Closed by the user (window closed, ESC) or by a signal; the boot
+ // arguments are not persisted.
+ BOOTUTILS_EMU_EXIT_QUIT = 2,
+ // Rebooted by one of the `reboot_*` calls; the persisted boot command
+ // tells which one.
+ BOOTUTILS_EMU_EXIT_REBOOT = 3,
+ // Jumped to the next boot stage (bootloader to firmware).
+ BOOTUTILS_EMU_EXIT_JUMP = 10,
+ // Powered off.
+ BOOTUTILS_EMU_EXIT_POWER_OFF = 11,
+ // Halted after showing the RSOD.
+ BOOTUTILS_EMU_EXIT_HALT = 12,
+} bootutils_emu_exit_code_t;
+
+// Writes the boot command and arguments to `trezor.bootargs` in the
+// profile directory and terminates the emulator process with the given
+// exit code.
+void __attribute__((noreturn)) bootutils_emu_exit(
+ bootutils_emu_exit_code_t code);
### core/embed/sys/startup/unix/bootutils.c
@@ -19,21 +19,43 @@
#include <trezor_rtl.h>
+#include <stdio.h>
#include <stdlib.h>
#include <sys/bootargs.h>
#include <sys/bootutils.h>
#include <sys/logging.h>
+#include <sys/profile.h>
#include <sys/systick.h>
+#include <sys/unix/bootutils_emu.h>
LOG_DECLARE(bootutils)
+// On exit, the boot command and its arguments are written to
+// `trezor.bootargs` in the profile directory, so that a test harness can
+// read what the next boot would have done. The file is never read back
+// implicitly; the bootloader emulator takes it as explicit input (-B).
+typedef struct {
+ // boot_command_t, stored as a fixed-width word
+ uint64_t command;
+ // raw argument block, see boot_args_t
+ uint8_t args[BOOT_ARGS_MAX_SIZE];
+} bootargs_file_t;
+
// Holds the 'command' for the next reboot.
static boot_command_t g_boot_command;
// Holds extra arguments for the command passed to the bootloader.
static boot_args_t g_boot_args;
+static const char* bootargs_path(void) {
+ static char path[1024];
+ if (path[0] == '\0') {
+ snprintf(path, sizeof(path), "%s/trezor.bootargs", profile_dir());
+ }
+ return path;
+}
+
void bootargs_set(boot_command_t command, const void* args, size_t args_size) {
// save boot command
g_boot_command = command;
@@ -58,34 +80,72 @@ void bootargs_get_args(boot_args_t* dest) {
memcpy(dest, &g_boot_args, sizeof(boot_args_t));
}
+static void bootargs_persist(void) {
+ bootargs_file_t file = {.command = (uint64_t)g_boot_command};
+ memcpy(file.args, g_boot_args.raw, BOOT_ARGS_MAX_SIZE);
+
+ FILE* f = fopen(bootargs_path(), "wb");
+ if (f == NULL) {
+ LOG_WARN("failed to write bootargs file");
+ return;
+ }
+ if (fwrite(&file, 1, sizeof(file), f) != sizeof(file)) {
+ LOG_WARN("failed to write bootargs file");
+ }
+ fclose(f);
+}
+
+// A test harness sets TREZOR_EMULATOR_FAST_EXIT to skip the delays that
+// let a human read the screen before the process ends.
+static bool fast_exit(void) {
+ const char* value = getenv("TREZOR_EMULATOR_FAST_EXIT");
+ return value != NULL && value[0] != '\0' && value[0] != '0';
+}
+
+static void exit_delay(void) {
+ if (!fast_exit()) {
+ systick_delay_ms(3000);
+ }
+}
+
+void bootutils_emu_exit(bootutils_emu_exit_code_t code) {
+ bootargs_persist();
+ exit(code);
+}
+
__attribute__((noreturn)) void reboot_device(void) {
LOG_WARN("reboot (normal)");
- exit(3);
+ bootargs_set(BOOT_COMMAND_REBOOT, NULL, 0);
+ bootutils_emu_exit(BOOTUTILS_EMU_EXIT_REBOOT);
}
__attribute__((noreturn)) void reboot_to_bootloader(void) {
LOG_WARN("reboot (to bootloader)");
- exit(3);
+ bootargs_set(BOOT_COMMAND_STOP_AND_WAIT, NULL, 0);
+ bootutils_emu_exit(BOOTUTILS_EMU_EXIT_REBOOT);
}
__attribute__((noreturn)) void reboot_and_connect(void) {
LOG_WARN("reboot (to bootloader, connect)");
- exit(3);
+ bootargs_set(BOOT_COMMAND_STOP_AND_CONNECT, NULL, 0);
+ bootutils_emu_exit(BOOTUTILS_EMU_EXIT_REBOOT);
}
__attribute__((noreturn)) void reboot_and_upgrade(const uint8_t hash[32]) {
LOG_WARN("reboot (upgrade)");
- exit(3);
+ bootargs_set(BOOT_COMMAND_INSTALL_UPGRADE, hash, 32);
+ bootutils_emu_exit(BOOTUTILS_EMU_EXIT_REBOOT);
}
__attribute__((noreturn)) void reboot_to_off(void) {
LOG_WARN("reboot (power off)");
- exit(3);
+ bootargs_set(BOOT_COMMAND_POWER_OFF, NULL, 0);
+ bootutils_emu_exit(BOOTUTILS_EMU_EXIT_POWER_OFF);
}
// To avoid including higher-layer code, we declare this function here.
@@ -99,17 +159,19 @@ __attribute__((noreturn)) void reboot_and_wipe(
LOG_WARN("reboot (wipe)");
- systick_delay_ms(3000);
-
- exit(3);
+ bootargs_set(BOOT_COMMAND_WIPE, info, sizeof(*info));
+ exit_delay();
+ bootutils_emu_exit(BOOTUTILS_EMU_EXIT_REBOOT);
}
__attribute__((noreturn)) void reboot_or_halt_after_rsod(void) {
- LOG_WARN("reboot (with timeout)");
+ LOG_WARN("halt after RSOD");
// Wait some time to let the user see the displayed
// message before shutting down
- systick_delay_ms(3000);
+ exit_delay();
- exit(3);
+ // Like halt_device() on hardware, leave a clean command behind
+ bootargs_set(BOOT_COMMAND_NONE, NULL, 0);
+ bootutils_emu_exit(BOOTUTILS_EMU_EXIT_HALT);
}Why this scored 19/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.