IRIX™ Device Driver Programmer's Guide
Total Page:16
File Type:pdf, Size:1020Kb
IRIX™ Device Driver Programmer’s Guide Document Number 007-0911-090 CONTRIBUTORS Written by David Cortesi Illustrated by Dany Galgani Significant engineering contributions by (in alphabetical order): Rich Altmaier, Peter Baran, Brad Eacker, Ben Fathi, Steve Haehnichen, Bruce Johnson, Tom Lawrence, Greg Limes, Ben Mahjoor, Charles Marker, Dave Olson, Bhanu Prakash, James Putnam, Sarah Rosedahl, Brett Rudley, Deepinder Setia, Adam Sweeney, Michael Wang, Len Widra, Daniel Yau. Beta test contributions by: Jeff Stromberg of GeneSys St Peter’s Basilica image courtesy of ENEL SpA and InfoByte SpA. Disk Thrower image courtesy of Xavier Berenguer, Animatica. © 1996-1997, Silicon Graphics, Inc.— All Rights Reserved The contents of this document may not be copied or duplicated in any form, in whole or in part, without the prior written permission of Silicon Graphics, Inc. RESTRICTED RIGHTS LEGEND Use, duplication, or disclosure of the technical data contained in this document by the Government is subject to restrictions as set forth in subdivision (c) (1) (ii) of the Rights in Technical Data and Computer Software clause at DFARS 52.227-7013 and/or in similar or successor clauses in the FAR, or in the DOD or NASA FAR Supplement. Unpublished rights reserved under the Copyright Laws of the United States. Contractor/manufacturer is Silicon Graphics, Inc., 2011 N. Shoreline Blvd., Mountain View, CA 94043-1389. Silicon Graphics, the Silicon Graphics logo, CHALLENGE, Indigo, Indy, and Onyx are registered trademarks and Crimson, Indigo2, Indigo2 Maximum Impact, IRIS InSight, IRIX, O2, Origin200, Origin2000, POWER CHALLENGE, POWER Channel, POWER Indigo2, and POWER Onyx are trademarks of Silicon Graphics, Inc. MIPS, R4000, R8000 are registered trademarks and R10000 is a trademark of MIPS Technologies, Inc. UNIX is a trademark of SCO. Sun and SunOS are trademarks of Sun Microsystems, Inc. MC6800, MC68000, and VERSAbus are trademarks of Motorola Corporation. IBM is a trademark of International Business Machines. Intel is a trademark of Intel Corporation. X Window System is a trademark of Massachusetts Institute of Technology. IRIX™ Device Driver Programmer’s Guide Document Number 007-0911-090 Contents List of Examples xxi List of Figures xxv List of Tables xxvii About This Guide xxxi What You Need to Know xxxi What This Guide Contains xxxii Other Sources of Information xxxiii Developer Program xxxiii Internet Resources xxxiii Standards Documents xxxiv Important Reference Pages xxxiv Additional Reading xxxv Conventions Used in This Guide xxxvi iii Contents PART I IRIX Device Integration 1. Physical and Virtual Memory 3 CPU Access to Memory and Devices 4 CPU Modules 4 CPU Access to Memory 5 Processor Operating Modes 7 Virtual Address Mapping 7 Address Space Creation 8 Address Exceptions 8 CPU Access to Device Registers 9 Direct Memory Access 10 PIO Addresses and DMA Addresses 11 Cache Use and Cache Coherency 13 The 32-Bit Address Space 15 Segments of the 32-bit Address Space 15 Virtual Address Mapping 17 User Process Space—kuseg 17 Kernel Virtual Space—kseg2 18 Cached Physical Memory—kseg0 18 Uncached Physical Memory—kseg1 18 The 64-Bit Address Space 19 Segments of the 64-Bit Address Space 19 Compatibility of 32-Bit and 64-Bit Spaces 21 Virtual Address Mapping 21 User Process Space—xkuseg 22 Supervisor Mode Space—xksseg 22 Kernel Virtual Space—xkseg 23 Cache-Controlled Physical Memory—xkphys 23 iv Contents Address Space Usage in Origin2000 Systems 25 User Process Space and Kernel Virtual Space 25 Uncached and Special Address Spaces 25 Cached Access to Physical Memory 26 Uncached Access to Memory 28 Synchronization Access to Memory 28 Device Driver Use of Memory 30 Allowing for 64-Bit Mode 30 Memory Use in User-Level Drivers 31 Memory Use in Kernel-Level Drivers 32 2. Device Configuration 35 Device Special Files 36 Devices as Files 36 Block and Character Device Access 36 Multiple Device Names 37 Major Device Number 38 Minor Device Number 39 Creating Conventional Device Names 40 Hardware Graph 41 UNIX Hardware Assumptions, Old and New 42 Hardware Graph Features 43 /hw Filesystem 46 Driver Interface to Hwgraph 47 Hardware Inventory 48 Using the Hardware Inventory 48 Creating an Inventory Entry 51 Using ioconfig for Global Controller Numbers 51 Configuration Files 55 Master Configuration Database 55 Kernel Configuration Files 56 System Tuning Parameters 58 X Display Manager Configuration 58 v Contents 3. Device Control Software 59 User-Level Device Control 59 PCI Mapping Support 60 EISA Mapping Support 60 VME Mapping Support 60 User-Level DMA From the VME Bus 61 User-Level Control of SCSI Devices 61 Managing External Interrupts 62 User-Level Interrupt Management 62 Kernel-Level Device Control 63 Kinds of Kernel-Level Drivers 63 Typical Driver Operations 63 Upper and Lower Halves 71 Layered Drivers 73 Combined Block and Character Drivers 73 Drivers for Multiprocessors 74 Loadable Drivers 75 PART II Device Control From Process Space 4. User-Level Access to Devices 79 PCI Programmed I/O 80 Mapping a PCI Device Into Process Address Space 80 PCI Device Special Files 80 Using mmap() With PCI Devices 82 PCI Bus Hardware Errors 83 PCI PIO Example 83 EISA Programmed I/O 84 Mapping an EISA Device Into Memory 85 EISA PIO Bandwidth 87 VME Programmed I/O 88 Mapping a VME Device Into Process Address Space 88 VME PIO Access 91 vi Contents VME User-Level DMA 92 Using the DMA Library Functions 92 5. User-Level Access to SCSI Devices 95 Overview of the dsreq Driver 96 Generic SCSI Device Special Files 96 Major and Minor Device Numbers in /dev/scsi 97 Form of Filenames in /dev/scsi 97 Creating Additional Names in /dev/scsi 98 Relationship to Other Device Special Files 99 The dsreq Structure 99 Values for ds_flags 101 Data Transfer Options 102 Return Codes and Status Values 103 Testing the Driver Configuration 106 Using the Special DS_RESET and DS_ABORT Calls 107 Using DS_ABORT 107 Using DS_RESET 107 Using dslib Functions 107 dslib Functions 108 Using dsopen() and dsclose() 109 Issuing a Request With doscsireq() 110 SCSI Utility Functions 110 Using Command-Building Functions 113 Example dslib Program 120 6. Control of External Interrupts 129 External Interrupts in Challenge and Onyx Systems 130 Generating Outgoing Signals 130 Responding to Incoming External Interrupts 131 External Interrupts In Origin2000 and Origin200 135 Generating Outgoing Signals 136 Responding to Incoming External Interrupts 138 vii Contents 7. User-Level Interrupts 141 Overview of ULI 141 The User Level Interrupt Handler 141 Restrictions on the ULI Handler 142 Planning for Concurrency 143 Using Multiple Devices 144 Setting Up 144 Opening the Device Special File 144 Locking the Program Address Space 145 Registering the Interrupt Handler 145 Interacting With the Handler 147 Sample Program 149 PART III Kernel-Level Drivers 8. Structure of a Kernel-Level Driver 155 Summary of Driver Structure 157 Entry Point Naming and lboot 157 Entry Point Summary 159 Driver Flag Constant 162 Flag D_MP 163 Flag D_MT 163 Flag D_WBACK 163 Flag D_OLD Not Supported 164 Initialization Entry Points 164 When Initialization Is Performed 164 Entry Point init() 165 Entry Point edtinit() 165 Entry Point start() 166 Entry Point reg() 167 Attach and Detach Entry Points 167 Entry Point attach() 167 Entry Point detach() 170 viii Contents Open and Close Entry Points 171 Entry Point open() 171 Entry Point close() 174 Control Entry Point 175 Choosing the Command Numbers 176 Supporting 32-Bit and 64-Bit Callers 176 User Return Value 176 Data Transfer Entry Points 176 Entry Points read() and write() 177 Entry Point strategy() 179 Poll Entry Point 180 Use and Operation of poll(2) 180 Entry Point poll() 181 Memory Map Entry Points 182 Concepts and Use of mmap() 183 Entry Point map() 184 Entry Point mmap() 186 Entry Point unmap() 187 Interrupt Entry Point and Handler 188 Associating Interrupt to Driver 188 Interrupt Handler Operation 189 Interrupts as Threads 190 Mutual Exclusion 191 Interrupt Performance and Latency 192 Support Entry Points 192 Entry Point unreg() 192 Entry Point unload() 193 Entry Point halt() 194 Entry Point size() 194 Entry Point print() 194 Handling 32-Bit and 64-Bit Execution Models 195 ix Contents Designing for Multiprocessor Use 196 The Multiprocessor Environment 196 Synchronizing Within Upper-Half Functions 198 Coordinating Upper-Half and Interrupt Entry Points 199 Converting a Uniprocessor Driver 201 Example Conversion Problem 201 9. Device Driver/Kernel Interface 203 Important Data Types 204 Hardware Graph Types 204 Address Types 205 Address/Length Lists 205 Structure uio_t 207 Structure buf_t 208 Lock and Semaphore Types 210 Device Number Types 211 Important Header Files 213 Kernel Memory Allocation 215 General-Purpose Allocation 215 Allocating Memory in Specific Nodes of a Origin2000 System 216 Allocating Objects of Specific Kinds 217 Transferring Data 219 General Data Transfer 219 Transferring Data Through a uio_t Object 221 Managing Virtual and Physical Addresses 222 Managing Mapped Memory 222 Working With Page and Sector Units 223 Using Address/Length Lists 224 Setting Up a DMA Transfer 228 Testing Device Physical Addresses 232 Hardware Graph Management 233 Interrogating the hwgraph 233 Extending the hwgraph 234 Attaching Information to Vertexes 240 x Contents User Process Administration 243 Sending a Process Signal 244 Waiting and Mutual Exclusion 245 Mutual Exclusion Compared to Waiting 245 Basic Locks 246 Long-Term Locks 248 Reader/Writer Locks 251 Priority Level Functions 253 Waiting for Time to Pass