SGI Techpubs Library

IRIX 6.5  »  Books  »  Developer  »  
IRIX Device Driver Programmer's Guide
(document number: 007-0911-210 / published: 2003-11-07)    table of contents  |  additional info  |  download
find in page

About This Guide

This guide describes the ways in which hardware devices are integrated into and controlled from an SGI computer system running the IRIX operating system version 6.5 and later.


Note: This edition applies only to IRIX versions 6.5 and later, and discusses only hardware supported by those versions. If your device driver will work with a different release or other hardware, you should use the version of this manual appropriate to that release (see “Internet Resources” for a way to read all versions online).

Three general classes of device-control software exist in an IRIX system: process-level drivers, kernel-level drivers, and STREAMS drivers.  

  • A process-level driver executes as part of a user-initiated process. An example is the use of the dslib library to control a SCSI device from a user program.  

  • A kernel-level driver is loaded as part of the IRIX kernel and executes in the kernel address space, controlling devices in response to calls to its read, write, and ioctl (control) entry points.

  • A STREAMS driver is dynamically loaded into the kernel address space to monitor or modify a stream of data passing between a device and a user process.

All three classes are discussed in this guide, although the greatest amount of attention is given to kernel-level drivers.

What You Need to Know to Write Device Drivers

In order to write a process-level driver, you must be an experienced C programmer with a thorough understanding of the use of UNIX system services and, of course, detailed knowledge of the device to be managed.

In order to write a kernel-level driver or a STREAMS driver, you must be an experienced C programmer who knows UNIX system administration, and especially IRIX system administration, and who understands the concepts of UNIX device management.

Updating Device Drivers from Previous Releases to IRIX 6.5

With the release of IRIX 6.5, the same operating system runs on all SGI supported platforms. The following sections summarize device driver differences between IRIX releases 6.2, 6.3, 6.4, and 6.5 to help you port existing drivers to IRIX 6.5:

Updating a Device Driver from IRIX 6.2

If you are updating a device driver from IRIX 6.2:

  • Familiarize yourself with the hardware graph—a new way to map devices that was introduced with IRIX 6.4. Refer to hwgraph.intro(4) and Chapter 2, “Device Configuration” of this guide.

  • Note that the SCSI host adapter interface has changed and SCSI drivers should now be written as described in Chapter 16, “SCSI Device Drivers” of this guide.

  • Note that the VME driver interface has changed with the SGI Origin and Onyx2 platforms. See “Porting From IRIX 6.2” in Chapter 13. VME drivers written for Challenge and Onyx platforms under IRIX 6.2 should work without modification under IRIX 6.5 on the same platforms.

  • Note that PCI bus support is now a part of IRIX (see Chapter 20, “PCI Device Attachment”, and Chapter 21, “Services for PCI Drivers”).

  • If you are using poll(), refer to “Entry Point poll()” in Chapter 7 and the poll(D2) man page for the discussion of the genp argument.

  • Beginning with IRIX 6.4, there is no restriction on which kernel services you can call from driver lower-half code. Refer to “Upper and Lower Halves” in Chapter 3.

  • Beginning with IRIX 6.4, there is no special provision for uniprocessor drivers in multiprocessor systems. You can write a uniprocessor-only driver and use it on a uniprocessor workstation, but not on a multiprocessor system.

  • Mapped driver routines (for example, v_mapphys) are now located in ksys/ddmap.h (not /sys/region.h), which also contains some new routines (see ksys/ddmap.h).

Updating a Device Driver from IRIX 6.3

If you are updating a device driver from IRIX 6.3:

  • Familiarize yourself with the hardware graph—a new way to map devices that was introduced with IRIX 6.4. Refer to hwgraph.intro(4) and Chapter 2, “Device Configuration” of this guide.

  • Note that the SCSI host adapter interface has changed and SCSI drivers should now be written as described in Chapter 16, “SCSI Device Drivers” of this guide.

  • Note that PCI drivers will have to be modified to work with the PCI interface as documented in Chapter 20, “PCI Device Attachment”, and Chapter 21, “Services for PCI Drivers” of this guide.

  • If you are using poll(), refer to “Entry Point poll()” in Chapter 7 and the poll(D2) man page for the discussion of the genp argument.

  • Beginning with IRIX 6.4, there is no restriction on which kernel services you can call from driver lower-half code. Refer to “Upper and Lower Halves” in Chapter 3.

  • Beginning with IRIX 6.4, there is no special provision for uniprocessor drivers in multiprocessor systems. You can write a uniprocessor-only driver and use it on a uniprocessor workstation, but not on a multiprocessor system.

  • Mapped driver routines (for example, v_mapphys) are now located in ksys/ddmap.h (not /sys/region.h) which also contains some new routines (see ksys/ddmap.h).

