About This Guide
Prev |  | Next

## About This Guide

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.

## 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”

- “Updating a Device Driver from IRIX 6.3”

- “Updating a Device Driver from IRIX 6.4”

### 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:

- 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”).

## 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 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.

## 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://techpubs.sgi.com/library/
SGI patches, examples, and other material. | ftp://ftp.sgi.com
Network of pages of information about Silicon Graphics and MIPS products | http://www.sgi.com
Text of all Internet RFC documents. | ftp://ds.internic.net/rfc/
Computer graphics pointers at the UCSC Perceptual Science Laboratory. | http://mambo.ucsc.edu/psl/cg.html
Pointers to binaries and sources at The National Research Council of Canada's Institute For Biodiagnostics. | http://zeno.ibd.nrc.ca:80/~sgi/
An SGI “meta page” at the Georgia Institute of Technology College of Computing. | http://www.cc.gatech.edu/services/ sgimeta.html
Complete SCSI-2 standard in HTML. | http://scitexdv.com:8080/SCSI2/
IEEE Catalog and worldwide ordering information. | http://standards.ieee.org/index.html
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 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.

## Conventions

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 pfx```unmap`() 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_`.

## 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://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-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.

Prev | Table of Contents | Next
New Features in This Guide |  | Part I. IRIX Device Integration