Designing PCI Cards and Drivers for Power Macintosh Computers 030-7650-A Developer Press Apple Computer, Inc. 1996 Thi d t t d ith F M k 4 0 4 Apple Computer, Inc. Helvetica and Palatino are registered LIMITED WARRANTY ON MEDIA AND 1995, 1996 Apple Computer, Inc. trademarks of Linotype Company. REPLACEMENT All rights reserved. Intel is a trademark of Intel Corporation. If you discover physical defects in the No part of this publication may be Internet is a trademark of Digital manual or in the media on which a software reproduced, stored in a retrieval Equipment Corporation. product is distributed, APDA will replace system, or transmitted, in any form or ITC Zapf Dingbats is a registered the media or manual at no charge to you by any means, mechanical, electronic, trademark of International Typeface provided you return the item to be replaced photocopying, recording, or otherwise, Corporation. with proof of purchase to APDA. without prior written permission of Motorola is a registered trademark of ALL IMPLIED WARRANTIES ON THIS Apple Computer, Inc. Printed in the Motorola Corporation. MANUAL, INCLUDING IMPLIED United States of America. NuBus is a trademark of WARRANTIES OF MERCHANTABILITY The Apple logo is a trademark of Texas Instruments. AND FITNESS FOR A PARTICULAR Apple Computer, Inc. PURPOSE, ARE LIMITED IN DURATION OpenBoot and Sun are trademarks of TO NINETY (90) DAYS FROM THE DATE Use of the “keyboard” Apple logo Sun Microsystems, Inc. (Option-Shift-K) for commercial OF THE ORIGINAL RETAIL PURCHASE purposes without the prior written PowerPC is a trademark of OF THIS PRODUCT. International Business Machines consent of Apple may constitute Even though Apple has reviewed this trademark infringement and unfair Corporation, used under license therefrom. manual, APPLE MAKES NO WARRANTY competition in violation of federal and OR REPRESENTATION, EITHER EXPRESS UNIX is a registered trademark of state laws. OR IMPLIED, WITH RESPECT TO THIS Novell, Inc. in the United States and No licenses, express or implied, are MANUAL, ITS QUALITY, ACCURACY, other countries, licensed exclusively granted with respect to any of the MERCHANTABILITY, OR FITNESS FOR A through X/Open Company, Ltd. technology described in this book. PARTICULAR PURPOSE. AS A RESULT, Apple retains all intellectual property Windows is a trademark of Microsoft THIS MANUAL IS SOLD “AS IS,” AND rights associated with the technology Corporation. YOU, THE PURCHASER, ARE ASSUMING described in this book. This book is Simultaneously published in the United THE ENTIRE RISK AS TO ITS QUALITY intended to assist product developers to States and Canada. AND ACCURACY. develop products only for Apple Power Macintosh computers. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, Every effort has been made to ensure INCIDENTAL, OR CONSEQUENTIAL that the information in this manual is DAMAGES RESULTING FROM ANY accurate. Apple is not responsible for DEFECT OR INACCURACY IN THIS printing or clerical errors. MANUAL, even if advised of the possibility Apple Computer, Inc. of such damages. 1 Infinite Loop THE WARRANTY AND REMEDIES SET Cupertino, CA 95014 FORTH ABOVE ARE EXCLUSIVE AND IN 408-996-1010 LIEU OF ALL OTHERS, ORAL OR Apple, the Apple logo, APDA, WRITTEN, EXPRESS OR IMPLIED. No AppleLink, Apple SuperDrive, Apple dealer, agent, or employee is AppleTalk, GeoPort, HyperCard, authorized to make any modification, LaserWriter, LocalTalk, Macintosh, extension, or addition to this warranty. Macintosh Quadra, MPW, PowerBook, Some states do not allow the exclusion or and QuickTime are trademarks of limitation of implied warranties or liability Apple Computer, Inc., registered in the for incidental or consequential damages, so United States and other countries. the above limitation or exclusion may not AOCE, AppleCD, Apple Desktop Bus, apply to you. This warranty gives you Mac, Power Macintosh, and specific legal rights, and you may also have other rights which vary from state to state. QuickDraw are trademarks of Apple Computer, Inc. Adobe Illustrator and PostScript are trademarks of Adobe Systems Incorporated, which may be registered in certain jurisdictions. America Online is a service mark of Quantum Computer Services, Inc. Code Warrior is a trademark of Metrowerks. CompuServe is a registered trademark of CompuServe, Inc. Ethernet is a registered trademark of Xerox Corporation. FrameMaker is a registered trademark Updated February, 1996 of Frame Technology Corporation. Thi d t t d ith F M k 4 0 4 Contents Figures, Tables, and Listings xv Preface About This Book xix Contents of This Book xix PCI Bus Overview xix System Startup by Open Firmware xx Native PowerPC Drivers xx Appendixes xx Supplementary Documents xxi Apple Publications xxi Other Publications xxiii Conventions and Abbreviations xxiv Typographical Conventions xxiv Notes xxv Abbreviations xxv Part One The PCI Bus 1 Chapter 1 Overview 3 Benefits of PCI 4 PCI and NuBus 5 The Macintosh Implementation of PCI 5 Power Macintosh PCI System Architecture 6 PCI Bus Characteristics 6 PCI Topology 8 PCI Host Bridge Operation 8 I/O Space 9 Configuration Space 10 Interrupt Acknowledge Cycles 10 Special Cycles 10 Maximizing Bus Performance 11 PCI Transaction Error Responses 11 Expansion Card Characteristics 12 Hard Decoding 13 Nonvolatile RAM 13 Access to Apple AV Technologies 14 iii Thi d t t d ith F M k 4 0 4 Chapter 2 Data Formats and Memory Usage 15 Address Allocations 16 PCI Bus Cycles 17 Addressing Modes 17 Addressing Mode Conversion 18 Addressing Mode Determination 20 Frame Buffers 20 Pixel Storage 21 Frame Buffer Apertures 22 Chapter 3 Data Transfers 23 Data Flow 24 Data Transfer Cycles 26 The PCI Bus and Open Firmware 26 Part Two The Open Firmware Process 27 Chapter 4 Startup and System Configuration 29 The Open Firmware Startup Process 30 Startup Firmware 30 Device Drivers 31 PowerPC Addressing and Alignment 32 Device Configuration 32 Open Firmware FCode Options 32 Full Open Firmware Support 33 Support for Mac OS 7.5 and Open Firmware 33 Minimum Open Firmware Support 33 No Open Firmware Support 33 Open Firmware Driver Support 34 Startup Sequence 34 Initializing the Hardware 35 Running Open Firmware 35 Starting the Operating System 36 PCI Bus Configuration 36 Configuration Tasks 36 Configuration Registers 37 Register Actions 37 PCI-To-PCI Bridges 41 Configuration Header 42 Register Settings 42 iv Chapter 5 PCI Open Firmware Drivers 47 General Requirements 48 Driver Interfaces 48 Open Firmware Driver Properties 49 Terminal Emulation in Graphics Drivers 49 Color Table Initialization 51 Display Device Standard Properties 52 Display Device Standard Methods 52 Open Firmware User Interface 53 Invoking the User Interface 53 User Interface Commands 54 Sample Driver 55 Part Three Native PCI Card Drivers 57 Chapter 6 Native Driver Overview 59 Macintosh System Evolution 60 Terminology 61 Concepts 63 Separation of Application and System Services 63 Common Packaging of Loadable Software 64 The Name Registry 64 Families of Devices 66 ROM-Based and Disk-Based Drivers 67 Noninterrupt and Interrupt-Level Execution 67 Symmetric Multiprocessing 67 Generic and Family Drivers 69 Driver Descriptions 70 Generic Driver Framework 70 Device Manager 70 Driver Package 71 Driver Services Library 71 Converting Previous Macintosh Drivers 72 Restricted Access to Services 72 Error Returns 72 Ensuring Future Compatibility 72 Copying Data 73 Synchronous and Asynchronous Driver Operation 74 Sharing Data With Applications 74 Power Management 75 Summary 75 Use the System Programming Interfaces 75 Use the Name Registry 76 v Chapter 7 Writing Native Drivers 77 Native Driver Framework 78 Native Container Format 78 Native Driver Data Exports 79 Native Driver Code Exports 79 Native Driver Imports 79 Drivers for Multiple Cards 80 The Device Manager and Generic Drivers 80 Native Driver Differences 80 Native Driver Limitations 82 Concurrent Generic Drivers 82 Completing an I/O Request 83 Concurrent I/O Request Flow 84 Driver Execution Contexts 85 Code Execution in General 85 Driver Execution 86 Writing a Generic Device Driver 87 Native Driver Package 87 Driver Description Structure 88 Driver Type Structure 90 Driver Run-Time Structure 90 Driver Services Structure 91 Driver Services Information Structure 92 DoDriverIO Entry Point 93 DoDriverIO Parameter Data Structures 93 Sample Handler Framework 95 Getting Command Information 97 Responding to Device Manager Requests 98 Initialization and Finalization Routines 98 Open and Close Routines 101 Read and Write Routines 101 Control and Status Routines 102 KillIO Routine 103 Replace and Superseded Routines 104 Handling Asynchronous I/O 104 Installing a Device Driver 105 Driver Gestalt 106 Supporting and Testing Driver Gestalt 106 Implementing Driver Gestalt 107 DCE Flags 108 Using DriverGestalt and DriverConfigure 110 DriverGestalt Selectors 111 Using the 'boot' Selector 113 DriverConfigure Selectors 113 vi Other Control and Status Calls 113 SetStartupDrive Control Call 114 Low Power Mode Support Calls 115 Device-Specific Status Calls 116 Driver Loader Library 117 Loading and Unloading 119 Installation 127 Load and Install Option 131 Match, Load, and Install 134 Driver Removal 136 Getting Driver Information 136 Searching for Drivers 138 Finding, Initializing, and Replacing Drivers 140 Device Properties 141 PCI Boot Sequence 141 Matching Drivers With Devices 142 Driver Initialization and Resource Verification 145 Opening Devices 149 Driver Replacement 150 Driver Migration 152 Driver Services That Have No Replacement 152 Device Manager