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 retitled this revision from to pmap_quick_enter_page.9.Aug 6 2015, 2:41 AM
jah updated this object.
jah edited the test plan for this revision. (Show Details)
jah updated this revision to Diff 7697.
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 marked 9 inline comments as done.Aug 6 2015, 2:56 PM
jah updated this revision to Diff 7713.

Fixing the bugs kib pointed out

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

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 edited edge metadata.Aug 6 2015, 3:38 PM
jah updated this revision to Diff 7718.

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 edited edge metadata.Aug 6 2015, 3:48 PM
jah updated this revision to Diff 7720.

Fix lint warnings

brueffer accepted this revision.
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 edited edge metadata.Aug 6 2015, 8:40 PM
jah updated this revision to Diff 7736.

Fix problems noted by wblock

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

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.