Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

Configuration Keys

This section describes keys that can be used in .table files in driver and system configuration bundles (in /NextLibrary/Devices). The configuration system and Configure application are described in Chapter 4.

Some keys can have several values, expressed as a space-delimited list. Space-delimited lists have one space between elements, with nothing before the first or after the last element. 

Key values that specify addresses are expressed as ranges. Ranges include both the start and end address. If a range consists of a single byte, it's indicated by specifying the same start and end addressÐfor example, ª0x0-0x0º.

Driver Configuration Keys

The keys described in this section can be used in .table files in a driver's bundle. You can also specify your own keys. User and kernel modules alike can get the value of any key using the IOConfigTable class. Configure inspectors, which set some key values, use NXStringTable to do so; the NXStringTable corresponding to the instance configuration is available through the table instance variable of IODeviceInspector. 

Here's an example of a default configuration file:

"Class Names" = "myTestDriver";
"Family" = "Example";
"Instance" = "0";
"Version" = "1.1";
"Driver Version" = "myTestDriver, 3.2 version, built by kw 8/20/93";
"DMA Channels" = "1";
"I/O Ports" = "0x0-0x0";
"IRQ Levels" = "2";
"Valid IRQ Levels" = "1 2 3 4";
"Memory Maps" = "0x20000-0x200ff";
"Server Name" = "myTestDriver";

See the driver bundles under /NextLibrary/Devices for more examples. 

The following table shows the keys and explains when they must be used. Each key is explained in detail later in this section.

Key	Used For

ªAuto Detect IDsº	Drivers that support device auto detection
ªAuto Recoveryº	IOTokenRing drivers
ªBlock Majorº	Drivers with UNIX block entry points; optional
ªBoot Driverº	Drivers that must be loaded at boot time
ªBus Typeº	Drivers that aren't EISA- or ISA-based 
ªCharacter Majorº	Drivers with UNIX character entry points; optional
ªClass Namesº	All drivers that don't specify ªDriver Nameº
ªDefault Tableº	Instance tables only (inserted by Configure)
ªDisplay Modeº	Display drivers
ªDMA Channelsº	Drivers that support DMA
ªDriver Nameº	Alternative to the preferred ªClass Namesº
ªDriver Versionº	All drivers
ªFamilyº	All drivers
ªInstanceº	All drivers
ªI/O Portsº	Drivers that need access to I/O ports
ªIRQ Levelsº	Drivers that support interrupts
ªLocationº	All drivers; optional
ªMemory Mapsº	Drivers that need access to mapped device memory
ªPost-Loadº	Drivers that require user-level help after loading
ªPostScript Driverº	IOSVGADisplay drivers
ªPre-Loadº	Drivers that require user-level help before loading
ªRing Speedº	IOTokenRing drivers
ªServer Nameº	All drivers (inserted by Driver Kit makefiles)
ªShare IRQ Levelsº	Drivers that use shared interrupts
ªSVGA PostScript Driver Extensionº	
	Display drivers that require a special PostScript driver
ªValid DMA Channelsº	Drivers that support DMA; optional but recommended
ªValid IRQ Levelsº	Drivers that support interrupts; optional but recommended
ªVersionº	All drivers
ªVGA Memory Mapsº	Display drivers
ª16Mb Early Tokenº	IOTokenRing drivers

Keys

Auto Detect IDs

Example:	ªAuto Detect IDsº = ªCPQ1234º;
	or
	ªAuto Detect IDsº = ª0x71789004 0x0e111234º;

This is a string used by Configure and installation software to identify hardware that can be controlled by the device driver. The string is a space separated list of auto detect IDs, each of which is an identifier that can be used to match a device connected to an I/O bus. 

The auto detect ID contains both a vendor ID and a 16-bit device ID. An ANSI committee assigns vendor IDs; the vendor assigns device IDs. The auto detect ID takes the form of a 7 character string described in the EISA specification. It consists of two fields: VVVdddd, where V is an upper-case letter, and d is a hexadecimal digit. The three letters VVV represent the vender code; the four digit hexadecimal number dddd represents the device ID. The combination of these two fields is guaranteed to be unique. For example, ªCPQº is the vendor ID for Compaq, so an ID of ªCPQ1234º represents the Compaq device with device ID ª1234º.

