Writing Device Drivers for Solaris

8/9/2019 Writing Device Drivers for Solaris

1/615


2/615

Copyright2008 SunMicrosystems, Inc. 4150 Network Circle, Santa Clara,CA 95054 U.S.A. Allrightsreserved.

SunMicrosystems, Inc. hasintellectual property rightsrelatingto technology embodied in theproduct that is describedin this document.In particular, andwithoutlimitation, these intellectualpropertyrights mayinclude oneor more U.S. patents or pending patentapplications in theU.S. andin other countries.

U.S. Government Rights Commercial sotware. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicableprovisionso theFARand itssupplements.

This distribution may include materials developed by thirdparties.Partso theproduct maybe derived rom Berkeley BSDsystems, licensed rom theUniversity o Caliornia. UNIXis a registered trademarkin theU.S. andothercountries, exclusivelylicensed through X/OpenCompany, Ltd.

Sun, SunMicrosystems, theSun logo, theSolaris logo, theJavaCofeeCup logo, docs.sun.com,Java,and Solaris aretrademarks or registered trademarks o SunMicrosystems, Inc. or itssubsidiariesin theU.S. andothercountries. AllSPARC trademarks areused under license andare trademarks or registered trademarks oSPARCInternational,Inc. in theU.S. andothercountries. Products bearing SPARCtrademarks arebasedupon an architecturedeveloped by SunMicrosystems, Inc.

The OPENLOOKandSunTM GraphicalUser Interacewas developedby SunMicrosystems, Inc. orits users andlicensees. Sunacknowledges thepioneering efortso Xerox in researching anddeveloping theconcept o visualor graphicaluser interaces orthe computer industry.Sun holds a non-exclusive licenseromXeroxtotheXeroxGraphical UserInterace,whichlicense also coversSun'slicenseeswho implementOPEN LOOK GUIs andotherwise complywith Sun's written licenseagreements.

Products covered by andinormationcontained in this publication arecontrolled by U.S. ExportControl laws andmay be subjectto theexport or importlaws inother countries. Nuclear,missile,chemicalor biological weapons or nuclear maritime enduses or endusers,whether director indirect,are strictly prohibited. Exportor reexport to countriessubject to U.S. embargo or to entities identiedon U.S. exportexclusion lists,including, butnot limited to,the deniedpersons andspeciallydesignated nationals lists is strictly prohibited.

DOCUMENTATION IS PROVIDED AS IS AND ALL EXPRESS OR IMPLIEDCONDITIONS, REPRESENTATIONSAND WARRANTIES, INCLUDINGANYIMPLIEDWARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED,EXCEPT TOTHEEXTENTTHAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.

Copyright2008 SunMicrosystems, Inc. 4150 Network Circle, Santa Clara,CA 95054 U.S.A. Tous droitsrservs.

SunMicrosystems, Inc. dtient lesdroits de propritintellectuellerelatis la technologie incorpore dans le produit quiest dcritdans ce document.En particulier,

et ce sans limitation, cesdroits de propritintellectuellepeuvent inclure un ou plusieursbrevets amricains ou desapplications de breveten attente auxEtats-Uniset dans d'autres pays.

Cette distribution peut comprendredes composants dveloppspar des tierces personnes.

Certainescomposants de ce produit peuvent tre drives du logiciel Berkeley BSD, licencispar l'Universitde Caliornie. UNIXest unemarque dpose auxEtats-Uniset dans d'autres pays; elle estlicencie exclusivementpar X/OpenCompany,Ltd.

Sun, SunMicrosystems, le logo Sun, le logo Solaris, le logo Java Cofee Cup, docs.sun.com,Java et Solaris sont desmarques de abrique ou desmarques dposes deSunMicrosystems, Inc., ou sesliales, auxEtats-Uniset dans d'autres pays. Toutesles marques SPARC sont utilisessous licence et sontdes marques de abrique oudesmarques dposes de SPARCInternational,Inc. auxEtats-Uniset dans d'autres pays. Les produits portant lesmarques SPARCsont bass surune architecturedveloppepar Sun Microsystems, Inc.

L'interace d'utilisation graphiqueOPEN LOOK et Suna tdveloppe parSun Microsystems, Inc. pour ses utilisateurset licencis. Sunreconnat leseforts de

pionniersde Xerox pour la rechercheet le dveloppement du concept desinteraces d'utilisation visuelle ou graphiquepour l'industrie de l'inormatique.Sun dtientunelicence nonexclusive de Xerox surl'interaced'utilisation graphiqueXerox, cette licence couvrant galementles licencisde Sunqui mettent en place l'interaced'utilisation graphiqueOPEN LOOK et qui, en outre,se conorment auxlicencescrites de Sun.

Les produits quiont l'objet de cette publication et lesinormations qu'il contient sontrgispar la legislation amricaine en matire de contrle desexportations etpeuvent tre soumisau droit d'autres pays dans le domaine desexportations et importations. Les utilisationsnales, ou utilisateursnaux, pour desarmesnuclaires,des missiles, des armeschimiques ou biologiquesou pour le nuclaire maritime, directementou indirectement, sont strictementinterdites. Les exportations ourexportations vers despays sous embargo desEtats-Unis,ou vers desentits gurantsur leslistes d'exclusion d'exportation amricaines, y compris, mais de manirenonexclusive, la liste de personnesqui ontobjet d'un ordre de ne pasparticiper,d'uneaondirecte ou indirecte, auxexportations desproduitsou desservicesquisont rgispar la legislationamricaine en matire de contrle des exportations et la listede ressortissants spciquement designs, sont rigoureusement interdites.

LA DOCUMENTATION EST FOURNIE "EN L'ETAT" ET TOUTES AUTRES CONDITIONS, DECLARATIONSET GARANTIES EXPRESSES OU TACITESSONT FORMELLEMENT EXCLUES, DANS LA MESUREAUTORISEE PAR LA LOIAPPLICABLE, Y COMPRISNOTAMMENTTOUTE GARANTIEIMPLICITERELATIVE A LA QUALITE MARCHANDE, A L'APTITUDE A UNEUTILISATION PARTICULIEREOU A L'ABSENCE DE CONTREFACON.

