NeXTSTEPDRIVERKIT:Chapter4 1

Driver Bundles

드라이버 번들(Driver Bundles)

To load your driver into the kernel--even if only for testing--you need to create a driver bundle for it with Project Builder. A driver bundle contains all the files needed to load and configure a driver: Its relocatable code and configuration information. A bundle may also contain help information and a configuration inspector for Configure to access configuration data. A driver bundle is also called a config bundle because it contains configuration information for the driver and typically has the name Driver.config, where Driver is the driver's name.

The driver name should be of the form

<vendor><model><type>Driver

The driver name Adaptec1542SCSIDriver follows this form.

Bundle Locations

Driver bundles for each system device--like the mouse, display, network card, SCSI devices, and so on--reside in a special directory called /NextLibrary/Devices. The bundles for each type of device are called Driver.config, where Driver is a type of device or a device name. In addition, every system has a bundle called System.config that configures the whole system.

An average system's directory /NextLibrary/Devices might contain the following directories, each of which is a bundle for a specific device:

ATI.config

Adaptec1542B.config

Beep.config

BusMouse.config

CirrusLogicGD542X.config

CompaqAudio.config

DPT2012.config

EtherExpress16.config

EtherLink3.config

Floppy.config

IDE.config

IntelGXProAudio.config

JAWS.config

MSWSoundSystem.config

PS2Keyboard.config

PS2Mouse.config

ParallelPort.config

ProAudioSpectrum.config

QVision.config

S3.config

SCSITape.config

SMC16.config

SerialMouse.config

SerialPorts.config

System.config

TokenExpress.config

TsengLabsET4000.config

VGA.config

Wingine.config

/NextLibrary/Devices is a link to the /private/Devices directory, which is a link to the driver directory for the current architecture (for example, /private/Drivers/i386). This link is always valid.

What's in a Bundle

Each driver bundle (including System.config) can contain the following files and directories:

Default.table

Instancen.table (created by Configure)

x.table

Display.modes

x.modes

CustomInspector (optional binary)

Language.lproj/

CustomInspector.nib (optional)

Localizable.strings

Help/ (replaces Info.rtf)

Driver_reloc (omitted for NeXT drivers that are compiled into the kernel)

Pre-Load

Post-Load

Default.table is a commented, read-only file that gives the default configuration settings for a generic device. Configure uses Default.table to build Instancen.table files, which contain specific configuration information for each device you have. There may be other x.table files, each expressing a different possible instance of the driver.

Each .table file is the ASCII representation of an NXStringTable object. Drivers and nondrivers can get access to these tables by using the IOConfigTable class. In addition, Driver Kit classes automatically interpret and use some of the standard keys in these tables.

Direct drivers have one Instancen.table for each device. For example, if you have two of the same card, Configure makes two files called Instance0.table and Instance1.table in the card's bundle. Indirect drivers and the system bundle have only one file, called Instance0.table.

Note: Because Configure's default device inspector has no way of knowing whether a device is direct or indirect, it can create more than one Instancen.table for an indirect driver. The consequence is that the driver's probe: method gets invoked more than once for each direct driver it might want to attach to. To get around this, you should either write your own device inspector or ensure that your driver's probe: method can handle more than one probe per direct driver.

The Display.mode and x.mode files hold display mode information. Default information is in Display.mode, and x.mode holds the information for other instances of the driver (just as x.table expresses configuration information for other driver instances).

For each language, Localizable.strings contains the text strings that applications display about the device. For example, it includes the name of the device as it appears in the list of devices in Configure. The Help/ directory contains files to inform the user about the driver and help them use it.

The Driver_reloc file is the relocatable object file of the device driver. The CustomInspector binary is the executable file for the Inspector panel; its name is the same as the bundle name (without the .config suffix). CustomInspector.nib is the nib file for the Inspector panel.

The bundle may contain Pre-Load and/or Post-Load programs that are run before and/or after the driver is loaded.

