Motorola MCP750 Spécifications

Device Driver Programming0890425-070October 1999

Device Driver ProgrammingxData Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5Byt

Device Driver Programming7-8VME Address Ranges 7The following text explains the address ranges used by VME devices on the (H)VMEprimary I/O bus when t

Power Hawk 620/640 Hardware Environment7-9Bus Time-Out 7For each data transfer accessing a slave device, the VME bus provides a bus timer whichmeasure

Device Driver Programming7-10Considerations” for more information. Also refer to Device Drivers and VME Bus Errorsand the iobus_err(2) man page for mo

Power Hawk 620/640 Hardware Environment7-11Bus arbitration is important only for devices that can act as bus masters. This is indicatedin a device spe

Device Driver Programming7-12VME interrupt request lines are only one source of interrupts in the system. VMEinterrupt request lines are mapped to the

Power Hawk 620/640 Hardware Environment7-13whereby the IACK* signal is propagated to each device via an IACKIN/IACKOUT*signal chain through the slots

Device Driver Programming7-14Table 7-3. Default PCI Address DecodeAddress Mode Processor PCI VMEPCI I/O: StartEndOffset0x800000000x960000000x00000000

8Motorola MCP750 Hardware EnvironmentSYSTEM OVERVIEW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1

Device Driver Programming

8-18Chapter 8Motorola MCP750 Hardware Environment888SYSTEM OVERVIEW 8The Motorola MCP750 system is a , single board, uniprocessor, real-time, super-mi

ContentsxiTiming and Timeout Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-19Interrupt Vector Routines . . .

Device Driver Programming8-2The MCP750 provides the 1 MB backdoor external cache option. The Falcon chip set con-trols the boot Flash and the ECC DRAM

Motorola MCP750 Hardware Environment8-3Figure 8-1. Motorola MCP750 System Block Diagram

Device Driver Programming8-4BUSSES 8There are two main busses on the MCP750, the processor bus (also called the MPC60Xbus) and the 64-bit PCI bus.Inte

Motorola MCP750 Hardware Environment8-5- The PCI bus (interrupts from PCI devices)- The CPCI bus (interrupts from CPCI devices)- Power monitor interru

