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


1. Overview of the SunOS Kernel	1
..What is the Kernel?	1
..Multithreading	2
..Virtual Memory	2
....Virtual Addresses	2
....Address Spaces	2
..Special Files	3
..Dynamic Loading of Kernel Modules	3
..Overview of the Solaris 2.x DDI/DKI	3
....Device Tree	5
....Example Device Tree	6
2. Hardware Overview	9
..SPARC Processor Issues	9
....Data Alignment	9
....Structure Member Alignment	10


....Byte Ordering	10
....Register Windows	10
....Floating Point Operations	11
.... Multiply and Divide Instructions	11
....SPARC Architecture Manual	11
..x86 Processor Issues	11
....Data Alignment	11
....Structure Member Alignment	11
....Byte Ordering	12
....Floating Point Operations	12
....x86 Architecture Manuals	12
..System Memory Model	12
....Store Buffers	12
..SPARC Memory Model	13
..Bus Architectures	14
....Device Identification	14
....Device Addressing	15
....Interrupts	15
..Bus Specifics	16
....SBus	16
....VMEbus	18
....x86 Buses	21
....MCA Bus	24
..Device Issues	24


....Timing-Critical Sections	24
....Delays	25
....Internal Sequencing Logic	25
....Interrupt Issues	25
....Byte Ordering	26
..The PROM on SPARC Machines	26
....Open Boot PROM 2.x	27
..Reading and Writing	32
....The Sun Monitor	34
3. Overview of SunOS Device Drivers	41
..What is a Device Driver?	41
..Types of Device Drivers	42
....Block Device Drivers	42
....Standard Character Device Drivers	42
....STREAMS Drivers	44
..Device Issues	44
....Accessing Device Registers	44
....Example Device Registers	45
....Device Register Structure	46
..Driver Interfaces	48
....Entry Points	48
..Callback functions	51
..Interrupt Handling	52
..Driver Context	52


..Printing Messages	53
..Dynamic Memory Allocation	54
..Software State Management	55
....State Structure	55
....State Management Routines	56
..Properties	57
..Driver Layout	60
....Header Files	60
..The C Language and Compiler Modes	65
....Compiler Modes	66
....Function Prototypes	66
....New Keywords	66
4. Multithreading	71
..Threads	71
....User Threads	71
....Kernel Threads	72
..Multiprocessing Changes Since SunOS 4.x	73
..Locking Primitives	74
....Storage Classes of Driver Data	74
....State Structure	75
....Mutual-Exclusion Locks	75
....Readers/Writer Locks	77
....Semaphores	77
..Thread Synchronization	77


....Bus-Interrupt Levels	106
....High-Level Interrupts	107
..Types of Interrupts	107
....Vectored Interrupts	107
....Polled Interrupts	108
....Software Interrupts	108
..Registering Interrupts	109
..Responsibilities of an Interrupt Handler	111
..State Structure	113
..Handling High-Level Interrupts	113
....Example	114
7. DMA	119
..The DMA Model	119
..Types of Device DMA	122
..DMA and DVMA	122
..Handles, Windows, Segments and Cookies	123
..DMA Operations	124
....Device limitations	126
....Object Locking	131
....Allocating DMA Resources	131
....Burst Sizes	135
....Programming the DMA Engine	136
....Freeing the DMA Resources	137
..Cancelling DMA Callbacks	138


..Synchronizing Memory Objects	140
....Cache	140
....`ddi_dma_sync( )`	142
..Allocating Private DMA Buffers	143
....`ddi_iopb_alloc()`	143
....`ddi_mem_alloc( )`	144
....`ddi_dma_devalign( )`	145
8. Drivers for Character Devices	147
..Entry Points	147
..Autoconfiguration	148
..Controlling Device Access	149
..I/O Request Handling	151
....User Addresses	151
....Vectored I/O	152
....Driver Operations	154
..Mapping Device Memory	159
..Multiplexing I/O on File Descriptors	162
..Miscellaneous I/O Control	165
9. Drivers for Block Devices	169
..File I/O	169
..State Structure	170
..Entry Points	170
..Autoconfiguration	171
..Controlling Device Access	173


