Re: [PATCH v4 3/3] Documentation: document panic_on_unrecoverable_memory_failure sysctl

[Breno Leitao <leitao@debian.org>]

On Wed, Apr 22, 2026 at 11:43:16AM +0800, Miaohe Lin wrote:
> On 2026/4/15 20:55, Breno Leitao wrote:
> > Add documentation for the new vm.panic_on_unrecoverable_memory_failure
> > sysctl, describing the three categories of failures that trigger a
> > panic and noting which kernel page types are not yet covered.
> > 
> > Signed-off-by: Breno Leitao <leitao@debian.org>
> > ---
> >  Documentation/admin-guide/sysctl/vm.rst | 37 +++++++++++++++++++++++++++++++++
> >  1 file changed, 37 insertions(+)
> > 
> > diff --git a/Documentation/admin-guide/sysctl/vm.rst b/Documentation/admin-guide/sysctl/vm.rst
> > index 97e12359775c9..592ce9ec38c4b 100644
> > --- a/Documentation/admin-guide/sysctl/vm.rst
> > +++ b/Documentation/admin-guide/sysctl/vm.rst
> > @@ -67,6 +67,7 @@ Currently, these files are in /proc/sys/vm:
> >  - page-cluster
> >  - page_lock_unfairness
> >  - panic_on_oom
> > +- panic_on_unrecoverable_memory_failure
> >  - percpu_pagelist_high_fraction
> >  - stat_interval
> >  - stat_refresh
> > @@ -925,6 +926,42 @@ panic_on_oom=2+kdump gives you very strong tool to investigate
> >  why oom happens. You can get snapshot.
> >  
> >  
> > +panic_on_unrecoverable_memory_failure
> > +======================================
> > +
> > +When a hardware memory error (e.g. multi-bit ECC) hits a kernel page
> > +that cannot be recovered by the memory failure handler, the default
> > +behaviour is to ignore the error and continue operation.  This is
> > +dangerous because the corrupted data remains accessible to the kernel,
> > +risking silent data corruption or a delayed crash when the poisoned
> > +memory is next accessed.
> > +
> > +When enabled, this sysctl triggers a panic on three categories of
> > +unrecoverable failures: reserved kernel pages, non-buddy kernel pages
> > +with zero refcount (e.g. tail pages of high-order allocations), and
> > +pages whose state cannot be classified as recoverable.
> > +
> > +Note that some kernel page types — such as slab objects, vmalloc
> > +allocations, kernel stacks, and page tables — share a failure path
> > +with transient refcount races and are not currently covered by this
> > +option. I.e, do not panic when not confident of the page status.
> > +
> > +For many environments it is preferable to panic immediately with a clean
> > +crash dump that captures the original error context, rather than to
> > +continue and face a random crash later whose cause is difficult to
> > +diagnose.
> 
> Should we add some userful cases to show the real-world application scenarios?

Yes, good idea. What about something like:

Use cases
---------

This option is most useful in environments where unattributed crashes
are expensive to debug or where data integrity must take precedence
over availability:

* Large fleets, where multi-bit ECC errors on kernel pages are observed
  regularly and post-mortem analysis of an unrelated downstream crash
  (often seconds to minutes after the original error) consumes
  significant engineering effort.

* Systems configured with kdump, where panicking at the moment of the
  hardware error produces a vmcore that still contains the faulting
  address, the affected page state, and the originating MCE/GHES
  record — context that is typically lost by the time a delayed crash
  occurs.

* High-availability clusters that rely on fast, deterministic node
  failure for failover, and prefer an immediate panic over silent data
  corruption propagating to replicas or persistent storage.