
#pragma ident   "@(#)README 1.3     97/10/06 SMI"

/*
 * Copyright (c) 1995-1997 by Sun Microsystems, Inc.
 */

The Solaris Device Driver Kit provides a number of sample drivers for
a variety of devices.  These drivers are supplied for the purpose
of illustrating how the DDI interfaces are used in real drivers,
and as a starting point for developing a custom driver.  The sample
drivers in the DDK have not been thoroughly tested or qualified and
are not intended for use as production quality drivers.

Here is a list of the sample drivers available, with a synopsis
of the type of driver, a brief description of the hardware on
which the driver runs if available, and an indication of what
type of driver features and interfaces are supported by each driver.

Support and usage of the following driver features and interfaces
are evaluated for each sample driver:

o hotplug-ready:
	A Solaris driver can be written to be hot-plug capable
	in a hot-plug environment.  To support hot-plugging,
	a driver must provide detach (DDI_DETACH) capability
	and set the D_HOTPLUG in the cb_ops driver compatibility
	flag.

o 64 bit-ready:
	Future releases of Solaris will provide a 64-bit kernel.
	With Solaris 2.6, drivers can made 64-bit clean so they
	can easily be ported to a 64-bit environment in the future.
	Some of the sample drivers have been made 64-bit clean.
	Refer to appendix F, Writing Device Driver Guide for
	more information.

o kstat support:
	Solaris provides a general-purpose mechanism for drivers to
	export statistics to user-level monitoring and I/O
	statistics tools.  Refer to kstat(3K) and iostat(1M)
 
o PM/CPR support:
	The Solaris DDI provides interfaces for drivers to manage
	their device's power through the power management and
	checkpoint/resume framework.  Refer to chapter 8 of WDD.

o data access functions:
	For driver that directly control hardware devices, accessing
	the device through the data access functions is an important
	aspect of platform and architecture independence.  Refer to
	chapter 3, Data Access Functions and appendix B and C, WDD.

o DMA support:
	The DDI provides interfaces for drivers with DMA-capable
	devices to enable devices to perform high-speed I/O directly
	to and from system memory.  Refer to chapter 7, WDD.

o devmap support:
	Devmap provides a mechanism for drivers to support
	memory-mapped devices.  Refer to devmap(9E) and
	chapter 12 of WDD.

o platform support:
	The DDI for the most part provides platform-independence for
	drivers.  It is recommended that drivers be written to run
	on both sparc and x86 architectures wherever possible.
	Refer to WDD for hints on writing portable drivers.

o DDI compliant:
	Ddict is a source-level DDI interface compliance tool for
	drivers.  It warns about use of improper header files
	and non-DDI compliant interfaces.

o locklint clean:
	Locklint is a source-level lock analysis tool for drivers.
	It can detect unprotected critical sections of code and
	potential deadlock situations.  Refer to the DDK tools.

o explicit bus support:
	Drivers for devices on PCI boards or PCMCIA PC cards may
	need to use interfaces designed explicitly to support that
	particular bus.  Refer to chapter 2 of WDD for information
	on ISA, EISA, PCI and SBus.  For information on PCMCIA,
	refer to WPDD (Writing PCMCIA Device Drivers).

o high-level interrupts:
	A driver for a device whose interrupt maps to a level above
	the scheduler priority level must use a high-level interrupt
	to manage the device.  A device may use a high-level interrupt
	depending on the bus, configuration and/or platform.  A driver
	may choose not to support a device with a high-level interrupt
	but it must verify this so as not to compromise system operation.


Sample Drivers:

- ae -- Ethernet driver

	h/w:	AM79C970 PCnet Ethernet Controller, PCI device

	hotplug-ready		- no
	64 bit-ready		- no
	kstat support		- yes
	PM/CPR support		- no
	data access functions	- yes	
	dma support		- yes
	devmap support		- n/a
	platforms		- sparc, x86
	DDI compliant		- yes
	locklint		- no
	explicit bus support	- pci
	high-level interrupts	- no
	

- bst -- Sample Block SCSI Target driver

	h/w:	SCSI disk device

        hotplug-ready           - yes
        64 bit-ready            - no   
        kstat support           - no  
        PM/CPR support          - yes   
        data access functions	- n/a    
	dma support		- n/a
	devmap support		- n/a
	platforms		- sparc, x86
        DDI compliant           - yes
	locklint		- yes
	explicit bus support	- n/a
	high-level interrupts	- n/a


- cgsix -- this framebuffer driver is somewhat obsolete

	h/w:	cg6 color frame buffer, sbus device

        hotplug-ready           - no 
        64 bit-ready            - no   
        kstat support           - no   
        PM/CPR support          - no    
        data access functions	- no     
        dma support             - no 
        devmap support          - no 
	platforms		- sparc only
        DDI compliant           - no 
	locklint		- no
	explicit bus support	- n/a
	high-level interrupts	- no


