docs.oracle.com Draft 2018-01-30-16:08:43-08:00 Using This Documentation ................................................................................ 23 I Designing Device Drivers

Writing Device Drivers in Oracle Solaris11.4

Part No: E61061

Draft -- January 30, 2018

Draft 2018-01-30-16:07:00-08:00


Draft 2018-01-30-16:07:00-08:00Writing Device Drivers in Oracle Solaris 11.4

Part No: E61061

Copyright 1992, 2018, Oracle and/or its affiliates. All rights reserved.

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Exceptas expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform,publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, isprohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation,delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplementalregulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on thehardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerousapplications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take allappropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of thissoftware or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks ofSPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registeredtrademark of The Open Group.

This software or hardware and documentation may provide access to or information about content, products, and services from third parties. Oracle Corporation and its affiliates arenot responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services unless otherwise set forth in an applicable agreementbetween you and Oracle. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content,products, or services, except as set forth in an applicable agreement between you and Oracle.

This documentation is in pre-General Availability status and is intended for demonstration and preliminary use only. It may not be specific to the hardware on which you are usingthe software. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to this documentation and will not beresponsible for any loss, costs, or damages incurred due to the use of this documentation.

Access to Oracle Support

Oracle customers that have purchased support have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.


http://www.oracle.com/pls/topic/lookup?ctx=acc&id=infohttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=infohttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs

Draft 2018-01-30-16:07:00-08:00Rfrence: E61061

Copyright 1992, 2018, Oracle et/ou ses affilis. Tous droits rservs.

Ce logiciel et la documentation qui l'accompagne sont protgs par les lois sur la proprit intellectuelle. Ils sont concds sous licence et soumis des restrictions d'utilisation etde divulgation. Sauf stipulation expresse de votre contrat de licence ou de la loi, vous ne pouvez pas copier, reproduire, traduire, diffuser, modifier, accorder de licence, transmettre,distribuer, exposer, excuter, publier ou afficher le logiciel, mme partiellement, sous quelque forme et par quelque procd que ce soit. Par ailleurs, il est interdit de procder touteingnierie inverse du logiciel, de le dsassembler ou de le dcompiler, except des fins d'interoprabilit avec des logiciels tiers ou tel que prescrit par la loi.

Les informations fournies dans ce document sont susceptibles de modification sans pravis. Par ailleurs, Oracle Corporation ne garantit pas qu'elles soient exemptes d'erreurs et vousinvite, le cas chant, lui en faire part par crit.

Si ce logiciel, ou la documentation qui l'accompagne, est livr sous licence au Gouvernement des Etats-Unis, ou quiconque qui aurait souscrit la licence de ce logiciel pour lecompte du Gouvernement des Etats-Unis, la notice suivante s'applique :

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation,delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplementalregulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on thehardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

Ce logiciel ou matriel a t dvelopp pour un usage gnral dans le cadre d'applications de gestion des informations. Ce logiciel ou matriel n'est pas conu ni n'est destin treutilis dans des applications risque, notamment dans des applications pouvant causer un risque de dommages corporels. Si vous utilisez ce logiciel ou ce matriel dans le cadred'applications dangereuses, il est de votre responsabilit de prendre toutes les mesures de secours, de sauvegarde, de redondance et autres mesures ncessaires son utilisation dansdes conditions optimales de scurit. Oracle Corporation et ses affilis dclinent toute responsabilit quant aux dommages causs par l'utilisation de ce logiciel ou matriel pour desapplications dangereuses.

Oracle et Java sont des marques dposes d'Oracle Corporation et/ou de ses affilis. Tout autre nom mentionn peut correspondre des marques appartenant d'autres propritairesqu'Oracle.

Intel et Intel Xeon sont des marques ou des marques dposes d'Intel Corporation. Toutes les marques SPARC sont utilises sous licence et sont des marques ou des marquesdposes de SPARC International, Inc. AMD, Opteron, le logo AMD et le logo AMD Opteron sont des marques ou des marques dposes d'Advanced Micro Devices. UNIX est unemarque dpose de The Open Group.

Ce logiciel ou matriel et la documentation qui l'accompagne peuvent fournir des informations ou des liens donnant accs des contenus, des produits et des services manant detiers. Oracle Corporation et ses affilis dclinent toute responsabilit ou garantie expresse quant aux contenus, produits ou services manant de tiers, sauf mention contraire stipuledans un contrat entre vous et Oracle. En aucun cas, Oracle Corporation et ses affilis ne sauraient tre tenus pour responsables des pertes subies, des cots occasionns ou desdommages causs par l'accs des contenus, produits ou services tiers, ou leur utilisation, sauf mention contraire stipule dans un contrat entre vous et Oracle.

Cette documentation est fournie dans la Version prliminaire de Disponibilit Gnrale ("Pre-GA") et uniquement des fins de dmonstration et d'usage titre prliminaire de laversion finale. Celle-ci n'est pas toujours spcifique du matriel informatique sur lequel vous utilisez ce logiciel. Oracle Corporation et ses affilis dclinent expressment touteresponsabilit ou garantie expresse quant au contenu de cette documentation. Oracle Corporation et ses affilis ne sauraient en aucun cas tre tenus pour responsable des pertessubies, des cots occasionns ou des dommages causs par l'utilisation de cette documentation.

Accs aux services de support Oracle

Les clients Oracle qui ont souscrit un contrat de support ont accs au support lectronique via My Oracle Support. Pour plus d'informations, visitez le site http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info ou le site http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs si vous tes malentendant.


http://www.oracle.com/pls/topic/lookup?ctx=acc&id=infohttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=infohttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs

Draft 2018-01-30-16:08:43-08:00

Contents

Using This Documentation................................................................................23

I Designing Device Drivers for the Oracle Solaris Platform..............................25

1 Overview of Oracle Solaris Device Drivers........................................... 27What's New in Oracle Solaris 11.4........................................................... 27Device Driver Basics............................................................................. 27Device Driver Entry Points..................................................................... 29Considerations in Device Driver Design.................................................... 38

2 Oracle Solaris Kernel and Device Tree..................................................47What Is the Kernel?............................................................................... 47Overview of the Device Tree...................................................................50

3 Multithreading in Oracle Solaris............................................................57Locking Primitives................................................................................ 57Thread Synchronization.......................................................................... 60Choosing a Locking Scheme................................................................... 65

4 Device Properties.................................................................................. 67Device Properties and Property Values...................................................... 67

5 Managing Events and Queueing Tasks................................................. 73Managing Events...................................................................................73Queueing Tasks..................................................................................... 79

6 Driver Autoconfiguration....................................................................... 85Driver Loading and Unloading................................................................ 85Data Structures Required for Drivers........................................................ 86Loadable Driver Interfaces...................................................................... 89Device Configuration Concepts................................................................ 93Using Device IDs................................................................................ 106


Draft 2018-01-30-16:08:43-08:00Contents

7 Device Access: Programmed I/O......................................................... 109Device Memory...................................................................................109Device Access Functions...................................................................... 112

8 Interrupt Handlers............................................................................... 117Interrupt Handler Overview................................................................... 117Device Interrupts................................................................................. 118DDI Interrupt Functions........................................................................ 121Registering Interrupts........................................................................... 125Interrupt Resource Management............................................................. 131Interrupt Handler Functionality.............................................................. 144Handling High-Level Interrupts.............................................................. 146