080821@20795


3/615

Contents

Preace ...................................................................................................................................................31

Part I Designing Device Drivers orthe Solaris Platorm .........................................................................37

1 Overview o Solaris DeviceDrivers ................................................................................................... 39

Device Driver Basics ........................................................................................................................... 39

What Is a Device Driver? ............................................................................................................. 39What Is a Device Driver Entry Point? ........................................................................................ 40

Device Driver Entry Points ................................................................................................................. 41

Entry Points Common to All Drivers ........................................................................................ 41

Entry Points or Block Device Drivers ....................................................................................... 44

Entry Points or Character Device Drivers ............................................................................... 45

Entry Points or STREAMS Device Drivers .............................................................................. 46

Entry Points or Memory Mapped Devices ............................................................................... 47

Entry Points or the Generic LAN Device (GLD) Driver ........................................................ 47

Entry Points or SCSI HBA Drivers ........................................................................................... 48

Entry Points or PC Card Drivers ............................................................................................... 50

Considerations in Device Driver Design .......................................................................................... 50

DDI/DKI Facilities ....................................................................................................................... 50

Driver Context ............................................................................................................................. 52Returning Errors .......................................................................................................................... 53

Dynamic Memory Allocation ..................................................................................................... 53

Hotplugging .................................................................................................................................. 54

2 Solaris Kernel and DeviceTree .......................................................................................................... 55

What Is the Kernel? ............................................................................................................................. 55Multithreaded Execution Environment .................................................................................... 57

3


4/615

Virtual Memory ........................................................................................................................... 57

Devices as Special Files ................................................................................................................ 57

DDI/DKI Interaces ..................................................................................................................... 58Overview o the Device Tree .............................................................................................................. 59

Device Tree Components ........................................................................................................... 59

Displaying the Device Tree ......................................................................................................... 60

Binding a Driver to a Device ....................................................................................................... 63

3 Multithreading .....................................................................................................................................67Locking Primitives .............................................................................................................................. 67

Storage Classes o Driver Data ................................................................................................... 67

Mutual-Exclusion Locks ............................................................................................................. 68

Readers/Writer Locks .................................................................................................................. 69

Semaphores ................................................................................................................................... 69

Thread Synchronization ..................................................................................................................... 70Condition Variables in Thread Synchronization ..................................................................... 70

cv_wait() and cv_timedwait() Functions ............................................................................. 72

cv_wait_sig() Function ............................................................................................................ 73

cv_timedwait_sig() Function ................................................................................................. 74

Choosing a Locking Scheme .............................................................................................................. 74

Potential Locking Pitalls ............................................................................................................ 74

Threads Unable to Receive Signals ............................................................................................ 75

4 Properties .............................................................................................................................................77

Device Properties ............................................................................................................................... .. 77

Device Property Names ............................................................................................................... 78

Creating and Updating Properties ............................................................................................. 78

Looking Up Properties ................................................................................................................ 79

prop_op() Entry Point ................................................................................................................ 80

5 Managing Events andQueueingTasks ............................................................................................ 83

Managing Events ................................................................................................................................. 83

Introduction to Events ................................................................................................................. 83Using ddi_log_sysevent() to Log Events .............................................................................. 85

Contents

Writing Device Drivers September 20084


5/615


6/615

Mapping Setup Example ........................................................................................................... 121

Device Access Functions ................................................................................................................... 122

Alternate Device Access Interaces .......................................................................................... 124

8 Interrupt Handlers .............................................................................................................................125

Interrupt Handler Overview ............................................................................................................ 125

Device Interrupts ............................................................................................................................... 126

High-Level Interrupts ................................................................................................................ 126

Legacy Interrupts ....................................................................................................................... 127Standard and Extended Message-Signaled Interrupts .......................................................... 127

Sotware Interrupts .................................................................................................................... 128

DDI Interrupt Functions .................................................................................................................. 129

Interrupt Capability Functions ................................................................................................ 129

Interrupt Initialization and Destruction Functions ............................................................... 129

Priority Management Functions .............................................................................................. 130

Sot Interrupt Functions ............................................................................................................ 130

Interrupt Function Examples ................................................................................................... 131

Registering Interrupts ....................................................................................................................... 132

Registering Legacy Interrupts ................................................................................................... 132

Registering MSI Interrupts ....................................................................................................... 135

Interrupt Handler Functionality ...................................................................................................... 139

Handling High-Level Interrupts ...................................................................................................... 140High-Level Mutexes ................................................................................................................... 141

High-Level Interrupt Handling Example ................................................................................ 141

9 Direct Memory Access(DMA) ...........................................................................................................147

DMA Model ..................................................................................................................................... .. 147

Types o Device DMA ....................................................................................................................... 148Bus-Master DMA ....................................................................................................................... 148

Third-Party DMA ...................................................................................................................... 148

First-Party DMA ........................................................................................................................ 149

Types o Host Platorm DMA .......................................................................................................... 149

DMA Sotware Components: Handles, Windows, and Cookies ................................................. 149

DMA Operations ............................................................................................................................... 150

Perorming Bus-Master DMA Transers ................................................................................ 150

Contents



7/615

Perorming First-Party DMA Transers .................................................................................. 151

Perorming Third-Party DMA Transers ................................................................................ 151

DMA Attributes ......................................................................................................................... 151Managing DMA Resources .............................................................................................................. 155

Object Locking ................................................................................................................... ........ 155

Allocating a DMA Handle ........................................................................................................ 155

Allocating DMA Resources ...................................................................................................... 156

Determining Maximum Burst Sizes ........................................................................................ 159

Allocating Private DMA Bufers .............................................................................................. 159

Handling Resource Allocation Failures ................................................................................... 161

Programming the DMA Engine ............................................................................................... 162

Freeing the DMA Resources ..................................................................................................... 163

Freeing the DMA Handle .......................................................................................................... 164

Canceling DMA Callbacks ........................................................................................................ 164

Synchronizing Memory Objects .............................................................................................. 166

DMA Windows ...................................................................................................................... ............ 168

10 Mapping Deviceand Kernel Memory .............................................................................................171

Memory Mapping Overview ............................................................................................................ 171