- dma -- pseudo-code illustrating DDI DMA interfaces (obsolete)

	h/w:	hypothetical

        hotplug-ready           - no 
        64 bit-ready            - no   
        kstat support           - no   
        PM/CPR support          - no    
        data access functions	- no     
        dma support             - no 
        devmap support          - no 
	platforms		- sparc, x86
        DDI compliant           - no 
	locklint		- no
	explicit bus support	- n/a
	high-level interrupts	- n/a


- isp -- sample SCSI Host Bus Adapter driver
 
	h/w:	QLogics ISP1000 SCSI peripheral, sbus device
		QLogics ISP1020 SCSI peripheral, pci device

        hotplug-ready           - yes  
        64 bit-ready            - yes   
        kstat support           - no    
        PM/CPR support          - no    
        data access functions	- yes      
        dma support             - yes 
        devmap support          - n/a
	platforms		- sparc, x86
        DDI compliant           - yes  
	locklint		- yes
	explicit bus support	- pci
	high-level interrupts	- no


- p9000 -- sample color frame buffer driver

	h/w:	Weitek p9000 8-bit color frame buffer

        hotplug-ready           - no
        64 bit-ready            - no
        kstat support           - no
        PM/CPR support          - no
        data access functions	- yes
        dma support             - n/
        devmap support          - no
	platforms		- x86 only
        DDI compliant           - yes
	locklint		- no
	explicit bus support	- n/a
	high-level interrupts	- no


- pcepp -- PC Card parallel port driver

	h/w:	PCMCIA parallel port PC card

        hotplug-ready           - yes
        64 bit-ready            - no
        kstat support           - no
        PM/CPR support          - yes
        data access functions	- yes
        dma support             - no
        devmap support          - no
	platforms		- sparc, x86
        DDI compliant           - yes
	locklint		- no
	explicit bus support	- pcmcia
	high-level interrupts	- yes


- pcsram -- PC Card memory client driver

	h/w:	PCMCIA memory PC card

        hotplug-ready           - yes
        64 bit-ready            - no
        kstat support           - no
        PM/CPR support          - yes
        data access functions	- yes
        dma support             - no
        devmap support          - no
	platforms		- sparc, x86
        DDI compliant           - yes
	locklint		- no
	explicit bus support	- pcmcia
	high-level interrupts	- n/a


- pio -- sample programmed I/O driver

	h/w:	hypothetical

        hotplug-ready           - no
        64 bit-ready            - yes
        kstat support           - no
        PM/CPR support          - no
        data access functions	- yes
        dma support             - no
        devmap support          - no
	platforms		- sparc, x86
        DDI compliant           - yes
	locklint		- no
	explicit bus support	- n/a
	high-level interrupts	- no


- psli -- sample STREAMS multithreaded DLPI driver

	h/w:	not intended for any particular DLPI device

        hotplug-ready           - no
        64 bit-ready            - no
        kstat support           - no
        PM/CPR support          - no
        data access functions	- n/a
        dma support             - n/a
        devmap support          - n/a
	platforms		- sparc, x86
        DDI compliant           - yes
	locklint		- no
	explicit bus support	- n/a
	high-level interrupts	- no


- pvip -- sample color frame buffer driver

	h/w:	Weitek p9000 color frame buffer

        hotplug-ready           - no
        64 bit-ready            - no
        kstat support           - no
        PM/CPR support          - no
        data access functions	- yes
        dma support             - n/a
        devmap support          - n/a
	platforms		- sparc, x86
        DDI compliant           - yes
	locklint		- no
	explicit bus support	- pci
	high-level interrupts	- no


- ramdisk: sample driver providing a pseudo-disk device

	h/w:	uses kernel-mapped system memory

        hotplug-ready           - no
        64 bit-ready            - no
        kstat support           - no
        PM/CPR support          - n/a
        data access functions	- n/a
        dma support             - n/a
        devmap support          - n/a
	platforms		- sparc, x86
        DDI compliant           - yes
	locklint		- no
	explicit bus support	- n/a
	high-level interrupts	- no


- sst -- Simple SCSI Target driver

	h/w:	must be customized for a particular type of SCSI device

        hotplug-ready           - yes
        64 bit-ready            - yes
        kstat support           - no
        PM/CPR support          - yes
        data access functions	- n/a
        dma support             - n/a
        devmap support          - n/a
	platforms		- sparc, x86
        DDI compliant           - yes
	locklint		- yes
	explicit bus support	- n/a
	high-level interrupts	- n/a
 

- tblt -- sample tablet STREAMS module

	h/w:	tablet graphics input device

        hotplug-ready           - no
        64 bit-ready            - no
        kstat support           - no
        PM/CPR support          - no
        data access functions	- n/a
        dma support             - n/a
        devmap support          - n/a
	platforms		- sparc, x86
        DDI compliant           - yes
	locklint		- no
	explicit bus support	- n/a
	high-level interrupts	- n/a
