Page MenuHomeFreeBSD

Add zero_region.9 manual page
ClosedPublic

Authored by khng on Feb 24 2021, 5:02 PM.

Details

Summary

zero_region lacks documentation currently. A manual page is proposed for
zero_region and ZERO_REGION_SIZE to describe what it is.

Submitted by: Ka Ho Ng <khng@freebsdfoundation.org>
Sponsored by: The FreeBSD Foundation

Diff Detail

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

khng requested review of this revision.Feb 24 2021, 5:02 PM

Forgot to add manpage to share/man/man9/Makefile

gbe added a subscriber: gbe.

LGTM from manpages . Did you run igor and 'mandoc -Tlint' against the man page?

This revision is now accepted and ready to land.Feb 24 2021, 6:35 PM

Reorder SEE ALSO section to fix mandoc -T lint warning.

This revision now requires review to proceed.Feb 24 2021, 6:51 PM
In D28914#647282, @gbe wrote:

LGTM from manpages . Did you run igor and 'mandoc -Tlint' against the man page?

I just checked it against mandoc -Tlint, and did some fixes.

The output from mandoc -Tlint in the current form is:

mandoc: share/man/man9/zero_region.9:80:28: STYLE: consider using OS macro: Fx

The output of igor is:

$ igor -R share/man/man9/zero_region.9
zero_region.9:28:date not today, February 25, 2021:.Dd February 24, 2021
In D28914#647311, @khng300_gmail.com wrote:
In D28914#647282, @gbe wrote:

LGTM from manpages . Did you run igor and 'mandoc -Tlint' against the man page?

I just checked it against mandoc -Tlint, and did some fixes.

The output from mandoc -Tlint in the current form is:

mandoc: share/man/man9/zero_region.9:80:28: STYLE: consider using OS macro: Fx

The output of igor is:

$ igor -R share/man/man9/zero_region.9
zero_region.9:28:date not today, February 25, 2021:.Dd February 24, 2021

Minor issues, still LGTM.

Thanks for contributing this manual page.

This revision is now accepted and ready to land.Feb 24 2021, 7:15 PM
share/man/man9/zero_region.9
26

do we still need to have $FreeBSD$ in newly added file?

share/man/man9/zero_region.9
26

If this will be MFC to 12, then yes. Otherwise no.

This could be MFCed, as zero_region is from FreeBSD 9 era.

Add a line in description to tell developers not to make an assumption.

This revision now requires review to proceed.Feb 25 2021, 5:47 AM

Move the last paragraph in DESCRIPTION section to CAVEATS section.

This revision is now accepted and ready to land.Feb 25 2021, 8:30 AM
markj added inline comments.
share/man/man9/zero_region.9
49

It would be useful to write a couple of sentences explaining what exactly the example is doing.

58

Note that the exclusive lock is not strictly required by VOP_WRITE. Since vnode locking is not really relevant to the example, I would just omit the assertion.

84

Are you referring to the fact that the zero region is the same 4KB page mapped multiple times (on amd64 at least)? Why is it a caveat? IMPLEMENTATION NOTES is more suitable IMO.

Updates with markj@'s suggestions.

This revision now requires review to proceed.Mar 1 2021, 4:52 PM
khng marked 3 inline comments as done.Mar 1 2021, 4:52 PM
khng marked 2 inline comments as done.Mar 1 2021, 4:53 PM
philip added a subscriber: philip.

Looks good to me. I'll go and commit this now.

This revision is now accepted and ready to land.Mar 2 2021, 9:11 AM
This revision was automatically updated to reflect the committed changes.