man: Add vm_fault_quick_hold_pages(9) man page

[khng]

Summary

vm_page_unhold_pages(9) man page is added as well.

Sponsored by: The FreeBSD Foundation

[kib]

This is nothing more than the mandoc-fication of the herald comment for the function, I am not sure that it is useful in this form. More, if the function signature or semantic is updated, the man page would be forgotten, I am sure.

I think this can be made into something that provides useful information for readers, e.g. by including (and expanding) the following points (this is probably incomplete fast list):

• All mappings in the range must be valid and managed, or at least the physical addresses must be represented in vm_page_array[]
• The function simulates the behavior of an access to memory with the specified access rights, and wires and returns page that would serve the access. In particular, it handles copy on write, paging in etc
• Function may need to sleep waiting for memory allocation; faults and resources used for page-in are accounted for the calling thread regardless of the map
• There should be no locks owned by the caller which are after any of VM/VFS/network locks; function may sleep if faults are not disabled
• VM_PROT_QUICK_NOFAULT should be explained, esp. since you are talking about disabled page faults
• in nofault case, some non-sleepable vm locks are still taken
• perhaps an example should be either provided or described

share/man/man9/vm_fault_quick_hold_pages.9

59

mapped by the map .Fa map

71

I am not sure what does this 'have mapping for vm_objects' statement should mean.

81

We never call vm_page_t 'objects'

87

s/hold/wire/

[khng]

• Update wording
• Document reasons why the call can fail
• Listed the points from kib@ and try to elaborate on them
• An example

[kib]

share/man/man9/vm_fault_quick_hold_pages.9

66

Pages do not 'allow' the protection. It is the mapping that permits/denies specific kinds of accesses.

74

vm_page_t is not a structure (it is struct vm_page *). Usually vm_page_t is considered as the page identity.

79

'Resident' is the wrong approach to describe it, the functionality is more nuanced. The page might be resident but still unmapped, in which case we do fall back to vm_fault() to install PTE (but page does not need to be fault in because it is resident). Also CoW is handled there, for instance if prot is VM_PROT_WRITE but allowed access in PTE is read-only and caller has the rights to write into the mapping.

80

s/wire/hold

81

This is where these details become important to be clearly specified.

106

physical map == pmap? I am not sure that this is useful expansion.

112

not paged out or freed

Idea is that held page cannot be reused from under holder, but it still might lost its identity (i.e. stop providing content for the specific object' offset)

144

This is the copy from vfs_bio.c or like? It is not too useful alone.

It would be more useful if you explain for instance that the resulting mapping could be used to access user memory from kernel without 'fear' of page faults, i.e. copyin etc are not needed.