I/O Kit Device Driver Design Guidelines 2006-10-04 CDB is a trademark of Third Eye Software, Apple Computer, Inc. Inc. © 2002, 2006 Apple Computer, Inc. Intel and Intel Core are registered All rights reserved. trademarks of Intel Corportation or its subsidiaries in the United States and other No part of this publication may be countries. reproduced, stored in a retrieval system, or transmitted, in any form or by any means, PowerPC and and the PowerPC logo are mechanical, electronic, photocopying, trademarks of International Business recording, or otherwise, without prior Machines Corporation, used under license written permission of Apple Computer, Inc., therefrom. with the following exceptions: Any person Simultaneously published in the United is hereby authorized to store documentation States and Canada. on a single computer for personal use only Even though Apple has reviewed this document, and to print copies of documentation for APPLE MAKES NO WARRANTY OR personal use provided that the REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS documentation contains Apple’s copyright DOCUMENT, ITS QUALITY, ACCURACY, notice. MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS The Apple logo is a trademark of Apple DOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE ASSUMING THE Computer, Inc. ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. Use of the “keyboard” Apple logo IN NO EVENT WILL APPLE BE LIABLE FOR (Option-Shift-K) for commercial purposes DIRECT, INDIRECT, SPECIAL, INCIDENTAL, without the prior written consent of Apple OR CONSEQUENTIAL DAMAGES may constitute trademark infringement and RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if unfair competition in violation of federal advised of the possibility of such damages. and state laws. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN No licenses, express or implied, are granted LIEU OF ALL OTHERS, ORAL OR WRITTEN, with respect to any of the technology EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any described in this document. Apple retains modification, extension, or addition to this all intellectual property rights associated warranty. with the technology described in this Some states do not allow the exclusion or document. This document is intended to limitation of implied warranties or liability for incidental or consequential damages, so the assist application developers to develop above limitation or exclusion may not apply to applications only for Apple-labeled or you. This warranty gives you specific legal rights, and you may also have other rights which Apple-licensed computers. vary from state to state. Every effort has been made to ensure that the information in this document is accurate. Apple is not responsible for typographical errors. Apple Computer, Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Carbon, Cocoa, ColorSync, FireWire, iMac, Mac, Mac OS, Macintosh, Pages, PowerBook, and Xcode are trademarks of Apple Computer, Inc., registered in the United States and other countries. Finder is a trademark of Apple Computer, Inc. NeXT and Objective-C are trademarks of NeXT Software, Inc., registered in the United States and other countries. Contents Introduction Introduction to I/O Kit Device Driver Design Guidelines 11 Who Should Read This Document? 11 Organization of This Document 11 See Also 13 Chapter 1 The libkern C++ Runtime 15 Creation of the Runtime System 15 Object Creation and Destruction 17 Using the OSMetaClass Constructor Macros 17 Allocating Objects Dynamically 18 Global Initializers 19 Object Introspection and Dynamic Casting 22 Binary Compatibility 24 The Fragile Base Class Problem 24 Reserving Future Data Members 26 Padding the Virtual Table 26 Chapter 2 libkern Collection and Container Classes 29 The libkern Classes and Your Driver 29 libkern Collection and Container Class Overview 30 libkern Container Classes 31 libkern Collection Classes 32 Using the libkern Collection and Container Classes 32 Container Object Creation and Initialization 33 Container Object Introspection and Access 34 Collection Object Creation and Initialization 34 Collection Object Introspection and Access 35 Reference Counting for Collection and Container Classes 35 Thread Safety and the Container and Collection Classes 36 libkern Objects and XML 36 Configuring Your Driver Using the libkern Classes 36 Configuring a Subclass of IOAudioDevice 37 Configuring a Subclass of IOUSBMassStorageClass 38 3 2006-10-04 | © 2002, 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS Chapter 3 The IOService API 41 Driver Life-Cycle and Matching Functionality 41 Driver Matching 42 Passive-Matching Keys 43 Driver State 45 Resources 46 User Clients 46 Probing 47 Notifications and Driver Messaging 47 Notification Methods 47 Messaging Methods 49 Access Methods 49 Getting Work Loops 50 Getting Clients and Providers 50 Getting Other I/O Kit Objects 51 Power Management 52 Power-Management Entities 52 Using the Power Management Methods 53 Memory Mapping and Interrupt Handling 56 Accessing Device Memory 56 Handling Interrupts 59 Miscellaneous IOService Methods 60 Chapter 4 Making Hardware Accessible to Applications 63 Transferring Data Into and Out of the Kernel 63 Issues With Cross-Boundary I/O 64 Programming Alternatives 65 Writing a Custom User Client 69 The Architecture of User Clients 69 Factors in User Client Design 73 Implementing the User Side of the Connection 77 Creating a User Client Subclass 82 A Guided Tour Through a User Client 95 Common Type Definitions 95 The Device Interface Library 98 The User Client 100 Chapter 5 Kernel-User Notification 105 Presenting Notification Dialogs 106 Launching User-Space Executables 109 Presenting Bundled Dialogs 110 4 2006-10-04 | © 2002, 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS Chapter 6 Displaying Localized Information About Drivers 117 Internationalizing Kernel Extensions 118 Creating and Populating the Localization Directories 118 Internationalizing Strings 119 Getting the Path to a KEXT From User Space 120 Chapter 7 Debugging Drivers 123 Some Debugging Basics 123 General Tips 123 Issues With 64-Bit Architectures 124 Driver-Debugging Tools 125 Debugging Matching and Loading Problems 126 Driver Dependencies 127 Using kextload, kextunload, and kextstat 127 Debugging Matching Problems 132 Two-Machine Debugging 133 Setting Up for Two-Machine Debugging 134 Using the Kernel Debugging Macros 136 Tips on Using gdb 141 Debugging Kernel Panics 144 Debugging System Hangs 148 Debugging Boot Drivers 149 Logging 150 Using IOLog 150 Custom Event Logging 151 Chapter 8 Testing and Deploying Drivers 155 Testing Strategies 155 Basic Quality Control 155 Configuration Testing 156 Power-Management Testing 157 Other Testing Strategies and Goals 157 Packaging Drivers for Installation 158 Package Contents 158 Package Validation and Installation 160 Chapter 9 Developing a Device Driver to Run on an Intel-Based Macintosh 163 Byte Swapping 163 Handling Architectural Differences 164 Viewing Values in the Device Tree Plane 164 Interrupt Sharing in an Intel-Based Macintosh 164 Using the OSSynchronizeIO Function 165 5 2006-10-04 | © 2002, 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS Accessing I/O Space 165 Debugging on an Intel-Based Macintosh 165 Glossary 167 Document Revision History 173 Index 175 6 2006-10-04 | © 2002, 2006 Apple Computer, Inc. All Rights Reserved. Figures, Tables, and Listings Chapter 1 The libkern C++ Runtime 15 Figure 1-1 Registering metaclass information from a KEXT binary 16 Figure 1-2 The aggregate data and vtable structures of a compiled class 25 Table 1-1 OSMetaClass and OSMetaClassBase introspection macros and member functions 23 Listing 1-1 Definition of a class to be declared global 21 Listing 1-2 Implementation of a global constructor 21 Listing 1-3 Implementation of a global destructor 22 Listing 1-4 Code showing dynamic casting and introspection 24 Listing 1-5 Initial declarations of the ExpansionData structure and reserved pointer 26 Listing 1-6 Adding a new field to the ExpansionData structure 26 Listing 1-7 The initial padding of a class virtual table (header file) 27 Listing 1-8 The initial padding of a class virtual table (implementation file) 27 Listing 1-9 Adjusting the pad slots when adding new virtual functions—header file 27 Listing 1-10 Adjusting the pad slots when adding new virtual functions—implementation file 28 Chapter 2 libkern Collection and Container Classes 29 Table 2-1 XML tags and libkern class names 30 Table 2-2 The libkern container classes 31 Table 2-3 The libkern collection classes 32 Table 2-4 libkern methods and reference-counting behavior 35 Listing 2-1 Using libkern objects and methods in audio-engine creation 37 Listing 2-2 Partial listing of IOUSBMassStorageClass start method 38 Chapter 3 The IOService API 41 Table 3-1 IOService matching methods 42 Table 3-2 Notification types and events 47 Table 3-3 Memory-mapping options for mapDeviceMemoryWithIndex 58 Listing 3-1 A matchPropertyTable implementation 43 Listing 3-2 A personality of the GossamerPE 44 Listing 3-3 Partial I/O Registry entry for GossamerPE 45 Listing 3-4 Using the addNotification method 47 Listing 3-5 Implementing a notification-handling method 48 Listing 3-6 Implementing the message method 49 7 2006-10-04 | © 2002, 2006 Apple Computer, Inc. All Rights Reserved. FIGURES, TABLES, AND LISTINGS Listing 3-7 getClientIterator example 51 Listing 3-8 The IODisplayWrangler setAggressiveness method 55