Skip to content

core: libxr_fatal_error no longer prints; REQUIRE carries no location - #364

Merged
Jiu-xiao merged 4 commits into
devfrom
refactor/fatal-error-print-split
Nov 14, 2026
Merged

Jiu-xiao merged 4 commits into
devfrom
refactor/fatal-error-print-split

Conversation

@Jiu-xiao

@Jiu-xiao Jiu-xiao commented Nov 14, 2026 •

Copy link
Copy Markdown
Member

libxr_fatal_error no longer prints, and a failed REQUIRE no longer carries a file name and a line number. The printing moves into a second function that only ASSERT and DEV_ASSERT call.

Why: all three assertion macros called libxr_fatal_error(__FILE__, __LINE__, in_isr), and that function printed Fatal error at file:line before every call of the fatal callback. REQUIRE is always on, so release firmware carried a file name and a line number at each of its REQUIRE sites, and the code that formats and prints them. Printing also takes the STDIO mutex with an unbounded wait, so a REQUIRE that fails while that mutex is held never reaches the callback.

Two functions with the same parameters:

Function Prints Called by
libxr_fatal_error(file, line, in_isr) no REQUIRE, REQUIRE_FROM_CALLBACK (with a null file name and line 0), C code
libxr_fatal_error_and_print(file, line, in_isr) Fatal error at file:line, as libxr_fatal_error did ASSERT, DEV_ASSERT and their _FROM_CALLBACK forms (with __FILE__ and __LINE__)

ASSERT and DEV_ASSERT are not active in release firmware, so nothing there refers to libxr_fatal_error_and_print, and a link that collects unreferenced sections drops it together with the printing code. Both functions are in src/core/assert/fatal_error.cpp; src/libxr.cpp, which held nothing but libxr_fatal_error, is gone.

Not changed: the type of the fatal callback, what happens after the failure (the callback is called in a loop with 500 ms between the calls and the function does not return) and the interrupt-context path.

Behaviour changes for users:

  • Where a REQUIRE failed is found with a debugger in the call stack. The fatal callback gets a null file name and line 0 for it, so a callback that uses the file name has to accept null.
  • C code that calls libxr_fatal_error(file, line, in_isr), such as a stack-overflow hook, compiles as before and no longer prints. The callback still gets its file name and line number.
  • A project that defines its own libxr_fatal_error and uses ASSERT or DEV_ASSERT has to define libxr_fatal_error_and_print as well.

Size, measured in an STM32H723 firmware:

Build Before After Saved
LIBXR_DEBUG_BUILD off (release) 131836 127700 4136 bytes (3.1 %)
LIBXR_DEBUG_BUILD on (Debug) 137092 136476 616 bytes

In the release build the flash image contains neither libxr_fatal_error_and_print nor the string Fatal error at. About 1 KB of the saving is the file names and arguments at the REQUIRE sites, the rest is the printing code.

Tests:

  • The four assertion-mode programs (test_assert_<debug>_<dev>) check which of the two functions each macro calls and what location it passes.
  • The case assert of libxr_test runs a failing REQUIRE and both functions through the library in child processes and checks the location the callback gets and that neither function returns. Because it forks, it runs in a process of its own without platform initialization, as the test runner requires.
  • The topic test confirmed by file name that the failed check is in topic.cpp. Those checks are REQUIREs, so it now confirms only that a fatal error happened.
  • The test runner prints (no location) for a failed REQUIRE.

All three assertion macros called libxr_fatal_error(__FILE__, __LINE__, in_isr), and
that function printed `Fatal error at file:line` before every call of the fatal
callback. REQUIRE is always on, so release firmware carried a file name and a line
number at each of its REQUIRE sites and the code that formats and prints them.

There are two functions now, with the same parameters:
- libxr_fatal_error(file, line, in_isr) does not print. It calls the fatal callback in
  a loop as before.
- libxr_fatal_error_and_print(file, line, in_isr) is the same and prints before every
  call of the callback, as libxr_fatal_error did.

ASSERT and DEV_ASSERT call libxr_fatal_error_and_print with __FILE__ and __LINE__.
Neither is active in release firmware, so nothing there refers to the printing function
and its source file (libxr_fatal_print.cpp) stays out of the link. REQUIRE calls
libxr_fatal_error with a null file name and line 0: where a REQUIRE failed is found with
a debugger in the call stack.

Unchanged: the type of the fatal callback, the loop (callback, 500 ms sleep, never
returns) and the interrupt-context path. C code that calls
libxr_fatal_error(file, line, in_isr) compiles as before and no longer prints; the
callback still gets its file name and line number.

For users:
- A fatal callback can get a null file name (a failed REQUIRE).
- A project that defines its own libxr_fatal_error and uses ASSERT or DEV_ASSERT has to
  define libxr_fatal_error_and_print as well.