Exporting the Mapping ............................................................................................................ ......... 171

The segmap(9E) Entry Point ..................................................................................................... 171

The devmap(9E) Entry Point ..................................................................................................... 174Associating Device Memory With User Mappings ....................................................................... 175

Associating Kernel Memory With User Mappings ....................................................................... 177

Allocating Kernel Memory or User Access ............................................................................ 177

Exporting Kernel Memory to Applications ............................................................................ 179

Freeing Kernel Memory Exported or User Access ................................................................ 181

11 Device ContextManagement ..........................................................................................................183

Introduction to Device Context ....................................................................................................... 183

What Is a Device Context? ........................................................................................................ 183

Context Management Model .................................................................................................... 183

Context Management Operation .................................................................................................... 185

devmap_callback_ctl Structure ............................................................................................. 185

Entry Points or Device Context Management ...................................................................... 186

Contents

7


8/615

Associating User Mappings With Driver Notications ........................................................ 194

Managing Mapping Accesses ................................................................................................... 195

12 Power Management ..........................................................................................................................197

Power Management Framework ..................................................................................................... 197

Device Power Management ...................................................................................................... 198

System Power Management ...................................................................................................... 198

Device Power Management Model ................................................................................................. 199

Power Management Components ........................................................................................... 199Power Management States ........................................................................................................ 200

Power Levels ............................................................................................................................... 200

Power Management Dependencies ......................................................................................... 201

Automatic Power Management or Devices ........................................................................... 202

Device Power Management Interaces .................................................................................... 203

power() Entry Point .................................................................................................................. 204

System Power Management Model ................................................................................................. 207

Autoshutdown Threshold ......................................................................................................... 207

Busy State .................................................................................................................................. .. 208

Hardware State ........................................................................................................................... 208

Automatic Power Management or Systems ........................................................................... 208

Entry Points Used by System Power Management ................................................................ 208

Power Management Device Access Example ................................................................................. 213Power Management Flow o Control .............................................................................................. 214

Changes to Power Management Interaces .................................................................................... 215

13 Hardening Solaris Drivers ................................................................................................................217

Sun Fault Management Architecture I/O Fault Services .............................................................. 217

What Is Predictive Sel-Healing? .............................................................................................. 218Solaris Fault Manager ................................................................................................................ 219

Error Handling ........................................................................................................................... 222

Diagnosing Faults ...................................................................................................................... 237

Event Registry ............................................................................................................................. 238

Glossary ..................................................................................................................................... .. 238

Resources .................................................................................................................................... 239

Deensive Programming Techniques or Solaris Device Drivers ................................................ 240

Contents



9/615

Using Separate Device Driver Instances ................................................................................. 240

Exclusive Use o DDI Access Handles ..................................................................................... 240

Detecting Corrupted Data ........................................................................................................ 241DMA Isolation ............................................................................................................................ 242

Handling Stuck Interrupts ........................................................................................................ 242

Additional Programming Considerations .............................................................................. 243

Driver Hardening Test Harness ....................................................................................................... 245

Fault Injection ............................................................................................................................ 246

Setting Up the Test Harness ...................................................................................................... 247

Testing the Driver ...................................................................................................................... 248

Using Scripts to Automate the Test Process ........................................................................... 250

14 LayeredDriver Interace (LDI) .........................................................................................................253

LDI Overview .......................................................................................................................... ........... 253

Kernel Interaces ..................................................................................................................... ........... 254Layered Identiers Kernel Device Consumers .................................................................... 254

Layered Driver Handles Target Devices .............................................................................. 255

LDI Kernel Interaces Example ................................................................................................ 259

User Interaces ........................................................................................................................ ........... 272

Device Inormation Library Interaces .................................................................................... 272

Print System Conguration Command Interaces ................................................................ 274

Device User Command Interaces ........................................................................................... 277

Part II Designing Specifc Kinds o Device Drivers .................................................................................. 279

15 Drivers orCharacter Devices ..........................................................................................................281

Overview o the Character Driver Structure .................................................................................. 281Character Device Autoconguration .............................................................................................. 283

Device Access (Character Drivers) .................................................................................................. 284

open() Entry Point (Character Drivers) ................................................................................. 284

close() Entry Point (Character Drivers) ............................................................................... 286

I/O Request Handling ....................................................................................................................... 286

User Addresses ........................................................................................................................... 286

Vectored I/O ...................................................................................................................... ......... 287

Contents

9


10/615

Diferences Between Synchronous and Asynchronous I/O ................................................. 289

Data Transer Methods ............................................................................................................. 289

Mapping Device Memory ................................................................................................................. 296Multiplexing I/O on File Descriptors .............................................................................................. 297

Miscellaneous I/O Control ............................................................................................................... 299

ioctl() Entry Point (Character Drivers) ............................................................................... 299

I/O Control Support or 64-Bit Capable Device Drivers ....................................................... 302

Handling copyout() Overow ................................................................................................ 304

32-bit and 64-bit Data Structure Macros ........................................................................................ 305

How Do the Structure Macros Work? ..................................................................................... 306

When to Use Structure Macros ................................................................................................ 306

Declaring and Initializing Structure Handles ......................................................................... 306

Operations on Structure Handles ............................................................................................ 307

Other Operations ....................................................................................................................... 308

16 Drivers or Block Devices ..................................................................................................................309

Block Driver Structure Overview .................................................................................................... 309

File I/O ....................................................................................................................... ......................... 310

Block Device Autoconguration ..................................................................................................... 311

Controlling Device Access ............................................................................................................... 313

open() Entry Point (Block Drivers) ......................................................................................... 313

close() Entry Point (Block Drivers) ....................................................................................... 314

strategy() Entry Point ............................................................................................................ 315

buf Structure ........................................................................................................................... ... 316

Synchronous Data Transers (Block Drivers) ................................................................................ 318

Asynchronous Data Transers (Block Drivers) ............................................................................. 321

Checking or Invalid buf Requests ........................................................................................... 322

Enqueuing the Request .............................................................................................................. 322Starting the First Transer ......................................................................................................... 323

Handling the Interrupting Device ............................................................................................ 325

dump() and print() Entry Points ................................................................................................... 326

