Skip to contentSkip to conversation

page-flags.rst

DISCUSSION Matthew Wilcox 3 participants 3 messages May 14, 2024 – May 16, 2024

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

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

#1 lore raw
Quoted 4 lines · 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.

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

Arbitrary incoherent comments follow:

Quoted 12 lines

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

Quoted 7 lines

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?

Quoted 9 lines

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

Quoted 4 lines

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.

Quoted 35 lines

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

Quoted 7 lines

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?

Quoted 81 lines

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

Quoted 6 lines

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

Quoted 41 lines

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

#2 lore raw
In reply to Matthew Wilcox
Quoted 5 lines · 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.

........

Quoted 4 lines

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.

Quoted 5 lines

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