Wdd-Ebook.Pdf

The illumos Writing Device Drivers Sun Microsystems, Inc. has intellectual property rights relating to technology embodied in the product that is described in this document. In particular, and without limitation, these intellectual property rights may include one or more U.S. patents or pending patent applications in the U.S. and in other countries. U.S. Government Rights – Commercial software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions of the FAR and its supplements. This distribution may include materials developed by third parties. Parts of the product may be derived from Berkeley BSD systems, licensed from the University of California. UNIX is a registered trademark in the U.S. and other countries, exclusively licensed through X/Open Company, Ltd. Sun, Sun Microsystems, the Sun logo, the Solaris logo, the Java Coffee Cup logo, docs.sun.com, Java, and Solaris are trademarks or registered trademarks of Sun Microsystems, Inc. or its subsidiaries in the U.S. and other countries. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. in the U.S. and other countries. Products bearing SPARC trademarks are based upon an architecture developed by Sun Microsystems, Inc. The OPEN LOOK and Sun™ Graphical User Interface was developed by Sun Microsystems, Inc. for its users and licensees. Sun acknowledges the pioneering efforts of Xerox in researching and developing the concept of visual or graphical user interfaces for the computer industry. Sun holds a non-exclusive license from Xerox to the Xerox Graphical User Interface, which license also covers Sun’s licensees who implement OPEN LOOK GUIs and otherwise comply with Sun’s written license agreements. Products covered by and information contained in this publication are controlled by U.S. Export Control laws and may be subject to the export or import laws in other countries. Nuclear, missile, chemical or biological weapons or nuclear maritime end uses or end users, whether direct or indirect, are strictly prohibited. Export or reexport to countries subject to U.S. embargo or to entities identified on U.S. export exclusion lists, including, but not limited to, the denied persons and specially designated nationals lists is strictly prohibited. DOCUMENTATION IS PROVIDED “AS IS” AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTA- TIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID. Copyright © 2008 Sun Microsystems, Inc. Contents Contents i List of Figures xvii List of Tables xviii I Designing Device Drivers for the illumos Platform1 1 Overview of illumos Device Drivers5 1.1 Device Driver Basics . .5 What Is a Device Driver? . .5 What Is a Device Driver Entry Point? . .6 1.2 Device Driver Entry Points . .6 Entry Points Common to All Drivers . .7 Device Access Entry Points . .7 Loadable Module Entry Points . .7 Autoconfiguration Entry Points . .7 Kernel Statistics Entry Points . .8 Power Management Entry Point . .8 Summary of Common Entry Points . .8 Entry Points for Block Device Drivers . 10 Entry Points for Character Device Drivers . 11 Entry Points for STREAMS Device Drivers . 12 Entry Points for Memory Mapped Devices . 13 Entry Points for the Generic LAN Device (GLD) Driver . 14 Entry Points for SCSI HBA Drivers . 14 Entry Points for PC Card Drivers . 16 1.3 Considerations in Device Driver Design . 16 DDI/DKI Facilities . 16 Device IDs . 16 Device Properties . 16 Interrupt Handling . 17 Callback Functions . 17 Software State Management . 17 Programmed I/O Device Access . 18 Direct Memory Access (DMA) . 18 Layered Driver Interfaces . 18 Driver Context . 18 i CONTENTS Returning Errors . 19 Dynamic Memory Allocation . 19 Hotplugging . 20 2 illumos Kernel and Device Tree 21 2.1 What Is the Kernel? . 21 Multithreaded Execution Environment . 22 Virtual Memory . 23 Devices as Special Files . 23 DDI/DKI Interfaces . 23 2.2 Overview of the Device Tree . 24 Device Tree Components . 24 Displaying the Device Tree . 25 libdevinfo Library . 26 prtconf Command . 26 /devices Directory . 27 Binding a Driver to a Device . 28 Generic Device Names . 28 3 Multithreading 31 3.1 Locking Primitives . 31 Storage Classes of Driver Data . 31 Mutual-Exclusion Locks . 32 Setting Up Mutexes . 32 Using Mutexes . 32 Readers/Writer Locks . 33 Semaphores . 33 3.2 Thread Synchronization . 34 Condition Variables in Thread Synchronization . 34 Initializing Condition Variables . 34 Waiting for the Condition . 35 Signaling the Condition . 35 cv_wait and cv_timedwait Functions . 36 cv_wait_sig Function . 37 cv_timedwait_sig Function . 37 3.3 Choosing a Locking Scheme . 37 Potential Locking Pitfalls . 38 Threads Unable to Receive Signals . 38 4 Properties 41 4.1 Device Properties . 41 Device Property Names . 42 Creating and Updating Properties . 42 Looking Up Properties . 42 prop_op Entry Point . 44 5 Managing Events and Queueing Tasks 47 5.1 Managing Events . 47 Introduction to Events . 47 ii Contents Using ddi_log_sysevent to Log Events . 48 ddi_log_sysevent Syntax . 48 Sample Code for Logging Events . 49 Defining Event Attributes . 50 5.2 Queueing Tasks . 53 Introduction to Task Queues . 53 Task Queue Interfaces . 54 Using Task Queues . 55 Observing Task Queues . 55 Task Queue Kernel Statistics Counters . 55 Task Queue DTrace SDT Probes . 56 6 Driver Autoconfiguration 59 6.1 Driver Loading and Unloading . 59 6.2 Data Structures Required for Drivers . 60 modlinkage Structure . 60 modldrv Structure . 61 dev_ops Structure . 61 cb_ops Structure . 62 6.3 Loadable Driver Interfaces . ..

Load more