IRIX® 6.3 for O2™ Device Driver Programming Guide Document Number 007-3443-002 CONTRIBUTORS Written by David Cortesi Illustrated by Dany Galgani Edited by Christina Cary 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, 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. © 1998, 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 and the Silicon Graphics logo, and the terms CHALLENGE, Crimson, Indigo, Indigo2, Indigo2 Maximum Impact, Indy, IRIX, O2, Onyx, Origin2000, POWER CHALLENGE, POWER Channel, POWER Indigo2, and POWER Onyx are trademarks of Silicon Graphics, Inc. MIPS, R4000, R8000, and R10000 are trademarks of MIPS Technologies, Inc. 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. UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company, Ltd. X Window System is a trademark of Massachusetts Institute of Technology. IRIX® for O2™ Device Driver Programming Guide Document Number 007-3443-002 Contents List of Examples xvii List of Figures xix List of Tables xxi About This Guide xxv What You Need to Know xxv What This Guide Contains xxvi Other Sources of Information xxvii Developer Program xxvii Internet Resources xxvii Standards Documents xxviii Important Reference Pages xxviii Additional Reading xxix Conventions Used in This Guide xxx PART I IRIX Device Integration 1. Physical and Virtual Memory 3 Physical Address Space 4 Physical Device Addresses 4 Physical Memory Addresses 4 iii : CPU Access to Memory and Devices 5 CPU Modules 5 CPU Access to Memory 6 Processor Operating Modes 8 Virtual Address Mapping 8 Address Space Creation 9 Address Exceptions 9 CPU Access to Device Registers 10 Direct Memory Access 11 PIO Addresses and DMA Addresses 12 Cache Use and Cache Coherency 15 The 32-Bit Address Space 16 Segments of the 32-bit Address Space 16 Virtual Address Mapping 18 User Process Space—kuseg 18 Kernel Virtual Space—kseg2 19 Cached Physical Memory—kseg0 19 Uncached Physical Memory—kseg1 20 The 64-Bit Address Space 20 Segments of the 64-Bit Address Space 20 Compatibility of 32-Bit and 64-Bit Spaces 22 Virtual Address Mapping 22 User Process Space—xkuseg 23 Supervisor Mode Space—xksseg 23 Kernel Virtual Space—xkseg 24 Cache-Controlled Physical Memory—xkphys 24 Device Driver Use of Memory 26 Allowing for 64-Bit Mode 26 Memory Use in User-Level Drivers 27 Memory Use in Kernel-Level Drivers 28 iv : 2. Device Configuration 31 Hardware Inventory 31 Using the Hardware Inventory 32 Creating an Inventory Entry 34 Device Special Files 34 Device Representation 35 Defining Device Names 37 Configuration Files 39 Master Configuration Database 40 System Configuration Files 41 System Tuning Parameters 41 X Display Manager Configuration 41 3. Device Control Software 43 User-Level Device Control 43 EISA Mapping Support 44 VME Mapping Support 44 PCI Mapping Support 45 User-Level DMA From the VME Bus 45 User-Level Control of SCSI Devices 45 Managing External Interrupts 46 User-Level Interrupt Management 46 Memory-Mapped Access to Serial Ports 47 Kernel-Level Device Control 47 Kinds of Kernel-Level Drivers 48 Typical Driver Operations 48 Upper and Lower Halves 56 Layered Drivers 58 Combined Block and Character Drivers 58 Drivers for Multiprocessors 59 Loadable Drivers 59 v : PART II Device Control From Process Space 4. User-Level Access to Devices 63 VME Programmed I/O 64 Mapping a VME Device Into Process Address Space 64 VME PIO Access 67 VME PIO Bandwidth 68 EISA Programmed I/O 68 Mapping an EISA Device Into Memory 69 EISA PIO Bandwidth 71 VME User-Level DMA 72 Using the udmalib Functions 73 Advantages of User DMA 75 DMA Engine Bandwidth 75 Example User DMA Function 76 PCI Programmed I/O 78 Mapping a PCI Device Into Process Address Space 78 5. User-Level Access to SCSI Devices 81 Overview of the dsreq Driver 82 Generic SCSI Device Special Files 82 Major and Minor Device Numbers in /dev/scsi 83 Form of Filenames in /dev/scsi 83 Creating Additional Names in /dev/scsi 84 Relationship to Other Device Special Files 85 The dsreq Structure 85 Values for ds_flags 87 Data Transfer Options 89 Return Codes and Status Values 89 Testing the Driver Configuration 92 Using the Special DS_RESET and DS_ABORT Calls 93 Using DS_ABORT 93 Using DS_RESET 94 vi : Using dslib Functions 94 dslib Functions 94 Using dsopen() and dsclose() 95 Issuing a Request With doscsireq() 97 SCSI Utility Functions 97 Using Command-Building Functions 100 Example dslib Program 107 6. Control of External Interrupts 117 External Interrupts in Challenge and Onyx Systems 118 Generating Outgoing Signals 118 Receiving Incoming External Interrupts 119 7. User-Level Interrupts 125 Overview of ULI 125 The User Level Interrupt Handler 126 Restrictions on the ULI Handler 126 Planning for Concurrency 127 Using Multiple Devices 128 Setting Up 128 Opening the Device Special File 128 Locking the Program Address Space 129 Registering the Interrupt Handler 130 Interacting With the Handler 131 Sample Program 133 PART III Kernel-Level Drivers 8. Structure of a Kernel-Level Driver 139 Summary of Driver Structure 140 Entry Point Naming and lboot 140 Entry Point Summary 142 vii : Driver Flag Constant 145 Flag D_MP 145 Flag D_WBACK 146 Flag D_MT 146 Flag D_OLD 146 Initialization Entry Points 147 When Initialization Is Performed 147 Entry Point init() 148 Entry Point edtinit() 148 Entry Point start() 149 Open and Close Entry Points 150 Entry Point open() 150 Entry Point close() 153 Control Entry Point 154 Choosing the Command Numbers 155 Supporting 32-Bit and 64-Bit Callers 155 User Return Value 155 Data Transfer Entry Points 155 Entry Points read() and write() 155 Entry Point strategy() 157 Poll Entry Point 158 Use and Operation of poll(2) 159 Entry Point poll() 160 Memory Map Entry Points 161 Concepts and Use of mmap() 162 Entry Point map() 163 Entry Point mmap() 165 Entry Point unmap() 166 Interrupt Entry Point 167 Associating Interrupt to Driver 167 Interrupt Handler Operation 167 viii : Support Entry Points 170 Entry Point unload() 170 Entry Point halt() 171 Entry Point size() 172 Entry Point print() 172 Handling 32-Bit and 64-Bit Execution Models 173 Planning for Multiprocessor Use 174 The Multiprocessor Environment 174 Synchronizing Within Upper-Half Functions 176 Coordinating Upper-Half and Interrupt Entry Points 177 Converting a Uniprocessor Driver 178 Example Conversion Problem 179 9. Device Driver/Kernel Interface 181 Important Data Types 182 The Device Number Types 182 Structure uio_t 184 Structure buf_t 185 Lock and Semaphore Types 187 Important Header Files 188 Memory Allocation 189 General-Purpose Allocation 190 Allocating Objects of Specific Kinds 191 Suballocation Functions 193 Transferring Data 194 General Data Transfer 195 Transferring Data Through a uio_t Object 197 Managing Virtual and Physical Addresses 198 Testing Device Physical Addresses 198 Managing Mapped Memory 199 Working With Page and Sector Units 200 Setting Up a DMA Transfer 201 User Process Administration 205 Sending a Process Signal 206 ix : Waiting and Mutual Exclusion 206 Mutual Exclusion Compared to Waiting 207 Basic Locks 208 Long-Term Locks 210 Reader/Writer Locks 213 Priority Level Functions 215 Waiting for Time to Pass 216 Waiting for Memory to Become Available 218 Waiting for Block I/O to Complete 219 Waiting for a General Event 221 Semaphores 224 10. Building and Installing a Driver 227 Defining Device Numbers 228 Selecting a Major Number 228 Selecting Minor Numbers 229 Defining Device Special Files 229 Static Definition of Device Special Files 229 Dynamic Definition of Device Special Files 229 Compiling and Linking 230 Using /var/sysgen/Makefile.kernio 230 Compiler Variables 231 Compile Options, 32-Bit Kernel 232 Compile Options, 64-Bit Kernel 233 Configuring a Nonloadable Driver 234 How Names Are Used in Configuration 234 Placing the Object File in /var/sysgen/boot 235 Describing the Driver in /var/sysgen/master.d 235 Configuring a Kernel 238 Generating a Kernel 239 x : Configuring a Loadable Driver 239 Public Global Variables 239 Compile Options for Loadable Drivers 240 Master File for Loadable Drivers 240 Registration 241 Loading 241 Unloading 242 Configuring for a Dynamic Major Number 243 11. Testing and Debugging a Driver 245 Preparing the System for Debugging 245 Placing symmon