Designing PCI Cards and Drivers for Power Macintosh Computers Revised Edition Revised 3/26/99 Technical Publications © Apple Computer, Inc. 1999 Apple Computer, Inc. Adobe, Acrobat, and PostScript are Even though Apple has reviewed this © 1995, 1996 , 1999 Apple Computer, trademarks of Adobe Systems manual, APPLE MAKES NO Inc. All rights reserved. Incorporated or its subsidiaries and WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH No part of this publication may be may be registered in certain RESPECT TO THIS MANUAL, ITS reproduced, stored in a retrieval jurisdictions. QUALITY, ACCURACY, system, or transmitted, in any form America Online is a service mark of MERCHANTABILITY, OR FITNESS or by any means, mechanical, Quantum Computer Services, Inc. FOR A PARTICULAR PURPOSE. AS A electronic, photocopying, recording, Code Warrior is a trademark of RESULT, THIS MANUAL IS SOLD “AS or otherwise, without prior written Metrowerks. IS,” AND YOU, THE PURCHASER, ARE permission of Apple Computer, Inc., CompuServe is a registered ASSUMING THE ENTIRE RISK AS TO except to make a backup copy of any trademark of CompuServe, Inc. ITS QUALITY AND ACCURACY. documentation provided on Ethernet is a registered trademark of CD-ROM. IN NO EVENT WILL APPLE BE LIABLE Xerox Corporation. The Apple logo is a trademark of FOR DIRECT, INDIRECT, SPECIAL, FrameMaker is a registered Apple Computer, Inc. INCIDENTAL, OR CONSEQUENTIAL trademark of Frame Technology Use of the “keyboard” Apple logo DAMAGES RESULTING FROM ANY Corporation. (Option-Shift-K) for commercial DEFECT OR INACCURACY IN THIS purposes without the prior written Helvetica and Palatino are registered MANUAL, even if advised of the consent of Apple may constitute trademarks of Linotype-Hell AG possibility of such damages. and/or its subsidiaries. trademark infringement and unfair THE WARRANTY AND REMEDIES competition in violation of federal Intel is a trademark of Intel SET FORTH ABOVE ARE EXCLUSIVE and state laws. Corporation. AND IN LIEU OF ALL OTHERS, ORAL No licenses, express or implied, are Internet is a trademark of Digital OR WRITTEN, EXPRESS OR IMPLIED. granted with respect to any of the Equipment Corporation. No Apple dealer, agent, or employee is technology described in this book. ITC Zapf Dingbats is a registered authorized to make any modification, Apple retains all intellectual trademark of International Typeface extension, or addition to this warranty. property rights associated with the Corporation. Some states do not allow the exclusion or technology described in this book. Motorola is a registered trademark of limitation of implied warranties or This book is intended to assist Motorola Corporation. liability for incidental or consequential application developers to develop NuBus is a trademark of damages, so the above limitation or applications only for Apple-labeled Texas Instruments. exclusion may not apply to you. This or Apple-licensed computers. OpenBoot and Sun are trademarks of warranty gives you specific legal rights, Every effort has been made to ensure Sun Microsystems, Inc. and you may also have other rights that the information in this manual is which vary from state to state. accurate. Apple is not responsible for PowerPC is a trademark of typographical errors. International Business Machines Corporation, used under license Apple Computer, Inc. therefrom. 1 Infinite Loop Cupertino, CA 95014 UNIX is a registered trademark of 408-996-1010 Novell, Inc. in the United States and other countries, licensed exclusively Apple, the Apple logo, and through X/Open Company, Ltd. Macintosh are trademarks of Apple Windows is a trademark of Microsoft Computer, Inc., registered in the Corporation. United States and other countries. AOCE, AppleCD, Apple Desktop Simultaneously published in the Bus, Mac, Power Macintosh, and United States and Canada. QuickDraw are trademarks of Apple Computer, Inc. Contents Figures, Tables, and Listings 17 Preface About This Book 23 Contents of This Book 24 PCI Bus Overview 24 System Startup by Open Firmware 24 Native PowerPC Drivers 25 Appendixes 25 Supplementary Documents 26 Apple Publications 26 Other Publications 26 Conventions and Abbreviations 28 Typographical Conventions 28 Notes 29 Abbreviations 29 Part 1 The PCI Bus 31 Chapter 1 PCI Bus Overview 33 Benefits of PCI 34 PCI and NuBus 35 The Macintosh Implementation of PCI 36 Power Macintosh PCI System Architecture 36 PCI Bus Characteristics 37 PCI Topology 39 PCI Host Bridge Operation 39 I/O Space 42 Configuration Space 42 Interrupt Acknowledge Cycles 43 Special Cycles 43 3 Maximizing PCI Bus Performance 43 PowerPC Processor and PCI Commands 45 Bursting from PowerPC to PCI 46 Bursting from PCI to PowerPC 46 Mac OS & Services That Maximize PCI Throughput 49 PCI Transaction Error Responses 52 PCI Card Characteristics 54 PCI Video and Display Card Characteristics 54 Hard Decoding Device Address Space 55 Nonvolatile RAM 56 Chapter 2 Data Formats and Memory Usage 57 Address Allocations 58 PCI Bus Cycles 59 Addressing Modes 60 Addressing Mode Conversion 61 Addressing Mode Determination 63 Frame Buffers 64 Pixel Storage 64 Frame Buffer Apertures 65 Part 2 The Open Firmware Process 67 Chapter 3 Introduction to the NewWorld Architecture 69 The Macintosh ROM and The NewWorld Architecture 70 Differences Introduced by the NewWorld Architecture 71 Boot Devices 71 RAM 72 Hardware Addresses 72 Macintosh Name Registry 73 The gestaltMachineType Value 73 Interrupt Handling 73 ROM-in-RAM 73 4 Runtime Abstraction Services (RTAS) 74 NVRAM and PRAM 74 USB 74 ADB 74 Floppy Drives 75 Video Drivers 75 NewWorld Components 75 NewWorld Boot Process 77 New Name Registry Functionality 79 Modifying Open Firmware Config Variables From the Mac OS 79 Communication Between Mac OS and Open Firmware Drivers 80 Chapter 4 Startup and System Configuration 81 Peripheral Devices and Open Firmware 82 The Open Firmware Startup Process 83 Startup Firmware 83 Device Drivers 85 PowerPC Addressing and Alignment 86 Device Configuration 86 Open Firmware FCode Options 87 Full Open Firmware Support 87 Support for Mac OS and Open Firmware 87 Minimum Open Firmware Support 88 No Open Firmware Support 88 Open Firmware Driver Support 89 Startup Sequence 89 Initializing the Hardware 90 Running Open Firmware 90 Starting the Operating System 91 Startup Sequence in the NewWorld Architecture 92 What Is Different 93 Interrupt Handling 93 RAM Footprint 93 Run-Time Abstraction Services (RTAS) 93 NVRAM 94 Startup Disk Control Panel 94 5 PCI Bus Configuration 95 Configuration Tasks 95 Configuration Registers 95 Register Actions 96 PCI-To-PCI Bridges 102 Configuration Header 102 Register Settings 103 Chapter 5 PCI Open Firmware Drivers 111 General Requirements 112 Driver Interfaces 113 Open Firmware Driver Properties 113 Open Firmware User Interface 114 Invoking the User Interface Via Remote Connection 115 Invoking the User Interface On the Current Machine 118 User Interface Environment 119 Open Firmware Forth Language Symbols 120 Defining Forth Words 120 Forth Commands (Words) 121 Open Firmware User Interface Commands and Examples 124 Open Firmware Forth Usage Examples 126 Terminal Emulation in Graphics Drivers 127 Color Table Initialization 129 Display Device Standard Properties 130 Display Device Standard Methods 130 Sample FCode Drivers 131 Part 3 Native Device Drivers 137 Chapter 6 Native Driver Overview 139 Macintosh System Evolution 140 Terminology 141 Concepts 143 6 Separation of Application and Driver Services 144 Common Packaging of Loadable Software 145 The Name Registry 146 Families of Devices 147 ROM-Based and Disk-Based Drivers 148 Noninterrupt and Interrupt-Level Execution 149 Symmetric Multiprocessing 150 Generic and Family Drivers 151 Driver Descriptions 152 Generic Driver Framework 153 Device Manager 153 Driver Package 154 Driver Services Library 154 Converting Previous Mac OS Drivers 155 Restricted Access to Services 155 Error Returns 156 Ensuring Future Compatibility 156 Copying Data 157 Power Management 157 Summary 158 Use the System Programming Interfaces 158 Use the Name Registry 159 Chapter 7 Finding, Initializing, and Replacing Drivers 161 Device Properties 162 PCI Boot Sequence 163 Matching Drivers With Devices 164 Driver Initialization and Resource Verification 167 Opening Devices 172 Driver Replacement 174 Driver Migration 177 Driver Services That Have No Replacement 177 Device Manager 177 Exception Manager 178 Gestalt Manager 178 Mixed Mode Manager 178 7 Notification Manager 178 Power Manager 178 Resource Manager 179 Segment Loader 179 Shutdown Manager 179 Slot Manager 179 Vertical Retrace Manager 179 Native Driver Services 179 Registry Services 179 Operating-System Services 180 Timing Services 180 Memory Management Services 181 Hardware Interrupt Mechanisms 181 Secondary Interrupt Services 181 Device Configuration 182 Chapter 8 Writing Native Drivers 183 Native Driver Framework 184 Native Driver CFM Container Format 185 Native Driver Data Exports 185 Generic Native Driver Code Exports 185 Native Driver Imports 186 Drivers for Multiple Cards 186 The Device Manager and Generic Drivers 187 Native Driver Differences 187 Native Driver Limitations 190 Concurrent Generic Drivers 190 Completing an I/O Request 191 Concurrent I/O Request Flow 193 Driver Execution Contexts 194 Code Execution in General 194 Driver Execution 195 Writing a Generic Device Driver 196 Native Driver Package 197 Driver Description Structure 198 Driver Type Structure 200 8 Driver Run-Time Structure 201 Driver Services Structure 202 Driver Services Information Structure