WRITING A DEVICE DRIVER FOR AIX VERSION 3 GG24-3629-00 Writing a Device Driver for AIX Version 3 Document Number GG24-3629 May, 1991 International Technical Support Center Austin, Texas Take Note -----------------------------------, Before using this information and the product it supports, be sure to read the general information under "Special Notices" on page xv. First Edition (May, 1991) This edition applies to Version 3, Release Number 1 of Advanced Interactive Executive, Program Number 5756-030 (the AIX 3.1 Operating System). Order publications through your IBM representative or the IBM branch office serving your locality. Publications are not stocked at the address given below. A form for reader's comments appears at the back of this publication. If the form has been removed, address your comments to: IBM Corporation, International Technical Support Center 11400 Burnet Road Dept. 948, Building 983 Austin, TX 78758 USA When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you. © Copyright International Business Machines Corporation 1991. All rights reserved. Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp. Abstract This document describes the writing and debugging of device drivers for the RISC/BOOO running under the AIX Version 3.1 operating system. This document is intended for programmers and software support personnel who need to know detailed information on writing device drivers. A knowledge of device drivers, device hardware, and the C programming language is assumed. AIX (435 pages) co Copyright IBM Corp. 1991 Iii Iv Contents Chapter 1. Introduction . .. 1-1 1.1 Device Driver Concepts ............................ 1-1 1.1.1 Special Files in AIX ............................ 1-1 1.1.2 Major and Minor Numbers ........................ 1-2 1.2 Device Driver Types .............................. 1-3 1.2.1 Block Mode Device Drivers ....................... 1-3 1.2.2 Character Mode Device Drivers .................... 1-3 1.3 Device Driver Roles .............................. 1-4 1.3.1 Device Head Role ............................. 1-4 1.3.2 Device Handler Role ........................... 1-4 1.3.3 Combining the Roles ........................... 1-4 1.4 Device Driver Structure ............................ 1-6 1.4.1 Device Driver Top Half Routines .................... 1-7 1.4.2 The Device Driver Bottom Half ..................... 1-7 Chapter 2. Programmer's model of the hardware ............... 2-1 2.1 Micro Channel Overview ........................... 2-1 2.2 System lID Structure .............................. 2-3 2.2.1 Overview .................................. 2-3 2.2.2 RISC System/6000 Addressing Model . .. 2-3 2.3 lID Data Transfer Protocols .......................... 2-9 2.3.1 Programmed lID Mode .......................... 2-9 2.3.2 DMA Transfers ............................... 2-9 2.4 Interrupt Processing .............................. 2-11 2.4.1 Priority Assignment ............................ 2-12 2.4.2 Off-Level Interrupts ............................ 2-13 2.5 Addressing Micro Channel Adapters .................... 2-13 2.5.1 Identifying an Adapter .......................... 2-13 2.5.2 Setting Adapter Attributes ........................ 2-14 2.5.3 Enabling an Adapter ........................... 2-14 2.5.4 lID Macros ................................. 2-14 2.5.5 Sample lID on the RISC System/6000 ................. 2-18 2.5.6 Byte Reversal from the System Bus to the Micro Channel Bus .. 2-19 2.5.7 Additional PIO Macro Information ................... 2-21 Chapter 3. Interface to Device Drivers . .. 3-1 3.1 Aix Version 3.1 Structure ........................... 3-1 3.1.1 AIX and the Interrupt and Process Environments .......... 3-1 3.1.2 The AIX Interrupt Handler Environment ................ 3-3 3.1.3 The AIX Process Environment . .. 3-4 3.1.4 Preemption in the AIX Operating System ............... 3-5 3.2 Kernel Interface ................................. 3-6 3.2.1 The Device Switch Table ......................... 3-7 3.2.2 Entry Points Common to Character and Block Device Drivers 3-8 3.2.3 Entry Points for Character and Raw Access to Block Device Driver 3-9 3.2.4 Entry Points Unique to Character Device Drivers .......... 3-9 3.2.5 Entry Points Unique to Block Device Drivers ............. 3-9 3.2.6 Entry, Points for Trusted Computing Path Device Drivers ...... 3-9 3.2.7 Miscellaneous Entry Points NOT Found in the Device Switch Table 3-9 3.3 Kernel Services . .. 3-10 3.3.1 I/O Services ................................ 3-10 @ Copyright I BM Corp. 1991 V 3.3.2 Memory Services 3-13 3.3.3 Other Services . 3-15 Chapter 4. Overview of a Character Device Driver 4-1 4.1 Implementation ............. 4-1 4.1.1 ddconfig Device Driver Entry Point 4-1 4.1.2 ddmpx Device Driver Entry Point 4-12 4.1.3 ddopen Device Driver Entry Point 4-19 4.1.4 ddclose Device Driver Entry Point 4-24 4.1.5 ddread Device Driver Entry Point 4-29 4.1.6 ddwrite Device Driver Entry Point 4-34 4.1.7 ddioctl Device Driver Entry Point 4-42 4.1.8 ddselect Device Driver Entry Point 4-46 4.1.9 dddump Device Driver Entry Point 4-52 Chapter 5. Overview of a Block Device Driver 5-1 5.1 Introduction .................. 5-1 5.1.1 Block I/O Device Driver Entry Points . 5-1 5.1.2 Character Access to Block Device Drivers 5-6 5.1.3 Block I/O Device Device Summary . 5-7 Chapter 6. Device Drivers Configuration 6-1 6.1 Introduction .............. 6-1 6.1.1 General Structure of the Device Configuration Subsystem 6-1 6.1.2 Device Configuration Database Overview .,. 6-5 6.1.3 Device Configuration Procedure Overview 6-7 6.2 Configuring an Unsupported Device to the System 6-13 6.2.1 Modifying the Predefined Database 6-13 6.2.2 Writing Device Methods . 6-14 Chapter 7. SMIT Interface 7-1 7.1 Introduction 7-1 7.2 SMIT Screens 7-3 7.2.1 Menu Screens 7-3 7.2.2 Selector Screens 7-3 7.2.3 Dialog Screens 7-4 7.3 SMIT Database ..... 7-5 7.4 Command Building and Running 7-12 7.4.1 Task Building 7-12 7.4.2 Command Execution 7-12 7.5 Dialogs Example 7-14 7.5.1 List All Defined Ric Ports 7-14 7.5.2 Add a Ric Port ..... 7-15 7.6 Additions to the SMIT Database 7-20 7.6.1 Database Creation ..... 7-20 7.6.2 SMIT Extensions Debugging 7-20 7.6.3 Task Additions ....... 7-21 Chapter 8. Device Drivers Packaging 8-1 8.1 Introduction ..... 8-1 8.2 DeSign Guidelines ....... 8-1 8.3 The installp Command ............ 8-1 8.4 Ensuring installp Command Compatibility 8-2 8.5 Files for installp Operation ..... 8-2 8.5.1 LPP Option List File: Ipp_name ..... 8-3 vi 8.S.2 Instal Script . .. 8-4 8.S.3 al (Option.al) ................................ 8-4 8.S.4 size (Option.size) ............................. 8-4 8.S.S copyright .................................. 8-4 8.S.6 Ipp.cleanup ................................. 8-4 8.S.7 Prereq (Option.prereq) .......................... 8-4 8.S.8 config (Option.config) ........................... 8-S 8.S.9 Ipp.deinst .................................. 8-S 8.S.10 inventory (Option.inventory) ...................... 8-S 8.S.11 productid ................................. 8-S 8.S.12 Ipp.acf ................................... 8-S 8.6 Installp Example ................................ 8-S 8.6.1 Introduction ................................. 8-6 8.6.2 How to Use the Makefile ......................... 8-6 8.6.3 Rootllpp_name File ......... 8-8 8.6.4 Apply List Files ........................... 8-8 Chapter 9. Tools for Debugging Device Drivers ............. 9-1 9.1 Debugging Overview ........................ , 9-1 9.2 System Dump .................................. 9-1 9.2.1 Initiating a System Dump ........................ 9-1 9.2.2 Including Device Driver Information in a System Dump 9-2 9.2.3 Formatting a System Dump ................ , 9-S 9.3 The crash Command ............................. 9-6 9.3.1 crash Subcommands ........................... 9-7 9.4 The Kernel Debugger ............................. 9-18 9.4.1 The Kernel Debug Program Commands ............... 9-20 9.S Using the Kernel Debugger to Debug Device Drivers .......... 9-29 9.S.1 Setting Breakpoints in Device Driver Routines ............ 9-29 9.S.2 Setting Breakpoints in System Routines ............... 9-30 9.S.3 Displaying Registers on a Micro Channel Adapter ......... 9-30 9.S.4 How to read/write Data Variables in your Device Driver ...... 9-31 9.6 Error Logging .................................. 9-3S 9.6.1 Pre-Coding Steps to Consider . .. ................. 9-37 9.6.2 Coding Steps .............. ................. 9-38 9.6.3 What Really Happens in /dev/error . .. 9-44 9.7 Performance Tracing for AIX ....... ................. 9-44 9.7.1 Introduction ................................. 9-44 9.7.2 Use of the trace Facility ......................... 9-48 9.7.3 Controlling trace ............................. , 9-S0 9.7.4 Producing a trace Report ........................ 9-S3 9.7.S Defining trace Events ........................... 9-S6 9.7.6 Usage Hints . .. 9-74 Chapter 10. Hints and Tips .......... 10-1 10.1 Crash and Kernel Debugging Addresses 10-1 10.2 Pinning Device Driver Code ....... 10-1 10.3 Compiling Device Drivers . .- ...... 10-3 10.4 Working with Kernel Processes ..... 10-3 10.4.1 Writing a Kernel Process ...... 10-3 10.4.2 Compiling a Kernel Process .... 10-3 10.4.3 Linking a Kernel Process ...... 10-4 10.4.4 Loading a Kernel Process ..... 10-4 10.4.S Starting a Kernel Process ..... 10-4 Contents vii Appendix A. AIX Devices ............................. A-1 A.1 Device Classes, Subclasses, and Types Overview ............ A-1 A.2 Device Dependencies and Child Devices .