IRIX™ Device Driver Programmer's Guide
Total Page:16
File Type:pdf, Size:1020Kb
IRIX™ Device Driver Programmer’s Guide Document Number 007-0911-060 CONTRIBUTORS Written by David Cortesi Illustrated by Dany Galgani Edited by Christina Cary Production by Gloria Ackley Significant engineering contributions by (in alphabetical order): Rich Altmaier, Brad Eacker, Ben Fathi, Steve Haehnichen, Bruce Johnson, Tom Lawrence, Ben Mahjoor, Charles Marker, Dave Olson, Bhanu Prakash, James Putnam, Sarah Rosedahl, Deepinder Setia, Adam Sweeney, Daniel Yau. Beta test contributions by: Jeff Stromberg of GeneSys Cover design and illustration by Rob Aguilar, Rikk Carey, Dean Hodgkinson, Erik Lindholm, and Kay Maitz © Copyright 1996, 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™, Onyx™, 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. 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-060 Contents List of Examples xxvii List of Figures xxix List of Tables xxxi About This Guide xxxv Audience xxxvi What This Guide Contains xxxvi Other Sources of Information xxxvii Developer Program xxxvii Internet Resources xxxvii Standards Documents xxxviii Important Reference Pages xxxviii Additional Reading xxxix Conventions Used in This Guide xl PART I IRIX Device Integration 1. Physical and Virtual Memory 3 Physical Address Space 4 Device Addresses 4 Memory Addresses 5 iii Contents Addresses of Memory and Devices 5 CPU Modules 5 Interrogating the CPU Type 6 CPU Access to Memory 6 Processor Operating Modes 8 Virtual Address Mapping 8 TLB Misses and TLB Sizes 8 Address Space Creation 9 Address Exceptions 9 CPU Access to Device Registers 10 Direct Memory Access 11 Bus Virtual Addresses 12 Cache Use and Cache Coherency 13 Cache Coherency in Multiprocessors 14 Cache Coherency in Uniprocessors 14 The 32-Bit Address Space 14 Segments of the 32-bit Address Space 15 Virtual Address Mapping 16 User Process Space—kuseg 16 Kernel Virtual Space—kseg2 17 Cached Physical Memory—kseg0 17 Uncached Physical Memory—kseg1 18 The 64-Bit Address Space 18 Segments of the 64-Bit Address Space 18 Compatibility of 32-Bit and 64-Bit Spaces 20 Virtual Address Mapping 20 User Process Space—xkuseg 21 Supervisor Mode Space—xksseg 22 Kernel Virtual Space—xkseg 22 Cache-Controlled Physical Memory—xkphys 22 iv Contents Device Driver Use of Memory 24 Allowing for 64-Bit Mode 24 Memory Use in User-Level Drivers 25 Access Using a Device Model 25 Access Using mmap() 26 Mapped Access Provided by a Device Driver 26 Memory Use in Kernel-Level Drivers 26 Uncached Memory Access in the Challenge and Onyx Series 27 Uncached Memory Access in the IP26 CPU 27 2. Device Configuration 29 Hardware Inventory 29 Using the Hardware Inventory 29 Contents of the Inventory 30 Displaying the Inventory with hinv 30 Testing the Inventory In Software 30 Creating an Inventory Entry 32 Device Special Files 32 Device Representation 33 Block Versus Character 33 Major Device Number 34 Minor Device Number 35 Defining Device Names 35 IRIX Conventional Device Names 36 The Script MAKEDEV 36 Making Device Files 37 Multiple Names for One Device 37 Configuration Files 38 Master Configuration Database 38 System Configuration Files 39 System Tuning Parameters 39 X Display Manager Configuration 40 v Contents 3. Device Control Software 41 User-Level Device Control 41 EISA Mapping Support 42 VME Mapping Support 42 User-Level DMA From the VME Bus 43 User-Level Control of SCSI Devices 43 Managing External Interrupts 43 User-Level Interrupt Management 44 Memory-Mapped Access to Serial Ports 45 Kernel-Level Device Control 45 Kinds of Kernel-Level Drivers 45 Typical Driver Operations 46 Overview of Device Open 46 Overview of Device Control 48 Overview of Programmed Kernel I/O 49 Overview of Memory Mapping 50 Overview of DMA I/O 52 Upper and Lower Halves 54 Driver Upper Half 54 Driver Lower Half 54 Relationship Between Halves 55 Layered Drivers 55 Combined Block and Character Drivers 55 Drivers for Multiprocessors 56 Loadable Drivers 57 vi Contents PART II Device Control From Process Space 4. User-Level Access to VME and EISA 61 VME Programmed I/O 62 Mapping a VME Device Into Process Address Space 62 Learning VME Device Addresses 62 Opening a Device Special File 63 Using the mmap() Function 64 Map Size Limits 64 VME PIO Access 65 VME PIO Bandwidth 66 EISA Programmed I/O 67 Mapping an EISA Device Into Memory 67 Learning EISA Device Addresses 67 Opening a Device Special File 68 Using the mmap() Function 68 EISA PIO Bandwidth 69 VME User-Level DMA 70 Using the udmalib Functions 71 Buffer Allocation for User DMA 71 Allocation of Descriptors 72 Advantages of User DMA 73 DMA Engine Bandwidth 73 Example User DMA Function 74 5. User-Level Access to SCSI Devices 77 Overview of the dsreq Driver 78 Generic SCSI Device Special Files 78 Form of Names in /dev/scsi 79 Names of SCSI Devices on a SCSI Bus 79 Names of SCSI Devices on the Jag (VME Bus) Controller 80 Major and Minor Device Numbers in /dev/scsi 80 Creating Additional Names in /dev/scsi 81 Relationship to Other Device Special Files 81 vii Contents The dsreq Structure 82 Values for ds_flags 83 Data Transfer Options 85 Return Codes and Status Values 85 Testing the Driver Configuration 88 Using the Special DS_RESET and DS_ABORT Calls 89 Using DS_ABORT 89 Using DS_RESET 90 Using dslib Functions 90 dslib Functions 90 Using dsopen() and dsclose() 92 Issuing a Request With doscsireq() 93 SCSI Utility Functions 93 Using filldsreq() 93 Using fillg0cmd() and fillg1cmd() 94 Using ds_vtostr() and ds_ctostr() 95 Using Command-Building Functions 96 inquiry12()—Issue an Inquiry Command 96 modeselect15()—Issue a Group 0 Mode Select Command 96 modesense1a()—Send a Group 0 Mode Sense Command 97 read08() and readextended28()—Issue a Read Command 98 readcapacity25()—Issue a Read Capacity Command 99 requestsense03()—Issue a Request Sense Command 100 reserveunit16() and releaseunit17()—Control Logical Units 100 senddiagnostic1d()—Issue a Send Diagnostic Command 101 testunitready00—Issue a Test Unit Ready Command 102 write0a() and writeextended2a()—Issue a Write Command 102 Example dslib Program 103 viii Contents 6. Control of External Interrupts 113 External Interrupts in Challenge and Onyx Systems 114 Generating Outgoing Signals 114 Receiving Incoming External Interrupts 115 Detecting Invalid External Interrupts 116 Setting the Expected Pulse Width 117 Setting the Stuck Pulse Width 118 Receiving Interrupts 118 7. User-Level Interrupts 121 Overview of ULI 121 The User Level Interrupt Handler 122 Restrictions on the ULI Handler 122 Planning for Concurrency 123 Debugging With Interrupts 123 Declaring Global Variables 123 Using Multiple Devices 124 Setting Up 124 Opening the Device Special File 124 Locking the Program Address Space 125 Registering the Interrupt Handler 126 Registering an External Interrupt Handler 127 Registering a VME Interrupt Handler 127 Interacting With the Handler 128 Achieving Mutual Exclusion 129 Sample Program 129 ix Contents PART III Kernel-Level Drivers 8. Structure of a Kernel-Level Driver 135 Summary of Driver Structure 136 Entry Point Naming and lboot 136 Driver Name Prefix 136 Kernel Switch Tables 137 Entry Point Summary 138 Driver Flag Constant 140 Flag D_MP 141 Flag D_WBACK 141 Flag D_MT 142 Flag D_OLD 142 Initialization Entry Points 143 When Initialization Is Performed 143 Initialization of Loadable Drivers 143 Entry Point init() 144 Entry Point edtinit() 144 Entry Point start() 145 Open and Close Entry Points 146 Entry Point open() 146 Use of the Device Number 147 Use of the Open Type 147 Use of the Open Flag 148 Use of the cred_t Object 148 Saving the Size of a Block Device 149 Saving the User ABI 149 Entry Point close() 149 Control Entry Point 150 Choosing the Command Numbers 151 Supporting 32-Bit and 64-Bit Callers 151 User Return Value 151 x Contents Data Transfer Entry Points 151 Entry Points read() and write() 152 Data Transfer for a PIO Device 152 Calling Entry Point strategy() From Entry Point read() or write() 153 Entry Point strategy() 154 Poll Entry Point 155 Use and Operation of poll(2) 155 Use of pollwakeup() 156 Use of pollwakeup() Without Interrupts 156 Entry Point poll() 156 Memory Map Entry Points 158 Concepts and Use of mmap() 158 Use of mmap() 158 Persistent Mappings 159 Entry Point map() 159 Entry Point mmap() 161 Entry Point unmap() 162 Interrupt