Device Driver Programming 0890425-070 October 1999 Copyright 1999 by Concurrent Computer Corporation. All rights reserved. This publication or any part thereof is intended for use with Concurrent Computer Corporation products by Concurrent Computer Corporation personnel, customers, and end–users. It may not be reproduced in any form without the written permission of the publisher. The information contained in this document is believed to be correct at the time of publication. It is subject to change without notice. Concurrent Computer Corporation makes no warranties, expressed or implied, concerning the infor- mation contained in this document. To report an error or comment on a specific portion of the manual, photocopy the page in question and mark the cor- rection or comment on the copy. Mail the copy (and any additional comments) to Concurrent Computer Corporation, 2101 W. Cypress Creek Road, Ft. Lauderdale, FL 33309–1892. Mark the envelope “Attention: Publications Department.” This publication may not be reproduced for any other reason in any form without written permission of the publisher. This document is based on copyrighted documentation from Novell, Inc. and is reproduced with permission. Power Hawk is a trademark of Concurrent Computer Corporation PowerPC is a trademark of IBM Corporation, used by permission of Motorola, Inc. Symmetric Superscalar is a trademark of Motorola, Inc. Night Hawk is a registered trademark of Concurrent Conputer Corporation UNIX is a registered trademark, licensed exclusively by X/Open Company Ltd. Printed in U. S. A. Revision History: Level: Effective With: Original Release -- August 1994 000 PowerUX 1.1 Previous Release-- February 1998 060 PowerMAX OS 4.2 Previous Release-- October 1999 070 PowerMAX OS 4.3 Preface Scope of Manual This manual provides reference information and procedures for developing device driver for all Concurrent systems (except PowerStack) running PowerMAX OS. It focuses only on development of drivers for character devices. Structure of Manual This manual consists of seventeen chapters, one appendix, a glossary, and an index. A brief description of the chapters is presented as follows: • Chapter 1 introduces this manual. • Chapter 2 overviews device drivers. • Chapter 3 describes the Peripheral Component Interconnect (PCI) Envi- ronment • Chapter 4 describes the Series 6000 hardware environment. • Chapter 5 describes the Power Hawk Model 610 hardware environment. • Chapter 6 describes the PowerMAXION hardware environment. • Chapter 7 describes the Power Hawk Model 620/640 hardware environ- ment. • Chapter 8 describes the Motorola MCP750 hardware environment. • Chapter 9 explains the kernel environment. • Chapter 10 decsribes the procedure for developing a device driver. • Chapter 11 explains how to multithread device drivers. • Chapter 12 explains how to support direct memory access (DMA). • Chapter 13 explains how to dynamically link device drivers to the system. • Chapter 14 explains driver installation and tuning. • Chapter 15 explains how to test and debug device drivers. • Chapter 16 describes the special factors considered when developing device drivers for real-time or secure systems. • Chapter 17 discusses how to write a user-level device driver. • Appendix A provides an example user-level device driver for a National Instruments PCI DIO-96 card. iii Device Driver Programming The glossary defines technical terms important to understanding the concepts this guide presents. The index contains an alphabetical reference to key terms and concepts and the page num- bers where they occur in the text. Syntax Notation This manual uses the following notation: italic Books, reference cards, and items that users must specify print in italic type. Special terms might also print in italic. list bold User input prints in list bold type and must match what this guide shows. Names of directories, files, commands, options and man page references also print in list bold type. list Operating system and program output such as prompts and mes- sages and listings of files and programs print in list type. [] Brackets enclose optional arguments and command options for ease of reading. Actual user input must not include brackets. Referenced Publications This manual refers to the following publications: 0830047 HN6200 Console Reference Manual 0830044 HN6800 Console Reference Manual 0830050 Motorola SBC Console Reference Manual 0830048 HN6200 Architecture Manual 0830046 HN6800 Architecture Manual 0830053 PowerMAXION Architecture Manual 0890276 HVME Extension Specification 0890423 PowerMAX OS Programming Guide 0890426 STREAMS Modules and Drivers 0890429 System Administration (Volume 1) 0890430 System Administration (Volume 2) 0890431 Audit Trail Administration 0890466 PowerMAX OS Real-Time Guide 0890479 PowerMAX OS Guide to Real-Time Services iv Preface On line Command Reference On line Operating System API Reference On line System Files and Devices Reference On line Device Driver Reference v Device Driver Programming vi Contents Contents Chapter 1 Introduction Focus of Manual . 1-1 Overview of the Driver Development Effort . 1-1 Writing a New Device Driver. 1-1 Porting an Existing Device Driver . 1-2 Organization of Manual. 1-2 Supporting Documentation . 1-3 Chapter 2 Understanding Device Drivers What Is a Device Driver?. 2-1 Application Programs Versus Drivers . 2-2 Structure . 2-2 Parallel Execution. 2-3 Interrupts. 2-3 Driver As Part of the Kernel. 2-4 Types of Devices . 2-5 Hardware Devices. 2-5 Software Devices . 2-5 Types of Device Driver Interfaces . 2-6 Block and Character Interfaces . 2-6 STREAMS Interface . 2-6 Major and Minor Numbers . 2-7 Major Numbers. 2-7 Minor Numbers . 2-7 Driver Entry Points and Kernel Utilities . 2-7 Entry Points . 2-7 Initialization Entry Points . 2-8 Switch Table Entry Points . 2-8 Interrupt Entry Points . 2-10 Kernel Support Routines . 2-10 Driver Environment . 2-10 Installation and Configuration . 2-10 Master, System, and Sadapters Files . 2-11 Master File. 2-11 System File . 2-12 Sadapters File . 2-12 Driver Header Files . 2-12 Driver Development. 2-12 Chapter 3 The PCI Environment Introduction . 3-1 PCI Variants and Form Factors . 3-1 Big Vs Little Endian Issues . 3-2 RISC Vs CISC CPU Processor Issues. 3-3 Types of PCI Resources. 3-3 vii Device Driver Programming Configuration Space . 3-3 Base Address Registers(BAR) . 3-4 Decode into I/O Space. 3-4 Decode into Memory Space. 3-4 ROM Base Address Registers(BAR) . 3-5 Decode into Memory Space. 3-5 Interrupts . 3-5 System Memory and PCI bus Master Devices . 3-5 Effects of PCI to PCI Bridges. 3-5 PowerMax OS Support . 3-5 Finding the Correct Adapter Structure . 3-6 Accessing the Configuration Space Registers. 3-6 Getting/Releasing the Base Address Register Assignments. 3-6 Determining the Kernel Virtual Address of PCI Base Address Register . 3-6 Accessing PCI Device Registers and Memory Space Though Kernel Virtual Maps . 3-7 Determining PCI Memory Address of Particular System Memory Location . 3-7 Attaching and Releasing a PCI Interrupt Vector Assigned to a PCI Slot/Function . 3-7 Chapter 4 Series 6000 Hardware Environment System Overview . 4-1 Processor Board . 4-1 Caches . 4-2 Memory..