This guide describes the ways in which hardware devices are integrated into and controlled from a SGI computer system running the IRIX operating system version 6.5. These systems include the SGI Origin 3000, SGI Origin 2000, Onyx2, SGI Origin 200, and Octane.
 | Note: This edition applies only to IRIX 6.5, and discusses only hardware supported by that version. 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.
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.
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:
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).
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).
If you are updating a device driver from IRIX 6.4:
Note that IRIX 6.5 covers all supported platforms. If you want your driver to support multiple platforms, refer to “Platform Support” in Chapter 9.
Note that the third-party SCSI drivers are supported as documented in Chapter 16, “SCSI Device Drivers”.
Note that PCI drivers for the O2 platform should be written as described in “PCI Drivers for the O2 (IP32) Platform” in Chapter 21, and user-level PCI drivers should be updated to support the pciba interface instead of usrpci (see “PCI Programmed I/O” in Chapter 4 of this guide.
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).
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.
VME drivers support either Origin and Onyx2 (refer to Chapter 12, “VME Device Attachment on Origin 2000/Onyx2” and Chapter 13, “Services for VME Drivers on Origin 2000/Onyx2”), or Challenge and Onyx (refer to Chapter 14, “VME Device Attachment on Challenge/Onyx” and Chapter 15, “Services for VME Drivers on Challenge/Onyx”).
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. |
|
| Kernel-level drivers for the VME bus. |
|
| Kernel-level drivers for the SCSI bus. |
|
| Kernel-level drivers for network interfaces. |
|
| Kernel-level drivers for the EISA bus. |
|
| Kernel-level drivers for the GIO bus. |
|
| Kernel-level drivers for the PCI bus. |
|
| 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 part-tabs printed in the margins. Using IRIS InSight, 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.
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.
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. | |
SGI patches, examples, and other material. | ftp://ftp.sgi.com |
Network of pages of information about Silicon Graphics and MIPS products | |
Text of all Internet RFC documents. | ftp://ds.internic.net/rfc/ |
Computer graphics pointers at the UCSC Perceptual Science Laboratory. | |
Pointers to binaries and sources at The National Research Council of Canada's Institute For Biodiagnostics. | |
An SGI “meta page” at the Georgia Institute of Technology College of Computing. | |
Complete SCSI-2 standard in HTML. | |
IEEE Catalog and worldwide ordering information. | |
MIPS processor manuals in HTML form. | |
Home page of the PCI bus standardization organization |
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”).
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 |
The following books, obtainable from SGI, can be helpful when designing or testing a device driver:
MIPSpro 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 User's Manual (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 Manual 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.
The following conventions are used throughout this document:
Data structures, variables, function arguments, and macros | The dsiovec structure has members iov_base and iov_len. Use the IOVLEN macro to access them. |
Kernel and library functions and functions in example | When successful, v_mapphys() returns 0. |
Driver entry point names that must be completed with a unique prefix string | The munmap() system function calls the pfxunmap() entry point. |
Files and directories | Device special files are in /dev, and are created using the /dev/MAKEDEV script. |
First use of terms defined in the glossary (see “Glossary”) | The inode of a device special file contains the major device number. |
Literal quotes of code example | The SCSI driver's prefix is scsi_. |
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://techpubs.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-1351Send a fax to the attention of “Technical Publications” at +1 650 932 0801.