page-flags.rst

page-flags.rst

[Matthew Wilcox]

As encouraged by my lively audience / collaborators, here is the
typos-and-all result of the LSFMM session which just finished.

Please don't respond to point out the typos; trust that I will fix them.


==========
Page flags
==========

Struct page includes a 'flags' word.  Despite its name, various other
things are also stored in this word, including the page's node, zone,
section, and last_cpupid.  See include/linux/page-flags-layout.h for
details.

Locked
======

This flag is per-folio.  If you attempt to lock a page, you will lock
the entire folio.  The folio lock is used for many purposes.  In the page
cache, folios are locked before reads are started and unlocked once the
read has completed.  The folio is also locked before writeback starts;
see the writeback flag for more detail.  The truncation path takes the
folio lock, and folios are also locked while being inserted into page
tables in order to prevent races between truncation and page fault.

... more detail here please ...

Writeback
=========

Per-folio
This is kind of a lock
We downgrade to it having taken the lock flag
Rekeased after wrut4back completes, but lock flag may be released any time after writeback flag set.  Deopends on filesystem whether needs to do more between
We can wait for writeback to complete by waiting on this flag
Folio put to tail of LRU for faster reclaim

Can prevent tearing write is filesystem needs stable folios
Truncate will wait for flag to clear


Referenced
==========

Per-folio flag.  At least one page table entry has a accessed bit set for this folio
We set this during scan.  Also set during buffered IO.  Referenced first time, Accessed second time.
Used during reclaim to determine dispotition (activate, reclaim, etc)

Uptodate
========

Every byte of the folio contents is at least as new as the contents of disk
implicit write bbarrier


Dirty
=====
  Also set during buffered IO.  Referenced first time, Accessed second time.
  Used during reclaim to determine dispotition (activate, reclaim, etc)
At least one byte of the folio contents is newer than on disk and the writeback flag is not yet set
folios may be both dirty and not uptodate
lazyfree pages can drop the dirty bit
dirty flag clear for file folios when we start writeback
set dirty flag when removed from swapcache
if already dirty, folios can be mapped writable without notifying filesystem
complicated interfaces to set easy to get wrong
redirty_for_writeback



LRU
===

FOlio has been added to the LRU and is no longer in percpu folio_batch


Head
====

This folio is a large folio.  It is not set on order-0 folios.


Waiters
=======

Page has waiters, check its waitqueue.
Only used by core code.  Don't touch.

Active
======

On the active LRU list.
Can be set in advance to tell kernel to put it on the right list

Workingset
==========

Set on folios in pagecache once readahead pages actually accessed
Set on LRU pages that were activated have been deactivated, treat refault as thrashing
refault handler also sets it on folios that were hot before reclaimed
used by PSI computation

Owner_Priv_1
============

Owner use. If pagecache, fs may use

Used as Checked flag by many filesystems.
Used as SwapBacked flag by swap code.

Arch_1
======

Many different uses depending on architecture.  Oftern used as a "dcache clean" or, comfusingly as "dcache dirty".  Check with your architecture.

s390 uses it for basically everything.

Historicalkly was used on a per page basis.  Think we've eliminated all per-page uses now so should only be set on folios.

Reserved
========



Private
=======

If pagecache, has fs-private data

Private_2
=========

If pagecache, has fs aux data

Mapped_to_disk
==============

Has blocks allocated on-disk

Reclaim
=======

To be reclaimed asap

Swap_backed
===========

Page is backed by RAM/swap

Unevictable
===========

Page is "unevictable"

Mlocked
=======

Page is vma mlocked

Uncached
========

Page has been mapped as uncached

HWPoison
========

hardware poisoned page. Don't touch

Young
=====

Idle
====

Arch 2
======

Arch 3
======

Readahead
=========

Aliases with Reclaim as they are usually never set on the same folio, and
if they are the consequences are a minor performance loss.

Anon_Exclusive
==============

Aliases with Mapped_To_Disk as that flag can never be set on anonymous folios.

Isolated
========

Shared with Reclaim flag, only valid for folios with LRU flag clear.

Reported
========

Only valid for buddy pages. Used to track pages that are reported

Has_HWPoisoned
==============

Large_Rmappable
===============

Re: page-flags.rst

[Darrick J. Wong]

On Tue, May 14, 2024 at 07:35:15PM +0100, Matthew Wilcox wrote:
> As encouraged by my lively audience / collaborators, here is the
> typos-and-all result of the LSFMM session which just finished.
> 
> Please don't respond to point out the typos; trust that I will fix them.

May I bikeshed starting sentences on a new line for better diffability,
then?

Arbitrary incoherent comments follow:

> ==========
> Page flags
> ==========
> 
> Struct page includes a 'flags' word.  Despite its name, various other
> things are also stored in this word, including the page's node, zone,
> section, and last_cpupid.  See include/linux/page-flags-layout.h for
> details.
> 
> Locked
> ======
> 
> This flag is per-folio.  If you attempt to lock a page, you will lock
> the entire folio.  The folio lock is used for many purposes.  In the page
> cache, folios are locked before reads are started and unlocked once the
> read has completed.  The folio is also locked before writeback starts;
> see the writeback flag for more detail.  The truncation path takes the
> folio lock, and folios are also locked while being inserted into page
> tables in order to prevent races between truncation and page fault.

If you drop the lock of a pagecache folio and relock it, you have to
revalidate mapping and index of the head, right?