9 Direct Memory Access (DMA)..............................................................153DMA Model....................................................................................... 153Types of Device DMA......................................................................... 154Types of Host Platform DMA................................................................ 155DMA Software Components: Handles, Windows, and Cookies..................... 156DMA Operations................................................................................. 156Managing DMA Resources....................................................................161DMA Windows................................................................................... 174

10 Mapping Device and Kernel Memory................................................. 179Memory Mapping Overview.................................................................. 179Exporting the Mapping......................................................................... 179Associating Device Memory With User Mappings..................................... 183Associating Kernel Memory With User Mappings..................................... 185

11 Device Context Management............................................................. 191Introduction to Device Context.............................................................. 191Context Management Operation............................................................. 193

12 Power Management........................................................................... 205Power Management Framework............................................................. 205Device Power Management Model..........................................................207System Power Management Model......................................................... 215Power Management Device Access Example............................................ 221Power Management Flow of Control....................................................... 222Changes to Power Management Interfaces................................................223

13 Hardening Oracle Solaris Drivers...................................................... 225

6 Writing Device Drivers in Oracle Solaris 11.4


Draft 2018-01-30-16:08:43-08:00Contents

Oracle Fault Management Architecture I/O Fault Services........................... 225

14 Layered Driver Interface (LDI)............................................................241LDI Overview..................................................................................... 241Kernel Interfaces................................................................................. 242User Interfaces.................................................................................... 259

II Designing Specific Kinds of Device Drivers................................................ 267

15 Drivers for Character Devices........................................................... 269Overview of the Character Driver Structure.............................................. 269Character Device Autoconfiguration........................................................271Device Access (Character Drivers)..........................................................272I/O Request Handling........................................................................... 275Mapping Device Memory......................................................................285Multiplexing I/O on File Descriptors....................................................... 285Miscellaneous I/O Control..................................................................... 28832-bit and 64-bit Data Structure Macros.................................................. 293

16 Drivers for Block Devices.................................................................. 299Block Driver Structure Overview............................................................299File I/O.............................................................................................. 300Block Device Autoconfiguration.............................................................301Controlling Device Access.................................................................... 303Synchronous Data Transfers (Block Drivers)............................................ 308Asynchronous Data Transfers (Block Drivers)...........................................311dump() and print() Entry Points........................................................... 316Disk Device Drivers............................................................................. 317

17 SCSI Target Drivers........................................................................... 319Introduction to Target Drivers................................................................ 319Sun Common SCSI Architecture Overview.............................................. 320Hardware Configuration File..................................................................322Declarations and Data Structures............................................................ 323Autoconfiguration for SCSI Target Drivers............................................... 326Resource Allocation............................................................................. 333Building and Transporting a Command.................................................... 335SCSI Options...................................................................................... 343

18 SCSI Host Bus Adapter Drivers......................................................... 345


Draft 2018-01-30-16:08:43-08:00Contents

Introduction to Host Bus Adapter Drivers................................................ 345SCSI Interface..................................................................................... 346SCSA HBA Interfaces.......................................................................... 347HBA Driver Dependency and Configuration Issues.................................... 357Entry Points for SCSA HBA Drivers.......................................................365SCSI HBA Driver Specific Issues........................................................... 394Support for Queuing.............................................................................397

19 Drivers for Network Devices.............................................................. 399GLDv3 Network Device Driver Framework............................................. 399GLDv2 Network Device Driver Framework............................................. 423

20 USB Drivers....................................................................................... 449USB in the Oracle Solaris Environment................................................... 449Binding Client Drivers..........................................................................451Basic Device Access............................................................................ 457Device Communication......................................................................... 460Device State Management..................................................................... 471Utility Functions.................................................................................. 478Sample USB Device Drivers..................................................................482

21 SR-IOV Drivers...................................................................................483Introduction to SR-IOV........................................................................ 483Supported Platforms............................................................................. 485Glossary............................................................................................. 485Overview of SR-IOV Device Driver....................................................... 486Boot Configuration Sequence.................................................................491SR-IOV Interfaces Summary................................................................. 491Interfaces for SR-IOV Drivers............................................................... 492SR-IOV Driver Ioctls........................................................................... 501Driver Callbacks.................................................................................. 506Fibre Channel SR-IOV Devices..............................................................507

III Building a Device Driver.............................................................................513

22 Compiling, Loading, Packaging, and Testing Drivers........................ 515Driver Development Summary............................................................... 515Driver Code Layout............................................................................. 516Preparing for Driver Installation............................................................. 518



Draft 2018-01-30-16:08:43-08:00Contents

Installing, Updating, and Removing Drivers............................................. 521Loading and Unloading Drivers..............................................................524Driver Packaging................................................................................. 524Criteria for Testing Drivers....................................................................525

23 Debugging, Testing, and Tuning Device Drivers................................ 531Testing Drivers.................................................................................... 531Debugging Tools................................................................................. 540Tuning Drivers.................................................................................... 554

24 Recommended Coding Practices...................................................... 567Debugging Preparation Techniques......................................................... 567Declaring a Variable Volatile................................................................. 570Driver Serviceability............................................................................ 572

IV Appendixes................................................................................................ 575

A Hardware Overview............................................................................. 577SPARC Processor Issues....................................................................... 577x86 Processor Issues............................................................................ 579Endianness, Byte Ordering.................................................................... 580Store Buffers.......................................................................................581System Memory Model........................................................................ 581Bus Architectures................................................................................ 582Bus Specifics...................................................................................... 583Device Issues...................................................................................... 587PROM on SPARC Systems................................................................... 588

B Summary of Oracle Solaris DDI/DKI Services..................................... 595Module Functions................................................................................ 596Device Information Tree Node (dev_info_t) Functions.............................. 596Device (dev_t) Functions...................................................................... 597Property Functions............................................................................... 597Device Software State Functions............................................................ 598Memory Allocation and Deallocation Functions........................................ 599Kernel Thread Control and Synchronization Functions............................... 599Task Queue Management Functions........................................................ 601Interrupt Functions............................................................................... 601Programmed I/O Functions.................................................................... 604


Draft 2018-01-30-16:08:43-08:00Contents

Direct Memory Access (DMA) Functions................................................ 610User Space Access Functions.................................................................612User Process Event Functions................................................................ 613User Process Information Functions........................................................ 614User Application Kernel and Device Access Functions............................... 614Time-Related Functions........................................................................ 615Power Management Functions............................................................... 616Fault Management Functions................................................................. 617Kernel Statistics Functions.................................................................... 618Kernel Logging and Printing Functions....................................................619Buffered I/O Functions......................................................................... 620Virtual Memory Functions..................................................................... 621Device ID Functions............................................................................ 621SCSI Functions................................................................................... 622Resource Map Management Functions.....................................................624System Global State............................................................................. 624Utility Functions.................................................................................. 625

C Making a Device Driver 64-Bit Ready.................................................. 627Introduction to 64-Bit Driver Design....................................................... 627General Conversion Steps..................................................................... 628Well Known ioctl Interfaces................................................................ 636

