Document the rest of the page allocator interface.
Details
Details
- Reviewers
alc kib - Group Reviewers
manpages - Commits
- rG6d3c78d97028: Rewrite the vm_page_alloc manual page
Diff Detail
Diff Detail
- Repository
- rG FreeBSD src repository
- Lint
Lint Not Applicable - Unit
Tests Not Applicable
Event Timeline
Comment Actions
Just a minor nit, the rest looks good, doc-wise.
| share/man/man9/vm_page_alloc.9 | ||
|---|---|---|
| 295 | s/behaviour/behavior/ | |
| share/man/man9/vm_page_alloc.9 | ||
|---|---|---|
| 162 | 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' | |
| 261 | 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? | |
| 291 | 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. | |
| 302 | when allocating pages without a VM object ? It sound too strange to me. | |
| share/man/man9/vm_page_alloc.9 | ||
|---|---|---|
| 186 | Perhaps mention that VM_ALLOC_WAITOK is invalid for obj != NULL there? | |
| share/man/man9/vm_page_alloc.9 | ||
|---|---|---|
| 261 | 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 | ||
|---|---|---|
| 261 | 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 | ||
|---|---|---|
| 261 | 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). | |
Comment Actions
Specify upfront that WAITOK is only to be used with noobj interfaces.
Mention unlocking the object only in the context of WAITFAIL.
Comment Actions
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.
| share/man/man9/vm_page_alloc.9 | ||
|---|---|---|
| 144 | ||
| 148–150 | ||
| 157–159 | ||
| 160–162 | ||
| 181 | ||
| 188–190 | ||
| 210–211 | 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. | |
| 228 | ||
| 241 | ||
| 260 | ||
| 261–264 | To avoid confusion, this should explicitly describe the status of the lock upon return. | |
| 316 | ||
| 327–328 | I find this confusing because vm_page_t is itself a pointer type. | |
Comment Actions
Address feedback. Note in the RETURN VALUES section that the object
is write-locked upon return.