page-flags.rst

[Matthew Wilcox <willy@infradead.org>]

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
===============