IRIX® Device Driver Programmer's Guide
Total Page:16
File Type:pdf, Size:1020Kb
IRIX® Device Driver Programmer’s Guide Document Number 007-0911-210 CONTRIBUTORS Written by David Cortesi, John Raithel, Bill Tuthill, and Anita Manders UpdatedbyJulieBoneyandStevenLevine Illustrated by Dany Galgani, Cheri Brown, and Chrystie Danzer Production by Karen Jacobson COPYRIGHT © 1998-2003 Silicon Graphics, Inc. All rights reserved; provided portions may be copyright in third parties, as indicated elsewhere herein. No permission is granted to copy, distribute, or create derivative works from the contents of this electronic documentation in any manner, in whole or in part, without the prior written permission of Silicon Graphics, Inc. LIMITED RIGHTS LEGEND The electronic (software) version of this document was developed at private expense; if acquired under an agreement with the USA government or any contractor thereto, it is acquired as "commercial computer software" subject to the provisions of its applicable license agreement, as specified in (a) 48 CFR 12.212 of the FAR; or, if acquired for Department of Defense units, (b) 48 CFR 227-7202 of the DoD FAR Supplement; or sections succeeding thereto. Contractor/manufacturer is Silicon Graphics, Inc., 1600 Amphitheatre Pkwy 2E, Mountain View, CA 94043-1351. TRADEMARKS AND ATTRIBUTIONS Silicon Graphics, SGI, the SGI logo, Challenge, Indigo, IRIS, IRIX, O2, Octane, Onyx, Onyx2, and Origin are registered trademarks and Indigo2,Indigo2 Maximum Impact, IRIS InSight, Power Challenge, Power Channel, Power Indigo2,PowerOnyx,andREACT/proare trademarks of Silicon Graphics, Inc., in the United States and/or other countries worldwide. Indy is a registered trademark, used under license in the United States and owned by Silicon Graphics,Inc.inothercountriesworldwide. IBM is a trademark of International Business Machines Corporation. Intel is a registered trademark of Intel Corporation. MC6800, MC68000, and VERSAbus are trademarks of Motorola Corporation. MIPS, R4000, and R8000 are registered trademarks and R5000 and R10000 are trademarks of MIPS Technologies, Inc., used under license by Silicon Graphics, Inc. Sun and SunOS are trademarks of Sun Microsystems, Inc. UNIX, the X device, and X Window System are registered trademarks of the Open Group in the United States and other countries. Cover design by Sarah Bolles, Sarah Bolles Design, and Dany Galgani, SGI Technical Publications. New Features in This Guide This rewrite of the IRIX Device Driver Programmer’s Guide supports the IRIX 6.5.22 release. New Features Documented This manual includes information on using a PCI driver to interrogate a PCI Bus in “Interrogating a PCI Bus” on page 757. 007-0911-210 iii Record of Revision Version Description 120 July 1998 Incorporates information for the IRIX 6.5 release. 130 October 1998 Incorporates information for the IRIX 6.5.2 release. 140 February 1999 Incorporates information for the IRIX 6.5.3 release. 150 April 2000 Incorporates information for the IRIX 6.5.8 release. 160 June 2000 Incorporates information for the IRIX 6.5.9 release. 170 December 2000 Incorporates information for the IRIX 6.5.11 release. 180 May 2001 Incorporates information for the IRIX 6.5.12 release. 190 July 2002 Incorporates information for the IRIX 6.5.17 release. 200 August 2003 Incorporates information for the IRIX 6.5.21 release. 210 November 2003 Incorporates information for the IRIX 6.5.22 release. 007-0911-210 v Contents Examples ........................xxvii Figures .........................xxix Tables .........................xxxi WhatYouNeedtoKnowtoWriteDeviceDrivers............xxxvii UpdatingDeviceDriversfromPreviousReleasestoIRIX6.5 . .xxxviii UpdatingaDeviceDriverfromIRIX6.2..............xxxviii UpdatingaDeviceDriverfromIRIX6.3..............xxxix UpdatingaDeviceDriverfromIRIX6.4..............xxxix WhatThisGuideContains....................xl OtherSourcesofInformation...................xli DeveloperProgram.....................xli InternetResources.....................xli StandardsDocuments....................xlii Importantmanpages.....................xlii AdditionalReading.................... xliii ReaderComments...................... xliv 007-0911-210 vii Contents PART I IRIX Device Integration 1. Physical and Virtual Memory ...................3 CPUAccesstoMemoryandDevices..................3 CPUModules.......................4 CPUAccesstoMemory....................5 ProcessorOperatingModes...................6 VirtualAddressMapping...................6 AddressSpaceCreation....................7 AddressExceptions.....................8 CPUAccesstoDeviceRegisters..................8 DirectMemoryAccess....................10 PIOAddressesandDMAAddresses................11 CacheUseandCacheCoherency.................13 The32-BitAddressSpace.....................14 Segmentsofthe32-bitAddressSpace................15 VirtualAddressMapping...................17 UserProcessSpace—kuseg...................17 KernelVirtualSpace—kseg2...................18 CachedPhysicalMemory—kseg0.................18 UncachedPhysicalMemory—kseg1................18 The64-BitAddressSpace.....................19 Segmentsofthe64-BitAddressSpace................19 Compatibilityof32-Bitand64-BitSpaces...............21 64-BitAddressFormat....................21 VirtualAddressMapping...................22 UserProcessSpace—xkuseg...................23 SupervisorModeSpace—xksseg.................23 KernelVirtualSpace—xkseg...................23 PhysicalAddress......................24 Cache-ControlledPhysicalMemory—xkphys..............24 viii 007-0911-210 Contents Address Space Usage in SGI Origin 2000 Systems. 26 UserProcessSpaceandKernelVirtualSpace..............26 UncachedandSpecialAddressSpaces................26 CachedAccesstoPhysicalMemory................27 UncachedAccesstoMemory..................29 SynchronizationAccesstoMemory................29 DeviceDriverUseofMemory...................31 Allowingfor64-BitMode...................31 MemoryUseinUser-LevelDrivers.................32 MemoryUseinKernel-LevelDrivers................34 2. Device Configuration .....................37 DeviceSpecialFiles......................37 DevicesasFiles......................38 BlockandCharacterDeviceAccess.................38 MultipleDeviceNames....................39 MajorDeviceNumber....................40 MinorDeviceNumber....................41 CreatingConventionalDeviceNames................42 HardwareGraph.......................44 UNIXHardwareAssumptions,OldandNew..............44 HardwareGraphFeatures...................45 /hwFilesystem......................48 DriverInterfacetoHwgraph..................49 HardwareInventory......................50 UsingtheHardwareInventory..................50 CreatinganInventoryEntry...................53 UsingioconfigforGlobalControllerNumbers.............53 ConfigurationFiles......................57 MasterConfigurationDatabase..................57 KernelConfigurationFiles...................58 SystemTuningParameters...................61 XDisplayManagerConfiguration.................61 007-0911-210 ix Contents 3. Device Control Software .....................63 User-LevelDeviceControl....................63 PCIMappingSupport.....................64 EISAMappingSupport....................64 VMEMappingSupport....................65 User-LevelDMAFromtheVMEBus................65 User-LevelControlofSCSIDevices.................65 ManagingExternalInterrupts..................66 Kernel-LevelDeviceControl....................66 KindsofKernel-LevelDrivers..................66 TypicalDriverOperations...................67 Upper and Lower Halves . 75 LayeredDrivers......................77 CombinedBlockandCharacterDrivers...............77 DriversforMultiprocessors...................77 LoadableDrivers......................78 PART II Device Control From Process Space 4. User-Level Access to Devices ...................83 PCIProgrammedI/O......................83 MappingaPCIDeviceIntoProcessAddressSpace............84 PCIDeviceSpecialFiles....................84 Usingmmap()WithPCIDevices.................86 PCIBusHardwareErrors....................87 PCIPIOExample......................87 EISAProgrammedI/O.....................89 MappinganEISADeviceIntoMemory................89 EISAPIOBandwidth.....................91 VMEProgrammedI/O.....................92 MappingaVMEDeviceIntoProcessAddressSpace............92 VMEPIOAccess......................95 VMEUser-LevelDMA......................96 UsingtheDMALibraryFunctions.................97 x 007-0911-210 Contents 5. User-LevelAccess toSCSI Devices..................99 OverviewofthedsreqDriver...................100 GenericSCSIDeviceSpecialFiles..................100 MajorandMinorDeviceNumbersin/dev/scsi.............101 FormofFilenamesin/dev/scsi..................101 CreatingAdditionalNamesin/dev/scsi...............102 RelationshiptoOtherDeviceSpecialFiles...............103 ThedsreqStructure......................103 Valuesfords_flags.....................105 DataTransferOptions....................107 ReturnCodesandStatusValues.................107 TestingtheDriverConfiguration..................110 UsingtheSpecialDS_RESETandDS_ABORTCalls.............111 UsingDS_ABORT.....................111 UsingDS_RESET......................112 UsingdslibFunctions......................112 dslibFunctions......................112 Usingdsopen()anddsclose()..................113 IssuingaRequestWithdoscsireq().................115 SCSIUtilityFunctions....................115 UsingCommand-BuildingFunctions................117 ExampledslibProgram.....................124 6. Control of External Interrupts ...................135 ExternalInterruptsinChallengeandOnyxSystems.............135