The 7 character format is the preferred form of the auto detect ID. However, this ID can also be expressed as a 32-bit hexadecimal number. The vendor ID is translated into a 16-bit hexadecimal number; the device ID is the same as in the other format. The layout in this format differs for each bus type. For the EISA bus, the device ID is in the lower 16 bits, and the vendor ID is in the upper 16 bits. For the PCI bus, the vendor ID is in the lower 16 bits, and the device ID is in the upper 16 bits.

Auto Recovery

Example:	ªAuto Recoveryº = ªYESº;

Used in IOTokenRing drivers to specify whether the driver should support automatic recovery from errors. See the IOTokenRing class specification for more information.

Block Major

Example:	ªBlock Majorº = ª1º;

Used by some drivers with UNIX entry points to specify the device's block major number. See the IODevice class specification for more information.

Boot Driver

Example:	ªBoot Driverº;

Specifies that the driver must be loaded at boot time. For example, SCSI controller drivers must typically be loaded at boot time so that the system can use the disks attached to the controller.

Bus Type

Example:	ªBus Typeº = ªPCIº;

Indicates the type of bus the device uses. The current valid values are ªEISAº (which includes ISA), ªPCIº and ªPCMCIAº. If the key isn't present or valid, it defaults to ªEISAº.

Character Major

Example:	ªCharacter Majorº = ª15º;

Used by some drivers with UNIX entry points to specify the device's character major number. See the IODevice class specification for more information.

Class Names

Example:	ªClass Namesº = ªFloppyController FloppyDiskº;
	ªClass Namesº = ªAHAControllerº;

A space-delimited list of the classes in the relocatable object file that should receive probe: messages. This key is preferred to the ªDriver Nameº key, which may become obsolete. 

Default Table

Example:	ªDefault Tableº = ªATIUltraProº;

Automatically inserted into Instancen.table files by Configure when necessary. You should never have to specify this key.

Display Mode 	

Example:	ªDisplay Modeº = ªWidth: 1024 Height: 768 Refresh: 76Hz ColorSpace: RGB:555/16º;

Used by display drivers to specify the mode the display should be in. This key's value should be equivalent to one of the values assigned to the ªDisplay Modesº key in the bundle's Language.lproj/Localizable.strings file.

The key's value should be of the form:

ªWidth:width Height:height ColorSpace:(BW:bits | RGB:xyz/w) Refresh:rate Hzº

White space and ordering are ignored, but correct capitalization is required. The color space parameter should be either BW: followed by the bits per pixel, or RGB: followed by the bits per color component and then the bits per pixel.

For example, the string shown below describes a display mode that's 800 pixels wide and 600 high, supports color at 16 bits per pixel (5 bits each of red, green, and blue per pixel), and has a refresh rate of 60 Hz.

 Width: 800 Height: 600 ColorSpace: RGB:555/16 Refresh: 60 Hz

DMA Channels

Example:	ªDMA Channelsº = ª2º;
	ªDMA Channelsº = ª3 7º;

A space-delimited list of DMA channels that should be reserved for the device. You must specify default values with this key if your device performs DMA. The user can change the default values with the Configure application, subject to restrictions that you impose with the ªValid DMA Channelsº key.

Driver Name 	

Example:	ªDriver Nameº = ªAHAControllerº;

This is obsolete; use the ªClass Namesº key instead. The ªDriver Nameº key is identical to the ªClass Namesº key, except that it doesn't allow you to specify more than one class.

Driver Version 	

Example:	ªDriver Versionº = ªPROGRAM:Wingine PROJECT:displayDrivers-14 DEVELOPER:mflynn BUILT:NO DATE SET (-B used)º;
	ªDriver Versionº = ªmyTestDriver, 3.2 version, built by kw 8/18/93º;

A string uniquely identifying the driver version. In the future, the system may display this string when appropriate.

Family 	

