Page MenuHomeFreeBSD

pmap_quick_enter_page.9
ClosedPublic

Authored by jah on Aug 6 2015, 2:41 AM.

Details

Summary

Create manpage for pmap_quick_enter_page() and pmap_quick_remove_page()

Diff Detail

Repository
rS 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

jah updated this revision to Diff 7697.Aug 6 2015, 2:41 AM
jah retitled this revision from to pmap_quick_enter_page.9.
jah updated this object.
jah edited the test plan for this revision. (Show Details)
jah added reviewers: kib, wblock.Aug 6 2015, 2:43 AM
kib added inline comments.Aug 6 2015, 7:04 AM
share/man/man9/pmap_quick_enter_page.9
34 ↗(On Diff #7697)

address space

46 ↗(On Diff #7697)

I do not think that wired is any sort of requirement for the state of the page m. Caller must ensure that the page is not reused for something undesirable, but thats all. E.g., the page could be unmanaged, or it could be managed but held instead of wired, or it could be busy. Any of the listed condition are enough to keep the m content stable.

56 ↗(On Diff #7697)

s/.$/, making the KVA frame used by pmap_quick_enter_page() available for reuse./

Or, some other way to say that the calling thread must not recurse into the dynamic region marked by pmap_quick_enter/remove.

62 ↗(On Diff #7697)

This sentence does not describe implementation, it should be moved to the main body of the function description. In particular, main text must say that the region cannot be nested, that the locking cannot be used in the region, and remove must be called as soon as possible.

Also, the context where the function can be called should be mentioned (thread but not interrupt handler, no spinlock may be owned when called).

72 ↗(On Diff #7697)

See above, this should be moved from notes.

77 ↗(On Diff #7697)

'Cannot fail' claim must be also moved.

79 ↗(On Diff #7697)

....

83 ↗(On Diff #7697)

No.

92 ↗(On Diff #7697)

I propose not to say this in the man page.

jah updated this revision to Diff 7713.Aug 6 2015, 2:56 PM
jah marked 9 inline comments as done.

Fixing the bugs kib pointed out

kib accepted this revision.Aug 6 2015, 3:16 PM
kib edited edge metadata.

Overall, it is fine WRT the content.

Note that the each sentence in the mdoc source should start on the new line.

share/man/man9/pmap_quick_enter_page.9
86 ↗(On Diff #7713)

Note that even if the page is swapped, nothing wrong would happen with the mapping. Both the page and the *m are still there. It is up to the caller to decide is it worrying.

jah updated this revision to Diff 7718.Aug 6 2015, 3:38 PM
jah edited edge metadata.

Move each sentence to its own line

brueffer added inline comments.
share/man/man9/pmap_quick_enter_page.9
89 ↗(On Diff #7718)

This .Pp is superfluous.

96 ↗(On Diff #7718)

This is superfluous as well.

Please run mandoc -Tlint on the manpage, it catches these kind of things :-)

jah updated this revision to Diff 7720.Aug 6 2015, 3:48 PM
jah edited edge metadata.

Fix lint warnings

brueffer accepted this revision.Aug 6 2015, 3:50 PM
brueffer added a reviewer: brueffer.
This revision is now accepted and ready to land.Aug 6 2015, 3:50 PM
wblock added inline comments.Aug 6 2015, 7:41 PM
share/man/man9/pmap_quick_enter_page.9
57 ↗(On Diff #7720)

The "at" should be on a separate line:

.Fn pmap_quick_enter_page
at
80 ↗(On Diff #7720)

"cannot fail" implies that they always work, but the next two sentences have some exceptions.

86 ↗(On Diff #7720)

"is valid" is ambiguous for the reader, who might not know what that means. Maybe "in place" or "active" or something like that?

jah updated this revision to Diff 7736.Aug 6 2015, 8:40 PM
jah edited edge metadata.

Fix problems noted by wblock

This revision now requires review to proceed.Aug 6 2015, 8:40 PM
wblock accepted this revision.Aug 6 2015, 9:17 PM
wblock edited edge metadata.

The man page changes look good to me. Before commit, please check with igor -R in addition to the mandoc -Tlint that brueffer mentioned. Thanks!

This revision is now accepted and ready to land.Aug 6 2015, 9:17 PM
This revision was automatically updated to reflect the committed changes.