> ... more detail here please ...
> 
> Writeback
> =========
> 
> Per-folio
> This is kind of a lock
> We downgrade to it having taken the lock flag
> Rekeased after wrut4back completes, but lock flag may be released any time after writeback flag set.  Deopends on filesystem whether needs to do more between

more between...? /me doesn't understand the sentence.

> We can wait for writeback to complete by waiting on this flag
> Folio put to tail of LRU for faster reclaim
> 
> Can prevent tearing write is filesystem needs stable folios

If the filesystem or the block device (e.g. T10 PI/RAID5) need stable
folios.

> Truncate will wait for flag to clear
> 
> 
> Referenced
> ==========
> 
> Per-folio flag.  At least one page table entry has a accessed bit set for this folio
> We set this during scan.  Also set during buffered IO.  Referenced first time, Accessed second time.
> Used during reclaim to determine dispotition (activate, reclaim, etc)
> 
> Uptodate
> ========
> 
> Every byte of the folio contents is at least as new as the contents of disk
> implicit write bbarrier
> 
> 
> Dirty
> =====
>   Also set during buffered IO.  Referenced first time, Accessed second time.
>   Used during reclaim to determine dispotition (activate, reclaim, etc)
> At least one byte of the folio contents is newer than on disk and the writeback flag is not yet set
> folios may be both dirty and not uptodate
> lazyfree pages can drop the dirty bit
> dirty flag clear for file folios when we start writeback
> set dirty flag when removed from swapcache
> if already dirty, folios can be mapped writable without notifying filesystem
> complicated interfaces to set easy to get wrong
> redirty_for_writeback
> 
> 
> 
> LRU
> ===
> 
> FOlio has been added to the LRU and is no longer in percpu folio_batch
> 
> 
> Head
> ====
> 
> This folio is a large folio.  It is not set on order-0 folios.

Is it not set on the non-head pages as well?

> 
> Waiters
> =======
> 
> Page has waiters, check its waitqueue.
> Only used by core code.  Don't touch.
> 
> Active
> ======
> 
> On the active LRU list.
> Can be set in advance to tell kernel to put it on the right list
> 
> Workingset
> ==========
> 
> Set on folios in pagecache once readahead pages actually accessed
> Set on LRU pages that were activated have been deactivated, treat refault as thrashing
> refault handler also sets it on folios that were hot before reclaimed
> used by PSI computation
> 
> Owner_Priv_1
> ============
> 
> Owner use. If pagecache, fs may use
> 
> Used as Checked flag by many filesystems.
> Used as SwapBacked flag by swap code.
> 
> Arch_1
> ======
> 
> Many different uses depending on architecture.  Oftern used as a "dcache clean" or, comfusingly as "dcache dirty".  Check with your architecture.
> 
> s390 uses it for basically everything.
> 
> Historicalkly was used on a per page basis.  Think we've eliminated all per-page uses now so should only be set on folios.
> 
> Reserved
> ========
> 
> 
> 
> Private
> =======
> 
> If pagecache, has fs-private data
> 
> Private_2
> =========
> 
> If pagecache, has fs aux data
> 
> Mapped_to_disk
> ==============
> 
> Has blocks allocated on-disk
> 
> Reclaim
> =======
> 
> To be reclaimed asap
> 
> Swap_backed
> ===========
> 
> Page is backed by RAM/swap
> 
> Unevictable
> ===========
> 
> Page is "unevictable"
> 
> Mlocked
> =======
> 
> Page is vma mlocked
> 
> Uncached
> ========
> 
> Page has been mapped as uncached
> 
> HWPoison
> ========
> 
> hardware poisoned page. Don't touch

I forgot the results of our expedition into why shmem.c checks
PageHWPoison so much vs checking for EIO on the file/inode/etc.
My hazy recollection is that poisoning a pagecache folio also sets
AS_EIO too?  If that's true, maybe we should mention that.

--D

> Young
> =====
> 
> Idle
> ====
> 
> Arch 2
> ======
> 
> Arch 3
> ======
> 
> Readahead
> =========
> 
> Aliases with Reclaim as they are usually never set on the same folio, and
> if they are the consequences are a minor performance loss.
> 
> Anon_Exclusive
> ==============
> 
> Aliases with Mapped_To_Disk as that flag can never be set on anonymous folios.
> 
> Isolated
> ========
> 
> Shared with Reclaim flag, only valid for folios with LRU flag clear.
> 
> Reported
> ========
> 
> Only valid for buddy pages. Used to track pages that are reported
> 
> Has_HWPoisoned
> ==============
> 
> Large_Rmappable
> ===============
> 
> 
> 

Re: page-flags.rst

[Sidhartha Kumar]

On 5/14/24 11:35 AM, Matthew Wilcox wrote:
> As encouraged by my lively audience / collaborators, here is the
> typos-and-all result of the LSFMM session which just finished.
> 
> Please don't respond to point out the typos; trust that I will fix them.
> 


........

> 
> Has_HWPoisoned
> ==============
> 

For Has_HWPoisoned, the comment in include/linux/page-flags.h:926 works well 
with some additional comments.

This flag is per-folio. Has_HWPoisoned indicates that at least one subpage is 
hwpoisoned in the compound page. This flag is set by hwpoison handler and is 
cleared by THP split or freeing of the page. This flag is not set on hugetlb folios.

> Large_Rmappable
> ===============
> 
> 
>