Page MenuHomeFreeBSD

Describe FreeBSD's virtual memory in memory(7)
Needs ReviewPublic

Authored by 0mp on Jan 7 2019, 11:00 AM.
Tags
None
Referenced Files
Unknown Object (File)
Wed, Oct 8, 6:32 AM
Unknown Object (File)
Sep 10 2025, 9:48 PM
Unknown Object (File)
Aug 1 2025, 11:03 PM
Unknown Object (File)
Jul 28 2025, 9:37 PM
Unknown Object (File)
Jul 28 2025, 8:54 PM
Unknown Object (File)
Jul 28 2025, 8:39 PM
Unknown Object (File)
Jul 28 2025, 6:34 PM
Unknown Object (File)
Jul 28 2025, 2:31 PM

Details

Reviewers
bcr
markj
avg
koobs
jhb
kib
alc
bnovkov
Group Reviewers
manpages
Summary
Describe FreeBSD's virtual memory in memory(7)

This manual page is based on the Memory article
from our wiki: https://wiki.freebsd.org/action/recall/Memory
Test Plan

igor, mandoc

Diff Detail

Repository
rG FreeBSD src repository
Lint
Lint Skipped
Unit
Tests Skipped
Build Status
Buildable 65399
Build 62282: arc lint + arc unit

Event Timeline

0mp added a subscriber: docs.

First of all: big thanks for creating this man page. I think it is good to have for non-developers and eventually moving the info out of the wiki into a man page.

I'd like to add a few more people (i.e. the ones who edited that wiki page) to get more technical review. I'm also adding John Baldwin who did the tech review for the "Absolute FreeBSD 3rd edition" book, since there are a couple of places where memory is described in lay-mans terms (i.e. the top section). Together with the others, we could fill in some gaps that might be there or add some more explanations when needed.

share/man/man7/memory.7
36

s/for non-developer audience/for a non-developer audience/

115

"Scans check" sounds wrong here (it's from the original). I think it should just be "check" or even "checks" since the scan is appearing again at the end of the sentence.

  • Break long lines.
  • Fix some grammar mistakes reported by @bcr.
0mp marked an inline comment as done.Jan 7 2019, 1:14 PM

Thanks for doing this, greatly appreciated! May I also suggest we add how do FreeBSD memory terms correlate and/or can be translated for those coming from GNU/Linux (their top(1) reports total, used, free, and buffers) or Windows environments (reserved vs. committed, see this question). This would make porting software that wants to obtain memory status much easier.

Thanks for doing this, greatly appreciated! May I also suggest we add how do FreeBSD memory terms correlate and/or can be translated for those coming from GNU/Linux (their top(1) reports total, used, free, and buffers) or Windows environments (reserved vs. committed, see this question). This would make porting software that wants to obtain memory status much easier.

Great idea. I think we can work on it in a separate revision to stay focused.

share/man/man7/memory.7
83

This is true for ZFS, but false for filesystems using buffer cache, i.e. for all non-pseudo filesystems, and even for tmpfs.

Buffer cache is for VMIO buffers is fully merged with the VM managed pages handling, VMIO buffers are only headers which point to an array of the backing VM pages for data. This is known as coherent buffer cache, and is the mechanism that ensures that read(2) and mmaped regions consistently see same data. All VMIO buffer' pages are wired.

90

Per above, memory is not evicted from buffer cache, rather when a VMIO buffer is reclaimed, the pages are unwired, and if no longer wired, put at the end of inactive queue. [It is more complicated, look at vfs_vmio_unwire()]

94

'belonging to page queues' is not correct. Managed pages are clean or dirty. For instance, managed wired page does not belong (logically) to any queue, but its dirty state is managed by VM.

Managed pages are exactly the kind of pages that are tracked by VM and can be paged out. They could be on queue or wired.

140

Unreferenced in which sense ? If you mean reference as in PG_A/PGA_REFERENCED/act_count, then it is irrelevant, clean page can be freed. If you mean something along lines of busy/hold/wired, then it would be better spelled explicitly, because otherwise even people who know our VM stop there.

170

There you clearly use 'referenced' as PG_A.

196

I do not think that we technically wire kernel text, we did not even allocated initialized vm_pages for text until recently. I believe. But the more important point is that there are a lot of allocations where memory pages are not wired but still fall into the category of being owned by some kernel subsystem. It might even represent substantial amount of the kernel memory usage.

0mp planned changes to this revision.Mar 3 2020, 2:43 PM
0mp marked an inline comment as done.

Thanks to @kib for posing a lot of comments about the VM subsystem. There is clearly a lot to be done before this manual page lands in the base system.

Changes:

  • Address some of the feedback points
0mp added inline comments.
share/man/man7/memory.7
83

I've updated the paragraph. I wasn't sure how to describe the VMIO part so I just let a comment in the source code for now.

90

I made an attempt at including this in the new revision.

94

I incorporated the feedback. The paragraph is rather dense now and will need to be revisited.

115

I'm not sure. It seems to me that there are scans that check if a certain thing happened since the previous check. It's something to clarify with a VM expert.

140

I don't know. I just copied it from the wiki page. I'll remove this part for now:

.It
Unreferenced, clean pages may be freed and reused immediately

and we can figure out later if we want to keep that and how to phrase it

170

I'm not sure what that means but it feels too detailed for memory(7), right?

196

Sounds interesting. Adding this info somewhere is a todo.

share/man/man7/memory.7
67

Buffer cache provides classical Unix buffer cache interface on top of the file data pages. Content of VMIO buffers is always consistent with the page cache for files.

(Might mention that read/write and mmaped memory are always consistent then).

70

These two sentences seems to be more logically placed after you described wiring.

87
165

I would say 'memory not used for anything and available for ...'
Since for instance clean inactive pages are de-fact available for use, just with more computing actions to free them.

170

freed is wrong term there. Perhaps cannot be reused until explicitly released ...

176
180
pauamma_gundo.com added inline comments.
share/man/man7/memory.7
71

What does "it" refer to here? (And if I missed something that makes it clear(er), should be "It" anyway at the start of a sentence.)

77
81

Also, should this be "in a queue" to match "and place it in the inactive queue" above?

87

Audience check: @kib will readers understand what "(page) name" refers to in your suggestion? It's never defined that I could see.

139
share/man/man7/memory.7
87

page name AKA page identity is the object (file, posix shm object, anon object etc) and offset in the object, which data is contained in the page

In source code it is pair of (object, pindex), you can find there fields in struct vm_page.