Updating a Device Driver from IRIX 6.4

If you are updating a device driver from IRIX 6.4:

What This Guide Contains

This guide is divided into the following major parts.

Part I, “IRIX Device Integration”

 

How devices are attached to SGI computers, configured to IRIX, and initialized at boot time.

Part II, “Device Control From Process Space”

 

Details of user-level handling of PCI devices and SCSI control using dslib.

Part III, “Kernel-Level Drivers”

 

How kernel-level drivers are designed, compiled, loaded, and tested. Survey of driver kernel services.

Part IV, “VME Device Drivers”

 

Kernel-level drivers for the VME bus.

Part V, “SCSI Device Drivers”

 

Kernel-level drivers for the SCSI bus.

Part VI, “Network Drivers”

 

Kernel-level drivers for network interfaces.

Part VII, “EISA Drivers”

 

Kernel-level drivers for the EISA bus.

Part VIII, “GIO Drivers”

 

Kernel-level drivers for the GIO bus.

Part IX, “PCI Drivers”

 

Kernel-level drivers for the PCI bus.

Part X, “STREAMS Drivers”

 

Design of STREAMS drivers.

Appendix A, “SGI Driver/Kernel API”

 

Summary of kernel functions with compatibility notes.

Appendix B, “Challenge DMA with Multiple IO4 Boards”

 

VME I/O considerations for Challenge and Onyx systems.

In the printed book, you can locate these parts using the table of contents. Using the online InfoSearch tool, each part is a top-level division in the clickable table of contents, or you can jump to any part by clicking the blue cross-references in the list above.

Other Sources of Information

Developer Program

Information and support are available through the SGI Developer Program. The Developer Toolbox CD contains numerous code examples. To join the program, contact the Developer Response Center at 800-770-3033 or e-mail devprogram@sgi.com.  

Internet Resources

A great deal of useful material can be found on the Internet. Some starting points are in the following list.

Earlier versions of this book as well as all other SGI technical manuals to read or download.

http://docs.sgi.com

SGI patches, examples, and other material.

http://www.sgi.com

Network of pages of information about SGI products

http://www.sgi.com

Computer graphics pointers at the UCSC Perceptual Science Laboratory.

http://mambo.ucsc.edu

Pointers to binaries and sources at The National Research Council of Canada's Institute For Biodiagnostics.

http://zeno.ibd.nrc.ca:80/~sgi/  

IEEE Catalog and worldwide ordering information.

http://standards.ieee.org

MIPS processor manuals in HTML form.

http://www.mips.com/  

Home page of the PCI bus standardization organization

http://www.pcisig.com


Standards Documents

The following documents are the official standard descriptions of buses:

  • PCI Local Bus Specification, Version 2.1, available from the PCI Special Interest Group, P.O. Box 14070, Portland, OR 97214 (fax: 503-234-6762).

  • ANSI/IEEE standard 1014-1987 (VME Bus), available from IEEE Customer Service, 445 Hoes Lane, PO Box 1331, Piscataway, NJ 08855-1331 (but see also “Internet Resources”).

Important man pages

The following man pages contain important details about software tools and practices that you need.

alenlist(d4x)

Overview of address/length list functions

getinvent(3)  

The interface to the inventory database

hinv(1)  

The use of the inventory display command

hwgraph.intro(d4x)

Overview of the hardware graph and kernel functions for it

intro(7)  

The conventions used for special device filenames

ioconfig(1M)  

The startup program that creates device special files

master(4)  

Syntax of files in /var/sysgen/master.d 

system(4)  

