[driver-discuss] Device Drivers Best Practice

[Steven Stallion]

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