Re: [LSF/MM/BPF TOPIC] Reclaiming & documenting page flags

[Mike Rapoport <rppt@kernel.org>]

On Sun, Feb 04, 2024 at 09:34:01PM +0000, Matthew Wilcox wrote:
> On Sun, Feb 04, 2024 at 11:39:33AM +0100, Mike Rapoport wrote:
> > On Mon, Jan 29, 2024 at 04:32:03AM +0000, Matthew Wilcox wrote:
> > > Our documentation of the current page flags is ... not great.  I think
> > > I can improve it for the page cache side of things; I understand the
> > > meanings of locked, writeback, uptodate, dirty, head, waiters, slab,
> > > mlocked, mappedtodisk, error, hwpoison, readahead, anon_exclusive,
> > > has_hwpoisoned, hugetlb and large_remappable.
> > > 
> > > Where I'm a lot more shaky is the meaning of the more "real MM" flags,
> > > like active, referenced, lru, workingset, reserved, reclaim, swapbacked,
> > > unevictable, young, idle, swapcache, isolated, and reported.
> > > 
> > > Perhaps we could have an MM session where we try to explain slowly and
> > > carefully to each other what all these flags actually mean, talk about
> > > what combinations of them make sense, how we might eliminate some of
> > > them to make more space in the flags word, and what all this looks like
> > > in a memdesc world.
> > > 
> > > And maybe we can get some documentation written about it!  Not trying
> > > to nerd snipe Jon into attending this session, but if he did ...
> > 
> > I suspect Jon will be there anyway, but not sure he'd be willing to do the
> > writing :)
> > 
> > I was going to propose the "mm docs" session again, but this one seems more
> > useful than talking yet again about how hard it is to get MM documentation
> > done.
> 
> I'm doing my best to write documentation as I go.  I think we're a bit
> better off than we were last year.  Do we have scripts to tell us which
> public functions (ie EXPORT_SYMBOL and static inline functions in header
> files) have kernel-doc?  And could we run them against kernels from, say,
> April 2023, 2022, 2021, 2020, 2019 (and in two months against April 2024)
> and see how we're doing in terms of percentage undocumented functions?

We didn't have such script, but it was easy to compare "grep
EXPORT_SYMBOL\|static inline" with ".. c:function" in kernel-doc.
We do improve slowly, but we are still below 50% with kernel-doc for
EXPORT_SYMBOL functions and slightly above 10% for static inlines.

Although with static inlines it's quite possible that the percentage of
actual public API documentation is higher because some of the functions in
inlcude/linux/ are only used inside mm.

There are also APIs that are not EXPORT_SYMBOL, but I didn't find an easy
way to check how well there are documented.

EXPORT_SYMBOL
version     	funcs	docs	percent
v5.0        	514	177	34
v5.6        	538	208	38
v5.12       	550	209	38
v5.17       	580	228	39
v6.3        	580	235	40
v6.8-rc1    	565	238	42

static inline
version     	funcs	docs	percent
v5.0        	581	33	5
v5.6        	596	41	6
v5.12       	629	42	6
v5.17       	746	74	9
v6.3        	867	95	10
v6.8-rc1    	944	116	12

 
> There's also the problem of getting long-form documentation done.
> But I think that's a different problem from getting kernel-doc written.
> Looking at the 55 commits in the last year to Documentation/mm, we seems
> to be doing a pretty good job of keeping the documentation we have up
> to date.  Just not a great job of adding new documentation.

I agree that long-form documentation is a different problem from getting
kernel-doc written and we are not doing a great job in writing new
documentation.

-- 
Sincerely yours,
Mike.