D Console Frame Buffer Drivers............................................................ 639Oracle Solaris Consoles and the Kernel Terminal Emulator..........................639Console Visual I/O Interfaces................................................................ 641Implementing the Visual I/O Interfaces in Console Frame Buffer Drivers........643Implementing Polled I/O in Console Frame Buffer Drivers.......................... 650Frame Buffer Specific Configuration Module............................................651The X Window System Frame Buffer Specific DDX Module....................... 651Developing, Testing, and Debugging Console Frame Buffer Drivers.............. 651

E pci.conf File........................................................................................ 655pci.conf Description........................................................................... 655System Configuration Section................................................................ 655Device Configuration Section................................................................ 656pci.conf Syntax................................................................................. 656pci.conf References............................................................................ 657



Draft 2018-01-30-16:08:43-08:00Contents

F Supported FC-HBA API....................................................................... 659Supported Fibre Channel HBA API........................................................ 659

G Equivalent kstat2 APIs for kstat......................................................... 661Equivalent kstat2 APIs for kstat.......................................................... 661kstat2 Data Structures......................................................................... 664

Index................................................................................................................ 665


Draft 2018-01-30-16:08:50-08:00

Figures

FIGURE 1 Managing Firmware Version in the attach() Function........................... 44FIGURE 2 Oracle Solaris Kernel....................................................................... 48FIGURE 3 Example Device Tree....................................................................... 52FIGURE 4 Device Node Names.........................................................................55FIGURE 5 Specific Driver Node Binding............................................................ 56FIGURE 6 Generic Driver Node Binding............................................................ 56FIGURE 7 Event Plumbing............................................................................... 74FIGURE 8 Module Loading and Autoconfiguration Entry Points............................. 86FIGURE 9 CPU and System I/O Caches............................................................173FIGURE 10 Device Context Management............................................................192FIGURE 11 Device Context Switched to User Process A....................................... 192FIGURE 12 Power Management Conceptual State Diagram.................................... 223FIGURE 13 Character Driver Roadmap.............................................................. 270FIGURE 14 Block Driver Roadmap................................................................... 300FIGURE 15 SCSA Block Diagram..................................................................... 320FIGURE 16 SCSA Interface.............................................................................. 346FIGURE 17 Transport Layer Flow..................................................................... 347FIGURE 18 HBA Transport Structures............................................................... 355FIGURE 19 Cloning Transport Operation............................................................ 356FIGURE 20 scsi_pkt(9S) Structure Pointers....................................................... 369FIGURE 21 Oracle Solaris USB Architecture.......................................................450FIGURE 22 Driver and Controller Interfaces........................................................451FIGURE 23 A Hierarchical USB Descriptor Tree..................................................458FIGURE 24 USB Device State Machine..............................................................471FIGURE 25 USB Power Management................................................................ 475FIGURE 26 SR-IOV Technology....................................................................... 484FIGURE 27 High-Level View of Sparc OVM Configuration................................... 490FIGURE 28 Byte Ordering Required for Host Bus Dependency............................... 580


Draft 2018-01-30-16:08:50-08:00Figures

FIGURE 29 Data Ordering Host Bus Dependency................................................ 581FIGURE 30 Machine Block Diagram..................................................................584FIGURE 31 Base Address Registers for Memory and I/O....................................... 585



Draft 2018-01-30-16:09:02-08:00

Tables

TABLE 1 Entry Points for All Driver Types....................................................... 31TABLE 2 Additional Entry Points for Block Drivers............................................ 33TABLE 3 Additional Entry Points for Character Drivers....................................... 34TABLE 4 Entry Points for STREAMS Drivers....................................................35TABLE 5 Entry Points for Character Drivers That Use devmap for Memory

Mapping......................................................................................... 36TABLE 6 Additional Entry Points for SCSI HBA Drivers..................................... 37TABLE 7 Property Interface Uses..................................................................... 69TABLE 8 Functions for Using Name-Value Pairs................................................ 78TABLE 9 Possible Node Types........................................................................ 99TABLE 10 Callback Support Interfaces............................................................. 133TABLE 11 Interrupt Vector Request Interfaces.................................................... 135TABLE 12 Resource Allocation Handling.......................................................... 168TABLE 13 Power Management Interfaces.......................................................... 224TABLE 14 Standard SCSA Functions................................................................322TABLE 15 SCSA HBA Entry Point Summary.................................................... 347TABLE 16 SCSA HBA Functions.................................................................... 357TABLE 17 SCSA Entry Points......................................................................... 365TABLE 18 GLDv3 Interfaces...........................................................................420TABLE 19 Request Initialization...................................................................... 465TABLE 20 Request Transfer Setup................................................................... 465TABLE 21 Configuration Parameters Definition.................................................. 488TABLE 22 Interfaces for SR-IOV Drivers.......................................................... 491TABLE 23 Compiler Options for SPARC and x86 64-bit Architectures.................... 519TABLE 24 Considerations and Compiler Options to Generate Code Without MMX or

SSE Instructions for the x86 Architecture........................................... 520TABLE 25 kmdb Macros................................................................................. 543TABLE 26 Ethernet MII/GMII Physical Layer Interface Kernel Statistics................. 563


Draft 2018-01-30-16:09:02-08:00Tables

TABLE 27 Deprecated Property Functions......................................................... 598TABLE 28 Deprecated Memory Allocation and Deallocation Functions................... 599TABLE 29 Deprecated Interrupt Functions......................................................... 603TABLE 30 Deprecated Programmed I/O Functions.............................................. 608TABLE 31 Deprecated Direct Memory Access (DMA) Functions........................... 611TABLE 32 Deprecated User Space Access Functions........................................... 613TABLE 33 Deprecated User Process Information Functions.................................. 614TABLE 34 Deprecated User Application Kernel and Device Access Functions.......... 615TABLE 35 Deprecated Time-Related Functions.................................................. 616TABLE 36 Deprecated Power Management Functions.......................................... 617TABLE 37 Deprecated Virtual Memory Functions............................................... 621TABLE 38 Deprecated SCSI Functions..............................................................623TABLE 39 Comparison of ILP32 and LP64 Data Types....................................... 627TABLE 40 APIs to Create and Delete kstat........................................................ 661TABLE 41 APIs to Monitor IO Queue.............................................................. 662TABLE 42 APIs to Add and Remove Visibility of kstat in Zones.......................... 663TABLE 43 APIs to Lock and Release kstats....................................................... 663TABLE 44 General APIs................................................................................. 663TABLE 45 Kstat2 Data Structures.................................................................... 664



Draft 2018-01-30-16:09:41-08:00

Examples

