bhnd: add/update inline documentation comments and man pages

[landonf]

Summary

This includes a number of copyedits for the inline code documentation comments, updates to the existing bhnd(4), bhndb(4), bcma(4), and siba(4) man pages, and new man pages for bhnd_chipc(4), bhnd_pmu(4), bhndb_pci(4), bhnd(9), and bhnd_erom(9).

The bhnd(9) and bhnd_erom(9) man pages were automatically generated by parsing the inline code comments, and then hand-edited to bring them into sync with standard man page conventions and groff_mdoc(9).

Depends on D12708, D12664, D12518, D12385, D12582

Test Plan

I've posted PDF rendered versions of bhnd(9) and bhnd_erom(9) for easier proofing:

• bhnd(9): bhnd.9.pdf
• bhnd_erom(9): bhnd_erom.9.pdf

[landonf]

Fix all igor(1) warnings.

[landonf]

regenerated diff with git's incorrect rename tracking heuristics disabled.

[wblock]

In the future, please use full context in review diffs: https://wiki.freebsd.org/action/show/Phabricator?action=show&redirect=CodeReview#Create_a_Revision_via_Web_Interface

Thank you for your work on this.

share/man/man4/bhnd_chipc.4

37 ↗

(On Diff #35014)

Please see https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/manpages-sample-structures.html#manpages-sample-structures-section-4 for suggested wording of the first part of section 4 man pages.

share/man/man4/bhnd_pmu.4

70 ↗

(On Diff #35014)

ported to
.Fx
and

share/man/man4/bhndb.4

59 ↗

(On Diff #35014)

To enable use for PCI/PCIe systems, see the
.Xr bhndb_pci 4
driver.

share/man/man4/bhndb_pci.4

38 ↗

(On Diff #35014)

Please see https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/manpages-sample-structures.html#manpages-sample-structures-section-4 for better wording for this section.

share/man/man9/bhnd_erom.9

200 ↗

(On Diff #35014)

s/will be/is/

204 ↗

(On Diff #35014)

Possessive is probably unnecessary. In general, avoid possessives.

A pointer to a bus I/O instance mapping the first hardware core device

207 ↗

(On Diff #35014)

Remove \(em.

"Should be mapped" implies that it is not required. If it is required, this would be "must be mapped".

233 ↗

(On Diff #35014)

This is confusingly worded.

.Dv NULL
is returned if there are no successful probe results from the erom class.

258 ↗

(On Diff #35014)

There is another \(em, which I suspect is from either an editor or a well-meaning but misguided man page generator.

261 ↗

(On Diff #35014)

And another.

270 ↗

(On Diff #35014)

Avoid possessives. They get ugly easily, and few people in the post-literacy world understand them precisely. In this case, it is not even needed, just remove the apostrophe.

274 ↗

(On Diff #35014)

"may" implies permission. "can" is probably a better word here.

325 ↗

(On Diff #35014)

s/will be/is/

327 ↗

(On Diff #35014)

s/will be/is/

329 ↗

(On Diff #35014)

s/will be/is/

333 ↗

(On Diff #35014)

Be imperative.

If the core information is not desired, set
.Fa core
to

352 ↗

(On Diff #35014)

s/the following/these/

432 ↗

(On Diff #35014)

Split sentences.

A return value equal to or less than zero indicates success.
Values greater than zero indicate an error and the error code.

438 ↗

(On Diff #35014)

"should be"? This sounds like sometimes it might not be.

.Er ENXIO
is returned if the device is not supported by the parser.

[landonf]

Thanks for reviewing; I've inlined a couple questions, and I'll follow up in a bit with the remaining requested edits.

share/man/man9/bhnd_erom.9

207 ↗

(On Diff #35014)

I can replace the em dash here by breaking this into two sentences, but what should I be using in other locations where a pair of commas is insufficient?

233 ↗

(On Diff #35014)

Since this is plural (if _any_ erom class succeeds, the call succeeds; if _all_ erom classes fail, the call fails), this would have to be:

.Dv NULL
is returned if there are no successful probe results from an erom class.

I'm not sure that's actually less confusing :-)

Perhaps this?

If none of the probed erom classes return a successful probe result,

[wblock]

share/man/man9/bhnd_erom.9

207 ↗

(On Diff #35014)

In general, two short declarative sentences are preferable to an emdash. The uses here are kind of asides, which again are better as two separate sentences.

231 ↗

(On Diff #35014)

s/will be/is/

233 ↗

(On Diff #35014)

Some redundancy with "returns" and "probe". Hmm, maybe:

If there are no successful probe results from the erom classes,
.Dv NULL
is returned.

258 ↗

(On Diff #35014)

This is an "aside". Typically, they use parentheses, but are better moved to a later sentence to avoid interrupting the train of thought of the reader.

This is ...an attempt. It's still early here, so apologies for probably weak wording.

Clients can manage the allocation of memory themselves with
.Fn bhnd_erom_init_static .
This is useful in cases like performing device enumeration before
.Xr malloc 9
has been initialized.
.Fn bhnd_erom_init_static
is called with 
.Fa erom
set to a pointer to the memory for the instance and
the total available bytes in
​.Fa esize .

[landonf]

Applied requested copy and line edits.