Tests: the four assertion-mode programs check which function each macro calls and what
location it passes; the case `assert` runs a failing REQUIRE and both functions of the
library in child processes and checks the location the callback gets. The topic test
confirmed by file name that the failed check is in topic.cpp; those checks are REQUIREs,
so it now confirms only that a fatal error happened.
@greptile-apps

greptile-apps Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

RetriggerView in GreptileConfidence Score: 4/5

[Medium impact] The change reaches fatal-error reporting across library checks and direct callers.

The library changes appear safe to merge, with a non-blocking test isolation fix recommended.

Fix All in Claude CodeFindings

  1. P2 Child can inherit locked mutex ▶
Fix with agent prompt
### Issue 1
test/automatic/core/assert/libxr_assert/test_assert.cpp:54
`FatalLocationSeenByCallback` now forks, but the `assert` case still runs after `PlatformInit` starts the STDIO threads. If a startup log holds `write_mutex_` when the fork happens, the child's printing call can wait forever because the thread holding that lock no longer exists. The parent then stays in `waitpid` until the test times out.

Register this case with `isolated=true` and `platform_init=false`, as the runner requires for tests that fork.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Splits fatal handling into quiet and printing entries:

  • Debug assertions print locations while REQUIRE stays silent.

The new child-process test should run without platform threads.

Acknowledged by Jiu-xiao: callbacks must accept null filenames, custom fatal handlers need the new printing entry, and topic tests no longer check the source filename. These are intentional compatibility changes.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  R["REQUIRE"] --> Q["libxr_fatal_error: null file, line 0"]
  A["ASSERT / DEV_ASSERT"] --> P["libxr_fatal_error_and_print: file and line"]
  Q --> L["FatalErrorLoop"]
  P --> L
  L --> I{"in_isr?"}
  I -->|Yes| F["Force fault"]
  I -->|No| O["Print if report is supplied"]
  O --> C["Call fatal callback"]
  C --> S["Sleep 500 ms"]
  S --> L
Loading

Reviews (1) · Last reviewed commit: "core: libxr_fatal_error no longer prints..." · Reviewed by Greptile

int FatalLocationSeenByCallback(void (*fail)())
{
std::fflush(nullptr);
const pid_t child = fork();

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Child can inherit locked mutex

FatalLocationSeenByCallback now forks, but the assert case still runs after PlatformInit starts the STDIO threads. If a startup log holds write_mutex_ when the fork happens, the child's printing call can wait forever because the thread holding that lock no longer exists. The parent then stays in waitpid until the test times out.

Register this case with isolated=true and platform_init=false, as the runner requires for tests that fork.

Prompt To Fix With AI
This is a comment left during a code review.
Path: test/automatic/core/assert/libxr_assert/test_assert.cpp
Line: 54

Comment:
**Child can inherit locked mutex**

`FatalLocationSeenByCallback` now forks, but the `assert` case still runs after `PlatformInit` starts the STDIO threads. If a startup log holds `write_mutex_` when the fork happens, the child's printing call can wait forever because the thread holding that lock no longer exists. The parent then stays in `waitpid` until the test times out.

Register this case with `isolated=true` and `platform_init=false`, as the runner requires for tests that fork.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Fix in Claude Code Fix in Codex

The case forks since it checks the fatal functions of the library in child
processes. The runner requires such a case to run in a process of its own
without PlatformInit: with the STDIO threads running, a child could inherit the
STDIO mutex in the locked state and wait for it forever in
libxr_fatal_error_and_print.
src/libxr.cpp held nothing but libxr_fatal_error, under a name that says
nothing about it, and the new libxr_fatal_print.cpp sat next to it. Both
functions are now in one file in the directory of the assertion support,
src/core/assert/fatal_error.cpp, with the loop they share as a local function;
the declaration of that loop in diag.hpp is gone again. src/ itself keeps only
the umbrella header. The build collects the files of src/core/*/ already, and
nothing refers to the old path.

libxr_fatal_error_and_print stays the only reference to the printing code. A
firmware link that collects unreferenced sections drops it when nothing calls
it.
Chinese lines are followed directly by their English counterpart, the @brief
of the two functions is one line with the details under @note, and two English
continuation lines that had dropped out of the @note indentation are fixed.
Source and test files use // comments only; the comment moved with
libxr_fatal_error gets its Chinese half. test_topic.cpp no longer includes
<cstring>, which only the removed file-name check used.
@Jiu-xiao
Jiu-xiao merged commit bbda994 into dev Nov 14, 2026
7 checks passed
@Jiu-xiao
Jiu-xiao deleted the refactor/fatal-error-print-split branch November 14, 2026 03:31
Jiu-xiao added a commit that referenced this pull request Nov 14, 2026
dev now has the fatal error split (#364) and the shared Topic test cleanup
(#363). One conflict, in test/automatic/main.cpp: the USB cases of this branch
stay and the case assert takes the registration from dev (isolated, without
platform initialization).

The CH32 endpoint test programs define libxr_fatal_error themselves; they now
define libxr_fatal_error_and_print as well and accept a null file name.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant