Page MenuHomeFreeBSD

Clarify and improve device.hints.5
Needs ReviewPublic

Authored by wblock on Jul 23 2015, 8:48 PM.

Details

Reviewers
brooks
imp
Group Reviewers
manpages
Summary

Improve the clarity and readability of device.hints.5.

Test Plan

igor -R and mandoc -Tlint

Diff Detail

Repository
rS FreeBSD src repository - subversion
Lint
Lint Skipped
Unit
Unit Tests Skipped

Event Timeline

wblock retitled this revision from to Clarify and improve device.hints.5.
wblock updated this object.
wblock edited the test plan for this revision. (Show Details)
wblock added reviewers: brooks, imp.
wblock set the repository for this revision to rS FreeBSD src repository - subversion.
wblock added a project: manpages.
share/man/man5/device.hints.5
69–71

I'd say: "ISA or system on chip device drivers"

89

I'm skeptical of the value of this list unless we're going to make a pass through the manpages for all the keywords currently in use. In general, the set accepted by a given driver are documented in the driver manpage.

111–112

resource_int_value.9 is an internal detail and seems out of place here.

share/man/man5/device.hints.5
89

They do serve as examples of typical entries. We could trim it a bit to just the most common ones.

111–112

The intention might have been to show the formats or capabilities, but agreed, resource_int_value.9 really does not add much at all.

wblock edited edge metadata.
wblock marked 3 inline comments as done.
share/man/man5/device.hints.5
89

'flags' 'at' and 'disabled' at least, are used inside of subr_bus.c

While I share the skepticism, some simple wording may help. Many of these things like IRQ and DRQ are up to the bus to configure, not the driver. And the ISA bus at that. But this is by far our biggest use of hints, so it seems reasonable to include carefully worded messages here.

brooks edited edge metadata.

Looks good as is. A bit more word smithing around the keywords wouldn't hurt, but I'm ok with what's there now.

share/man/man5/device.hints.5
89

I'm fine with leaving this alone. My main issue is that while it does tell you what the standard values mean, that's not very useful to the reader since they can't know which ones (other than 'flags' 'at' and 'disabled') even apply to their device. Directing users to consult the manpage for their device for supported flags is likely one more helpful.

This revision is now accepted and ready to land.Jul 24 2015, 4:36 PM
share/man/man5/device.hints.5
89

What if we change the introduction to the table on line 86 from saying "The keyword may be:" to "Typical keywords include:"?

share/man/man5/device.hints.5
89

Works for me.

wblock edited edge metadata.

Change "The keyword may be:" to "Typical keywords include:" to show that the list is not exhaustive.

This revision now requires review to proceed.Jul 24 2015, 9:26 PM