Example:	ªFamilyº = ªDisplayº;

The family the device belongs to. Configure uses this key to group devices and to make sure that all essential device families are represented. Valid values are listed in the table below.

Value	Configure View

ªDisplayº	Display (at least one is required in the system configuration)	
ªPointing Deviceº	Mouse (at least one pointing device is required)
ªNetworkº	Network
ªSCSIº	SCSI
ªAudioº	Audio
ªKeyboardº	Other (at least one keyboard is required)
ªDiskº	Other

The ªSCSIº value should be used only for SCSI controllersÐnot for SCSI devices such as tape drives. The ªDiskº value should be used for both disks and disk controllers (except for SCSI controllers). For example, the IDE disk and IDE controller drivers (which are in the same relocatable object file) have the value ªDiskº in their default configuration file.

Values besides those listed in the table above are permitted, but aren't treated specially. They're included in the Configure view labeled Other. Examples of other values in use include ªParallelº and ªSerialº.

Instance 	

Example:	ªInstanceº = ª0º;

The instance number of this configuration file. Configure automatically specifies this key in Instancen.table files, but you should specify ªInstanceº = ª0º in default files.

I/O Ports 	

Example:	ªI/O Portsº = ª0x170-0x177º;
	ªI/O Portsº = ª0x3f8-0x3ff 0x2f8-0x2ffº;

A space-delimited list of I/O port ranges that should be reserved for the device. You must specify default values with this key if your driver uses I/O ports to get access to the device. If your driver uses Configure's default inspector, the user can change the starting address of the first range (but not the length of the range) using the inspector. 

IRQ Levels 	

Example:	ªIRQ Levelsº = ª1º;
	ªIRQ Levelsº = ª4 3º;

A space-delimited list of interrupts (IRQs) that should be reserved for the device. You must specify default values with this key if your device interrupts. The user can change the default values with the Configure application, subject to restrictions that you impose with the ªValid IRQ Levelsº key.

Location 	

Example:	ªLocationº = ªSlot 3º;

The location of the device. This string is set automatically by the device auto detection software and has a different format for each bus.

EISA
ªSlot nº	where n is replaced by a slot number, as in ªSlot 1º.

PCI
ªDev:d Func:f Bus:bº	where d is the device number,
	           f is the function number, and
	          b is the bus number; 
	ªDev:6 Func:0 Bus:0º, for example.

Memory Maps 	

Example:	ªMemory Mapsº = ª0x0D0000-0xD3FFFº;
	ªMemory Mapsº = ª0xa0000-0xbffff 0xc0000-0xcffffº;

A space-delimited list of memory ranges that should be reserved for the device. You must specify default values with this key if your driver needs access to mapped device memory. If your driver uses Configure's default inspector, the user can change the starting address of the first range (but not the length of the range) using the inspector. 

Post-Load 	

Example:	ªPost-Loadº = ªInstallPPDevº;

A user-level program to be run just after the driver is loaded. In the example above, the executable file InstallPPDev is a file in the driver's bundle that installs the driver's device files. 

PostScript Driver 	

Example:	ªPostScript Driverº = ª/usr/lib/NextStep/Displays/SVGA_psdrvrº;

Used by display drivers to specify the PostScript driver that matches them. IOFrameBufferDisplays don't specify this key, since they use the default PostScript driver. IOSVGADisplay drivers, however, must specify the SVGA PostScript driver, as shown above. See the IOSVGADisplay class description for more information. 

Pre-Load	

Example:	ªPre-Loadº = ªRemovePPDevº	;

A user-level program to be run just before the driver is loaded. In the example above, the executable file RemovePPDev is a file in the driver's bundle that removes the driver's old device files before the driver is loaded. 

Ring Speed	

Example:	ªRing Speedº = ª4º	;

Used by IOTokenRings to specify the speed of the Token Ring. This must be either 4 or 16. See the IOTokenRing class specification for more information. 

Server Name	

Example:	ªServer Nameº = ªATIº;