..Data Transfers	176
.....`strategy( )`	176
.....The `buf` Structure	176
..Synchronous Data Transfers	178
..Asynchronous Data Transfers	182
..Miscellaneous Entry Points	186
.....`dump( )`	186
.....`print( )`	188
10. SCSI Target Drivers	189
..Overview	189
..Reference Documents	190
..Sun Common SCSI Architecture Overview	191
.....General Flow of Control	192
..SCSA Functions	194
..SCSA Compatibility Functions	195
..SCSI Target Drivers	195
.....Hardware Configuration File	195
.....Declarations and Data Structures	196
.....Autoconfiguration	199
.....Resource Allocation	205
..Building and Transporting a Command	208
.....Building a Command	208
.....Transporting a Command	209
.....Command Completion	210


11. Device Context Management	213
..What Is A Device Context?	213
..Context Management Model	213
.....Multiprocessor Considerations	215
..Context Management Operation	216
.....State Structure	216
.....Declarations and Data Structures	217
.....Associating Devices with User Mappings	217
.....Managing Mapping Accesses	219
.....Device Context Management Entry Points	220
12. Loading and Unloading Drivers	225
..Preparing for Installation	225
.....Module Naming	225
.....Compile and Link the Driver	226
.....Write a Hardware Configuration File	226
..Installing and Removing Drivers	227
.....Copy the Driver to a Module Directory	227
.....Run `add_drv`(1M)	227
..Removing the Driver	228
..Loading Drivers	228
..Getting the Driver Module's ID	228
..Unloading Drivers	229
13. Debugging	231
..Machine Configuration	231


.....Setting Up a `tip`(1) Connection	231
.....Preparing for the Worst	233
..Coding Hints	236
.....Process Layout	237
.....System Support	237
.....Conditional Compilation and Variables	239
.....The Optimizer and `volatile`	241
..Using Existing Drivers	241
..Debugging Tools	243
.....`/etc/system`	243
.....`modload` and `modunload`	244
.....Saving System Core Dumps	245
.....`adb` and `kadb`	246
.....Example: `adb` on a Core Dump	257
.....Example: `kadb` on a Deadlocked Thread	260
..Testing	263
.....Configuration Testing	263
.....Functionality Testing	264
.....Error Handling	264
.....Stress, Performance, and Interoperability Testing	265
.....DDI/DKI Compliance Testing	265
.....Installation and Packaging Testing	266
.....Testing Specific Types of Drivers	266
A. Converting a Device Driver to SunOS 5.4	269


..Before Starting the Conversion	269
.....Review Existing Functionality	269
.....Read the Manual	269
.....ANSI C	270
..Development Environment	270
.....DDI/DKI	270
.....Things to Avoid	270
.....System V Release 4	271
.....Development Tools	271
.....Debugging Tools	272
.....ANSI C	272
.....Header Files	273
..Overview of Changes	273
.....Autoconfiguration	273
.....`/devices`	274
.....`/dev`	275
.....Multithreading	275
.....Locking	276
.....Interrupts	280
.....DMA	281
..Conversion Notes	282
.....SunOS 4.1.x to SunOS 5.4 Differences	287
B. Advanced Topics	295
..Multithreading	295


.....Lock Granularity	295
.....Avoiding Unnecessary Locks	296
.....Locking Order	296
.....Scope of a Lock	297
.....Potential Panics	298
..Sun Disk Device Drivers	299
.....Disk I/O Controls	299
.....Disk Performance	300
..SCSA	301
.....Global Data Definitions	301
.....Tagged Queueing	302
.....Untagged Queueing	303
.....Auto-Request-Sense Mode	303
C. Summary of Solaris 2.4 DDI/DKI Services	307
..`buf`(9S) Handling	308
..Copying Data	311
..Device Access	312
..Device Configuration	313
..Device Information	314
..DMA Handling	315
..Flow of Control	322
..Interrupt Handling	322
..Kernel Statistics	324
..Memory Allocation	326


...Polling	327
...Printing System Messages	327
...Process Signaling	328
...Properties	329
...Register and Memory Mapping	331
...I/O Port Access	333
...SCSI and SCSA	334
...Soft State Management	341
...String Manipulation	342
...System Information	344
...Thread Synchronization	344
...Timing	349
...`uio`(9S) Handling	350
...Utility Functions	350
D. Sample Driver Source Code Listings	355
Index	357