dump() Entry Point (Block Drivers) ......................................................................................... 326

print() Entry Point (Block Drivers) ....................................................................................... 327

Disk Device Drivers .......................................................................................................................... 327

Diskioctls ............................................................................................................................ ..... 327

Contents



11/615

Disk Perormance ...................................................................................................................... 328

17 SCSITarget Drivers ............................................................................................................................329

Introduction to Target Drivers ........................................................................................................ 329

Sun Common SCSI Architecture Overview ................................................................................... 330

General Flow o Control ............................................................................................................ 331

SCSA Functions .......................................................................................................................... 332

Hardware Conguration File ........................................................................................................... 333

Declarations and Data Structures .................................................................................................... 334scsi_device Structure .............................................................................................................. 334

scsi_pkt Structure (Target Drivers) ....................................................................................... 335

Autoconguration or SCSI Target Drivers ................................................................................... 337

probe() Entry Point (SCSI Target Drivers) ............................................................................ 337

attach() Entry Point (SCSI Target Drivers) ......................................................................... 339

detach() Entry Point (SCSI Target Drivers) ......................................................................... 342

getinfo() Entry Point (SCSI Target Drivers) ....................................................................... 343

Resource Allocation ................................................................................................................. ......... 343

scsi_init_pkt() Function ...................................................................................................... 343

scsi_sync_pkt() Function ...................................................................................................... 344

scsi_destroy_pkt() Function ............................................................................................... 345

scsi_alloc_consistent_buf() Function ............................................................................ 345

scsi_free_consistent_buf() Function .............................................................................. 345Building and Transporting a Command ........................................................................................ 345

Building a Command ................................................................................................................ 345

Setting Target Capabilities ........................................................................................................ 347

Transporting a Command ........................................................................................................ 347

Command Completion ............................................................................................................. 348

Reuse o Packets ......................................................................................................................... 349

Auto-Request Sense Mode ........................................................................................................ 350

Dump Handling ................................................................................................................... ...... 351

SCSI Options ......................................................................................................................... ............. 353

18 SCSI HostBus Adapter Drivers ........................................................................................................355

Introduction to Host Bus Adapter Drivers ..................................................................................... 355

SCSI Interace ........................................................................................................................ ............ 356

Contents

11


12/615


13/615

gld_stats Structure .................................................................................................................. 422

GLD Arguments ................................................................................................................................ 424

GLD Entry Points .............................................................................................................................. 425gldm_reset() Entry Point ........................................................................................................ 425

gldm_start() Entry Point ........................................................................................................ 425

gldm_stop() Entry Point .......................................................................................................... 425

gldm_set_mac_addr() Entry Point ......................................................................................... 426

gldm_set_multicast() Entry Point ....................................................................................... 426

gldm_set_promiscuous() Entry Point ................................................................................... 427

gldm_send() Entry Point .......................................................................................................... 427

gldm_intr() Entry Point .......................................................................................................... 428

gldm_get_stats() Entry Point ............................................................................................... 428

gldm_ioctl() Entry Point ........................................................................................................ 429

GLD Return Values ................................................................................................................... 429

GLD Service Routines ....................................................................................................................... 429

gld_mac_alloc() Function ...................................................................................................... 429gld_mac_free() Function ........................................................................................................ 430

gld_register() Function ........................................................................................................ 430

gld_unregister() Function ................................................................................................... 430

gld_recv() Function ................................................................................................................ 431

gld_sched() Function .............................................................................................................. 431

gld_intr() Function ................................................................................................................ 431

20 USB Drivers .........................................................................................................................................433

USB in the Solaris Environment ...................................................................................................... 433

USBA 2.0 Framework ................................................................................................................ 433

USB Client Drivers ............................................................................................................... ...... 434

Binding Client Drivers ............................................................................................................ .......... 436How USB Devices Appear to the System ................................................................................. 436

USB Devices and the Solaris Device Tree ................................................................................ 436

Compatible Device Names ....................................................................................................... 436

Devices With Multiple Interaces ............................................................................................. 438

Checking Device Driver Bindings ............................................................................................ 439

Basic Device Access ........................................................................................................................... 440

Beore the Client Driver Is Attached ........................................................................................ 440

Contents

13


14/615

The Descriptor Tree ................................................................................................................... 440

Registering Drivers to Gain Device Access ............................................................................. 442

Device Communication ................................................................................................................... 443USB Endpoints ........................................................................................................................... 443

The Deault Pipe ......................................................................................................................... 444

Pipe States .................................................................................................................................. . 444

Opening Pipes ............................................................................................................................ 445

Closing Pipes ............................................................................................................................. . 445

Data Transer .............................................................................................................................. 445

Flushing Pipes ............................................................................................................................ 452

Device State Management ................................................................................................................ 453

Hotplugging USB Devices ......................................................................................................... 453

Power Management ................................................................................................................... 456

Serialization ................................................................................................................................ 460

Utility Functions ............................................................................................................................... . 460

Device Conguration Facilities ................................................................................................ 460Other Utility Functions ............................................................................................................. 462

Sample USB Device Driver ............................................................................................................... 463

Part III Building a DeviceDriver ................................................................................................................... 465

21 Compiling,Loading, Packaging,andTesting Drivers ................................................................. 467

Driver Development Summary ....................................................................................................... 467

Driver Code Layout ........................................................................................................................... 468

Header Files ................................................................................................................................ 468

Source Files ................................................................................................................................. 469

Conguration Files .................................................................................................................... 469

Preparing or Driver Installation ..................................................................................................... 470Compiling and Linking the Driver .......................................................................................... 471

Module Dependencies ............................................................................................................... 472

Writing a Hardware Conguration File .................................................................................. 472

Installing, Updating, and Removing Drivers ................................................................................. 472

Copying the Driver to a Module Directory ............................................................................. 472

Installing Drivers with add_drv ............................................................................................... 474

Updating Driver Inormation .................................................................................................. 474

Contents



15/615

Removing the Driver ................................................................................................................. 474

Loading and Unloading Drivers ...................................................................................................... 475

Driver Packaging ..................................................................................................................... .......... 475Package Postinstall ..................................................................................................................... 475

