ChorusOS 4.0 Device Driver Framework Guide Sun Microsystems, Inc. 901 San Antonio Road Palo Alto, CA 94303-4900 U.S.A. Part Number 806-0616–10 December 1999 Copyright 1999 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California 94303-4900 U.S.A. All rights reserved. This product or document is protected by copyright and distributed under licenses restricting its use, copying, distribution, and decompilation. No part of this product or document may be reproduced in any form by any means without prior written authorization of Sun and its licensors, if any. Third-party software, including font technology, is copyrighted and licensed from Sun suppliers. Parts of the product may be derived from Berkeley BSD systems, licensed from the University of California. UNIX is a registered trademark in the U.S. and other countries, exclusively licensed through X/Open Company, Ltd. Sun, Sun Microsystems, the Sun logo, docs.sun.com, AnswerBook, AnswerBook2, ChorusOS, Sun Embedded Workshop and Solaris are trademarks, registered trademarks, or service marks of Sun Microsystems, Inc. in the U.S. and other countries. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. in the U.S. and other countries. Products bearing SPARC trademarks are based upon an architecture developed by Sun Microsystems, Inc. The OPEN LOOK and SunTM Graphical User Interface was developed by Sun Microsystems, Inc. for its users and licensees. Sun acknowledges the pioneering efforts of Xerox in researching and developing the concept of visual or graphical user interfaces for the computer industry. Sun holds a non-exclusive license from Xerox to the Xerox Graphical User Interface, which license also covers Sun’s licensees who implement OPEN LOOK GUIs and otherwise comply with Sun’s written license agreements. RESTRICTED RIGHTS: Use, duplication, or disclosure by the U.S. Government is subject to restrictions of FAR 52.227–14(g)(2)(6/87) and FAR 52.227–19(6/87), or DFAR 252.227–7015(b)(6/95) and DFAR 227.7202–3(a). DOCUMENTATION IS PROVIDED “AS IS” AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID. Copyright 1999 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, Californie 94303-4900 Etats-Unis. Tous droits réservés. Ce produit ou document est protégé par un copyright et distribué avec des licences qui en restreignent l’utilisation, la copie, la distribution, et la décompilation. Aucune partie de ce produit ou document ne peut être reproduite sous aucune forme, par quelque moyen que ce soit, sans l’autorisation préalable et écrite de Sun et de ses bailleurs de licence, s’il y en a. Le logiciel détenu par des tiers, et qui comprend la technologie relative aux polices de caractères, est protégé par un copyright et licencié par des fournisseurs de Sun. Des parties de ce produit pourront être dérivées du système Berkeley BSD licenciés par l’Université de Californie. UNIX est une marque déposée aux Etats-Unis et dans d’autres pays et licenciée exclusivement par X/Open Company, Ltd. Sun, Sun Microsystems, le logo Sun, docs.sun.com, AnswerBook, AnswerBook2, ChorusOS, Sun Embedded Workshop et Solaris sont des marques de fabrique ou des marques déposées, ou marques de service, de Sun Microsystems, Inc. aux Etats-Unis et dans d’autres pays. Toutes les marques SPARC sont utilisées sous licence et sont des marques de fabrique ou des marques déposées de SPARC International, Inc. aux Etats-Unis et dans d’autres pays. Les produits portant les marques SPARC sont basés sur une architecture développée par Sun Microsystems, Inc. L’interface d’utilisation graphique OPEN LOOK et SunTM a été développée par Sun Microsystems, Inc. pour ses utilisateurs et licenciés. Sun reconnaît les efforts de pionniers de Xerox pour la recherche et le développement du concept des interfaces d’utilisation visuelle ou graphique pour l’industrie de l’informatique. Sun détient une licence non exclusive de Xerox sur l’interface d’utilisation graphique Xerox, cette licence couvrant également les licenciés de Sun qui mettent en place l’interface d’utilisation graphique OPEN LOOK et qui en outre se conforment aux licences écrites de Sun. CETTE PUBLICATION EST FOURNIE “EN L’ETAT” ET AUCUNE GARANTIE, EXPRESSE OU IMPLICITE, N’EST ACCORDEE, Y COMPRIS DES GARANTIES CONCERNANT LA VALEUR MARCHANDE, L’APTITUDE DE LA PUBLICATION A REPONDRE A UNE UTILISATION PARTICULIERE, OU LE FAIT QU’ELLE NE SOIT PAS CONTREFAISANTE DE PRODUIT DE TIERS. CE DENI DE GARANTIE NE S’APPLIQUERAIT PAS, DANS LA MESURE OU IL SERAIT TENU JURIDIQUEMENT NUL ET NON AVENU. Please Recycle Contents Preface 7 1. Introduction to the ChorusOS Driver Framework 11 Introduction 11 Benefits of Using the Driver Framework 12 Framework Architecture Overview 12 Driver Framework APIs 15 Driver/Kernel Interface (DKI) 16 Device Drivers Interface (DDI) 17 Driver Framework Mechanisms and Principles 18 Driver Registration 18 Driver Initialization 19 Driver Framework Components 21 Source Files 21 Organization (trees) 22 Manpage Documentation 23 Device Driver Conventions 23 Driver Names 24 Driver Information 24 Message Logging 25 3 Use of ASSERT Macro 25 2. Driver Kernel Interface Overview 27 Common Driver Services 27 Synchronization 27 Device and Driver Registration 29 General Purpose Memory Allocation 33 Special Purpose Physical Memory Allocation 33 Timeouts 34 Precise Busy Wait 34 System Event Management 35 Global Interrupts Masking 35 Thread Preemption Disabling 36 Specific Input/Output Services 36 Processor Family Specific DKI Services 37 3. Writing Device Drivers 39 Include the Appropriate APIs (DKI/DDI) 39 Register the Driver (using main function) 40 Write Device Driver-Class-Specific Functions 42 Write Device Driver Registry Functions 45 Write the Probe Function 45 Write the Bind Function 46 Write the Init Function 47 Write Unload Function 51 Write Bus Events Handler Function 54 4. Writing Bus Drivers 63 Include the Appropriate APIs (DKI/DDI) 63 Register the Driver (using main function) 64 Write Bus Driver Class-Specific Functions 66 4 ChorusOS 4.0 Device Driver Framework Guide ♦ December 1999 Write General Functions 66 Write Registry Functions 69 Write the Probe Function 69 Write the Bind Function 71 Write the Init Function 72 Write the Unload Function 76 Write Event Handler Function 79 Hot-Plug Removal 83 Write Load Handler Function 85 A. Further Information 89 Index 91 Contents 5 6 ChorusOS 4.0 Device Driver Framework Guide ♦ December 1999 Preface The ChorusOS 4.0 Device Driver Framework Guide explains the set of tools provided within the ChorusOS operating system to build device and bus drivers, and how to use them. It provides an overview of the device and bus driver architecture within the ChorusOS operating system environment, and explains how the Driver Framework can be used to build highly portable, platform-independent drivers, as well as highly tunable, processor-family specific drivers using the same software paradigm. It also contains a summary of the APIs that make up the Driver Framework, although details of the API calls are discussed in the man pages. Who Should Use This Guide This book is designed to be used by developers already familiar with building bus and device drivers. For this reason, there is no general description of the tasks involved in building bus or device drivers. It is recommended that the reader consult books and/or websites dealing specifically with the architecture of the different device, bus, and processor architectures for this kind of information. Before You Read This Guide Before starting to build drivers using the ChorusOS operating system, read the ChorusOS 4.0 Introduction. The introduction provides an overview of the features and components of the ChorusOS operating system and explains how to create an application that runs on the ChorusOS operating system. 7 How This Guide is Organized This book is organized into the following sections. Chapter 1 provides an introduction to the toolset, gives an overview of hardware representation in the ChorusOS operating system, and outlines some of the benefits of using the Driver Framework. Chapter 2 outlines tasks and services common to device and bus driver production within the Driver Framework Device Kernel Interface API. Chapter 3 provides a step-by-step overview of writing device drivers in the Driver Framework, using a working driver as an example. Chapter 4 provides a step-by-step overview of writing bus drivers in the Driver Framework, using a working driver as an example. Appendix A provides pointers to detailed information. Related Reading The ChorusOS 4.0 Introduction introduces the features and components of the ChorusOS operating system. It explains how to use ChorusOS and how to create an application that runs on the ChorusOS operating system. The ChorusOS Release Notes contain information about new features and restrictions in this release of the product. The following books describe how to use ChorusOS ChorusOS 4.0 File Systems User’s Guide explains how to use the file systems provided with the ChorusOS operating system. It includes information about using the NFS server. ChorusOS 4.0 Installation Guide for Solaris Hosts explains how to download and install ChorusOS on a Solaris host. ChorusOS 4.0 Installation Guide for Windows NT Hosts explains how to download and install ChorusOS on a Windows NT host. ChorusOS 4.0 Network Administration Guide explains how to use various network protocols with the ChorusOS operating system, including the point-to-point protocol (PPP) and the serial line internet protocol (SLIP). ChorusOS 4.0 Hot Restart Programmer’s Guide describes the support for hot restart provided in the ChorusOS operating system and explains how to use it.