Configuration Tables

Files with a .table suffix contain strings of key/value pairs that describe a configuration. See "Configuration Keys" in the Appendix for information on what these tables should contain.

You can use the Default.table of an existing driver as a starting point for a configuration. Later, you should let the Configure application (with your custom inspector, if any) create the Instancen.table files.

Here's a sample Instancen.table for a parallel port driver:

"Driver Name"  = "IOParallelPort";
"Title"   = "System Parallel";
"Location"   = "System Baseboard";
"Family"   = "Parallel";
"Version"   = "1.0";
"Server Name"  = "ParallelPort";
"Path 0"   = "/dev/pp0";
"Post-Load"   = "InstallPPDev";
"Memory Maps"  = "";
"Pre-Load"   = "RemovePPDev";
"DMA Channels"  = "";
"Minor Device Number" = "0";
"Valid IRQ Levels"  = "7";
"I/O Ports"   = "0x378-0x37f";
"Instance"   = "0";
"Port Count"   = "1";
"IRQ Levels"   = "7";

Warning: C-style comment delimiters (that is, /* */) aren't recognized in configuration tables, such as Default.table or Instance0.table. Anything inside the delimiters will be parsed along with the rest of the file. This means that, for example, if you are testing a driver under development, you can't remove a key-value pair by simply commenting it out.

Other Configuration Tables

A bundle may also contain other configuration tables of the form x.table, where x is a prefix such as "PCI". Each of these is a table like default.table but expresses a possible instance of the driver with a slightly different "personality" than default.table. For example, PCI.table might be identical to Default.table except that it contains a line specifying a PCI-compliant driver:

"Bus Type" = "PCI";

By convention, Default.table specifies an ISA or VL-bus compliant driver--the simplest case. The prefix x in x.table usually designates the bus type.

These configuration table files should contain all information appropriate for the bus type. PCI-compliant drivers, for instance, contain a line specifying the auto detect IDs, such as this:

"Auto Detect IDs" = "0x71789004 0x0e111234";

Custom Device Inspector Files

For initial testing, you probably don't need a custom inspector. Instead, you can put the appropriate values directly into your test Default.table or Instancen.table files.

If you create a custom inspector, you should put the executable file and nib file in the places described in "What's in a Bundle," earlier in this chapter. Project Builder does this for you automatically. See "Writing a Custom Inspector" later in this chapter for information on creating custom inspectors.

Note: Project Builder creates an Inspector Panel executable file in the bundle and gives it the same name as the bundle (without the .config suffix). This executable loads the default inspector.

Localizable Strings File

This file should contain any strings you add to your Configure inspector's user interface, plus the following strings:

"Driver" = "UltimateTech XYZ-12";
    "Long Name" = "Ultimate Technologies XYZ-12 Transmogrifier";

where Driver is the name of the bundle (minus the .config suffix). Configure uses the string associated with the Driver key ("UltimateTech XYZ-12") whenever space is tight. When Configure has more space to display the driver's name, it uses the string associated with the "Long Name" key.

Display Mode Tables

If your driver is a display driver that supports multiple display modes, you need to specify which modes the user can choose. This information is supplied in the Display.modes file. Here's a sample file:

