Update for pmap_enter(9) man page.

[kib]

Summary

Document flags argument. Mention important required behaviour from the method implementation, for new architectures.

[alc]

share/man/man9/pmap_enter.9

46–47

This is really a comment about the existing first sentence. I find "... inserts ... into the physical map ..." to be utterly meaningless. How does the first sentence not include the word "mapping".

I suggest changing this sentence to "... function creates a mapping in the physical map ... from the virtual address ... to the physical page ... with the protection ..."

Maybe add the following sentence: "Any previous mapping at the virtual address ... is destroyed."

67–68

I would simply say, "The mapping should be marked as wired."

70

The phrasing "The pmap implementation ..." sounds like the entire pmap. Restrict it by saying, "This function may not ..."

71

"If the mapping cannot be created without sleeping, ..."

76–77

I don't think that "lazy-evaluate" adds anything here to the clarity of the statement. I would say, "... this function must create the requested mapping before returning. It may not fail in the creation of the mapping."

78–81

"In order to create the requested mapping, this function may destroy any non-wired mapping in any pmap."

83–89

The word "managed" should really be in the first clause, not the second.

I need to stop here for now.

[kib]

Do the suggested changes.

[alc]

share/man/man9/pmap_enter.9

61

"... takes ..." -> "... may have ..."

64

As a rule, try to avoid passive voice, so...
"A read access to the given virtual address triggered the call."

66

"A write access to the given virtual address triggered the call."

68

"An execute access to the given virtual address triggered the call."

74

"... error code is returned."

80

I think you can simply say "It may not fail.

83

Insert a paragraph with a couple sentences about psind here?

"The psind parameter specifies the page size that should be used by the mapping. The supported page sizes are described by the global array pagesizes[]. The desired page size is specified by passing the index of the array element that equals the desired page size.

Maybe add a bugs or implementation notes section saying that the implementation is incomplete on amd64, arm, and x86. Only 0 is supported.

84–90

"When the pmap_enter function destroys or updates a managed mapping, including an existing mapping at virtual address va, it updates the vm_page structure corresponding to the previously mapped physical page. If the physical page was accessed through the managed mapping, then the vm_page structure's PGA_REFERENCED aflag is set.

91–96

"If the physical page was modified through the managed mapping, then the vm_page_dirty function is called on the vm_page structure.

98–102

We only set PGA_WRITEABLE for managed mappings.

109

Drop "passed". The use of "m" here makes it clear that we're talking about the given physical page.

111–112

"..., then it must be ... caller (no comma here) or ... locked. In the latter case, the PMAP_ENTER_NOSLEEP flag must be specified by the caller.

117–118

This is equivalent to saying, "the Alan", which I don't think that you would do. :-) Use "this function", "the pmap_enter function", or simply "pmap_enter".

121–122

See previous comment.

127–128

"... specified (no comma here) and the resources required for the mapping cannot be acquired without sleeping, KERN_RESOURCE_SHORTAGE is returned."

I don't see the point of encouraging people to invent different return values. Didn't we use the same return value in all the implementations so far?

160–162

I think that your name should go first. There is nothing left of the original text.

[alc]

P.S. Just to be clear, I'm done. I don't have any other comments.

[kib]

I added NOTES section with the new unreviewed text about psind values supported.

Should I add you (Alan) to the authors ?

[alc]

Sure, I think it's fair to add my name to the authors lists.

share/man/man9/pmap_enter.9

159

"... was first written ...

[kib]

r277793