This may or may not be OT, but I've always wondered what the official view of re-using the various DDI return statuses (i.e. DDI_SUCCESS and friends) within driver internal functions was.
It seems that there are two main approaches used at the moment; this, and the use of boolean_t. Perhaps it may be useful to have an appendix dedicated to style? Garrett D'Amore wrote: > Vicki Abe wrote: >> Hiya, Garrett! >> >> Great idea - thanks for proactively putting a stake in the ground >> to document the process. >> > > No prob'. Recall this is a Best Practices document that is intended for > projects coming to ARC, not a replacement for information that belongs > in WDD or in a test plan. That may help frame some of my comments below. > >> One item that could be very helpful is to define clearly what is >> and is-not supported by the driver. For example, we may have a >> very basic driver for a sophisticated device -- the device may have >> several enhanced features that are not supported by the "plain vanilla" >> driver. >> > > This should be part of the ARC case for the driver or the man page of > the driver, I'd think. Unfortunately, there is no master of features > where such a description makes sense. Supporting Jumbo Frames is > important for ethernet drivers, but completely pointless for storage > drivers, or even other kinds of NIC driver, for example. > >> If we could distinguish in the man page between features that may exist >> in the chip, but may not be supported in the driver (a design decision), >> it would help to set user expectations correctly -- and avoid needless >> confusion (and customer calls). >> > > Yes, but this isn't architectural. This sounds like a potential docs > req't, and should be coordinated with the docs folks, IMO. > >> Also, if the driver carried versioning information (version of the DDI, >> version of the USB spec, version of the driver itself, version of the >> gld framework), this would help with maintenance and ongoing support >> for our drivers. >> > > There is no versioning of the DDI, although some specific interfaces are > versioned. This sounds more like a release engineering problem, > though. I'll note that bundled drivers carry the ON build they were > built as part of in the ELF comments (accessible via "what"). Other > kinds of versioning information would be hard to express universally, I > think. At least with our current DDI. If you want to enhance the DDI > for that, we'd need a specific proposal. In any case, its out of scope > for this Best Practices proposal (at least unless the DDI were enhanced > to express that information.) > >> We also noticed in a recent device driver class that we sponsored for >> IHVs, that driver developers coming from a Linux environment had some >> key differences in approach -- for example, their use of the watchdog >> interrupt is a common technique in Linux, but was actually a violation >> of the spirit of the Solaris DDI. >> > > Hmmm... I'm not sure how to express this difference in a best practices > document. > > Are you saying that these folks were hanging off a platform wide > watchdog for some other non-platform-specific driver? Weird. And yes, > not really in the spirit (or the letter, for that matter) of the DDI. > (timeout(9f) can be used to create soft watchdogs, though.) I'm not > sure I want to get into the philosophy of different design approaches, > but I think DDI compliance already covers the main concern here. > > (Conversely, if the device has its own internal watchdog timer that the > driver wishes to use to ensure proper function, I see no problem with that.) >> Can we add these items to your list? >> > I think most of the items you've mentioned probably have some other > context than what I'm intending the Best Practices document for. But > I'm happy to hear arguments to the contrary -- perhaps our Best > Practices guru (Plocher) would care to comment? > > -- Garrett > _______________________________________________ > driver-discuss mailing list > driver-discuss at opensolaris.org > http://mail.opensolaris.org/mailman/listinfo/driver-discuss
