Hiya, Garrett!
Great idea - thanks for proactively putting a stake in the ground
to document the process.
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.
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).
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.
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.
Can we add these items to your list?
--
thanks,
--vla =:-)
========================================================================
Vicki Abe
Accessline number: (408) 404-6916 (x.69966)
Solaris x86 IHV Engineering Team
Garrett D'Amore wrote:
> During today's PSARC meeting, we talked about best practices. One of
> the ones that seemed pretty stale and incomplete was the one for device
> drivers (see
> http://www.opensolaris.org/os/community/arc/bestpractices/bp-device-drivers/
> )
>
> So I've undertaken to write a replacement. Here's a draft. Note that
> this is not in the format for BPs. We can correct that later -- mostly
> I want to offer this up for a general review/comment/feedback at this
> point, and once we have the content mostly stable, I'll submit a new
> case for it.
>
> So, here's what I have. Some of the items listed below may never have
> been expressed in any other document before:
>
> Device Drivers Best Practices
> -----------------------------
>
> 1. DDI conformance. Device drivers for bundled device drivers SHOULD
> adhere to the documented DDI, using only header files, functions,
> macros,
> structures, and fields that are documented. Note that this precludes
> taking the sizeof() certain structures (struct msgb, struct datab,
> struct
> buf) which are intended to be dynamically allocated. Unbundled device
> drivers MUST adhere to the documented DDI, or obtain contracts for any
> exceptions required.
>
> 2. Proper use of bus/device type specific APIs where applicable. Drivers
> SHOULD, when possible, use the latest driver frameworks for certain
> types of driver, rather than reimplementing common functionality. For
> example, NIC drivers should use the GLD, and SCSI drivers should use the
> SCSA framework and USB drivers should use the USB framework.
>
> 3. Independence from firmware initialization. Device drivers should not
> depend on firmware to initialize devices. While certain portions of
> the device may be initialized by OS or BIOS (assignment of PCI
> addresses to BARs for example), device drivers should not rely on
> firmware to perform any device specific initialization.
>
> 4. Support for DDI_SUSPEND and DDI_RESUME. Device drivers must properly
> support DDI_SUSPEND and DDI_RESUME, including dealing with a potential
> loss of power in between. Note that system firmware may not execute
> on resume, so adherence to #3 above will help greatly. Pseudo-drivers
> generally don't have to worry about this, and certain kinds of hardware
> drivers may be able to rely on their bus parents to properly shutdown
> the device.
>
> 5. Support for quiesce(9e). In order to facilitate fast-reboot,
> drivers should
> support the quiesce(9e) DDI entry point. (Not applicable to Solaris
> 10 or
> earlier.)
>
> 6. Support for power management. If possible, devices should support
> fine grained power management to reduce overall power consumption on
> the platform. See power(9e).
>
> 7. Portability. Device drivers should avoid assumptions about the
> platform they are to run on. A driver should be coded to operate
> properly on either SPARC or x86 CPUs. Drivers should not make
> assumptions
> about the cache, endian, or word size attributes of the host
> platform, and
> proerly make use of Solaris interfaces such as ddi_dma_sync(9f),
> ddi_get32(9f), etc.
>
> 8. MP safety. All device drivers must be MP-hot. That is, they must
> assume
> that entry points and interrupts can all run synchronously, and make use
> of synchronization guards (mutex_enter(9f) or similar) to ensure correct
> operation.
>
> 9. Fault tolerance. Device drivers MUST NEVER panic in response to bad
> data received from a source outside of the kernel address space. That
> means that data received from a physical device (disk, network, etc.)
> must be validated before used in the kernel, as well as data that comes
> from user-space. Device drivers should use watchdogs or similar to
> guard
> against device failure. Device drivers should make use of FMA
> interfaces
> to handle and report fault conditions.
>
> 10. Userland interaction. Device drivers that interact with userland must
> be able to deal with either 32-bit or 64-bit applications, performing
> any word size conversions as necessary. (Note that no conversion is
> necessary when the kernel is running in 32-bit mode.) See
> ddi_get_model(9F).
>
> 11. Avoiding polling. Drivers should avoid polling whenever possible,
> particularly in long running situations. Polling prevents the CPU
> from reaching idle state, and increases power consumption for the
> entire platform.
>
> 12. Do not depend on the system clock rate. The value of HZ can be
> different
> across reboots. drv_usectohz(9f) can be used if an absolute time is
> required.
>
> 13. Minimize time running in interrupt context. This is a general
> guideline
> for all device drivers.
>
> 14. Avoid use of custom tracing or debugging facilities. Use DTrace
> instead.
>
> 15. Observability. Drivers SHOULD properly report their operation via
> the appropriate kstat(9s)'s for their driver type. This includes
> correct accounting of I/O times (kstat_io(9s)) and interrupts
> (kstat_intr(9s)).
>
> 16. Proper support for dynamic loading & unloading. Device drivers must
> support being modunload(1M)'ed through correct support for _fini(9e).
> This also means that drivers must support detach(9e) properly.
>
> 17. Proper support for hotplug where applicable. A driver for a removable
> system peripheral must support hot insertion and removal. Via
> attach(9e) and detach(9e). Note that PCI and PCI express busses are
> hotpluggable on some platforms.
>
>
>
>
>