Package Preremove .................................................................................................................... 477

Criteria or Testing Drivers .............................................................................................................. 478

Conguration Testing ............................................................................................................... 478

Functionality Testing ................................................................................................................. 478

Error Handling ........................................................................................................................... 479

Testing Loading and Unloading .............................................................................................. 479

Stress, Perormance, and Interoperability Testing ................................................................. 479

DDI/DKI Compliance Testing ................................................................................................. 480

Installation and Packaging Testing .......................................................................................... 480

Testing Specic Types o Drivers ............................................................................................. 480

22 Debugging,Testing, andTuning Device Drivers .......................................................................... 483

Testing Drivers ...................................................................................................................... ............ 483

Enable the Deadman Feature to Avoid a Hard Hang ............................................................. 483

Testing With a Serial Connection ............................................................................................ 484

Setting Up Test Modules ........................................................................................................... 486

Avoiding Data Loss on a Test System ...................................................................................... 489

Recovering the Device Directory ............................................................................................. 491Debugging Tools ............................................................................................................................... 492

Postmortem Debugging ............................................................................................................ 493

Using the kmdb Kernel Debugger ............................................................................................. 493

Using the mdb Modular Debugger ............................................................................................ 496

Useul Debugging Tasks With kmdb and mdb .......................................................................... 498

Tuning Drivers ...................................................................................................................... ............ 506

Kernel Statistics .......................................................................................................................... 506

DTrace or Dynamic Instrumentation .................................................................................... 512

23 Recommended Coding Practices ....................................................................................................513

Debugging Preparation Techniques ............................................................................................... 513

Use a Unique Prex to Avoid Kernel Symbol Collisions ....................................................... 513

Use cmn_err() to Log Driver Activity ..................................................................................... 514

Contents

15


16/615


17/615

Internal Sequencing Logic ........................................................................................................ 533

Interrupt Issues ........................................................................................................................... 533

PROM on SPARC Machines ............................................................................................................ 534Open Boot PROM 3 ................................................................................................................... 534

Reading and Writing ................................................................................................................. 538

B Summary o Solaris DDI/DKI Services ............................................................................................541

Module Functions ............................................................................................................................. 542

Device Inormation Tree Node (dev_info_t) Functions ............................................................ 542Device (dev_t) Functions ................................................................................................................. 542

Property Functions ............................................................................................................................ 543

Device Sotware State Functions ...................................................................................................... 544

Memory Allocation and Deallocation Functions .......................................................................... 544

Kernel Thread Control and Synchronization Functions .............................................................. 545

Task Queue Management Functions .............................................................................................. 546Interrupt Functions ........................................................................................................................... 547

Programmed I/O Functions ............................................................................................................. 549

Direct Memory Access (DMA) Functions ...................................................................................... 555

User Space Access Functions ........................................................................................................... 557

User Process Event Functions .......................................................................................................... 558

User Process Inormation Functions .............................................................................................. 558User Application Kernel and Device Access Functions ................................................................ 559

Time-Related Functions ................................................................................................................... 560

Power Management Functions ........................................................................................................ 561

Fault Management Functions .......................................................................................................... 561

Kernel Statistics Functions ............................................................................................................... 562

Kernel Logging and Printing Functions ......................................................................................... 563

Bufered I/O Functions ..................................................................................................................... 563

Virtual Memory Functions ............................................................................................................... 564

Device ID Functions .......................................................................................................................... 564

SCSI Functions ....................................................................................................................... ............ 565

Resource Map Management Functions .......................................................................................... 567

System Global State ........................................................................................................................... 567

Utility Functions ................................................................................................................................ 567

Contents

17


18/615


19/615

Testing the Video Mode Change Callback Function ............................................................. 592

Additional Suggestions or Testing Console Frame Bufer Drivers ..................................... 593

Index ................................................................................................................................................... 595

Contents

19


20/615

20


21/615

Figures

FIGURE 21 Solaris Kernel ............................................................................................................. 56

FIGURE 22 Example Device Tree ................................................................................................ 60FIGURE 23 Device Node Names .................................................................................................. 63

FIGURE 24 Specic Driver Node Binding .................................................................................. 64

FIGURE 25 Generic Driver Node Binding .................................................................................. 65

FIGURE 51 Event Plumbing ......................................................................................................... 84

FIGURE 61 Module Loading and Autoconguration Entry Points ......................................... 96

FIGURE 91 CPU and System I/O Caches .................................................................................. 166

FIGURE 111 Device Context Management ................................................................................ 184

FIGURE 112 Device Context Switched to User Process A ........................................................185

FIGURE 121 Power Management Conceptual State Diagram ..................................................215

FIGURE 151 Character Driver Roadmap .................................................................................... 282

FIGURE 161 Block Driver Roadmap ........................................................................................... 310

FIGURE 171 SCSA Block Diagram .............................................................................................. 331

FIGURE 181 SCSA Interace ......................................................................................................... 357

FIGURE 182 Transport Layer Flow .............................................................................................. 358

FIGURE 183 HBA Transport Structures ..................................................................................... 366

FIGURE 184 Cloning Transport Operation ................................................................................ 367

FIGURE 185 scsi_pkt(9S) Structure Pointers ........................................................................... 379

FIGURE 201 Solaris USB Architecture ........................................................................................ 434

FIGURE 202 Driver and Controller Interaces ........................................................................... 435FIGURE 203 A Hierarchical USB Descriptor Tree .....................................................................441

FIGURE 204 USB Device State Machine ..................................................................................... 453

FIGURE 205 USB Power Management ........................................................................................ 457

FIGURE A1 Byte Ordering Required or Host Bus Dependency ............................................524

FIGURE A2 Data Ordering Host Bus Dependency ..................................................................525

FIGURE A3 MachineBlock Diagram ......................................................................................... 528

FIGURE A4 Base Address Registers or Memory and I/O .......................................................529

21


22/615

22


23/615

Tables

TABLE 11 Entry Points or All Driver Types ............................................................................ 42

TABLE 12 Additional Entry Points or Block Drivers .............................................................44TABLE 13 Additional Entry Points or Character Drivers ...................................................... 45

