On Fri, Jul 03, 2009 at 02:56:29PM -0700, Garrett D'Amore wrote: > >(As an aside, our network driver manpages really need some work -- many of > >them still describe common stuff that is automatically handled by GLDv3, > >and suggest direct programmatic access via DLPI primitives on their /dev > >node; all of this text needs to be updated and much of it needs to be > >changed to reference a common manpage that describes interacting with > >/dev/net nodes. This has been on my TODO list forever but I never seem to > >get to it.) > > Yes, mine too. > > But this really underscores a problem... a strategy assuming that manual > pages will continuously kept up to date with the software, to the point > that the only way to learn about tunables is through the manual pages, > flies in the face of reality. The *reality* is that manual pages often > lag software integrations by several builds, and sometimes aren't even > updated at all. The current sad state of NIC driver manual pages is an > excellent example of why relying on manual pages to provide accurate > information is an idea that sounds good, but proves out not to work so well. > > Again, I don't think the properties need to be enumerated by default, > but there needs to be *some* way to locate these.
+1 (though arguably engineers should step up to fix manpages more often, and certainly should be allowed to). Even driver-specific properties should be enumerable and self- documenting. That we shouldn't have a shantytown of properties that started life as not-generic then became so over time[*] should no mean that we want to hide driver-specific properties. [*] I have no idea how to prevent such evolution, frankly, since a property that seems unlikely to be generic this year might be generic next year when three more devices (or new firmware for existing devices) appear on the market that could use that same property. What should happen is that driver-specific properties should be Volatile interfaces and generic ones should mostly be Committed, with interface stability shown along with any other documentation shown to the user. Nico -- _______________________________________________ networking-discuss mailing list [email protected]