Syntax of files in /var/sysgen/system/*.sm

prom(1)  

Commands of the “miniroot” and other features of the boot PROM, which you use to bring up the system when testing a new device driver

udmalib(3)  

Functions for performing user-level DMA from VME

uli(3)  

Functions for registering and using a user-level interrupt handler (installs with the REACT/Pro product)

usrvme(7)  

Naming conventions for mappable VME device special files


Additional Reading

The following books, obtainable from SGI, can be helpful when designing or testing a device driver:

  • MIPSpro N32/64 Compiling and Performance Tuning Guide, document number 007-2360-nnn, tells how to use the C compiler and related tools.

  • MIPSpro Assembly Language Programmer's Guide, document number 007-2418-nnn, tells how to compile assembly-language modules.

  • MIPSpro 64-Bit Porting and Transition Guide, document number 007-2391-nnn, documents the implications of the 64-bit execution mode for user programs.

  • MIPSpro N32 ABI Handbook, document number 007-2816-nnn, gives details of the code generated when the -n32 compiler option is used.

  • MIPS R4000 Microprocessor User's Guide (2nd ed.) by Joe Heinrich, document 007-2489-001, gives detailed information on the MIPS instruction set and hardware registers for the processor used in many IRIX systems (also available on http://www.mips.com/).

  • MIPS R10000 User's Guide by Joe Heinrich gives detailed information on the MIPS instruction set and hardware registers for the processor used in certain high-end systems. Available only in HTML form from http://www.mips.com/.

The following books, obtainable from bookstores or libraries, can also be helpful.

  • Lenoski, Daniel E. and Wolf-Dietrich Weber. Scalable Shared-Memory Multiprocessing. Morgan Kaufmann Publishers, San Francisco, 1995. ISBN 1-55860-315-8.

  • Egan, Janet I., and Thomas J. Teixeira. Writing a UNIX Device Driver. John Wiley & Sons, 1992.

  • Leffler, Samuel J., et alia. The Design and Implementation of the 4.3BSD UNIX Operating System. Palo Alto, California: Addison-Wesley Publishing Company, 1989.

  • A. Silberschatz, J. Peterson, and P. Galvin. Operating System Concepts, Third Edition. Addison Wesley Publishing Company, 1991.

  • Heath, Steve. VMEbus User's Handbook. CRC Press, Inc, 1989. ISBN 0-8493-7130-9.

  • Device Driver Reference, UNIX SVR4.2, UNIX Press 1992.

  • UNIX System V Release 4 Programmer's Guide, UNIX SVR4.2. UNIX Press, 1992.

  • STREAMS Modules and Drivers, UNIX SVR4.2, UNIX Press 1992. ISBN 0-13-066879.

Reader Comments

If you have comments about the technical accuracy, content, or organization of this document, please tell us. Be sure to include the title and document number of the manual with your comments. (Online, the document number is located in the front matter of the manual. In printed manuals, the document number can be found on the back cover.)

You can contact us in the following ways:

  • Send e-mail to the following address:

    techpubs@sgi.com
    

  • Use the Feedback option on the Technical Publications Library World Wide Web page:

    http://docs.sgi.com

  • Contact your customer service representative and ask that an incident be filed in the SGI incident tracking system.

  • Send mail to the following address:

    Technical Publications
    SGI
    1600 Amphitheatre Pkwy., M/S 535
    Mountain View, California 94043-1351

  • Send a fax to the attention of “Technical Publications” at +1 650 932 0801.

We value your comments and will respond to them promptly.

IRIX Device Driver Programmer's Guide
(document number: 007-0911-210 / published: 2003-11-07)    table of contents  |  additional info  |  download

    Front Matter
    New Features in This Guide
    About This Guide
    Part I. IRIX Device Integration
    Part II. Device Control From Process Space
    Part III. Kernel-Level Drivers
    Part IV. VME Device Drivers
    Part V. SCSI Device Drivers
    Part VI. Network Drivers
    Part VII. EISA Drivers
    Part VIII. GIO Drivers
    Part IX. PCI Drivers
    Part X. STREAMS Drivers
    Appendix A. SGI Driver/Kernel API
    Appendix B. Challenge DMA with Multiple IO4 Boards
    Glossary
    Index


home/search | what's new | help