TABLE 14 EntryPoints or STREAMS Drivers ........................................................................ 46

TABLE 15 Entry Points or Character Drivers That Use devmap or Memory Mapping ..... 47

TABLE 16 Additional Entry Points or the Generic LAN Driver ...........................................48

TABLE 17 Additional Entry Points or SCSI HBA Drivers ..................................................... 49

TABLE 18 Entry Points or PC Card Drivers Only .................................................................. 50

TABLE 41 Property Interace Uses ............................................................................................. 79

TABLE 51 Functions or Using Name-Value Pairs .................................................................. 89

TABLE 61 PossibleNode Types ................................................................................................ 108

TABLE 91 Resource Allocation Handling ............................................................................... 162

TABLE 121 PowerManagementInteraces .............................................................................. 216

TABLE 171 Standard SCSA Functions ...................................................................................... 332

TABLE 181 SCSA HBA EntryPoint Summary .........................................................................358

TABLE 182 SCSA HBA Functions ............................................................................................. 368

TABLE 183 SCSA Entry Points ................................................................................................... 375

TABLE 201 Request Initialization .............................................................................................. 447

TABLE 202 Request Transer Setup ........................................................................................... 448

TABLE 221 kmdb Macros .............................................................................................................495

TABLE 222 Ethernet MII/GMII Physical Layer Interace Kernel Statistics .......................... 509TABLE A1 Device Physical Space in the Ultra 2 ...................................................................... 531

TABLE A2 Ultra2 SBusAddress Bits .......................................................................................532

TABLE B1 Deprecated Property Functions ............................................................................. 543

TABLE B2 Deprecated Memory Allocation and Deallocation Functions ...........................545

TABLE B3 Deprecated Interrupt Functions ............................................................................ 548

TABLE B4 Deprecated Programmed I/O Functions .............................................................. 552TABLE B5 Deprecated Direct Memory Access (DMA) Functions .......................................556

23

Tables


24/615

TABLE B6 Deprecated User Space Access Functions ............................................................558

TABLE B7 Deprecated User Process Inormation Functions ...............................................559

TABLE B8 Deprecated User Application Kernel and Device Access Functions .................559

TABLE B9 Deprecated Time-Related Functions .................................................................... 560

TABLE B10 Deprecated PowerManagement Functions ......................................................... 561

TABLE B11 Deprecated Virtual Memory Functions ................................................................ 564

TABLE B12 Deprecated SCSI Functions .................................................................................... 566

TABLE C1 Comparison o ILP32 and LP64 Data Types ........................................................569



25/615

Examples


26/615

EXAMPLE 92 Determining Burst Size ........................................................................................... 159

EXAMPLE 93 Using ddi_dma_mem_alloc(9F) ............................................................................160

EXAMPLE 94 ddi_dma_cookie(9S) Example .............................................................................162

EXAMPLE 95 Freeing DMA Resources ......................................................................................... 163

EXAMPLE 96 Canceling DMA Callbacks ..................................................................................... 164

EXAMPLE 97 Setting Up DMA Windows .................................................................................... 168

EXAMPLE 98 Interrupt Handler Using DMA Windows ............................................................170

EXAMPLE 101 segmap(9E) Routine ................................................................................................ 173

EXAMPLE 102 Using the segmap() Function to Change the Address Returned by the mmap()

Call ............................................................................................................................ 173EXAMPLE 103 Using the devmap_devmem_setup() Routine .......................................................176

EXAMPLE 104 Using the ddi_umem_alloc() Routine .................................................................178

EXAMPLE 105 devmap_umem_setup(9F) Routine ......................................................................... 180

EXAMPLE 111 Using the devmap() Routine ..................................................................................187

EXAMPLE 112 Using the devmap_access() Routine ...................................................................188

EXAMPLE 113 Using the devmap_contextmgt() Routine ...........................................................190

EXAMPLE 114 Using the devmap_dup() Routine ..........................................................................191

EXAMPLE 115 Using the devmap_unmap() Routine .....................................................................193

EXAMPLE 116 devmap(9E) Entry Point WithContext Management Support .......................... 195

EXAMPLE 121 Sample pm-component Entry ..................................................................................200

EXAMPLE 122 attach(9E) Routine With pm-components Property ..........................................200

EXAMPLE 123 MultipleComponent pm-components Entry .......................................................201

EXAMPLE 124 Using the power() Routine or a Single-Component Device ............................205EXAMPLE 125 power(9E) Routine or Multiple-Component Device .........................................206

EXAMPLE 126 detach(9E) Routine Implementing DDI_SUSPEND ..............................................210

EXAMPLE 127 attach(9E) Routine Implementing DDI_RESUME .................................................211

EXAMPLE 128 Device Access ........................................................................................................... 213

EXAMPLE 129 Device Operation Completion .............................................................................. 213

EXAMPLE 141

Conguration File ................................................................................................... 259EXAMPLE 142 Driver Source File .................................................................................................... 260

EXAMPLE 143 Write a Short Message to the Layered Device ......................................................270

EXAMPLE 144 Write a Longer Message to the Layered Device ................................................... 271

EXAMPLE 145 Change the Target Device ...................................................................................... 271

EXAMPLE 146 Device Usage Inormation ..................................................................................... 274

EXAMPLE 147 Ancestor Node Usage Inormation ....................................................................... 274

EXAMPLE 148 Child Node Usage Inormation ............................................................................. 275


Examples


27/615

EXAMPLE 149 Layering and Device Minor Node Inormation Keyboard ..............................275

EXAMPLE 1410 Layering and Device Minor Node Inormation Network Device ...................276

EXAMPLE 1411 Consumers o Underlying Device Nodes .............................................................277

EXAMPLE 1412 Consumer o the KeyboardDevice .......................................................................278

EXAMPLE 151 CharacterDriver attach() Routine .....................................................................283

EXAMPLE 152 CharacterDriver open(9E) Routine ...................................................................... 285

EXAMPLE 153 Ramdiskread(9E) Routine Using uiomove(9F) ..................................................290

EXAMPLE 154 Programmed I/O write(9E) Routine Using uwritec(9F) .................................291

EXAMPLE 155 read(9E) and write(9E) Routines Using physio(9F) ........................................292