EXAMPLE 1 Using Mutexes and Condition Variables............................................... 62EXAMPLE 2 Using cv_timedwait()..................................................................... 63EXAMPLE 3 Using cv_wait_sig()....................................................................... 64EXAMPLE 4 Driver Check for Locally Configured Timeout Value.............................. 71EXAMPLE 5 prop_op() Routine...........................................................................72EXAMPLE 6 Calling ddi_log_sysevent()............................................................. 76EXAMPLE 7 Creating and Populating a Name-Value Pair List................................... 77EXAMPLE 8 Loadable Interface Section................................................................ 89EXAMPLE 9 _init() Function............................................................................ 91EXAMPLE 10 probe(9E) Routine........................................................................... 95EXAMPLE 11 probe(9E) Routine Using ddi_poke8(9F)............................................. 96EXAMPLE 12 Typical attach() Entry Point...........................................................100EXAMPLE 13 Typical detach() Entry Point...........................................................103EXAMPLE 14 Typical getinfo() Entry Point......................................................... 105EXAMPLE 15 Mapping Setup.............................................................................. 112EXAMPLE 16 Mapping Setup: Buffer....................................................................113EXAMPLE 17 Changing Soft Interrupt Priority........................................................124EXAMPLE 18 Checking for Pending Interrupts....................................................... 124EXAMPLE 19 Setting Interrupt Masks................................................................... 124EXAMPLE 20 Clearing Interrupt Masks................................................................. 124EXAMPLE 21 Registering a Legacy Interrupt..........................................................126EXAMPLE 22 Removing a Legacy Interrupt........................................................... 128EXAMPLE 23 Registering a Set of MSI Interrupts................................................... 129EXAMPLE 24 Removing MSI Interrupts................................................................ 131EXAMPLE 25 Interrupt Example.......................................................................... 145EXAMPLE 26 Handling High-Level Interrupts With attach()................................... 147EXAMPLE 27 High-Level Interrupt Routine........................................................... 149EXAMPLE 28 Low-Level Soft Interrupt Routine..................................................... 150


Draft 2018-01-30-16:09:41-08:00Examples

EXAMPLE 29 DMA Callback Example................................................................. 164EXAMPLE 30 Determining Burst Size................................................................... 165EXAMPLE 31 Using ddi_dma_mem_alloc(9F)........................................................ 167EXAMPLE 32 ddi_dma_cookie(9S) Example......................................................... 169EXAMPLE 33 Freeing DMA Resources................................................................. 170EXAMPLE 34 Canceling DMA Callbacks.............................................................. 171EXAMPLE 35 Setting Up DMA Windows.............................................................. 175EXAMPLE 36 Interrupt Handler Using DMA Windows............................................ 176EXAMPLE 37 segmap(9E) Routine....................................................................... 181EXAMPLE 38 Using the segmap() Function to Change the Address Returned by the

mmap() Call................................................................................... 181EXAMPLE 39 Using the devmap_devmem_setup() Routine........................................ 184EXAMPLE 40 Using the ddi_umem_alloc() Routine................................................ 187EXAMPLE 41 devmap_umem_setup(9F) Routine...................................................... 189EXAMPLE 42 Using the devmap() Routine............................................................ 195EXAMPLE 43 Using the devmap_access() Routine................................................. 196EXAMPLE 44 Using the devmap_contextmgt() Routine........................................... 198EXAMPLE 45 Using the devmap_dup() Routine...................................................... 199EXAMPLE 46 Using the devmap_unmap() Routine................................................... 201EXAMPLE 47 devmap(9E) Entry Point With Context Management Support................... 203EXAMPLE 48 Sample pm-component Entry............................................................ 208EXAMPLE 49 attach(9E) Routine With pm-components Property.............................. 209EXAMPLE 50 Multiple Component pm-components Entry......................................... 209EXAMPLE 51 Using the power() Routine for a Single-Component Device................... 213EXAMPLE 52 power(9E) Routine for Multiple-Component Device............................. 214EXAMPLE 53 detach(9E) Routine Implementing DDI_SUSPEND.................................. 218EXAMPLE 54 attach(9E) Routine Implementing DDI_RESUME................................... 220EXAMPLE 55 Device Access............................................................................... 221EXAMPLE 56 Device Operation Completion.......................................................... 222EXAMPLE 57 Configuration File.......................................................................... 248EXAMPLE 58 Driver Source File..........................................................................249EXAMPLE 59 Write a Short Message to the Layered Device..................................... 258EXAMPLE 60 Write a Longer Message to the Layered Device................................... 258EXAMPLE 61 Change the Target Device................................................................ 259EXAMPLE 62 Device Usage Information............................................................... 262EXAMPLE 63 Ancestor Node Usage Information.................................................... 262



Draft 2018-01-30-16:09:41-08:00Examples

EXAMPLE 64 Child Node Usage Information......................................................... 262EXAMPLE 65 Layering and Device Minor Node Information Keyboard.................... 263EXAMPLE 66 Layering and Device Minor Node Information Network Device............263EXAMPLE 67 Consumers of Underlying Device Nodes............................................ 265EXAMPLE 68 Consumer of the Keyboard Device.................................................... 265EXAMPLE 69 Character Driver attach() Routine................................................... 271EXAMPLE 70 Character Driver open(9E) Routine................................................... 274EXAMPLE 71 Ramdisk read(9E) Routine Using uiomove(9F)................................... 278EXAMPLE 72 Programmed I/O write(9E) Routine Using uwritec(9F)....................... 279EXAMPLE 73 read(9E) and write(9E) Routines Using physio(9F)............................ 280EXAMPLE 74 aread(9E) and awrite(9E) Routines Using aphysio(9F)....................... 282EXAMPLE 75 minphys(9F) Routine...................................................................... 283EXAMPLE 76 strategy(9E) Routine.....................................................................283EXAMPLE 77 Interrupt Routine............................................................................ 284EXAMPLE 78 chpoll(9E) Routine........................................................................ 286EXAMPLE 79 Interrupt Routine Supporting chpoll(9E)........................................... 287EXAMPLE 80 ioctl(9E) Routine......................................................................... 289EXAMPLE 81 Using ioctl(9E)............................................................................ 290EXAMPLE 82 ioctl(9E) Routine to Support 32-bit Applications and 64-bit

Applications.................................................................................. 291EXAMPLE 83 Handling copyout(9F) Overflow....................................................... 293EXAMPLE 84 Using Data Structure Macros to Move Data........................................ 293EXAMPLE 85 Block Driver attach() Routine........................................................ 301EXAMPLE 86 Block Driver open(9E) Routine........................................................ 303EXAMPLE 87 Block Device close(9E) Routine...................................................... 304EXAMPLE 88 Synchronous Interrupt Routine for Block Drivers................................. 310EXAMPLE 89 Enqueuing Data Transfer Requests for Block Drivers............................ 313EXAMPLE 90 Starting the First Data Request for a Block Driver................................ 314EXAMPLE 91 Block Driver Routine for Asynchronous Interrupts............................... 315EXAMPLE 92 SCSI Target Driver probe(9E) Routine.............................................. 327EXAMPLE 93 SCSI Target Driver attach(9E) Routine............................................. 329EXAMPLE 94 SCSI Target Driver detach(9E) Routine............................................. 331EXAMPLE 95 Alternative SCSI Target Driver getinfo() Code Fragment.................... 332EXAMPLE 96 Completion Routine for a SCSI Driver...............................................338EXAMPLE 97 Enabling Auto-Request Sense Mode.................................................. 340EXAMPLE 98 dump(9E) Routine........................................................................... 341


Draft 2018-01-30-16:09:41-08:00Examples

