Page MenuHomeFreeBSD

Rewrite the vm_page_alloc manual page
ClosedPublic

Authored by markj on Sep 21 2021, 2:45 AM.

Details

Summary

Document the rest of the page allocator interface.

Diff Detail

Repository
R10 FreeBSD src repository
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

markj requested review of this revision.Sep 21 2021, 2:45 AM

Just a minor nit, the rest looks good, doc-wise.

share/man/man9/vm_page_alloc.9
295

s/behaviour/behavior/
American English in our docs

markj marked an inline comment as done.

Address feedback, placate mandoc -Tlint.

share/man/man9/vm_page_alloc.9
161

I believe it would be somewhat helpful to expand 'anonymous' there as meaning 'not belonging to an object' as opposed to 'belonging to OBJ_ANON object'

260

This statement somewhat contradict the previous sentence. If you mean that VM_ALLOC_WAITOK can be only used with noobj allocators, then why state that it unlocks the object?

290

I think this is misleading, because even VM_ALLOC_INTERRUPT allocations can fail. Might be it is better to say something along lines 'if a way to handle allocation failure at the caller is worse than consuming the last free page'. Then you could mention kernel page table page allocation as an example.

301

when allocating pages without a VM object ? It sound too strange to me.

markj marked 4 inline comments as done.

Tweaks, address feedback.

share/man/man9/vm_page_alloc.9
185

Perhaps mention that VM_ALLOC_WAITOK is invalid for obj != NULL there?
Otherwise it is still looking somewhat self-contradicting to me.

markj marked an inline comment as done.

Improve WAITOK description

share/man/man9/vm_page_alloc.9
260

This text still leaves the same issue present. At least I find the text self-contradicting or confusing at best. You cannot unlock object when noobj allocator is used.

share/man/man9/vm_page_alloc.9
260

This is why I included "if any". I could perhaps expand it to, "if one is specified by the interface" but I am not sure how to make it less confusing.

share/man/man9/vm_page_alloc.9
260

You are saying that VM_ALLOC_WAITOK is only valid for _noobj functions, right? Why not to say it outright when the flag is listed instead at the end, after you said that !noobj + VM_ALLOC_WAITOK relock (which is not true because you should not pass VM_ALLOC_WAITOK at all).

Specify upfront that WAITOK is only to be used with noobj interfaces.
Mention unlocking the object only in the context of WAITFAIL.

This revision is now accepted and ready to land.Sep 24 2021, 8:07 PM

Remove mention of VM_ALLOC_NORMAL, just describe the default behaviour of page
allocators with respect to the minimum number of free pages required for an
allocation to succeed.

This revision now requires review to proceed.Oct 5 2021, 1:38 PM
This revision is now accepted and ready to land.Oct 6 2021, 5:47 AM
share/man/man9/vm_page_alloc.9
143
147–149
156–158
159–161
180
187–189
209–210

More importantly, we set the md_page field that is read by a future call to a mapping function, e.g., pmap_enter, pmap_qenter, etc., when creating a PTE so that the PTE encodes the right memory attributes.

227
240
259
260–263

To avoid confusion, this should explicitly describe the status of the lock upon return.

315
327–328

I find this confusing because vm_page_t is itself a pointer type.

markj marked 13 inline comments as done.

Address feedback. Note in the RETURN VALUES section that the object
is write-locked upon return.

This revision now requires review to proceed.Oct 17 2021, 8:48 PM
This revision was not accepted when it landed; it landed in state Needs Review.Oct 20 2021, 1:23 AM
This revision was automatically updated to reflect the committed changes.