EXAMPLE 156 aread(9E) and awrite(9E) Routines Using aphysio(9F) ..................................293EXAMPLE 157 minphys(9F) Routine .............................................................................................. 294

EXAMPLE 158 strategy(9E) Routine ............................................................................................ 295

EXAMPLE 159 Interrupt Routine .................................................................................................... 296

EXAMPLE 1510 chpoll(9E) Routine ................................................................................................ 298

EXAMPLE 1511 Interrupt Routine Supporting chpoll(9E) ........................................................... 299

EXAMPLE 1512 ioctl(9E) Routine .................................................................................................. 300

EXAMPLE 1513 Using ioctl(9E) ......................................................................................................301

EXAMPLE 1514 ioctl(9E) Routine to Support 32-bit Applications and 64-bit Applications ...303

EXAMPLE 1515 Handling copyout(9F) Overow ........................................................................... 304

EXAMPLE 1516 Using Data Structure Macros to Move Data ........................................................305

EXAMPLE 161 Block Driver attach() Routine ............................................................................. 312

EXAMPLE 162 Block Driver open(9E) Routine ............................................................................. 313

EXAMPLE 163 Block Device close(9E) Routine ........................................................................... 315

EXAMPLE 164 Synchronous Interrupt Routine or Block Drivers ..............................................320

EXAMPLE 165 Enqueuing Data Transer Requests or Block Drivers ........................................322

EXAMPLE 166 Starting the First Data Request or a Block Driver ...............................................324

EXAMPLE 167 Block Driver Routine or AsynchronousInterrupts ...........................................325

EXAMPLE 171 SCSI Target Driver probe(9E) Routine ................................................................ 338

EXAMPLE 172 SCSI Target Driver attach(9E) Routine .............................................................. 340EXAMPLE 173 SCSI Target Driver detach(9E) Routine .............................................................. 342

EXAMPLE 174 Alternative SCSI Target Driver getinfo() Code Fragment ..............................343

EXAMPLE 175 CompletionRoutine or a SCSI Driver .................................................................348

EXAMPLE 176 Enabling Auto-Request Sense Mode ..................................................................... 350

EXAMPLE 177 dump(9E) Routine ..................................................................................................... 352

EXAMPLE 181 Module Initialization or SCSI HBA .....................................................................370

EXAMPLE 182 HBA Driver Initialization o a SCSI Packet Structure .........................................379

27


28/615

Examples


29/615

EXAMPLE 2224 Modiying a Kernel Variable With a Debugger ...................................................506

29


30/615

30


31/615

Preace

Writing Device Drivers provides inormation on developing drivers or character-orienteddevices, block-oriented devices, network devices, SCSI target and HBA devices, and USBdevices or the SolarisTM Operating System (Solaris OS). This book discusses how to developmultithreaded reentrant device drivers or all architectures that conorm to the Solaris OSDDI/DKI (Device Driver Interace, Driver-Kernel Interace). A common driver programmingapproach is described that enables drivers to be written without concern or platorm-specicissues such as endianness and data ordering.

Additional topics include hardening Solaris drivers; power management; driverautoconguration; programmed I/O; Direct Memory Access (DMA); device context

management; compilation, installation, and testing drivers; debugging drivers; and portingSolaris drivers to a 64-bit environment.

Note This Solaris release supports systems that use the SPARC and x86 amilies o processorarchitectures: UltraSPARC, SPARC64, AMD64, Pentium, and Xeon EM64T. For supportedsystems, see the Solaris OS Hardware Compatibility Lists athttp://www.sun.com/bigadmin/hcl/ . This document cites any implementation diferences

between the platorm types.

Who Should UseThis BookThis book is written or UNIX programmers who are amiliar with UNIX device drivers.Overview inormation is provided, but the book is not intended to serve as a general tutorial on

device drivers.

Note The Solaris operating system (Solaris OS) runs on both SPARC and x86 architectures.The Solaris OS also runs on both 64-bit and 32-bit address spaces. The inormation in thisdocument applies to all platorms and address spaces unless specically noted.

31

Preace
http://www.sun.com/bigadmin/hcl/http://www.sun.com/bigadmin/hcl/


32/615

How This Book Is Organized

This book is organized into the ollowing chapters:

Chapter 1, Overview o Solaris Device Drivers, provides an introduction to device drivers

and associated entry points on the Solaris platorm. The entry points or each device driver

type are presented in tables.

Chapter 2, Solaris Kernel and Device Tree, provides an overview o the Solaris kernel with

an explanation o how devices are represented as nodes in a device tree.

Chapter 3, Multithreading, describes the aspects o the Solaris multithreaded kernel that

are relevant or device driver developers. Chapter 4, Properties, describes the set o interaces or using device properties.

Chapter 5, Managing Events and Queueing Tasks, describes how device drivers log events

and how to use task queues to perorm a task at a later time.

Chapter 6, Driver Autoconguration, explains the support that a driver must provide or

autoconguration.

Chapter 7, Device Access: Programmed I/O, describes the interaces and methodologies

or drivers to read or write to device memory.

Chapter 8, Interrupt Handlers, describes the mechanisms or handling interrupts. These

mechanisms include registering, servicing, and removing interrupts.

Chapter 9, Direct Memory Access (DMA), describes direct memory access (DMA) and the

DMA interaces.

Chapter 10, Mapping Device and Kernel Memory, describes interaces or managing

device and kernel memory.

Chapter 11, Device Context Management, describes the set o interaces that enable device

drivers to manage user access to devices.

Chapter 12, Power Management, explains the interaces or Power ManagementTM, a

ramework or managing power consumption.

Chapter 13, Hardening Solaris Drivers, describes how to integrate ault managementcapabilities into I/O device drivers, how to incorporate deensive programming practices,

and how to use the driver hardening test harness. Chapter 14, Layered Driver Interace (LDI), describes the LDI, which enables kernel

modules to access other devices in the system.

Chapter 15, Drivers or Character Devices, describes drivers or character-oriented

devices.

Chapter 16, Drivers or Block Devices, describes drivers or a block-oriented devices.

Chapter 17, SCSI Target Drivers, outlines the Sun Common SCSI Architecture (SCSA)