EXAMPLE 99 Module Initialization for SCSI HBA..................................................360EXAMPLE 100 HBA Driver Initialization of a SCSI Packet Structure........................... 369EXAMPLE 101 HBA Driver Allocation of DMA Resources........................................ 371EXAMPLE 102 DMA Resource Reallocation for HBA Drivers.................................... 374EXAMPLE 103 HBA Driver tran_destroy_pkt(9E) Entry Point................................. 376EXAMPLE 104 HBA Driver tran_sync_pkt(9E) Entry Point...................................... 377EXAMPLE 105 HBA Driver tran_dmafree(9E) Entry Point........................................ 377EXAMPLE 106 HBA Driver tran_start(9E) Entry Point........................................... 379EXAMPLE 107 HBA Driver Interrupt Handler.......................................................... 381EXAMPLE 108 HBA Driver tran_getcap(9E) Entry Point......................................... 385EXAMPLE 109 HBA Driver tran_setcap(9E) Entry Point......................................... 388EXAMPLE 110 HBA Driver tran_reset_notify(9E) Entry Point................................ 392EXAMPLE 111 The mac_init_ops() and mac_fini_ops() Functions........................... 401EXAMPLE 112 The mac_alloc(), mac_register(), and mac_free() Functions and

mac_register Structure.................................................................. 402EXAMPLE 113 The mac_unregister() Function...................................................... 403EXAMPLE 114 The mac_callbacks Structure........................................................... 404EXAMPLE 115 The mc_getcapab() Entry Point....................................................... 405EXAMPLE 116 The mc_tx() and mri_tx() Entry Point............................................. 413EXAMPLE 117 The mc_getstat() Entry Point......................................................... 418EXAMPLE 118 USB Mouse Compatible Device Names............................................. 453EXAMPLE 119 Compatible Device Names Shown by the Print Configuration

Command..................................................................................... 453EXAMPLE 120 USB Audio Compatible Device Names.............................................. 455EXAMPLE 121 USB Video Interface Association Compatible Names............................456EXAMPLE 122 Setting Device Configuration Parameters............................................ 489EXAMPLE 123 SR-IOV pci_param_get(9F) Routine................................................. 493EXAMPLE 124 Setting input-device and output-device With Boot PROM

Commands.................................................................................... 533EXAMPLE 125 Setting input-device and output-device With the eeprom Command..... 533EXAMPLE 126 Using modinfo to Confirm a Loaded Driver........................................ 535EXAMPLE 127 Recovering a Damaged Device Directory........................................... 539EXAMPLE 128 Setting Standard Breakpoints in kmdb.................................................542EXAMPLE 129 Setting Deferred Breakpoints in kmdb.................................................542EXAMPLE 130 Invoking mdb on a Crash Dump........................................................ 545EXAMPLE 131 Invoking mdb on a Running Kernel....................................................545



Draft 2018-01-30-16:09:41-08:00Examples

EXAMPLE 132 Reading All Registers on a SPARC Processor With kmdb....................... 546EXAMPLE 133 Reading and Writing Registers on an x86 Machine With kmdb................ 546EXAMPLE 134 Inspecting the Registers of a Different Processor..................................547EXAMPLE 135 Retrieving the Value of an Individual Register From a Specified

Processor...................................................................................... 547EXAMPLE 136 Displaying Kernel Data Structures With a Debugger............................. 548EXAMPLE 137 Displaying the Size of a Kernel Data Structure.................................... 549EXAMPLE 138 Displaying the Offset to a Kernel Data Structure.................................. 549EXAMPLE 139 Displaying the Relative Addresses of a Kernel Data Structure................. 549EXAMPLE 140 Displaying the Absolute Addresses of a Kernel Data Structure................ 549EXAMPLE 141 Using the ::prtconf Dcmd............................................................. 550EXAMPLE 142 Displaying Device Information for an Individual Node..........................551EXAMPLE 143 Using the ::prtconf Dcmd in Verbose Mode..................................... 551EXAMPLE 144 Using the ::devbindings Dcmd to Locate Driver Instances................... 552EXAMPLE 145 Modifying a Kernel Variable With a Debugger.................................... 554EXAMPLE 146 Registering Optional Kstats..............................................................555EXAMPLE 147 Optional Kstats Callback Handling.................................................... 556EXAMPLE 148 Enabling Optional Kstats................................................................. 558EXAMPLE 149 Disabling Optional Kstats................................................................ 559EXAMPLE 150 Listing the Optional Kstats.............................................................. 559EXAMPLE 151 Enabling Optional Kstats................................................................. 560EXAMPLE 152 Disabling Optional Kstats................................................................ 560EXAMPLE 153 Clear Persistent State of Optional Kstats............................................ 561


Draft 2018-01-30-16:09:41-08:00

Using This Documentation

Overview Writing Device Drivers provides information on developing drivers forcharacter-oriented devices, block-oriented devices, network devices, SCSI target andHBA devices, and USB devices for the Oracle Solaris Operating System (Oracle SolarisOS). This book discusses how to develop multithreaded reentrant device drivers for allarchitectures that conform to the Oracle Solaris OS DDI/DKI (Device Driver Interface,Driver-Kernel Interface). A common driver programming approach is described that enablesdrivers to be written without concern for platform-specific issues such as endiannessand data ordering. Additional topics include hardening Oracle Solaris drivers; powermanagement; driver autoconfiguration; programmed I/O; Direct Memory Access (DMA);device context management; compilation, installation, and testing drivers; debuggingdrivers; and porting Oracle Solaris drivers to a 64-bit environment.

Audience This book is written for UNIX programmers who are familiar with UNIXdevice drivers. Overview information is provided, but the book is not intended to serve as ageneral tutorial on device drivers.

Note - The Oracle Solaris operating system (Oracle Solaris OS) runs on both SPARCand x86 architectures. The Oracle Solaris OS also runs on both 64-bit and 32-bit addressspaces. The information in this document applies to all platforms and address spaces unlessspecifically noted.

Required knowledge Familiarity with C programming and developing device drivers.

Product Documentation Library

Documentation and resources for this product and related products are available at http://www.oracle.com/pls/topic/lookup?ctx=E37838-01.

Using This Documentation


23

http://www.oracle.com/pls/topic/lookup?ctx=E37838-01http://www.oracle.com/pls/topic/lookup?ctx=E37838-01

Draft 2018-01-30-16:09:41-08:00Feedback

Feedback

Provide feedback about this documentation at http://www.oracle.com/goto/docfeedback.



http://www.oracle.com/goto/docfeedback

Draft 2018-01-30-16:09:44-08:00

PART I

Designing Device Drivers for the Oracle SolarisPlatform

The first part of this manual provides general information for developing device drivers on theOracle Solaris platform. This part includes the following chapters:

Chapter 1, Overview of Oracle Solaris Device Drivers provides an introduction to devicedrivers and associated entry points on the Oracle Solaris platform. The entry points for eachdevice driver type are presented in tables.

Chapter 2, Oracle Solaris Kernel and Device Tree provides an overview of the OracleSolaris kernel with an explanation of how devices are represented as nodes in a device tree.

Chapter 3, Multithreading in Oracle Solaris describes the aspects of the Oracle Solarismultithreaded kernel that are relevant for device driver developers.

Chapter 4, Device Properties describes the set of interfaces for using device properties. Chapter 5, Managing Events and Queueing Tasks describes how device drivers log events

and how to use task queues to perform a task at a later time. Chapter 6, Driver Autoconfiguration explains the support that a driver must provide for

