............................Contents


Preface	xix
1. SunOS Kernel and Device Tree	1
...What Is the Kernel?	1
......Multithreading Considerations	2
......Virtual Memory	2
......Special Files	2
......Dynamic Loading of Kernel Modules	3
...Overview of the Solaris 2.x DDI/DKI	3
...Device Tree	4
......Example Device Tree	6
......Displaying the Device Tree	7
......Binding a Driver to a Device Node	9
2. Hardware Overview	13
...SPARC Processor Issues	13
......SPARC Data Alignment	13


......SPARC Structure Member Alignment	14
......SPARC Byte Ordering	14
......SPARC Register Windows	14
......SPARC Floating-Point Operations	15
...... SPARC Multiply and Divide Instructions	15
......SPARC Architecture Manual	15
...x86 Processor Issues	15
......x86 Data Alignment	15
......x86 Structure Member Alignment	16
......x86 Byte Ordering	16
......x86 Floating-Point Operations	16
......x86 Architecture Manuals	16
...Store Buffers	16
...System Memory Model	17
......Total Store Ordering (TSO)	17
......Partial Store Ordering (PSO)	18
...Bus Architectures	18
......Device Identification	18
......Interrupts	19
...Bus Specifics	19
......PCI Local Bus	19
......PCI Address Domain	21
......SBus	24
......VMEbus	27


......ISA Bus	28
......EISA Bus	29
......MCA Bus	30
...Device Issues	31
......Timing-Critical Sections	31
......Delays	31
......Internal Sequencing Logic	31
......Interrupt Issues	32
......Byte Ordering	32
......Device Attribute Representations	34
...PROM on SPARC Machines	34
......Open Boot PROM 3.x	35
......Reading and Writing	39
3. Overview of SunOS Device Drivers	43
...What Is a Device Driver?	43
...Types of Device Drivers	44
......Block Device Drivers	44
......Standard Character Device Drivers	44
......STREAMS Drivers	46
...Bus Address Spaces	46
......Address Mapping Setup	47
......Data Access Functions	49
......Example Device Registers	51
......Device Register Structure	52


...Driver Interfaces	55
......Entry Points	55
......Driver Structure Overview	57
...Callback Functions	59
...Interrupt Handling	59
......Device-Interrupt Cookies	60
......Block-Interrupt Cookies	60
...Driver Context	60
......User Context	61
......Kernel Context	61
......Interrupt Context	61
......High-level Interrupt Context	61
...Printing Messages	61
...Dynamic Memory Allocation	62
...Software State Management	63
......Software State Structure	63
......Software State Management Routines	64
...Properties	65
......`prop_op( )`	67
...Driver Layout	69
......Header Files	69
......Source Files	69
......Configuration Files	70
...64-Bit-Safe Device Drivers	70


...C Language and Compiler Modes	70
......Compiler Modes	70
......Function Prototypes	71
......Keywords	71
4. Multithreading	75
...Threads	75
......User Threads	75
......Kernel Threads	76
...Multiprocessing Changes Since the SunOS 4.x System	77
...Locking Primitives	78
......Storage Classes of Driver Data	78
......State Structure	79
......Mutual-Exclusion Locks	79
......Readers/Writer Locks	81
......Semaphores	81
...Thread Synchronization	81
......Condition Variables	81
......`cv_timedwait( )`	85
......`cv_wait_sig( )`	86
......`cv_timedwait_sig( )`	87
...Choosing a Locking Scheme	87
5. Autoconfiguration	89
...Autoconfiguration Overview	89
...Additions to State Structure	89


...Driver Loading and Configuration	90
...Data Structures	91
......`modlinkag`e()	91
......`modldrv()`	91
......`dev_ops()`	92
......`cb_ops`	92
...Loadable Driver Interface	94
...Device Configuration	96
......Instance Numbers	96
......`identify( )`	97
......`probe( )`	97
......`attach( )`	101
......`detach( )`	107
......`getinf`o( )	110
6. Interrupt Handlers	113
...Interrupt Handler Overview	113
......Interrupt Specification	114
......Interrupt Number	114
......Interrupt Block Cookies	114
......Bus Interrupt Levels	115
......High-Level Interrupts	115
...Types of Interrupts	115
......Vectored Interrupts	116
......Polled Interrupts	116


......Software Interrupts	116
...Registering Interrupts	117
...Responsibilities of an Interrupt Handler	119
...State Structure	121
...Handling High-Level Interrupts	122
......High-Level Interrupt Handling Example	123
7. DMA	127
...DMA Model	127
...Types of Device DMA	128
...DMA and DVMA	129
...Handles, Windows, and Cookies	130
......Scatter-Gather	130
...DMA Operations	130
......Bus-Master DMA	130
......First-Party DMA	131
......Third-Party DMA	132
......DMA Attributes	132
......Object Locking	137
......Allocating a DMA Handle	137
......Allocating DMA Resources	138
......Burst Sizes	141
......Programming the DMA Engine	142
......Freeing the DMA Resources	143
......Freeing the DMA Handle	145


...Canceling DMA Callbacks	145
...Synchronizing Memory Objects	147
......Cache	147
......`ddi_dma_sync( )`	148
...DMA Windows	149
...Allocating Private DMA Buffers	153
8. Power Management	155
...Power Management Overview	155
......Device Power Management	156
......System Power Management	156
...Power Management Additions to the State Structure	157
...Device Power Management Model	157
......Components	157
......Idleness	158
......Power Levels	158
......Dependency	158
......Policy	159
......Device Power Management Interfaces	159
......Entry Points Used by Device Power Management	162
...System Power Management Model	166
......Autoshutdown Threshold	166
......Busy State	166
......Hardware State	167
......Policy	167


