Re: [PATCH] Docs/mm: document the OOM killer

[Michal Hocko <mhocko@suse.com>]

On Mon 16-03-26 14:16:19, Lorenzo Stoakes (Oracle) wrote:
> On Mon, Mar 16, 2026 at 08:32:31AM +0100, Michal Hocko wrote:
> > On Sun 15-03-26 20:48:22, Lorenzo Stoakes (Oracle) wrote:
> > > NAK for being AI slop again, obviously.
> > >
> > > Again, +cc the OOM maintainer you failed to bother to look up.
> >
> > Thanks!
> 
> No problem!
> 
> >
> > > Reasons, as the rest:
> > > - Worthless documentation
> > > - Everything about patch screams 'zero effort, Claude did it all'
> > > - Bad etiquette
> > >
> > > As with all the rest it'd need to be totally rewritten and it's not worth the
> > > maintainer time.
> > >
> > > On Sat, Mar 14, 2026 at 04:25:18PM +0100, Kit Dallege wrote:
> > > > Fill in the oom.rst stub that was created in commit 481cc97349d6
> > > > ("mm,doc: Add new documentation structure") as part of the structured
> > > > memory management documentation following Mel Gorman's book outline.
> > >
> > > I mean the more I see it the more annoying it is.
> > >
> > > >
> > > > Cover the scoring heuristic, allocation constraints, OOM reaper,
> > > > process_mrelease syscall, and sysctl knobs.
> > >
> > > This sentence contains almost as much content as the patch.
> >
> > The real question is who is the expected audience of this documentation?
> > Administrators, kernel developers?
> > Reading through this proposal this doesn't really seem to fit neither
> > well. For kernel developers who try to wrap their heads around the code
> > it is barely scratches the surface. For admins it doesn't really explain
> > more than an existing documentation for tunables.
> >
> > So if there is a serious interest to make this useful kernel developers
> > oriented documentation I am more than willing to help. The code is not
> > really easy to follow as it is scattered. There are many subtle
> > expectations spread out and it is quite easy to break a delicate balance
> > tuned for through years. So there is a big documentatin gap I never got
> > around to fill up.
> 
> I mean, we definitely could do with better documentation :) Obviously I
> somewhat document it from a 'learning the code in depth' perspective in my
> book, but that's tied to v6.0, effectively paywalled (sorry!) and not the
> same as the kind of documentation we'd ideally like the kernel to expose,
> which would be less specific I thik but also up-to-date with newer kernels.
> 
> The point WRT this patch however is that really, it needs to come from
> somebody who has some experience/understanding, and generating it via an
> LLM is just not useful - any kernel developer with understanding could do
> so.

I think we are struggling with capacity here. I am willing to help shape
an existing text but will be struggling to find time to cook up that
text myself. I do mind involving LLMs are long as the content is
properly reviewed and factually correct. 

Wrt OOM, most people/developers struggle to understand these areas from
my experience
- what is the purpose of the oom killer and its limitations
- different contexts oom handles
- when is the oom killer triggered
- oom killer in progress handling and locking
- forward progress guarantee (oom_reaper)
- coordination with task exit path
- memory reserves for oom victims

I bet there is some more but these are the most prominent ones.
-- 
Michal Hocko
SUSE Labs