autoconfiguration. Chapter 7, Device Access: Programmed I/O describes the interfaces and methodologies

for drivers to read or write to device memory. Chapter 8, Interrupt Handlers describes the mechanisms for handling interrupts. These

mechanisms include allocating, registering, servicing, and removing interrupts.

PART I Designing Device Drivers for the Oracle Solaris Platform


25

Draft 2018-01-30-16:09:44-08:00

Chapter 9, Direct Memory Access (DMA) describes direct memory access (DMA) andthe DMA interfaces.

Chapter 10, Mapping Device and Kernel Memory describes interfaces for managingdevice and kernel memory.

Chapter 11, Device Context Management describes the set of interfaces that enable devicedrivers to manage user access to devices.

Chapter 12, Power Management explains the interfaces for the Power Managementfeature, a framework for managing power consumption.

Chapter 13, Hardening Oracle Solaris Drivers describes how to integrate faultmanagement capabilities into I/O device drivers, how to incorporate defensive programmingpractices, and how to use the driver hardening test harness.

Chapter 14, Layered Driver Interface (LDI) describes the LDI, which enables kernelmodules to access other devices in the system.



Draft 2018-01-30-16:09:44-08:00

1 C H A P T E R 1 Overview of Oracle Solaris Device Drivers

This chapter gives an overview of Oracle Solaris device drivers. The chapter providesinformation on the following subjects:

What's New in Oracle Solaris 11.4 on page 27 Device Driver Basics on page 27 Device Driver Entry Points on page 29 Considerations in Device Driver Design on page 38

What's New in Oracle Solaris 11.4This release provides kstat2 to analyze kernel statistics. kstat2 is an improved version of theolder kstat interface. The kstat2 interface provides easier access to the kernel statistics andmanages data in the libkstat2 library. Starting with Oracle Solaris 11.4, you must use onlykstat2. For more information about the APIs available in kstat2, see Equivalent kstat2 APIsfor kstat on page 661.

Device Driver BasicsThis section introduces you to device drivers and their entry points on the Oracle Solarisplatform.

What Is a Device Driver?

A device driver is a kernel module that is responsible for managing the low-level I/O operationsof a hardware device. Device drivers are written with standard interfaces that the kernel can callto interface with a device. Device drivers can also be software-only, emulating a device thatexists only in software, such as RAM disks, buses, and pseudo-terminals.

Chapter 1 Overview of Oracle Solaris Device Drivers


27

Draft 2018-01-30-16:09:44-08:00Device Driver Basics

A device driver contains all the device-specific code necessary to communicate with a device.This code includes a standard set of interfaces to the rest of the system. This interface shieldsthe kernel from device specifics just as the system call interface protects application programsfrom platform specifics. Application programs and the rest of the kernel need little, if any,device-specific code to address the device. In this way, device drivers make the system moreportable and easier to maintain.

When the Oracle Solaris operating system (Oracle Solaris OS) is initialized, devices identifythemselves and are organized into the device tree, a hierarchy of devices. In effect, the devicetree is a hardware model for the kernel. An individual device driver is represented as a nodein the tree with no children. This type of node is referred to as a leaf driver. A driver thatprovides services to other drivers is called a bus nexus driver and is shown as a node withchildren. As part of the boot process, physical devices are mapped to drivers in the tree so thatthe drivers can be located when needed. For more information on how the Oracle Solaris OSaccommodates devices, see Chapter 2, Oracle Solaris Kernel and Device Tree.Device drivers are classified by how they handle I/O. Device drivers fall into three broadcategories:

Block device drivers For cases where handling I/O data as asynchronous chunks isappropriate. Typically, block drivers are used to manage devices with physically addressablestorage media, such as disks.

Character device drivers For devices that perform I/O on a continuous flow of bytes.

Note - A driver can be both block and character at the same time if you set up two differentinterfaces to the file system. See Devices as Special Files on page 49.

Included in the character category are drivers that use the STREAMS model (see below),programmed I/O, direct memory access, SCSI buses, USB, and other network I/O.

STREAMS device drivers Subset of character drivers that uses the streamio(4I) set ofroutines for character I/O within the kernel.

What Is a Device Driver Entry Point?

An entry point is a function within a device driver that can be called by an external entity toget access to some driver functionality or to operate a device. Each device driver provides astandard set of functions as entry points. For the complete list of entry points for all drivertypes, see the Intro(9E) man page.The Oracle Solaris kernel uses entry points for these general task areas:

Loading and unloading the driver



http://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN4streamio-4ihttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Eintro-9e

Draft 2018-01-30-16:09:44-08:00Device Driver Entry Points

Autoconfiguring the device Autoconfiguration is the process of loading a device driver'scode and static data into memory so that the driver is registered with the system.

Providing I/O services for the driver

Drivers for different types of devices have different sets of entry points according to the kindsof operations the devices perform. A driver for a memory-mapped character-oriented device, forexample, supports a devmap(9E) entry point, while a block driver does not support this entry.

Use a prefix based on the name of your driver to give driver functions unique names. Typically,this prefix is the name of the driver, such as xx_open() for the open(9E) routine of driverxx. See Use a Unique Prefix to Avoid Kernel Symbol Collisions on page 567 for moreinformation. In subsequent examples in this book, xx is used as the driver prefix.

Device Driver Entry Points

This section provides lists of entry points for the following categories:

Entry Points Common to All Drivers on page 29 Entry Points for Block Device Drivers on page 33 Entry Points for Character Device Drivers on page 34 Entry Points for STREAMS Device Drivers on page 35 Entry Points for Memory Mapped Devices on page 35 Entry Points for Network Device Drivers on page 36 Entry Points for SCSI HBA Drivers on page 36

Entry Points Common to All Drivers

Some operations can be performed by any type of driver, such as the functions that are requiredfor module loading and for the required autoconfiguration entry points. This section discussestypes of entry points that are common to all drivers. The common entry points are listedin Summary of Common Entry Points on page 31 with links to man pages and otherrelevant discussions.

Device Access Entry Points

Drivers for character and block devices export the cb_ops(9S) structure, which defines thedriver entry points for block device access and character device access. Both types of drivers



29

http://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Edevmap-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Scb-ops-9s


are required to support the open(9E) and close(9E) entry points. Block drivers are requiredto support strategy(9E), while character drivers can choose to implement whatever mix ofread(9E), write(9E), ioctl(9E), mmap(9E), or devmap(9E) entry points is appropriate for thetype of device. Character drivers can also support a polling interface through chpoll(9E).Asynchronous I/O is supported through aread(9E) and awrite(9E) for block drivers and thosedrivers that can use both block and character file systems.

Loadable Module Entry Points

All drivers are required to implement the loadable module entry points _init(9E), _fini(9E),and _info(9E) to load, unload, and report information about the driver module.

Drivers should allocate and initialize any global resources in _init(9E). Drivers should releasetheir resources in _fini(9E).

Note - In the Oracle Solaris OS, only the loadable module routines must be visible outside thedriver object module. Other routines can have the storage class static.

Autoconfiguration Entry Points

Drivers are required to implement the attach(9E), detach(9E), and getinfo(9E) entry pointsfor device autoconfiguration. Drivers can also implement the optional entry point probe(9E)in cases where devices do not identify themselves during boot-up, such as SCSI target devices.See Chapter 6, Driver Autoconfiguration for more information on these routines.

