Driver Developer Kit Mac OS USB DDK API Reference Preliminary Working Draft, Revision 26 12/23/99 Technical Publications © Apple Computer, Inc. 1999 Apple Computer, Inc. accurate. Apple is not responsible for PURPOSE. AS A RESULT, THIS © 1999 Apple Computer, Inc. printing or clerical errors. MANUAL IS PROVIDED “AS IS,” All rights reserved. Apple Computer, Inc. AND YOU, THE DEVELOPER, No part of this publication or the 1 Infinite Loop ARE ASSUMING THE ENTIRE software described in it may be Cupertino, CA 95014 RISK AS TO ITS QUALITY AND reproduced, stored in a retrieval 408-996-1010 ACCURACY. system, or transmitted, in any form Apple, the Apple logo, LaserWriter, IN NO EVENT WILL APPLE BE or by any means, mechanical, and Macintosh are trademarks of electronic, photocopying, recording, LIABLE FOR DIRECT, INDIRECT, Apple Computer, Inc., registered in SPECIAL, INCIDENTAL, OR or otherwise, without prior written the United States and other permission of Apple Computer, Inc., countries. CONSEQUENTIAL DAMAGES except in the normal use of the RESULTING FROM ANY DEFECT Adobe, Acrobat, and PostScript are software or to make a backup copy OR INACCURACY IN THIS of the software or documentation. trademarks of Adobe Systems Incorporated or its subsidiaries and MANUAL, even if advised of the The same proprietary and copyright possibility of such damages. notices must be affixed to any may be registered in certain permitted copies as were affixed to jurisdictions. THE WARRANTY AND the original. This exception does not Helvetica and Palatino are registered REMEDIES SET FORTH ABOVE allow copies to be made for others, trademarks of Linotype-Hell AG ARE EXCLUSIVE AND IN LIEU whether or not sold, but all of the and/or its subsidiaries. OF ALL OTHERS, ORAL OR material purchased (with all backup ITC Zapf Dingbats is a registered WRITTEN, EXPRESS OR copies) may be sold, given, or loaned trademark of International Typeface IMPLIED. No Apple dealer, agent, to another person. Under the law, Corporation. copying includes translating into or employee is authorized to make Intel is a registered trademark of another language or format. You any modification, extension, or Intel Corporation. may use the software on any addition to this warranty. Simultaneously published in the computer owned by you, but extra Some states do not allow the copies cannot be made for this United States and Canada. purpose. exclusion or limitation of implied warranties or liability for incidental Printed in the United States of LIMITED WARRANTY ON America. or consequential damages, so the MEDIA AND REPLACEMENT above limitation or exclusion may The Apple logo is a trademark of not apply to you. This warranty Apple Computer, Inc. Use of the ALL IMPLIED WARRANTIES ON “keyboard” Apple logo THIS MANUAL, INCLUDING gives you specific legal rights, and (Option-Shift-K) for commercial IMPLIED WARRANTIES OF you may also have other rights purposes without the prior written MERCHANTABILITY AND which vary from state to state. consent of Apple may constitute FITNESS FOR A PARTICULAR trademark infringement and unfair PURPOSE, ARE LIMITED IN competition in violation of federal DURATION TO NINETY (90) and state laws. DAYS FROM THE DATE OF THE No licenses, express or implied, are ORIGINAL RETAIL PURCHASE granted with respect to any of the technology described in this book. OF THIS PRODUCT. Apple retains all intellectual Even though Apple has reviewed property rights associated with the this manual, APPLE MAKES NO technology described in this book. WARRANTY OR This book is intended to assist REPRESENTATION, EITHER application developers to develop applications only for Apple-labeled EXPRESS OR IMPLIED, WITH or Apple-licensed computers. RESPECT TO THIS MANUAL, ITS Every effort has been made to ensure QUALITY, ACCURACY, that the information in this manual is MERCHANTABILITY, OR FITNESS FOR A PARTICULAR Preliminary Working Draft, Revision 26. © Apple Computer, Inc. 12/23/99 Contents Figures and Tables 11 Preface About This Note 13 Contents of This Note 14 Supplemental Reference Documents 15 Mac OS USB Resources 15 Apple Developer Connection Web Site 16 Chapter 1 Overview 17 Introduction to USB 18 Why Incorporate USB Into the Macintosh Architecture? 18 Better Device Expansion Model 18 Compact Connectors and Cables 19 Use of Standard Hardware 19 Lower Cost Than Comparable Non-USB Peripherals 20 Wide Selection of USB Devices 20 Device Classes 20 Low- and High-Speed Devices 21 USB Hub Devices 22 The USB Root Hub 22 Compatibility Issues 23 USB Software Gestalt Selectors 23 ADB, Serial/LocalTalk, and USB 23 Macintosh-To-Macintosh USB Connections 23 USB Storage Devices 24 Keyboard Requirements 24 USB Data Transfer Types Supported 24 USB Controller Support 25 Maintaining Printer Device and Driver Compatibility 25 Device Support For Multiple Vendor Specific Devices 26 USB PCI Adapter Card Support 26 3 Preliminary Working Draft, Revision 26. © Apple Computer, Inc. 12/23/99 Transaction Timeouts 26 Chapter 2 USB Topology and Communication 29 USB Bus Topology 30 Host Software 30 Physical Topology 31 Logical Topology 31 Communication Over the USB 32 USB Interface 33 USB Devices 33 Endpoints 33 Endpoint 0 34 Non-0 Endpoints 34 Pipes 34 A Look At USB Devices with USB Prober 35 USB Prober Features for Developers 37 USB Prober Windows 37 Chapter 3 USB Software Components 41 Mac OS Software for USB Devices 42 USB Software Presence and Version Attributes 45 USB Interface Module (UIM) 45 USB Manager 46 Hub Driver 47 USB Class Drivers 47 USB Services Library (USL) 48 Applications and USB Drivers 49 Chapter 4 Writing Mac OS USB Drivers 51 Mac OS USB Driver Overview 53 USB Device and Driver Matching 54 Matching Interfaces to Interface Drivers 57 Matching Class Drivers to Composite Devices 59 4 Preliminary Working Draft, Revision 26. © Apple Computer, Inc. 12/23/99 Device Driver and Interface Driver Matching Differences 60 Core Mac OS USB Driver Data Exports 60 USBDriverDescription Structure 60 USBClassDriverPlugInDispatchTable Structure 65 ValidateHWProc Function 67 InitializeDeviceProc Function 67 InitializeInterfaceProc Function 69 Driver notificationProc Function 70 FinalizeProc Function 71 Handling Hot Unplugging, Dealing With Notifications 71 Communicating With Client Processes 72 The Disappearing Driver 73 Common Ground and The Compatibility Shim 73 Where To Implement a Compatibility Shim 73 Designing A Compatibility Shim 74 Helpful Resources For Compatibility Shim Development 75 Communicating with the Human Interface Device Driver 75 The HIDDeviceDispatchTable Structure 76 The USBHIDModuleDispatchTable Structure 81 Detecting USB Device Presence 83 Mac OS USB Compatibility With Mac OS Toolbox Calls 86 Chapter 5 USB Services Library Reference 89 USB Services Library (USL) 90 Errors And Error Reporting Conventions 91 Device Access Errors 91 Errors on the USB Bus 92 Incorrect Command Errors 93 Driver Logic Errors 93 PCI Bus Busy Errors 93 USB References 93 The USBPB Parameter Block 94 Required USB Parameter Block Fields 98 Standard Parameter Block Errors 99 Using the USBPB For Isochronous Transactions 99 Asynchronous Call Support 101 5 Preliminary Working Draft, Revision 26. © Apple Computer, Inc. 12/23/99 Polling Versus Asynchronous Completion (Important) 103 Transaction and Data Timeouts 104 USL Functions 106 Determining The Version of USB Software Present 106 USB Configuration Functions 107 Opening An Interface 112 Configuring The Device Interface(s) 113 Finding A Pipe 115 Getting Information About an Open Interface or Pipe 116 Generalized USB Device Request Function 120 USB Transaction Functions 124 Pipe State Control Functions 133 Data Toggle Synchronization 134 Device Control and Status Functions 141 USB Management Services Functions 144 USB Time Utility Functions 146 USB Memory Functions 149 Byte Ordering (Endianism) Functions 152 USL Logging Services Functions 154 USB Descriptor Functions 157 Debugger Aware Flag 163 Deprecated Pipe Functions 163 Constants and Data Structures 164 USB Constants 164 Parameter Block Constants 164 Flag Constants 164 Endpoint Type Constants 165 usbBMRequest Direction Constants 165 usbBMRequestType Type Constants 165 usbBMRequest Recipient Constants 165 usbBRequest Constants 165 Interface Constants 166 Interface Protocol Constants 166 Driver Class Constants 166 Descriptor Type Constants 167 Feature Selector Constants 167 Pipe State Constants 167 USB Power and Bus Attribute Constants 167 6 Preliminary Working Draft, Revision 26. © Apple Computer, Inc. 12/23/99 Driver File and Resource Types 168 Driver Loading Option Constants 168 Error Status Level Constant 168 USB Data Structures 168 Device Descriptor Structure 169 Configuration Descriptor Structure 169 Interface Descriptor Structure 170 Endpoint Descriptor Structure 170 HID Descriptor Structure 170 HID Report Descriptor Structure 171 USL Error Codes 171 Chapter 6 USB Manager Reference 175 Overview 176 USB Manager API 177 Topology Database Access Functions 177 Getting Device Descriptors 178 Getting Interface Descriptors 178 Finding The Driver For A Device By Class 179 Getting The Connection ID For Class Driver 181 Getting The Bus Reference For a Device 181 Passing Messages To Another Driver 182 Receiving A Message From A Child Driver 183 Registering Shims After Boot Time 183 Adding a Driver For a Device After Boot Time 184 Callback Routine for Device Notification 185 Device Notification Callback Routine 185 Device Notification Parameter Block 186 Installing The Device Callback Request 187 Removing The Device Callback Request 188 Errors Returned