Re: [PATCH 2/5] buffer: Add kernel-doc for block_dirty_folio()

[Matthew Wilcox <willy@infradead.org>]

On Thu, Jan 04, 2024 at 01:06:10PM -0800, Randy Dunlap wrote:
> > +/**
> > + * block_dirty_folio - Mark a folio as dirty.
> > + * @mapping: The address space containing this folio.
> > + * @folio: The folio to mark dirty.
> > + *
> > + * Filesystems which use buffer_heads can use this function as their
> > + * ->dirty_folio implementation.  Some filesystems need to do a little
> > + * work before calling this function.  Filesystems which do not use
> > + * buffer_heads should call filemap_dirty_folio() instead.
> > + *
> > + * If the folio has buffers, the uptodate buffers are set dirty, to
> > + * preserve dirty-state coherency between the folio and the buffers.
> > + * It the folio does not have buffers then when they are later attached
> > + * they will all be set dirty.
> > + *
> > + * The buffers are dirtied before the folio is dirtied.  There's a small
> > + * race window in which writeback may see the folio cleanness but not the
> > + * buffer dirtiness.  That's fine.  If this code were to set the folio
> > + * dirty before the buffers, writeback could clear the folio dirty flag,
> > + * see a bunch of clean buffers and we'd end up with dirty buffers/clean
> > + * folio on the dirty folio list.
> > + *
> > + * We use private_lock to lock against try_to_free_buffers() while
> > + * using the folio's buffer list.  This also prevents clean buffers
> > + * being added to the folio after it was set dirty.
> > + *
> > + * Context: May only be called from process context.  Does not sleep.
> > + * Caller must ensure that @folio cannot be truncated during this call,
> > + * typically by holding the folio lock or having a page in the folio
> > + * mapped and holding the page table lock.
> 
>  * Return: tbd

+ *
+ * Return: True if the folio was dirtied; false if it was already dirtied.