On Wed, Jul 30, 2014 at 10:32 AM, Andrew Gabriel < [email protected]> wrote:
> On 07/28/14 07:26 PM, Garrett D'Amore via illumos-developer wrote: > >> I'd like to propose that we "cleanup" certain things in man pages. >> >> 1. For section 7D pages, I'd like to remove the FILES section, or at >> least any references to driver binaries. The location of driver binaries >> is architecture, and in some cases distribution-, specific, and offers >> little useful value. I think even documenting driver.conf location is >> rather pointless, since driver.conf covers it. >> > > So, driver.conf should be in the SEE ALSO section. Yes. > > > 2. For NIC drivers, I want to remove the entire APPLICATION PROGRAMMING >> INTERFACE that describes the various DLPI parameters. Instead, the page >> should document that the driver is an ethernet driver, and include a >> reference to dlpi(7p). >> > > Fine if they are all the same. Max frame size should be mentioned (and > probably also explicitly mention support for jumbo frames, or not). You can determine that information programmatically, and it may differ between different versions of the chipset. It seems like its better to get this from the code, than to rely on documentation which will almost certainly become out of date as new chipsets are added (even to the same driver). > > > Likewise, the various ethernet-generic driver.conf properties ought to >> be removed from documentation -- the correct way to configure properties is >> via dladm instead of driver.conf. >> > > Are they all configurable via dladm? > For drivers that support dladm, yes. And I recommend that we only remove it for those drivers that do support it. > Personally I would prefer that information remains, but also states dladm > is now the preferred interface where that is the case. Ok, although its a lot redundancy. driver.conf properties are also implicitly supported by dladm / brussels, so that means that every driver has to document the same properties over and over again. That feels like a lot of duplication. Instead, it would be better, IMO, to document this in the appropriate dladm or ethernet generic page, rather than in every single driver. (And leave a cross reference behind, of course.) > > 3. For class wide drivers (e.g. ethernet), maybe we should also remove >> the /dev/igb* (or whatever) notation from FILES. Again, DLPI is the right >> way to access these, not by accessing the /dev node directly. (And again, >> the /dev node can vary based upon vanity naming, style 1 vs style 2 DLPI, >> etc.) >> > > DLPI API requires that the vendor specifies the device node to open. But again, it varies. I think dlpi(7P) is the place to do this. > > > 4. Each driver doesn't need to include a reference to the WDD, STREAMS >> Programming guide, etc. That is covered in Intro(7), and the driver pages >> can just list that in SEE ALSO. >> > > Yes, but you probably exceeded the max link count a human will follow, > thus obscuring the information. Who ever follows the links from igb(7D) to WDD? Seriously? There is almost no value in leaving the link there. If someone is that interested they'll follow the link trail back to the generic page. Having every detail linked off every driver's page is just plain silly. > > -- > Andrew Gabriel > ------------------------------------------- illumos-discuss Archives: https://www.listbox.com/member/archive/182180/=now RSS Feed: https://www.listbox.com/member/archive/rss/182180/21175430-2e6923be Modify Your Subscription: https://www.listbox.com/member/?member_id=21175430&id_secret=21175430-6a77cda4 Powered by Listbox: http://www.listbox.com