Kernel Statistics Entry Points

The Oracle Solaris platform provides a rich set of interfaces to maintain and export kernel-level statistics, also known as kstats. Drivers are free to use these interfaces to export driver anddevice statistics that can be used by user applications to observe the internal state of the driver.The ks2_update() entry point is provided for working with kernel statistics. This entry pointcan be used to update kstat data at will. The ks2_update() entry point is useful in situationswhere a device is set up to track kernel data but extracting that data is time-consuming.

For further information, see the kstat2_create(9F) and kstat2(9S) man pages. See alsoKernel Statistics on page 554.



http://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Eopen-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Eclose-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Estrategy-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Eread-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Ewrite-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Eioctl-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Emmap-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Edevmap-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Echpoll-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Earead-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Eawrite-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Eu-init-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Eu-fini-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Eu-info-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Eu-init-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Eu-fini-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Eattach-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Edetach-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Egetinfo-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Eprobe-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Fkstat2-create-9fhttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Skstat2-9s


Power Management Entry Point

Drivers for hardware devices that provide Power Management functionality can support theoptional power(9E) entry point. See Chapter 12, Power Management for details about thisentry point.

System Quiesce Entry Point

A driver that manages devices must implement the quiesce(9E) entry point. Driversthat do not manage devices can set the devo_quiesce field in the dev_ops structure toddi_quiesce_not_needed(). The quiesce() function can be called only when the systemis single-threaded at high PIL (priority interrupt level) with preemption disabled. Therefore,this function must not be blocked. If a device has a defined reset state configuration, the drivershould return that device to that reset state as part of the quiesce operation. An example ofthis case is Fast Reboot, where firmware is bypassed when booting to a new operating systemimage.

Summary of Common Entry Points

The following table lists entry points that can be used by all types of drivers.

TABLE 1 Entry Points for All Driver Types

Category / Entry Point Usage Description

cb_ops Entry Points

open(9E) Required Gets access to a device. Additional information:

open() Entry Point (Character Drivers) on page 273 open() Entry Point (Block Drivers) on page 303

close(9E) Required Gives up access to a device. The version of close() for STREAMSdrivers has a different signature than character and block drivers.Additional information:

close() Entry Point (Character Drivers) on page 274 close() Entry Point (Block Drivers) on page 304

Loadable Module EntryPoints

_init(9E) Required Initializes a loadable module. Additional information: LoadableDriver Interfaces on page 89

_fini(9E) Required Prepares a loadable module for unloading. Required forall driver types. Additional information: Loadable DriverInterfaces on page 89



31

http://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Epower-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Equiesce-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Eopen-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Eclose-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Eu-init-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Eu-fini-9e



_info(9E) Required Returns information about a loadable module. Additionalinformation: Loadable Driver Interfaces on page 89

Autoconfiguration EntryPoints

attach(9E) Required Adds a device to the system as part of initialization. Also used toresume a system that has been suspended. Additional information:attach() Entry Point on page 97

detach(9E) Required Detaches a device from the system. Also, used to suspend adevice temporarily. Additional information: detach() EntryPoint on page 103

getinfo(9E) Required Gets device information that is specific to the driver, such as themapping between a device number and the corresponding instance.Additional information:

getinfo() Entry Point on page 104 getinfo() Entry Point (SCSI Target Drivers) on page 332.

probe(9E) SeeDescription

Determines if a non-self-identifying device is present. Required for adevice that cannot identify itself. Additional information:

probe() Entry Point on page 94 probe() Entry Point (SCSI Target Drivers) on page 327

Kernel Statistics EntryPoints

ks_update(9E) Optional Updates kstat2(9S) data dynamically. Additional information:Kernel Statistics on page 554

Power Management EntryPoint

power(9E) Required Sets the power level of a device. If not used, set to NULL. Additionalinformation: power() Entry Point on page 213

System Quiesce Entry Point

quiesce(9E) SeeDescription

Quiesces a device so that the device no longer generates interrupts ormodifies or accesses memory.

Miscellaneous Entry Points

prop_op(9E) SeeDescription

Reports driver property information. Required unlessddi_prop_op(9F) is substituted. Additional information:

Creating and Updating Properties on page 68 prop_op() Entry Point on page 71

dump(9E) SeeDescription

Dumps memory to a device during system failure. Required forany device that is to be used as the dump device during a panic.Additional information:

dump() Entry Point (Block Drivers) on page 316 Dump Handling on page 341



http://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Eu-info-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Eattach-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Edetach-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Egetinfo-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Eprobe-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Eks-update-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Skstat2-9shttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Epower-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Equiesce-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Eprop-op-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Fddi-prop-op-9fhttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Edump-9e



identify(9E) Obsolete Do not use this entry point. Assign nulldev(9F) to this entry point inthe dev_ops structure.

Entry Points for Block Device Drivers

Devices that support a file system are known as block devices. Drivers written for these devicesare known as block device drivers. Block device drivers take a file system request, in the formof a buf(9S) structure, and issue the I/O operations to the disk to transfer the specified block.The main interface to the file system is the strategy(9E) routine. See Chapter 16, Drivers forBlock Devices for more information.

A block device driver can also provide a character driver interface to enable utility programsto bypass the file system and to access the device directly. This device access is commonlyreferred to as the raw interface to a block device.

The following table lists additional entry points that can be used by block device drivers. Seealso Entry Points Common to All Drivers on page 29.

TABLE 2 Additional Entry Points for Block Drivers

Entry Point Usage Description

aread(9E) Optional Performs an asynchronous read. Drivers that do not support anaread() entry point should use the nodev(9F) error return function.Additional information:

Differences Between Synchronous and Asynchronous I/O on page 277

DMA Transfers (Asynchronous) on page 281

awrite(9E) Optional Performs an asynchronous write. Drivers that do not support anawrite() entry point should use the nodev(9F) error return function.Additional information:

Differences Between Synchronous and Asynchronous I/O on page 277

DMA Transfers (Asynchronous) on page 281

print(9E) Required Displays a driver message on the system console. Additionalinformation: print() Entry Point (Block Drivers) on page 317

strategy(9E) Required Perform block I/O. Additional information:

Canceling DMA Callbacks on page 171 DMA Transfers (Synchronous) on page 280 strategy() Entry Point on page 283 DMA Transfers (Asynchronous) on page 281 General Flow of Control on page 321



33

http://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Fnulldev-9fhttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Sbuf-9shttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Estrategy-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Earead-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Fnodev-9fhttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Eawrite-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Fnodev-9fhttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Eprint-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Estrategy-9e


Entry Point Usage Description x86 Target Driver Configuration Properties on page 396

Entry Points for Character Device Drivers

Character device drivers normally perform I/O in a byte stream. Examples of devices that usecharacter drivers include tape drives and serial ports. Character device drivers can also provideadditional interfaces not present in block drivers, such as I/O control (ioctl) commands,memory mapping, and device polling. See Chapter 15, Drivers for Character Devices formore information.

The main task of any device driver is to perform I/O, and many character device drivers dowhat is called byte-stream or character I/O. The driver transfers data to and from the devicewithout using a specific device address. This type of transfer is in contrast to block devicedrivers, where part of the file system request identifies a specific location on the device.