Device Driver Programming8-6Figure 8-2, “Big Endian Bit and Byte Notation” for more information. (Note that thedepicted bit ordering (with bit 31 most

Motorola MCP750 Hardware Environment8-7

Device Driver Programming8-8

Motorola MCP750 Hardware Environment8-9

Device Driver Programming8-10

9Understanding the Kernel EnvironmentOverview of the Kernel I/O Structure and Flow of Control . . . . . . . . . . . . . . . . . . . 9-1Overview of So

Device Driver ProgrammingxiiUsing Multiple Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-18Synchr

Device Driver Programming

9-19Chapter 9Understanding the Kernel Environment999This chapter describes the role of device drivers within the kernel and gives an overview ofvariou

Device Driver Programming9-2Figure 9-1. Kernel I/O StructureBy issuing system calls from the user level, a program accesses the file and process contr

Understanding the Kernel Environment9-3/usr/include/sys directories contain the system header files that contain the defini-tions of the structures us

Device Driver Programming9-4CAUTIONWhen using C data types to communicate with hardware deviceson the Series 6000 platform, care must be taken to ensu

Understanding the Kernel Environment9-5cmn_err.h Defines the interface to display messages or panic the system.param.h Defines the machine type dependen

Device Driver Programming9-6The cdevsw structure specifies the interface routines present for the character device.Each device driver can provide open

Understanding the Kernel Environment9-7d_msgio VOP_MSGIO() routine called for non-STREAMS characterdevices that support msgio.d_ttys Pointer to the dr

Device Driver Programming9-8the transfer, two structures are used: the iovec(D4) and uio(D4) structures. Thesestructures are defined in /usr/include/s

Understanding the Kernel Environment9-9uio_fmode The file status flags set by the value of the oflag argument speci-fied when the file was opened with

Contentsxiiiidspace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-5idtune. . . . . . . .

Device Driver Programming9-10/** Used by drivers*/device_t *devices; /* List of devices on this adapter */long adapter_state;/* Adapter has b

Understanding the Kernel Environment9-11cpu Reserved for future use.sio_address Short I/O address of the adapter. The term short I/O refersto the sixt

Device Driver Programming9-12The device Structure 9The device_t structure is defined in adapter.h as follows:typedef struct devices device_t;struct dev

Understanding the Kernel Environment9-13The command word is a 32-bit integer divided into several fields. The fields are explainedin Table 9-2:As mentio

Device Driver Programming9-14manual for additional information. The system buffers are used to implement the tradi-tional UNIX buffer cache, which is

Understanding the Kernel Environment9-15ready to manage its own allocation and deallocation requests. This is done by indexing thememory units in the

Device Driver Programming9-16btopr(D3) Convert size in bytes to size in pages (round up)ptob(D3) Convert size in pages to size in bytesvtop(D3) Conver

Understanding the Kernel Environment9-17Synchronization Routines 9The kernel provides three broad categories of synchronization/serialization routines

Device Driver Programming9-18Sleep Locks 9Sleep locks are used for serializing access to shared resources when spin locks cannot beused. At base level

Understanding the Kernel Environment9-19sor. Only interrupt requests at level 4 or higher are presented to the processor. All otherrequests are ignore

Device Driver ProgrammingxivBreakpoints in the Initialization Phase. . . . . . . . . . . . . . . . . . . . . . . . . 15-14Using crash to Debug a Drive

Device Driver Programming9-20To assist you in converting between microseconds and clock ticks, the kernel provides thefollowing routines:drv_hztousec(

Understanding the Kernel Environment9-21device unit identifier or a pointer to a configuration structure. When the interrupt becomesactive, the interrup

Device Driver Programming9-22offsets in all of its dealings with the rest of the kernel. This is the new off64_t type andwith it offsets, up to approx

Understanding the Kernel Environment9-23Although old binaries will install correctly, old sources cannot be rebuilt under the newPowerMAX OS without s

Device Driver Programming9-24

10Developing a Device DriverUnderstanding the Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1Dev

Device Driver Programming

10-110Chapter 10Developing a Device Driver101010This chapter describes the procedures for developing a device driver. It identifies aspectsof the devi

Device Driver Programming10-2reset in hardware or via a software command. While in this mode, the only functions thatthe HPS can perform are to open c

Developing a Device Driver10-3Programmed I/O Support 10A programmed I/O device does not directly access physical memory. Instead the devicesupplies da

ContentsxvThe Asynchronous I/O Support Routines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-25The aread Routine . . . . . . . . . .

Device Driver Programming10-4NOTEThis section illustrates the installation procedure for a 13-slotmodel of the Series 6000 platform. Different models

Developing a Device Driver10-5To install the board on the HVME primary I/O bus:• Mount the VME board onto an HVME adapter board (see A1). Thereis a mo

Device Driver Programming10-6The e command displays a byte, word, or longword of memory beginningat the specified memory location. This command can al

Developing a Device Driver10-7Each type of entry point is briefly described as follows.Initialization Routines 10Typically, there are some initializati

Device Driver Programming10-8You might also want to declare other structures for your device driver. The definitions forsuch structures should be in th

Developing a Device Driver10-9Typically, the types of activities performed by a driver’s init() or start() routine areas follows:1. Find the adapter’s

Device Driver Programming10-10tine. The rest of the initialization tasks can be coded either in the init() routine or in thestart() routine.The Start

Developing a Device Driver10-11Information needed to develop each type of driver I/O service routine is presented in thesections that follow.The Open

Device Driver Programming10-12FEXCL Interpreted in a driver dependent manner. Some driversinterpret this flag to mean open the device with exclusiveac

Developing a Device Driver10-13The Close Routine 10Specification#include <sys/types.h>#include <sys/file.h>#include <sys/errno.h>#inc

Device Driver ProgrammingxviTablesTable 4-1. HVME Address Range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6Table

Device Driver Programming10-14The Read Routine 10Specification#include <sys/types.h>#include <sys/errno.h>#include <sys/uio.h>#includ

Developing a Device Driver10-15To transfer characters to the user’s I/O buffers, the driver calls the uiomove(D3) kernelfunction and sets the read–wri

Device Driver Programming10-16The Write Routine 10Specification#include <sys/types.h>#include <sys/errno.h>#include <sys/uio.h>#inclu

Developing a Device Driver10-17The Ioctl Routine 10Specification#include <sys/types.h>#include <sys/errno.h>#include <sys/file.h>#inc

Device Driver Programming10-18The Chpoll Routine 10Specification#include <sys/types.h>#include <sys/errno.h>#include <sys/file.h>#inc

Developing a Device Driver10-19device minor number. If the I/O event for which the device is being polled has notoccurred when the driver’s chpoll rou

Device Driver Programming10-20the mmap routine returns NOPAGE. If the offset does exist, mmap returns the physical pageID for the page at offset off i

Developing a Device Driver10-21The Intr Routine 10Specificationvoidxxintr(ivec)intivec;Return ValuesNone.The ivec argument specifies a driver-defined n

Device Driver Programming10-22waiting on completion of a write request that data have been written fromthe internal driver buffers by waking up any ba

Developing a Device Driver10-23device driver uses a local routine to probe each VME slot until the device is found. Itignores slots that are already m

1IntroductionFocus of Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1Overview of t

Device Driver Programming10-24Finally, the kernel provides an error reporting facility. This facility consists of a kernelerror logging routine, an er

Developing a Device Driver10-25When a process blocked by SLEEP_LOCK_SIG is interrupted by a job control stop signaland is subsequently continued, the

Device Driver Programming10-26in SV_WAIT_SIG and needs to be wakened. If the flag is still set, the interrupt routineclears it and then invokes SV_SIG

11Multithreading a Device DriverThe Multithreaded, Preemptive Kernel and Device Drivers . . . . . . . . . . . . . . . . . . . 11-1Protecting a Device

Device Driver Programming

11-111Chapter 11Multithreading a Device Driver111111This chapter describes the methods for protecting a device driver in a multiprocessorsystem. It pr

Device Driver Programming11-2• Linked lists, state fields, and other data structures used by the driver• Global variables• Hardware registersAs indicat

Multithreading a Device Driver11-3of some code depends upon the current state being constant, then the lock that protectsupdates to the state must be

Device Driver Programming11-4Using the Synchronization Primitives 11The synchronization primitives to use in a multithreaded environment are spin lock

Multithreading a Device Driver11-5Spin Locks 11Spin locks are low-level, busy waiting synchronization primitives. They coordinate accessto data struct

Device Driver Programming

Device Driver Programming11-6Basic Locks 11After you have defined a basic lock’s lock information structure by using theLKINFO_DECL(D5) macro, you mus

Multithreading a Device Driver11-7Note that strictly speaking, the interrupt levels listed here are machine independentabstractions of the hardware in

Device Driver Programming11-8Upon acquiring a lock with the priority level set at the specified pl, LOCK returns the pre-vious priority level to the ca

Multithreading a Device Driver11-9#include <sys/types.h>#include <sys/ksynch.h>#include <sys/ddi.h>void LOCK_DEALLOC(lockp)lock_t *l

Device Driver Programming11-10#include <sys/types.h>#include <sys/kmem.h>#include <sys/ksynch.h>#include <sys/ddi.h>rwlock_t *

Multithreading a Device Driver11-11NOTEDo not use the plbase priority value for the min_pl argumentThis value is invalid because it does not block any

Device Driver Programming11-12Upon acquiring the lock, the RW_TRYRDLOCK routine returns the previous priority level.If the lock is not acquired, the R

Multithreading a Device Driver11-13pl is the interrupt priority level to be set after releasing the lock.The RW_UNLOCK routine has no return value.Fin

Device Driver Programming11-14#include <sys/types.h>#include <sys/kmem.h>#include <sys/ksynch.h>#include <sys/ddi.h>sleep_t *S

Multithreading a Device Driver11-15prihi High priorityprimed Medium priority (recommended)prilo Low priorityDrivers can use these values to request a

1-11Chapter 1Introduction111This chapter defines the scope of this manual and overviews the effort required to developa device driver for PowerMAX OS.

Device Driver Programming11-16porarily boost the priority of an LWP which is in the timesharing class as a reward forvoluntarily blocking itself. Vali

Multithreading a Device Driver11-17#include <sys/types.h>#include <sys/ksynch.h>#include <sys/ddi.h>bool_t SLEEP_LOCKOWNED(lockp)loc

Device Driver Programming11-18Using Multiple Locks 11If multiple LWPs are contending for the resources of the driver, it can be more efficient tohave

Multithreading a Device Driver11-19flag specifies if the caller can sleep waiting for memory if sufficient memory is notimmediately available to alloc

Device Driver Programming11-20primed Medium priority (recommended)prilo Low priorityDrivers can use these values to request a priority appropriate to

Multithreading a Device Driver11-21If an LWP sleeps because of a call to SV_WAIT_SIG, signals can cause the LWP to wakeup. Job control stop signals (S

Device Driver Programming11-22svp is a pointer to the synchronization variable to be broadcast signaled.flags is a bit field for flags. No flags are cur

11 Supporting Direct Memory Access (DMA)Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Device Driver Programming

12-112Chapter 12 Supporting Direct Memory Access (DMA)121212This chapter explains how to program devices that support Direct Memory Access (DMA)using

Copyright 1999 by Concurrent Computer Corporation. All rights reserved. This publication or any part thereof isintended for use with Concurrent Comput

Device Driver Programming1-22. Design the driver.3. Write the driver.4. Integrate the driver into the system5. Test and debug the driver.Procedures fo

Device Driver Programming12-2system loads it from disk back into RAM. This activity is not under the control of the userand may happen at any time. Me

Supporting Direct Memory Access (DMA)12-3physical memory pages. If the device is capable of performing scatter/gather DMA, thenthe driver should creat

Device Driver Programming12-4count. Also construct a new chain pair if the addition of this count to theprevious pair would result in the count exceed

Supporting Direct Memory Access (DMA)12-5else {/* * we must add another chain pair * * return an error if there are too many discontiguous * memory ar

Device Driver Programming12-6Direct Memory Access to Kernel Space 12Because kernel memory is never paged out, the driver writer needs only to handle v

12Loadable ModulesThe DLM Mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2Loadable Modul

Device Driver Programming

13-113Chapter 13Loadable Modules131313The Dynamically Loadable Modules (DLM) feature allows you to add a device driver (orother kernel module) to a ru

Device Driver Programming13-2The DLM Mechanism 13Loadable Module Types 13Since this book is about device drivers, this chapter focuses on loadable dev

Loadable Modules13-3Overview of the Load Process 13When a loadable module needs to be added to the system, the DLM mechanism reads themodule's lo

Introduction1-3Chapters 4-8 describe the hardware environments, briefly overview the platform and thenprovide more information on configuring and opera

Device Driver Programming13-4NOTELoadable high-level drivers (HDRV) cannot be auto loaded.HDRV drivers can, however, be demand loaded using themodadmi

Loadable Modules13-5Making Modules Loadable 13The following sections explain how to convert your non-loadable driver to be a loadabledriver.Coding a W

Device Driver Programming13-6The mod_drvdetach routine is called by the driver's _unloadroutine to disable and remove the driver's interrupt

Loadable Modules13-7NOTEA DLM can contain only one wrapper macro definition.Note that only MOD_DRV_WRAPPER and MOD_HDRV_WRAPPER module types have theha

Device Driver Programming13-8Screen 13-2 shows a sample wrapper for a high level (HDRV) driver.Screen 13-2. High Level Driver Wrapper Coding ExampleS

Loadable Modules13-9Screen 13-4 shows a sample wrapper for a file system module. Notice that this file systemmodule doesn't need to do any clean-up

Device Driver Programming13-10Packaging a Loadable Module for Installation 13Dynamically Loadable Modules under PowerUX are compiled as shared objects

Loadable Modules13-11The $modtype line in the Master file lets you define a character string that helps iden-tify a driver in error messages. This strin

Device Driver Programming13-12The global auto-unload delay values are defined as:DEF_UNLOAD_DELAY 60 0 3600This says that, by default, a

Loadable Modules13-13The -l option instructs modadmin to load a loadable module into the running system.For example, the commandmodadmin -l lploads a

Device Driver Programming1-4PowerMAX OS Real-Time Guide (Pub. No. 0890466)Explains user-level interrupt routines and inter-process synchronization on

Device Driver Programming13-14Unloading the Module 13The -u and -U options instruct modadmin to unload a module from the running system.For example, t

14Driver Installation and TuningUsing idtools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Device Driver Programming

14-114Chapter 14Driver Installation and Tuning141414For device driver writers, installation means different things. If you are installing a driverfor

Device Driver Programming14-2for these commands are provided in the Command Reference. Details about the DSP com-ponent files (such as the Driver.o, Ma

Driver Installation and Tuning14-3Base kernel rebuilds are usually needed after a statically linked kernel module is installed,when any static module

Device Driver Programming14-4NOTEThe exact pathnames of installed files in /etc/conf can changein future releases. These files should be accessed only

Driver Installation and Tuning14-5On the next system reboot after a kernel reconfiguration, in sysinit state, the idmknodcommand is run automatically (

Device Driver Programming14-6By default, if the parameter has already been tuned previously, you are asked to confirmthe change with the messageTunabl

Driver Installation and Tuning14-7figuration files from the installation media to the hard disk of the system, installs any DSPsusing idinstall, then th

2Understanding Device DriversWhat Is a Device Driver?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1Ap

Device Driver Programming14-8DSP Component Files 14Following are each of the component files that make up the typical DSP. Where possible,an example ha

Driver Installation and Tuning14-9Driver.o 14A required component, the Driver.o component is the driver object module that is to beconfigured into the

Device Driver Programming14-10component of a DSP is installed, idinstall stores the module's System file informa-tion in /etc/conf/sdevice.d/modu

Driver Installation and Tuning14-112. Generates a valid id field value (called a tag) and prepends it to the entry.3. Generates an rstate field with a v

Device Driver Programming14-12For complete information about the Mtune file format, refer to the Mtune(4) manualpage.Node 14An optional component, the

Driver Installation and Tuning14-13The contents of the /etc/conf/rc.d directory are linked to /etc/idrc.d whenevera new configuration of the kernel is

Device Driver Programming14-14Packages should never access Sd files in /etc/conf directly; they should use theidinstall command instead.The contents o

Driver Installation and Tuning14-15Packaging the Driver 14For complete information on the system packaging tools, refer to System AdministrationVolume

Device Driver Programming14-16Following is an example of a prototype file for a driver add-on package.For more information, refer to the prototype(4) m

Driver Installation and Tuning14-17When writing a postinstall script, you should make liberal use of echo andmessage commands to tell the user what is

Device Driver Programming

Device Driver Programming14-183. Invoke idbuild without any options to cause the kernel to be rebuiltwhen the system is rebooted.Following is an examp

Driver Installation and Tuning14-19Removing a Package 14As shown above, the installation process is relatively simple and straightforward from theuser

Device Driver Programming14-20Updating a DSP 14If a check for the existence of the DSP (using idcheck) turns up positive, apostinstall script should u

Driver Installation and Tuning14-21removed. An idbuild is required to reconfigure the kernel once the DSP has beenremoved.Building a New Kernel 14A ne

Device Driver Programming14-22Documenting Your Driver Installation 14If you are developing a DSP to be installed by users who might not be familiar wi

15Driver Testing and DebuggingIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Device Driver Programming

15-115Chapter 15Driver Testing and Debugging151515Introduction 15Testing a device driver consists of installing the driver on a working system and att

Device Driver Programming15-24. ioctl(D2), read(D2), write(D2) and/or strategy(D2) andprint(D2)When the driver seems to be functioning properly under

Driver Testing and Debugging15-3a file or to a remote terminal. You can also write cmn_err statements to the console, butmassive amounts of statements

2-12Chapter 2Understanding Device Drivers222This chapter explains what a device driver is and how a driver differs from an application.It describes th

Device Driver Programming15-4Installing a Driver for Testing 15Many of the steps that follow require you to modify files and directories owned by root

Driver Testing and Debugging15-5Common Driver Problems 15Following is a discussion of some common driver bugs, with possible symptoms. Theseshould be

Device Driver Programming15-6Timing Errors 15Timing errors occur when the driver code executes too quickly or too slowly for the devicebeing driven. F

Driver Testing and Debugging15-7the input and output. As soon as any one of these operations fails, you should reboot thesystem immediately to ensure

Device Driver Programming15-8• If a system panic is repetitively occurring in a section of driver code, abreakpoint can be set beforehand in that code

Driver Testing and Debugging15-9Understanding the p command of the console processor debugging commands is essentialto booting the system and debuggin

Device Driver Programming15-10##INIT: :New run level: 0The system is coming down. Please wait.CPU 0 halted001fea24 [001fea24] pause_self+60% 48000000

Driver Testing and Debugging15-11001baf5c [001baf5c] idle+84 % 80700014 lwz r3,0x14(r16)#0>#0>b gdread#0>r# dd if=/dev/rusr of=/dev/null

Device Driver Programming15-12CPU 1 breakpoint00124808 [00124808] gdread+1c %*48000095 bl gdsizeCPU 0 halted001baf5c [001baf5c] idle+84 % 8070

Driver Testing and Debugging15-1300:00: hsa: Adapter 8 configured in slot 10.00: SCSI disk @ID 0 on hsa adapter 8.00: hsa: Adapter 9 configured i

Device Driver Programming2-2Figure 2-1. Driver Placement in the KernelUNIX systems see every device as a file. Even the user-level interface to the d

Device Driver Programming15-14STACK TRACE FOR PROCESS 30 LWP 0:xcmn_panic+0x64 () sp:058cc100 ret:002ade28xcmn_err

Driver Testing and Debugging15-15 CPU 0 CPU 1dsk(a,0,0,0)/.dsk(a,0,0,0)/bootNH Boot LoaderBoot: /stand/unix2997340+626016+2768732 start 0xE000symb

Device Driver Programming15-16#0>#0>bk all#0>r00:00: The system is coming up. Please wait.00:00: hsa: Adapter 8 configured in slot 10.00:

Driver Testing and Debugging15-17The system automatically saves the dump image when it detects an improper shutdown.By default, when entering multi-us

Device Driver Programming15-18the starting address of the stack, list the registers with the paniccommand.proc List the process table. Use this inform

Driver Testing and Debugging15-19matically under various conditions, such as panics and breakpoint traps. Any time thekdb>> prompt displays, you

Device Driver Programming15-20analysis. If the error is recoverable, the driver should not panic the system. An example ofpanicking using cmn_err() is

16Special ConsiderationsDevice Drivers and Real Time. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-1Device Dri

Device Driver Programming

16-116Chapter 16Special Considerations161616This chapter describes the special factors that you must consider when developing adevice driver for a rea

Understanding Device Drivers2-3System data structures, called switch tables, contain the starting addresses for the principalroutines included in all

Device Driver Programming16-2should not be blocked for long periods of time. A device driver that is written for a con-ventional UNIX kernel can block

Special Considerations16-3system start-up script, to register itself to catch a range of VME addresses. If a VME buserror occurs within this registere

Device Driver Programming16-44. Based on the state of the device and the information from the IO_INFOiobus_err(2) call, the signal handler should deci

Special Considerations16-5labeling of imported or exported data. For a description of these and related issues, refer tothe TCSEC.Design and Implement

Device Driver Programming16-6

17Writing a User-Level Device DriverUnderstanding a User-Level Device Driver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-1What I

Device Driver ProgrammingCreate a User-Level Interrupt Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-40Provide Debug and

17-117Chapter 17Writing a User-Level Device DriverThis chapter provides an overview of user-level device drivers. It describes thecomponents that make

Device Driver Programming17-2What Are the Advantages and Disadvantages of a User-Level Driver?17The chief advantage of a user-level device driver is t

Writing a User-Level Device Driver17-3Because of these limitations, it is intended that a user-level device driver be used only byapplications that ex

Device Driver Programming2-4much more slowly than the CPU, the data transfer can squander many processor cycles ifthe CPU waits on the drive. To avoid

Device Driver Programming17-4Single-User Drivers versus Multiuser Drivers 17Developing a user-level device driver that allows only one lightweight pro

Writing a User-Level Device Driver17-5different types of driver routines that can be provided is presented in “Overview of User-Level Device Driver Ro

Device Driver Programming17-6Shared Memory Regions 17Shared memory regions are needed to provide access to a device’s registers and to provideaccess t

Writing a User-Level Device Driver17-7int register_id; /* IPC id for register region */unsigned int register_offset;/* register offset into shared mem

Device Driver Programming17-81. Define a reserved section of physical memory by initializing theres_sects[] array in the /etc/conf/pack.d/mm/space.c fil

Writing a User-Level Device Driver17-9you use the userdma(2) system call to prepare a buffer forDMA transfers.The dmavec structure has been defined to

Device Driver Programming17-10Generally a user-level device driver performs I/O asynchronously rather thansynchronously. The reason is that asynchrono

Writing a User-Level Device Driver17-11Overview of Interrupt-Handling Issues 17A user-level driver can be written to support only polling and provide

Device Driver Programming17-12Overview of Synchronization Issues 17During development of a user-level device driver, you must address a number ofsynch

Writing a User-Level Device Driver17-13overview of these system calls is provided in “Process Synchronization Tools” on page17-19.Overview of Error Re

Understanding Device Drivers2-5NOTESome of the DDI/DKI functions (such as kmem_alloc(D3))resemble standard library functions (such as malloc(3C)), but

Device Driver Programming17-14Overview of the Device Configuration Program 17User-level device drivers written by Concurrent Computer Corporation perso

Writing a User-Level Device Driver17-15Understanding Operating System Support for a User-LevelDriver 17Operating system support for writing and using

Device Driver Programming17-16• The application’s buffer must be locked in physical memory; that is, thebuffer must be resident, and the virtual to ph

Writing a User-Level Device Driver17-17buffer a pointer to an I/O buffer in the user’s virtual address spacesize the size of the I/O buffer in bytesus

Device Driver Programming17-18functions. The order in which the functions are executed is the reverse of the order inwhich they are registered with a

Writing a User-Level Device Driver17-19is suggested that the string indicate the name of the routine that has producedthe error.The uderror routine wr

Device Driver Programming17-20exclusion mechanisms, and coordinating client-server interaction among processes.Descriptions of the tools that are pert

Writing a User-Level Device Driver17-21able and re-enable rescheduling and to determine the number of rescheduling locks ineffect. These macros are br

Device Driver Programming17-22Procedures for using the server_block and the server_wake1 system calls in auser-level driver’s interrupt routine are ex

Writing a User-Level Device Driver17-23The vme_address(3C) Library Routine 17The vme_address(3C) routine enables you to obtain a 32-bit physical addre

iiiPrefaceScope of ManualThis manual provides reference information and procedures for developing device driverfor all Concurrent systems (except Powe

Device Driver Programming2-6Types of Device Driver Interfaces 2A device driver interface is the set of structures, routines, and optional functions us

Device Driver Programming17-24shmget(2) to obtain the shared memory identifier for the regionshmat(2) to attach the shared memory region to the process

Writing a User-Level Device Driver17-25Return ValueThe driver’s open routine returns EUD_NOERROR if the device is successfully opened.Otherwise, it re

Device Driver Programming17-26For an I/O device that performs programmed I/O or a user-level device driver that doesintermediate buffer copying, the u

Writing a User-Level Device Driver17-27Return ValueThe driver’s aread routine returns EUD_NOERROR if the operation is successfullyqueued. It returns t

Device Driver Programming17-28Parametersdev_desc the identifier for the device to which data are to be written. This identifier isreturned by the driver

Writing a User-Level Device Driver17-29Return ValueThe driver’s acheck routine returns EUD_NOERROR if the specified asynchronous I/Ooperation has been

Device Driver Programming17-30Parametersdev_desc the identifier for the device to or from which the asynchronous I/O operationis being performed. This

Writing a User-Level Device Driver17-31A general purpose control function similar to the ioctl routine used by kernel devicedrivers has not been defin

Device Driver Programming17-32• Ensuring that all I/O operations have been completedThis function is especially important for a device that uses DMA b

Writing a User-Level Device Driver17-33Example specification and pseudo code for a user-level driver’s close routine ispresented as follows:intdev_clo

Understanding Device Drivers2-7Major and Minor Numbers 2Before the operating system can access a device, the device needs its driver installed and asp

Device Driver Programming17-34Developing the Driver’s Interrupt Service Routine 17To develop a user-level driver routine that services interrupts gene

Writing a User-Level Device Driver17-351. Provide for communication between the user-level interrupt process andother processes to which the driver is

Device Driver Programming17-36the process is in this state, all signals are ignored. The process no longerexecutes at normal program level. Each time

Writing a User-Level Device Driver17-37For those user-level interrupt applications that want to bind some portion of their addressspace to local memor

Device Driver Programming17-38and the Secure/PowerUX kernels, the exception-handling code checks forinterrupt-handling routines.• An interrupt-handlin

Writing a User-Level Device Driver17-39-i create the user-level interrupt process-d display debug and status information-x remove the user-level devic

Device Driver Programming17-403. Initialize global data structures that contain information about a particulardevice, and initialize synchronization p

Writing a User-Level Device Driver17-41Provide Debug and Status Information 17You might want to provide the -d option to facilitate debugging. To supp

Device Driver Programming17-42• Use printf throughout your code.• Maintain event statistics and trace information. Maintain a trace buffer inshared me

A-1AAppendix AExample PCI User-Level Device Driver111This appendix contains an example of a user-level device driver for a National InstrumentsPCI DIO

Device Driver Programming2-8• System calls by applications• Interrupts by devices.The process of initializing the system creates several tables so the

Device Driver ProgrammingA-2#include <sys/bridge.h>#include <sys/pci_info.h>extern int shmctl();extern int shmdt();extern int errno;#defin

Example PCI User-Level Device DriverA-3 int bus,dev; PCI_DWORD dev_vend_id; bus = PCITAG_BUSNUM(tag); dev = PCITAG_DEVNUM(tag)+1; for (; bus

Device Driver ProgrammingA-4 perror("PCIud - unable to alloc DIO Base address 0 (PCImite) "); goto hot_swap_only;}/* map base address

Example PCI User-Level Device DriverA-5 goto error_exit;}/* bind phys address of PCI dev to shm_id */if (shmbind(bar1_shm_id, bar1.cpu_addr) == -1)

Device Driver ProgrammingA-6}if (bar0_shm_id != NULL) {/* check if shmid valid */ shmctl(bar0_shm_id, IPC_RMID, NULL);/* yes, free it */ bar1_sh

Glossary-1Glossary222adapterA hardware set which connects one or more device controllers to the computer system.alignmentThe position in memory of a u

Device Driver ProgrammingGlossary-2block data transferThe method of transferring data in units (blocks) between a block device such as a mag-netic tap

GlossaryGlossary-3cacheA section of computer memory where the most recently used buffers, i-nodes, pages, andso on are stored for quick access.charact

Device Driver ProgrammingGlossary-4device understands. For example, on a disk drive, the controller accepts a request to read afile and converts the re

GlossaryGlossary-5device switch tableThe kernel table constructed during automatic configuration that contains the address ofeach driver entry point r

Understanding Device Drivers2-91. The system directs the I/O system call (open and read, for exam-ple) to a special device file. This file includes th

Device Driver ProgrammingGlossary-6FDDIFiber Distributed Data Interface.functionA kernel utility used in a driver. The term function is used interchan

GlossaryGlossary-7kernel buffer cacheA set of buffers used to minimize the number of times a block-type device must beaccessed.lightweight processA li

Device Driver ProgrammingGlossary-8moduleA STREAMS module consists of two related queue structures, one each for upstreamand downstream messages. One

GlossaryGlossary-9raw I/OMovement of data directly between user address spaces and the device. Raw I/O is usedprimarily for administrative functions w

Device Driver ProgrammingGlossary-10small computer system interface (SCSI)The American National Standards Institute (ANSI) approved interface for supp

GlossaryGlossary-11threadAn abstraction of the concept of execution in a shared address space. A sequence ofinstructions that are executed as an indep

Device Driver ProgrammingGlossary-12

Index-1Aacheck routine 17-28adapter structure 9-9, 10-9address assignment and configuration 4-8, 5-8, 6-8, 7-10address management routines 9-15addr

Device Driver ProgrammingIndex-2DLM 13-2DMA device 17-3dma_pageio(D3) routine 12-3DR11W user-level driver 17-30Driveruser-level 17-1driverconfigu

IndexIndex-310-20, 17-34, 17-40interrupt-handling routineconstraints 17-37interrupts 2-3, 15-6intr routine 10-21iobus_err 6-8, 7-9ioctl macros 9-

Device Driver Programming2-10Devices need not use all the entry points provided by the switch table. For instance, printerdrivers do not need read rou

Device Driver ProgrammingIndex-4Pparallel execution 2-3physiock routine 12-2physmap routine 10-9physmap_alloc routine 9-15physmap_free routine 9-

IndexIndex-5SV_ALLOC routine 9-18, 11-18SV_BROADCAST routine 9-18SV_DEALLOC routine 9-18, 11-22SV_SIGNAL routine 9-18, 11-21SV_WAIT routine 9-18,

Device Driver ProgrammingIndex-6

Understanding Device Drivers2-111. Prepare a Driver Software Package (DSP), including the Driver.o objectmodule (the actual driver code), Master, Syst

Device Driver Programming2-12ram_ results in routines named ram_open, ram_init and so on. For more informa-tion, see the prefix(D1) manual page.The Ma

3The PCI EnvironmentIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1PC

Device Driver Programming

3-13Chapter 3The PCI Environment333Introduction 3The PCI (Peripheral Component Interconnect) BUS specifications was created out of theneed to create a

Device Driver ProgrammingivThe glossary defines technical terms important to understanding the concepts this guidepresents.The index contains an alpha

Device Driver Programming3-2high performance form factors are used only when the design of the add on device requiresperformance or resources that exc

The PCI Environment3-3Endian translation is necessary whenever a memory or I/O mapped address space isaccessed, or when accessing configuration space i

Device Driver Programming3-4of the configuration space. The remaining 192 or 1984(2048-64) is reserved for customuse by the device.Within the configura

The PCI Environment3-5ROM Base Address Registers(BAR) 3Decode into Memory Space 3Similar to Base Address Registers that decode into Memory Space with

Device Driver Programming3-6Finding the Correct Adapter Structure 3Use the routines adapter_find and adapter_find2 to locate instances of your device.

The PCI Environment3-7call must be used. The arguments must include the CPU physical address and the size ofthe PCI BAR register returned from the “pc

Device Driver Programming3-8

3Series 6000 Hardware EnvironmentSystem Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Device Driver Programming

4-14Chapter 4Series 6000 Hardware Environment444This chapter provides hardware-specific information useful in developing device driversfor the Series

PrefacevOn line Command ReferenceOn line Operating System API ReferenceOn line System Files and Devices ReferenceOn line Device Driver Reference

Device Driver Programming4-2Figure 4-1. Elements of an HN6800 Processor BoardCaches 4The processor features separate 16-Kb, four-way set-associative

Series 6000 Hardware Environment4-3Memory 4The HN6800 system uses 32-bit addresses for up to four gigabytes of virtual addressspace.Figure 4-1 shows t

Device Driver Programming4-4Byte-Ordering and Alignment 4The Series 6000 platform orders bytes according to the Big Endian convention, in whichthe mos

Series 6000 Hardware Environment4-5Transfer Width Support 4For all non-block mode transfers, (H)VME supports byte, word and long-word addresses.It sup

Device Driver Programming4-6HVME Address Ranges 4Table 4-1 shows the address ranges for HVME devices:VME Address Ranges 4This section details the addr

Series 6000 Hardware Environment4-7Table 4-3 shows the address ranges for (H)VME bus master accesses:Table 4-3. HVME Bus Master AccessTransfer Type

Device Driver Programming4-8Bus Time-Out 4The (H)VME bus measures with a bus timer the duration of data transfers accessing slavedevices. If a data tr

Series 6000 Hardware Environment4-9then the device vendor must build a programmable assembly for a suitableaddress.NOTEInstalling components not speci

Device Driver Programming4-10NOTEThe VMEbus specification defines an optional bus clear (BCLR)signal for the present master to relinquish the bus. HVM

Series 6000 Hardware Environment4-11Interrupt Request Levels and Priorities 4In the Series 6000, interrupts come from both processors or other hardwar

Device Driver Programmingvi

Device Driver Programming4-12NOTEFor system speed and proper device operation, increase the prior-ity of devices needing a quick response to interrupt

Series 6000 Hardware Environment4-13• If hardware settings determine the interrupt vector (preset), thenreconfigure the interrupt vector by modifying

Device Driver Programming4-14

5Power Hawk 610 Hardware EnvironmentSystem Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Device Driver Programming

5-15Chapter 5Power Hawk 610 Hardware Environment555This chapter provides hardware-specific information useful in developing device driversfor the Powe

Device Driver Programming5-2Figure 5-1. Elements of a Power Hawk PH610 Processor BoardCaches 5The processor features separate 16-Kb, four-way set-ass

Power Hawk 610 Hardware Environment5-3Memory 5The Power Hawk 610 uses 32-bit addresses for up to four gigabytes of virtual addressspace.Figure 5-1 dep

Device Driver Programming5-4individually enable and disable them. It sends the resultant interrupt through the MPC105Bridge chip to the PowerPC 604 pr

Power Hawk 610 Hardware Environment5-5Figure 5-2. Big Endian Bit and Byte NotationVME Addressing 5This section describes the characteristics of data

ContentsviiContentsChapter 1 IntroductionFocus of Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Device Driver Programming5-6Address Modifiers 5For each data transfer on the VME bus, the bus master (either a processor or an I/O device)must identify

Power Hawk 610 Hardware Environment5-7VME Devices as Bus Masters 5When a VME device addresses memory (or other VME sources), the VME device is thebus

Device Driver Programming5-8• Invalid transfer• Nonexistent device addressed• Device correctly addressed but malfunctioningThe kernel tries to recogni

Power Hawk 610 Hardware Environment5-9Bus Arbitration 5Busses that support multiple bus masters must provide a means of resolving the contentionof con

Device Driver Programming5-10A system can use more than one of these options. By default, the system uses the straightslot priority scheme, wherein th

Power Hawk 610 Hardware Environment5-11If two interrupt requests with the same interrupt level occur simultaneously on the VMEI/O bus, the system reso

Device Driver Programming5-127. When the interrupt handler on the (H)VME bus forwards an interruptacknowledge to a processor, the low-level portion of

6PowerMAXION Hardware EnvironmentSystem Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Device Driver Programming

6-16Chapter 6PowerMAXION Hardware Environment666This chapter provides hardware-specific information useful in developing device driversfor PowerMAXION

Device Driver ProgrammingviiiConfiguration Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3Base Ad

Device Driver Programming6-2Figure 6-1. Elements of a PowerMAXION Processor BoardCaches 6There are separate 16-Kbyte, four-way set-associative instru

PowerMAXION Hardware Environment6-3tained in the hardware. Secondary data cache support is provided. Caches can be disabledin software. They can also

Device Driver Programming6-4Byte-Ordering and Alignment 6The byte-ordering convention used in the PowerMAXION platform is Big Endian. In thismodel, th

PowerMAXION Hardware Environment6-5Transfer Width Support 6For all non-block mode transfers, byte, word and long-word addresses are supported. Byteadd

Device Driver Programming6-6VME Devices as VME Bus Slaves 6When a processor acts as bus master on the VME bus and addresses VME devices on theVME I/O

PowerMAXION Hardware Environment6-7Bus Time-Out 6For each data transfer accessing a slave device, the VME bus provides a bus timer whichmeasures the d

Device Driver Programming6-8A data transfer malfunction occurs when using an invalid address, address modifier, ortransfer on the bus. Another possibi

PowerMAXION Hardware Environment6-9Bus Arbitration 6Because a bus provides the capability to support multiple bus masters, a means of resolv-ing the c

Device Driver Programming6-10powerfail, 60 Hz clock, timers, real-time clocks, the console processor, serial or parallelport controllers, and so on. S

PowerMAXION Hardware Environment6-11Interrupt Vector Generation and Configuration 6In hardware, the interrupt process functions as follows. On the VME

ContentsixBuses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3Timers. . . . .

Device Driver Programming6-12

7Power Hawk 620/640 Hardware EnvironmentSystem Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Device Driver Programming

7-17Chapter 7Power Hawk 620/640 Hardware Environment777The objective of this chapter is to give some background information to address hardwareissues

Device Driver Programming7-2Figure 7-1. Elements of an Power Hawk 620 Processor BoardDRAMFLASHPowerPC604L2 Cache33MHz 32/64-BIT PCI LOCAL BUSFalconIS

Power Hawk 620/640 Hardware Environment7-3Figure 7-2. Power Hawk 640 System Block DiagramBase BoardClockGeneratorDebug ConnectorMemory Expansion Conn

Device Driver Programming7-4Processor Board 7Figure 7-1 and Figure 7-2 give an overview of the main architectural features of the PowerHawk 620/640 pr

Power Hawk 620/640 Hardware Environment7-5Another bus on the Power Hawk systems is the local ISA bus, which is used tocommunicate with the serial and

Device Driver Programming7-6Byte-Ordering and Alignment 7The byte-ordering convention used in the Power Hawk 620/640 platform is Big Endian.Inthis mod

Power Hawk 620/640 Hardware Environment7-7VME Addressing 7The main objective of this section is to help comprehend the characteristics of datatransfer