Indicates the name of this driver's bundle, minus the .config suffix. You shouldn't need to specify this key, since it's inserted automatically by the Driver Kit makefiles. For information on using the Driver Kit makefiles, refer to Chapter 4. 

Share IRQ Levels

Example:	ªShare IRQ Levelsº = ªYesº;

Indicates whether the device uses shared interrupts or not. On EISA and PCI systems, using shared interrupts implies using level-triggered interrupts. The value is either ªYesº or ªNoº with the default being ªNoº. Shared interrupts are not supported on ISA bus computers.

SVGA PostScript Driver 	Extension

Example:	ªSVGA PostScript Driver Extensionº = ªCirrusLogicGD542X_psdrvrº;

Used by IOSVGADisplay drivers to specify the driver-specific module to be loaded into the SVGA PostScript driver. See the IOSVGADisplay class description for more information. 

Valid DMA Channels

Example:	ªValid DMA Channelsº = ª0 1 3 5 6 7º;
	ªValid DMA Channelsº = ª2º	;

A space-delimited list of DMA channels that can be used by the device. When the user inspects the device, Configure automatically dims every DMA channel that isn't valid, so that the user can select only valid channels. See also the ªDMA Channelsº key.

Valid IRQ Levels	

Example:	ªValid IRQ Levelsº = ª1º;
	ªValid IRQ Levelsº = ª11 12 14 15º	;

A space-delimited list of interrupts (IRQs) that can be used by the device. When the user inspects the device, Configure automatically dims every IRQ that isn't valid, so that the user can select only valid IRQs. See also the ªIRQ Levelsº key.

Note:  IRQ 2 can't be used on ISA- and EISA-based machines, so it should never be in the ªValid IRQ Levelsº list.

Version 	

Example:	ªVersionº = ª1.0º;
	ªVersionº = ª2.1º;

A floating point number that describes the version of this driver. In the future, the system may warn the user whenever the user attempts to install a driver that has a lower version than the already installed version of the same driver. By convention, the number before ª.º should change only when the driver is incompatible (for user-level clients) from earlier versions. Configure display this version string.

VGA Memory Maps 	

Example:	ªVGA Memory Mapsº = ª0xa0000-0xbffff 0xc0000-0xcffffº;

A space-delimited list of memory ranges used for VGA access. Every display driver's default configuration table must include this key with the value ª0xa0000-0xbffff 0xc0000-0xcffffº. 

16Mb Early Token

Example:	ª16Mb Early Tokenº = ªYESº;

Used in IOTokenRing drivers to specify whether the driver should support early token release. See the IOTokenRing class specification for more information.

System Configuration Keys

The keys described in this section are used in .table files in the system bundle. You don't usually have to specify any of the keys except perhaps the ªKernel Flagsº key.

Active Drivers	

Example:	ªActive Driversº = ªEtherExpress16 ParallelPort ATI Beepº;

Drivers to be loaded automatically and probed after boot time. Configure automatically adds drivers to either this list or the ªBoot Driversº list whenever the user adds a driver to the system configuration. By default, drivers are added to this list; if the default table contains the ªBoot Driverº key, however, the driver is added to the ªBoot Driversº list.

Boot Drivers	

Example:	ªBoot Driversº = ªPS2Keyboard BusMouse DPT2012 IDE Floppyº;

Drivers to be loaded and probed at boot time. See also ªActive Driversº, above.

Boot Graphics	

Example:	ªBoot Graphicsº = ªYesº;

Specifies whether graphics (instead of system messages) should be displayed during boot time.

Bus Type	

Example:	ªBus Typeº = ªISAº;
	ªBus Typeº = ªEISAº;

The system bus architecture. This key isn't currently used for the System Configuration.

Kernel

Example:	ªKernelº = ªmach_kernelº;

The name of the kernel to use.

Kernel Flags	

Example:	ªKernel Flagsº = ªrootdev=sd1aº;

Options to pass to the kernel.

Machine Name	

Example:	ªMachine Nameº = ªDell 450DE/2 DGXº;

The system manufacturer name/model. This key isn't currently used.

Version 	

Example:	ªVersionº = ª1.0º;

Used by the Configure application.