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

[NeilBrown]

On Tue, 20 Feb 2024, Matthew Wilcox wrote:
> On Tue, Feb 20, 2024 at 09:45:36AM +1100, NeilBrown wrote:
> > On Tue, 20 Feb 2024, Matthew Wilcox wrote:
> > > The example is filemap_range_has_writeback().  It's EXPORT_SYMBOL_GPL()
> > > and it's a helper function for filemap_range_needs_writeback().
> > > filemap_range_needs_writeback() has kernel-doc, but nobody should be
> > > calling filemap_range_has_writeback() directly, so it shouldn't even
> > > exist in the htmldocs.  But we should have a comment on it saying
> > > "Use filemap_range_needs_writeback(), don't use this", in case anyone
> > > discovers it.  And the existance of that comment should be enough to
> > > tell our tools to not flag this as a function that needs kernel-doc.
> > > 
> > 
> > Don't we use a __prefix for internal stuff that shouldn't be used?
> 
> No?  Or if we do, we are inconsistent with that convention.  Let's
> consider some examples.
> 
> __SetPageReferenced -- non-atomic version of SetPageReferenced.
> Akin to __set_bit.
> 
> __filemap_fdatawrite_range() -- like filemap_fdatawrite_range but
> allows the specification of sync_mode
> 
> __page_cache_alloc() -- like page_cache_alloc() but takes the gfp mask
> directly instead of inferring it from mapping_gfp_mask()
> 
> __folio_lock() -- This does fit the "don't call this pattern"!
> 
> __set_page_dirty() -- Like set_page_dirty() but allows warn to be
> specified.
> 
> __filemap_remove_folio() -- Like filemap_remove_folio() but allows it
> to be replaced with a shadow entry.
> 
> __readahead_folio() -- Another internal one
> 
> I mostly confined myself to pagemap.h for this survey, but if you've
> conducted a different survey that shows your assertion is generally true
> and I've hit on the exceptions to the rule ... ?
> 

Yes, __ is used for other things too.
It would be nice to have some consistency with naming, but probably
impossible.

And with 1074 functions named __foo having kernel doc already, it is too
late to close that gate.
:-(

Thanks,
NeilBrown