"Height: 600 Width: 800 Refresh: 60Hz ColorSpace: RGB:555/16";
"Height: 600 Width: 800 Refresh: 72Hz ColorSpace: RGB:555/16";
"Height: 768 Width:1024 Refresh: 60Hz ColorSpace: RGB:256/8";
"Height: 768 Width:1024 Refresh: 66Hz ColorSpace: RGB:256/8";
"Height: 768 Width:1024 Refresh: 72Hz ColorSpace: RGB:256/8";
"Height: 768 Width:1024 Refresh: 76Hz ColorSpace: RGB:256/8";
"Height: 768 Width:1024 Refresh: 60Hz ColorSpace: BW:8";
"Height: 768 Width:1024 Refresh: 66Hz ColorSpace: BW:8";
"Height: 768 Width:1024 Refresh: 72Hz ColorSpace: BW:8";
"Height: 768 Width:1024 Refresh: 76Hz ColorSpace: BW:8";
"Height: 768 Width:1024 Refresh: 60Hz ColorSpace: RGB:555/16";
"Height: 768 Width:1024 Refresh: 72Hz ColorSpace: RGB:555/16";
"Height:1024 Width:1280 Refresh: 68Hz ColorSpace: RGB:256/8";
"Height:1024 Width:1280 Refresh: 68Hz ColorSpace: BW:8";
"Height: 400 Width: 640 Refresh: 60Hz ColorSpace: RGB:888/32";
"Height: 400 Width: 640 Refresh: 70Hz ColorSpace: RGB:888/32";
"Height: 480 Width: 640 Refresh: 60Hz ColorSpace: RGB:888/32";

If your driver has more than one "personality," specify alternate display information in x.modes files where x is the appropriate prefix such as "PCI".

See the specification for the IODisplayInspector, IOFrameBufferDisplay, and IOSVGADisplay classes for more information on display modes.

Help Directory

This directory contains the help files supported by the NeXT help facility. You add this directory to your project with Project Builder's Add Help Directory command. For more information on adding help to your driver, see "Attaching Help to Objects" in Chapter 3, "The Interface Builder Application" of NEXTSTEP Development Tools and Techniques'.

The Help directory replaces the Info.rtf file, formerly used to provide information about the driver.

Driver Relocatable Code

This file contains the driver's relocatable code. An example of building a driver relocatable object file is located in /NextLibrary/Documentation/NextDev/Examples/DriverKit/TestDriver.

Pre-and Post-Load Programs

Your driver may require some action to be taken before and/or after it is loaded. For instance, you may want to run a program after the driver is loaded to look up its major device number and create a device node for the driver. Use the "Pre-Load" configuration key to specify a program that will run prior to your driver being loaded; use the "Post-Load" key to specify a program that runs after the driver is loaded.

The System Configuration Bundle

The System.config bundle is special in several ways. Its Instance0.table has default configuration information for the system as a whole. For example, it specifies which device drivers to load at boot time ("Boot Drivers") and which to load later ("Active Drivers"). Here's a sample Default.table from a System.config bundle:

"Version" = "2.0";
"Boot Drivers" = "PS2Keyboard PS2Mouse BusMouse Adaptec1542B DPT2012 IDE Floppy VGA";
"Active Drivers" = "SerialPorts SerialMouse ParallelPort";
"Kernel" = "mach_kernel";
"Kernel Flags" = "";
"Boot Graphics" = "No";

For writers of Driver Kit drivers, "Active Drivers" and "Boot Drivers" are the most important keywords. They specify which drivers are automatically loaded into the system the next time it's started. When someone uses Configure to add a device that has a loadable driver, the driver is added to one of these two lists. See the "Boot Drivers" and "Active Drivers" keys in the "Configuration Keys" section of the Appendix to see how to specify which list a driver should be in. This section also lists the other keywords for the system configuration table.

Note: Changes to system configuration information don't take effect until the system is restarted. However, you can load a driver without rebooting by using the d option of driverLoader (documented in "Loading a Driver with driverLoader" later in this chapter).

Creating a Driver Bundle

Create a project for your driver with Project Builder, and give the project the name you want your driver to have. Copy your driver files into the project by dragging them into the appropriate suitcase (header files to the Header suitcase and so on) or by using the Add command in the Files menu. Switch to the Builder view in the project window and select "bundle" as the Target. Click the Build button. Project Builder builds the driver and puts it in a driver bundle called Driver.config where Driver is the name you chose for the driver. Now you can configure and load the driver.

See NEXTSTEP Development Tools and Techniques for more information about using Project Builder. The example in /NextLibrary/Documentation/NextDev/Examples/DriverKit/TestDriver shows building a bundle with Project Builder.