and the requirements or SCSI target drivers.


Preace


33/615

Chapter 18, SCSI Host Bus Adapter Drivers, explains how to apply SCSA to SCSI Host BusAdapter (HBA) drivers.

Chapter 19, Drivers or Network Devices, describes the Generic LAN driver (GLD), a

Solaris network driver that uses STREAMS technology and the Data Link Provider Interace(DLPI).

Chapter 20, USB Drivers, describes how to write a client USB device driver using theUSBA 2.0 ramework.

Chapter 21, Compiling, Loading, Packaging, and Testing Drivers, provides inormationon compiling, linking, and installing a driver.

Chapter 22, Debugging, Testing, and Tuning Device Drivers, describes techniques or

debugging, testing, and tuning drivers. Chapter 23, Recommended Coding Practices, describes the recommended coding

practices or writing drivers.

Appendix A, Hardware Overview, discusses multi-platorm hardware issues or devicedrivers.

Appendix B, Summary o Solaris DDI/DKI Services, provides tables o kernel unctions ordevice drivers. Deprecated unctions are indicated as well.

Appendix C, Making a Device Driver 64-Bit Ready, provides guidelines or updating adevice driver to run in a 64-bit environment.

Appendix D, Console Frame Bufer Drivers, describes how to add the necessary interacesto a rame bufer driver to enable the driver to interact with the Solaris kernel terminalemulator.

Related Books and PapersFor detailed reerence inormation about the device driver interaces, see the section 9 manpages. Section 9E, Intro(9E), describes DDI/DKI (Device Driver Interace, Driver-KernelInterace) driver entry points. Section 9F, Intro(9F), describes DDI/DKI kernel unctions.Sections 9P and 9S, Intro(9S), describe DDI/DKI properties and data structures.

For inormation on hardware and other driver-related issues, see the ollowing books rom Sun

Microsystems: Device Driver Tutorial. Sun Microsystems, Inc., 2008. Application Packaging Developers Guide. Sun Microsystems, Inc., 2005. Open Boot PROM Toolkit User's Guide. Sun Microsystems, Inc., 1996. STREAMS Programming Guide. Sun Microsystems, Inc., 2005. Multithreaded Programming Guide. Sun Microsystems, Inc., 2008. Solaris 64-bit Developers Guide. Sun Microsystems, Inc., 2005. Solaris Modular Debugger Guide. Sun Microsystems, Inc., 2007. Solaris Dynamic Tracing Guide. Sun Microsystems, Inc., 2005.

33

Preace
http://docs.sun.com/doc/816-5179/intro-9e?a=viewhttp://docs.sun.com/doc/816-5179/intro-9e?a=viewhttp://docs.sun.com/doc/816-5179/intro-9e?a=viewhttp://docs.sun.com/doc/816-5180/intro-9f?a=viewhttp://docs.sun.com/doc/816-5180/intro-9f?a=viewhttp://docs.sun.com/doc/816-5180/intro-9f?a=viewhttp://docs.sun.com/doc/816-5181/intro-9s?a=viewhttp://docs.sun.com/doc/816-5181/intro-9s?a=viewhttp://docs.sun.com/doc/816-5181/intro-9s?a=viewhttp://docs.sun.com/doc/817-5789http://docs.sun.com/doc/817-5789http://docs.sun.com/doc/817-0406http://docs.sun.com/doc/817-0406http://docs.sun.com/doc/816-4855http://docs.sun.com/doc/816-4855http://docs.sun.com/doc/816-5137http://docs.sun.com/doc/816-5138http://docs.sun.com/doc/816-5138http://docs.sun.com/doc/816-5041http://docs.sun.com/doc/816-5041http://docs.sun.com/doc/817-6223http://docs.sun.com/doc/817-6223http://docs.sun.com/doc/817-6223http://docs.sun.com/doc/816-5041http://docs.sun.com/doc/816-5138http://docs.sun.com/doc/816-5137http://docs.sun.com/doc/816-4855http://docs.sun.com/doc/817-0406http://docs.sun.com/doc/817-5789http://docs.sun.com/doc/816-5181/intro-9s?a=viewhttp://docs.sun.com/doc/816-5180/intro-9f?a=viewhttp://docs.sun.com/doc/816-5179/intro-9e?a=view


34/615

DTrace User Guide. Sun Microsystems, Inc., 2006.

The ollowing books rom other sources might also be useul:

The SPARC Architecture Manual, Version 9. Prentice Hall, 1998. ISBN 0-13-099227-5. The SPARC Architecture Manual, Version 8. Prentice Hall, 1994. ISBN 0-13-825001-4.

Pentium Pro Family Developer's Manual, Volumes 1-3. Intel Corporation, 1996. Volume 1,ISBN 1-55512-259-0; Volume 2, ISBN 1-55512-260-4; Volume 3, ISBN 1-55512-261-2.

Documentation, Support, andTrainingThe Sun web site provides inormation about the ollowing additional resources:

Documentation (http://www.sun.com/documentation/) Support (http://www.sun.com/support/) Training (http://www.sun.com/training/)

Typographic ConventionsThe ollowing table describes the typographic conventions that are used in this book.

TABLE P1 TypographicConventions

Typeace Meaning Example

AaBbCc123 The names o commands, les, and directories,and onscreen computer output

Edit your .login le.

Use ls -a to list all les.

machine_name% you have mail.

AaBbCc123 What you type, contrasted with onscreencomputer output

machine_name% su

Password:

aabbcc123 Placeholder: replace with a real name orvalue The command to remove a le is rm

flename.

AaBbCc123 Book titles, new terms, and terms tobeemphasized

Read Chapter 6 in the User's Guide.

A cache is a copythatis stored

locally.

Do notsave the le.

Note: Some emphasized items

appear bold online.


Preace
http://docs.sun.com/doc/819-5488http://www.sun.com/documentation/http://www.sun.com/documentation/http://www.sun.com/documentation/http://www.sun.com/support/http://www.sun.com/s

Date post:	30-May-2018
Category:	Documents
Upload:	nevdull
View:	219 times
Download:	0 times

Writing Device Drivers for Solaris

Documents