......Entry Points Used by System Power Management	167
......Device Access	171
...Power Management Flow of Control	173
......Device Power Management Flow of Control for Component
........Zero	173
......Device Power Manangement Flow of Control for Components
........Other Than Component Zero	174
9. Drivers for Character Devices	177
...Character Driver Structure Overview	177
......Character Driver Device Access	177
...Entry Points	179
...Autoconfiguration	180
...Controlling Device Access	181
...I/O Request Handling	183
......User Addresses	183
......Vectored I/O	184
......Synchronous Versus Asynchronous I/O	186
......Data Transfer Methods	187
...Mapping Device Memory	194
...Multiplexing I/O on File Descriptors	195
...Miscellaneous I/O Control	198
......I/O Control Support for 64-Bit Capable Device Drivers	201
10. Drivers for Block Devices	205
...Block Driver Structure Overview	205
......Block Driver Device Access	205


...File I/O	207
...State Structure	207
...Entry Points	207
...Autoconfiguration	208
...Controlling Device Access	211
...Data Transfers	214
......`strategy( )`	214
......`buf` Structure	214
...Synchronous Data Transfers	216
...Asynchronous Data Transfers	220
...Miscellaneous Entry Points	225
......`dump( )`	225
......`print( )`	226
11. Mapping Device or Kernel Memory	227
...Memory Mapping Operations	227
...Exporting the Mapping	227
......Associating Device Memory With User Mappings	228
......Associating Kernel Memory With User Mappings	231
12. Device Context Management	237
...What Is a Device Context?	237
...Context Management Model	237
......Multiprocessor Considerations	239
...Context Management Operation	240
......Context Management Additions to the State Structure	240


......Declarations and Data Structures	241
......Associating User Mappings With Driver Notifications	241
......Managing Mapping Accesses	243
......Device Context Management Entry Points	244
13. SCSI Target Drivers	253
...SCSI Target Driver Overview	253
...Reference Documents	254
...Sun Common SCSI Architecture Overview	255
......General Flow of Control	256
...SCSA Functions	258
...SCSA Compatibility Functions	259
...SCSI Target Drivers	259
......Hardware Configuration File	259
......Declarations and Data Structures	260
......Autoconfiguration	263
......Resource Allocation	270
...Building and Transporting a Command	272
......Building a Command	273
......Setting Target Capabilities	274
......Transporting a Command	274
......Command Completion	275
......Reuse of Packets	277
14. SCSI Host Bus Adapter Drivers	281
...SCSI HBA Driver Overview	281


......SCSA Interface	282
......HBA Transport Layer	283
...SCSA HBA Interfaces	284
......SCSA HBA Entry Point Summary	284
......SCSA HBA Data Structures	284
......Per-Target Instance Data	290
......Transport Structure Cloning (optional)	292
......SCSA HBA Functions	294
...HBA Driver Dependency and Configuration Issues	294
......HBA Configuration Properties	295
......Declarations and Structures	296
......Module Initialization Entry Points	298
......Autoconfiguration Entry Points	301
...SCSA HBA Entry Points	305
......Target Driver Instance Initialization	307
......Resource Allocation	309
......Command Transport	320
......Capability Management	328
......Abort and Reset Management	334
...Driver Installation	336
......Hardware Configuration File	336
......Installing the Driver	336
......x86 Target Driver Configuration Properties	337
15. Loading and Unloading Drivers	339


...Preparing for Installation	339
......Module Naming	339
......Compiling and Linking the Driver	340
......Writing a Hardware Configuration File	340
...Installing and Removing Drivers	341
......Copying the Driver to a Module Directory	341
......Running `add_drv`(1M)	342
...Removing the Driver	342
...Loading Drivers	342
...Getting the Driver Module's ID	343
...Unloading Drivers	343
16. Debugging	345
...Machine Configuration	345
......Setting Up a `tip`(1) Connection	345
......Preparing for Disasters	348
...Coding Hints	351
......Process Layout for Sun4m, Sun4c, Sun4d, and x86 Platforms	351
......Process Layout for Sun4u Platforms	352
......System Support	353
......Conditional Compilation and Variables	354
......`volatile` and `_depends_on`	356
...Debugging Tools	356
......`/etc/system`	356
......`moddebug`	357


......`modload` and `modunload`	358
......Saving System Core Dumps	358
......`adb` and `kadb`	360
......Example: `adb` on a Core Dump	373
......Example: `kadb` on a Deadlocked Thread	376
...Testing	379
......Configuration Testing	379
......Functionality Testing	380
......Error Handling	381
......Stress, Performance, and Interoperability Testing	381
......DDI/DKI Compliance Testing	382
......Installation and Packaging Testing	382
......Testing Specific Types of Drivers	383
A. Converting a SunOS 4.x Device Driver to SunOS 5.6	385
B. Interface Transition List	413
C. Summary of Solaris 2.6 DDI/DKI Services	417
D. Sample Driver Source Code Listings	479
E. Driver Code Layout Structure	481
F. Making a Device Driver 64-Bit Ready	487
G. Advanced Topics	499