The read(9E) and write(9E) entry points handle byte-stream I/O for standard character drivers.See I/O Request Handling on page 275 for more information.

The following table lists additional entry points that can be used by character device drivers.For other entry points, see Entry Points Common to All Drivers on page 29.

TABLE 3 Additional Entry Points for Character Drivers


chpoll(9E) Optional Polls events for a non-STREAMS character driver. Additionalinformation: Multiplexing I/O on File Descriptors on page 285

ioctl(9E) Optional Performs a range of I/O commands for character drivers. ioctl()routines must make sure that user data is copied into or out of thekernel address space explicitly using copyin(9F), copyout(9F),ddi_copyin(9F), and ddi_copyout(9F), as appropriate. Additionalinformation:

ioctl() Entry Point (Character Drivers) on page 288 Well Known ioctl Interfaces on page 636

read(9E) Required Reads data from a device. Additional information:

Vectored I/O on page 275 Differences Between Synchronous and Asynchronous I/

O on page 277 Programmed I/O Transfers on page 278 DMA Transfers (Synchronous) on page 280 General Flow of Control on page 321

segmap(9E) Optional Maps device memory into user space. Additional information:



http://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Eread-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Ewrite-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Echpoll-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Eioctl-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Fcopyin-9fhttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Fcopyout-9fhttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Fddi-copyin-9fhttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Fddi-copyout-9fhttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Eread-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Esegmap-9e


Entry Point Usage Description Exporting the Mapping on page 179 Allocating Kernel Memory for User Access on page 186 Associating User Mappings With Driver

Notifications on page 202

write(9E) Required Writes data to a device. Additional information:

Device Access Functions on page 112 Vectored I/O on page 275 Differences Between Synchronous and Asynchronous I/

O on page 277 Programmed I/O Transfers on page 278 DMA Transfers (Synchronous) on page 280 General Flow of Control on page 321

Entry Points for STREAMS Device DriversSTREAMS is a separate programming model for writing a character driver. Devices thatreceive data asynchronously, such as terminal and network devices, are suited to a STREAMSimplementation. STREAMS device drivers must provide the loading and autoconfigurationsupport described in Chapter 6, Driver Autoconfiguration. See the STREAMS ProgrammingGuide for additional information on how to write STREAMS drivers.

The following table lists additional entry points that can be used by STREAMS device drivers.For other entry points, see Entry Points Common to All Drivers on page 29 and EntryPoints for Character Device Drivers on page 34.

TABLE 4 Entry Points for STREAMS Drivers


put(9E) SeeDescription

Coordinates the passing of messages from one queue to the nextqueue in a stream. Required, except for the side of the driver thatreads data. Additional information: STREAMS Programming Guide

srv(9E) Required Manipulate messages in a queue. Additional information: STREAMSProgramming Guide

Entry Points for Memory Mapped Devices

For certain devices, such as frame buffers, providing application programs with direct access todevice memory is more efficient than byte-stream I/O. Applications can map device memoryinto their address spaces using the mmap(2) system call. To support memory mapping, devicedrivers implement segmap(9E) and devmap(9E) entry points. For information on devmap(9E),



35

http://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Ewrite-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E37838-01&id=STREAhttp://www.oracle.com/pls/topic/lookup?ctx=E37838-01&id=STREAhttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Eput-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E37838-01&id=STREAhttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Esrv-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E37838-01&id=STREAhttp://www.oracle.com/pls/topic/lookup?ctx=E37838-01&id=STREAhttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN2mmap-2http://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Esegmap-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Edevmap-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Edevmap-9e


see Chapter 10, Mapping Device and Kernel Memory. For information on segmap(9E), seeChapter 15, Drivers for Character Devices.

Drivers that define the devmap(9E) entry point usually do not define read(9E) and write(9E)entry points, because application programs perform I/O directly to the devices after callingmmap(2).

The following table lists additional entry points that can be used by character device driversthat use the devmap framework to perform memory mapping. For other entry points, seeEntry Points Common to All Drivers on page 29 and Entry Points for Character DeviceDrivers on page 34.

TABLE 5 Entry Points for Character Drivers That Use devmap for Memory Mapping


devmap(9E) Required Validates and translates virtual mapping for a memory-mapped device. Additional information: Exporting theMapping on page 179

devmap_access(9E) Optional Notifies drivers when an access is made to a mapping with validationor protection problems. Additional information: devmap_access()Entry Point on page 195

devmap_contextmgt(9E) Required Performs device context switching on a mapping. Additionalinformation: devmap_contextmgt() Entry Point on page 197

devmap_dup(9E) Optional Duplicates a device mapping. Additional information:devmap_dup() Entry Point on page 198

devmap_map(9E) Optional Creates a device mapping. Additional information: devmap_map()Entry Point on page 194

devmap_unmap(9E) Optional Cancels a device mapping. Additional information:devmap_unmap() Entry Point on page 200

Entry Points for Network Device Drivers

See Table 18, GLDv3 Interfaces, on page 420 for a list of entry points for networkdevice drivers that use the Generic LAN Driver version 3 (GLDv3) framework. For moreinformation, see GLDv3 Network Device Driver Framework on page 399 and GLDv3MAC Registration Functions on page 400 in Chapter 19, Drivers for Network Devices.

Entry Points for SCSI HBA Drivers

The following table lists additional entry points that can be used by SCSI HBA device drivers.For information on the SCSI HBA transport structure, see scsi_hba_tran(9S). For other



http://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Esegmap-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Edevmap-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Eread-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Ewrite-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN2mmap-2http://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Edevmap-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Edevmap-access-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Edevmap-contextmgt-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Edevmap-dup-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Edevmap-map-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Edevmap-unmap-9ehttp://www.oracle.com/pls/topic/lookup?ctx=E88353-01&id=REFMAN9Sscsi-hba-tran-9s


entry points, see Entry Points Common to All Drivers on page 29 and Entry Points forCharacter Device Drivers on page 34.

TABLE 6 Additional Entry Points for SCSI HBA Drivers


tran_abort(9E) Required Aborts a specified SCSI command that has been transported to aSCSI Host Bus Adapter (HBA) driver. Additional information:tran_abort() Entry Point on page 391

tran_bus_reset(9E) Optional Resets a SCSI bus. Additional information: tran_bus_reset()Entry Point on page 391

tran_destroy_pkt(9E) Required Frees resources that are allocated for a SCSI packet. Additionalinformation: tran_destroy_pkt() Entry Point on page 376

tran_dmafree(9E) Required Frees DMA resources that have been allocated for a SCSIpacket. Additional information: tran_dmafree() EntryPoint on page 377

tran_getcap(9E) Required Gets the current value of a specific capability that is provided bythe HBA driver. Additional information: tran_getcap() EntryPoint on page 385

tran_init_pkt(9E) Required Allocate and initialize resources for a SCSI packet. Additionalinformation: Resource Allocation on page 368

tran_quiesce(9E) Optional Stop all activity on a SCSI b

Documents

docs.oracle.com Draft 2018-01-30-16:08:43-08:00 Using This Documentation ................................................................................ 23 I Designing Device Drivers