Inside Mac OS X Kernel Programming November 2002 Apple Computer, Inc. NeXT and OpenStep are trademarks © 2001–2002 Apple Computer, Inc. of NeXT Software, Inc., registered in All rights reserved. the United States and other countries. No part of this publication may be Java and all Java-based trademarks reproduced, stored in a retrieval are trademarks or registered system, or transmitted, in any form or trademarks of Sun Microsystems, by any means, mechanical, electronic, Inc., registsered in the United States photocopying, recording, or and other countries. otherwise, without prior written OpenGL is a registered trademark of permission of Apple Computer, Inc., Silicon Graphics, Inc. with the following exceptions: Any Simultaneously published in the person is hereby authorized to store United States and Canada. documentation on a single computer Even though Apple has reviewed this for personal use only and to print manual, APPLE MAKES NO copies of documentation for personal WARRANTY OR REPRESENTATION, use provided that the documentation EITHER EXPRESS OR IMPLIED, WITH contains Apple’s copyright notice. RESPECT TO THIS MANUAL, ITS The Apple logo is a trademark of QUALITY, ACCURACY, Apple Computer, Inc. MERCHANTABILITY, OR FITNESS Use of the “keyboard” Apple logo FOR A PARTICULAR PURPOSE. AS A (Option-Shift-K) for commercial RESULT, THIS MANUAL IS SOLD “AS purposes without the prior written IS,” AND YOU, THE PURCHASER, ARE consent of Apple may constitute ASSUMING THE ENTIRE RISK AS TO trademark infringement and unfair ITS QUALITY AND ACCURACY. competition in violation of federal and state laws. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, No licenses, express or implied, are INCIDENTAL, OR CONSEQUENTIAL granted with respect to any of the DAMAGES RESULTING FROM ANY technology described in this book. DEFECT OR INACCURACY IN THIS Apple retains all intellectual property MANUAL, even if advised of the rights associated with the technology possibility of such damages. described in this book. This book is intended to assist application THE WARRANTY AND REMEDIES SET developers to develop applications FORTH ABOVE ARE EXCLUSIVE AND only for Apple-labeled or IN LIEU OF ALL OTHERS, ORAL OR Apple-licensed computers. WRITTEN, EXPRESS OR IMPLIED. No Every effort has been made to ensure Apple dealer, agent, or employee is that the information in this document authorized to make any modification, is accurate. Apple is not responsible extension, or addition to this warranty. for typographical errors. Some states do not allow the exclusion or Apple Computer, Inc. limitation of implied warranties or 1 Infinite Loop liability for incidental or consequential Cupertino, CA 95014 damages, so the above limitation or 408-996-1010 exclusion may not apply to you. This Apple, the Apple logo, AppleTalk, warranty gives you specific legal rights, Cocoa, Firewire, Mac, Macintosh, and and you may also have other rights which QuickTime are trademarks of Apple vary from state to state. Computer, Inc., registered in the United States and other countries. Carbon and Quartz are trademarks of Apple Computer, Inc. Contents Figures and Tables 1 Chapter 1 About This Document 2 Who Should Read This Document 2 Road Map 3 Other Apple Publications 5 Mach API Reference 5 Information on the Web 6 Chapter 2 Keep Out 7 Why You Should Avoid Programming in the Kernel 7 Chapter 3 Security Considerations 9 Security Implications of Paging 10 Buffer Overflows and Invalid Input 11 User Credentials 12 Remote Authentication 14 One-Time Pads 15 Time-based authentication 15 Temporary Files 17 /dev/mem and /dev/kmem 17 Key-based Authentication and Encryption 18 Public Key Weaknesses 19 Trust Models 19 Sensitivity to Patterns and Short Messages 20 Using Public Keys for Message Exchange 21 1 Apple Computer, Inc. November 2002 CONTENTS Using Public Keys for Identity Verification 21 Using Public Keys for Data Integrity Checking 22 Encryption Summary 22 Console Debugging 23 Code Passing 24 Chapter 4 Performance Considerations 26 Interrupt Latency 26 Locking Bottlenecks 27 Working With Highly Contended Locks 28 Reducing Contention by Decreasing Granularity 29 Code Profiling 30 Using Counters for Code Profiling 30 Lock Profiling 31 Chapter 5 Kernel Programming Style 33 C++ Naming Conventions 33 Basic Conventions 34 Additional Guidelines 34 Standard C Naming Conventions 35 Commonly Used Functions 37 Performance and Stability Tips 38 Performance and Stability Tips 39 Stability Tips 40 Style Summary 41 Chapter 6 Mach Overview 42 Mach Kernel Abstractions 43 Tasks and Threads 44 Ports, Port Rights, Port Sets, and Port Namespaces 46 Memory Management 47 Interprocess Communication (IPC) 49 IPC Transactions and Event Dispatching 50 2 Apple Computer, Inc. November 2002 CONTENTS Message Queues 50 Semaphores 51 Notifications 51 Locks 51 Remote Procedure Call (RPC) Objects 51 Time Management 52 Chapter 7 Memory and Virtual Memory 53 Mac OS X VM Overview 53 Memory Maps Explained 55 Named Entries 57 Universal Page Lists (UPLs) 58 Using Mach Memory Maps 60 Other VM and VM-Related Subsystems 62 Pagers 62 Working Set Detection Subsystem 63 VM Shared Memory Server Subsystem 63 Allocating Memory in the Kernel 64 Allocating Memory Using Mach Routines 64 Allocating Memory From the I/O Kit 66 Chapter 8 Mach Scheduling and Thread Interfaces 67 Overview of Scheduling 67 Why Did My Thread Priority Change? 69 Using Mach Scheduling From User Applications 69 Using the pthreads API to Influence Scheduling 70 Using the Mach Thread API to Influence Scheduling 71 Using the Mach Task API to Influence Scheduling 73 Kernel Thread APIs 75 Creating and Destroying Kernel Threads 76 SPL and Friends 77 Wait Queues and Wait Primitives 77 3 Apple Computer, Inc. November 2002 CONTENTS Chapter 9 Bootstrap Contexts 81 How Contexts Affect Users 82 How Contexts Affect Developers 83 Chapter 10 I/O Kit Overview 85 Redesigning the I/O Model 86 I/O Kit Architecture 87 Families 88 Drivers 89 Nubs 89 Connection Example 90 For More Information 93 Chapter 11 BSD Overview 94 BSD Facilities 95 Differences between Mac OS X and BSD 97 For Further Reading 98 Chapter 12 File Systems Overview 100 Working With the File System 101 VFS Transition 101 Chapter 13 Network Architecture 102 Review of 4.4BSD Network Architecture 103 NKE Types 104 Modifications to 4.4BSD Networking Architecture 106 Chapter 14 Boundary Crossings 107 Security Considerations 109 4 Apple Computer, Inc. November 2002 CONTENTS Choosing a Boundary Crossing Method 109 Kernel Subsystems 110 Bandwidth and Latency 110 Mach Messaging and Mach Interprocess Communication (IPC) 111 Using Well-Defined Ports 112 Remote Procedure Calls (RPC) 113 Calling RPC From User Applications 116 BSD syscall API 116 BSD ioctl API 117 BSD sysctl API 118 General Information on Adding a sysctl 118 Adding a sysctl Procedure Call 119 Registering a New Top Level sysctl 122 Adding a Simple sysctl 123 Calling a sysctl From User Space 124 The sysctlbyname System Call 124 The sysctl System Call 125 Memory Mapping and Block Copying 126 Summary 128 Chapter 15 Synchronization Primitives 129 Semaphores 130 Condition Variables 132 Locks 132 Spinlocks 132 Mutexes 134 Read-Write Locks 136 Spin/Sleep Locks 137 Chapter 16 Miscellaneous Kernel Services 139 Using Kernel Time Abstractions 139 Obtaining Time Information 139 Event and Timer Waits 140 Using IODelay and IOSleep 141 5 Apple Computer, Inc. November 2002 CONTENTS Using Mach Absolute Time Functions 141 Using tsleep 142 Boot Option Handling 143 Queues 144 Installing Shutdown Hooks 145 Chapter 17 Kernel Extension Overview 146 Implementation of a Kernel Extension (KEXT) 147 Kernel Extension Dependencies 148 Building and Testing Your Extension 149 Debugging Your KEXT 150 Installed KEXTs 151 Chapter 18 Building and Debugging Kernels 153 Adding New Files or Modules 153 Modifying the Configuration Files 154 Adding the Files or Modules 154 Enabling Module Options 155 Modifying the Source Code Files 155 Building Your First Kernel 156 Building an Alternate Kernel Configuration 158 When Things Go Wrong: Debugging the Kernel 159 Setting Debug Flags in Open Firmware 159 Choosing a Debugger 161 Using gdb for Kernel Debugging 162 Using ddb for Kernel Debugging 165 Commands and Syntax of ddb 167 6 Apple Computer, Inc. November 2002 CONTENTS Appendix A Document Revision History 173 Bibliography 175 Glossary 183 Index 197 7 Apple Computer, Inc. November 2002 CONTENTS 8 Apple Computer, Inc. November 2002 Figures and Tables Chapter 5 Kernel Programming Style 33 Table 5-1 Commonly used C functions 37 Chapter 8 Mach Scheduling and Thread Interfaces 67 Table 8-1 Thread priority bands 68 Table 8-2 Thread policies 72 Table 8-3 Task roles 74 Chapter 10 I/O Kit Overview 85 Figure 10-1 I/O Kit architecture 91 Chapter 13 Network Architecture 102 Figure 13-1 4.4 BSD network architecture 104 Figure 13-2 NKE architecture 106 Chapter 18 Building and Debugging Kernels 153 Table 18-1 Debugging flags 160 Table 18-2 Switch options in ddb 168 Appendix A Document Revision History 173 Table A-1 Document revision history 173 1 Apple Computer, Inc. November 2002 CHAPTER 1 1 About This Document The purpose of this document is to provide fundamental high-level information about the Mac OS X core operating-system architecture. It also provides background for system programmers and developers of device drivers, file systems, and network extensions. In addition, it goes into detail about topics of interest to kernel programmers as a whole. This is not a document on drivers. It covers device