> > > document the driver's private properties correctly after Brussel?
> >
> > Minimally, in the driver's manpage.
>
> Well, documenting private properties is something that needs to be
> done with extreme discretion, becuase private properties are an extremely
> Unstable interface. However, there may be some private properties
> that are worth documenting
Yes. BTW, "unstable" by PSARC's definition means "only changes in a minor
release" -- you may mean something more like "volatile". In any case, the
manpage should set expectations appropriately (if the stuff is even
manpage-worthy).
> and we also need a central place to document public properties.
The WiFi properties are covered in dladm(1M), which seemed logical to me
(since the administrative view of the property namespace is via dladm).
> I was looking into this yesterday, and, so far, it seems like the
> existing documents that carry this type of information are
>
> (i) man page (e.g, section 7D man page for the driver, ieee802.3(5)
> (ii) the "Solaris Tunable Parameters" available at docs.sun.com - this
> does not have a section for drivers, but looks like a good place
> to track Public properties
> (iii) Platform notes exist for some drivers (I found some for qfe, dmfe,
> eri).
> Maybe we should have one for each driver? This would be a good
> place for documenting driver-private tunables.
My view on this is:
* The authoritative reference should always be the manpage. For
driver-specific tunables, that can be the driver manpage; for
general ones dladm(1M) seems reasonable unless it gets unwieldy.
* The notion of a "tunable parameters" guide is itself misguided.
Tunable parameters -- when they have to exist -- should be a
means to an end. As such, I could see discussing security- or
performance-related tunables as part of a broader discussion on
those topics, but discussing them in isolation from the broader
discussion (and intermixed with one another) encourages abuse
and misunderstanding.
* If by "platform notes" you mean "driver notes", I suppose that
could be useful, but I'm not sure how it differs from what we
could cover in a driver manpage.
--
meem
