skip book previous and next navigation links
go up to top of book: HP OpenVMS System Manager's Manual, Volume 1:... HP OpenVMS System Manager's Manual, Volume 1:...
go to beginning of chapter: Managing Peripheral Devices Managing Peripheral Devices
go to previous page: Connecting Devices and Loading Device Drivers Connecting Devices and Loading Device Drivers
go to next page: Managing TerminalsManaging Terminals
end of book navigation links

Automatically Configuring Devices for OpenVMS Alpha and I64 Systems  



Autoconfiguration is the process of discovering the hardware devices on a system and loading the appropriate device drivers. File-based autoconfiguration is a feature that enables OpenVMS Alpha or I64 to automatically configure third-party hardware devices.

Beginning with OpenVMS Alpha Version 7.1, device configuration tables are constructed from ASCII text files on the OpenVMS Alpha (and I64) operating system disk. By adding simple descriptions of their devices in the appropriate ASCII text file, third parties and end users can configure non-HP supported devices and load user-written device drivers.

The following sections briefly explain device configuration and describe how to use the new file-based autoconfiguration method to configure non-HP supported devices.

Understanding Device Configuration  

A device is configured on OpenVMS when system code is able to locate it on a bus, give it a name, and load a device driver for it. When a device is autoconfigured, all these steps happen without any user intervention.

OpenVMS discovers devices during the boot process in a bus-specific manner. The discovery process includes storing data about detected devices in bus-specific data structures. These data structures are later used to search configuration tables of known devices. The configuration table provides the information necessary to determine the driver name, the device name, and other parameters for loading and connecting the appropriate driver.

Prior to OpenVMS Alpha Version 7.1, configuration tables were built into the OpenVMS kernel and could not be modified without replacing a system image. As of OpenVMS Alpha Version 7.1 and on I64, the configuration tables are constructed from ASCII text files on the system disk. A system file (SYS$SYSTEM:SYS$CONFIG.DAT) is provided for all OpenVMS supported devices, and a user file (SYS$SYSTEM:SYS$USER_CONFIG.DAT) is provided for all third-party, layered-product, and user-written device drivers. The system reads these files during the boot process and uses the files to create a set of configuration tables. These tables are used for subsequent autoconfiguration of hardware devices. Although the tables are built from two files and collected by bus type, they can be considered one logical configuration table of known devices.

Using File-Based Autoconfiguration describes how to use the SYS$SYSTEM:SYS$USER_CONFIG.DAT file to autoconfigure devices.

Using File-Based Autoconfiguration  

File-based autoconfiguration reads two files during system boot to build the configuration tables of known devices:

Both files use the same format, and the data from both files are combined to create the configuration tables for each bus on the system. The SYS$USER_CONFIG.DAT file is read first, and takes precedence over any duplicate device descriptions contained in both files. If multiple device descriptions exist in a single file, the first occurrence of the description is used.

The configuration files consist of device description blocks, each of which provides the information needed to configure the correct device driver for a device.

Each device description block consists of a series of statements starting with a DEVICE keyword and ending with the END_DEVICE keyword. Between these two keywords, additional keywords define the hardware ID, the device name, the driver name, the bus type, and any other required or optional information.

The SYS$USER_CONFIG.DAT file is an ASCII text file, which can be processed with any utility that handles variable-length record files (for example, a text editor or DCL commands).


NoteThe SYS$CONFIG.DAT file is read-only and should not be modified by users or by third parties. It should only be modified by HP, and it might be replaced by OpenVMS upgrades. Inappropriate edits to this file could result in the inability to boot the system.

Adding Descriptions to SYS$USER_CONFIG.DAT  

Statements in the SYS$SYSTEM:SYS$USER_CONFIG.DAT take the general form:

KEYWORD = value
where the value is a string, a quoted string, or a numeric value. The END_DEVICE keyword has no associated value. For example, a minimal description of a non-disk device might look like the following:
DEVICE          = "My device"
 NAME           = UU
 DRIVER         = USER$UUDRIVER
 ID             = 0x0005111
 ADAPTER        = PCI
 FLAGS          = NOVECTOR
END_DEVICE
In this example, the description indicates that when a device with the hardware ID of 5111 (hex) is found on a PCI bus, the device named UU should be configured, and the USER$UUDRIVER device driver should be loaded. This example also specifies that the driver does not want to be connected to an interrupt vector. (If the bus information had a vector, it would be ignored.)

In addition to the values shown in the previous example, the following implied values can also be specified:

UNITS           = 1
NUM_VECTORS     = 1
These values usually default to the correct values for a single unit controller.

Configuration File Syntax  

The following syntax rules apply to the SYS$USER_CONFIG.DAT file.

Device Descriptions  

A minimal device description consists of DEVICE, NAME, DRIVER, ADAPTER, and END_DEVICE statements. The following keywords are defined for file-based autoconfiguration device descriptions:

Keyword Summary indicates keywords that can be included in the configuration file.

Table 1   Keyword Summary
Keyword Required Description
DEVICE
Yes
Begins a device description
END_DEVICE
Yes
Ends a device description
ID
Yes
Specifies the hardware ID
NAME
Yes
Device name
DRIVER
Yes
Driver name
ADAPTER
Yes
Adapter type
UNITS
No
Units Default: 1
FLAGS
No
Device flags: Default: No flags
PRIVATE_DATA
No
Specifies private data
BEGIN_PRIVATE
No
Specifies start of private data
END_PRIVATE
No
Specifies end of private data
NUM_VECTORS
No
Number of vectors Default: 1

Rebuilding the SYS$USER_CONFIG.DAT File  

The REBUILD keyword requests SYSMAN to rebuild the configuration tables attached to each of the adapter blocks by re-reading and parsing SYS$SYSTEM:SYS$USER_CONFIG.DAT and SYS$SYSTEM:SYS$CONFIG.DAT. The REBUILD command will always rebuild all of the configuration tables, regardless of the type of bus. It is then necessary to reexecute the AUTOCONFIGURE command to load the device drivers for any newly defined devices:

$ MC SYSMAN IO REBUILD
$ MC SYSMAN IO AUTOCONFIGURE
Note that once a driver has been loaded for a device, it cannot be reloaded.

The MC SYSMAN IO REBUILD/VERIFY command causes SYSMAN to read and process the SYS$SYSTEM:SYS$USER_CONFIG.DAT and SYS$SYSTEM:CONFIG.DAT files, but not to rebuild the configuration files for OpenVMS. Messages will be displayed for any errors that are encountered. This command can be used by developers to test new changes to SYS$SYSTEM:SYS$USER_CONFIG.DAT without modifying the current system.

Supported Buses for User Devices  

File-based autoconfiguration is supported for user-written device drivers on PCI, ISA, EISA, and TURBOchannel buses. This section includes additional information specific to configurations.

ISA Device Configuration  

ISA devices do not provide a readable device ID that can be discovered during bus probing. A user must explicitly indicate the presence of the device at the console and must also reserve resources for the device at the console (IRQs, I/O ports, etc.). Once the device is known to the console, OpenVMS can then autoconfigure it using file-based autoconfiguration.

ISA devices may be used on either an ISA bus or an EISA bus. If the system has an ISA bus, the device is configured at the console using ISACFG. If the system has an EISA bus, the ISA device is configured using ECU. Both console utilities allow the users to reserve device resources.

Configuring ISA Devices on the ISA Bus    In previous versions of OpenVMS Alpha, ISA devices on an ISA bus required an entry in the SYS$MANAGER:ISA_CONFIG.DAT file that defined the hardware and the use of the console command ISACFG to reserve system resources like IRQs.


CautionBeginning with OpenVMS Alpha Version 7.2, the ISA_CONFIG.DAT file is no longer supported. Refer to SYS$MANAGER:ISA_CONFIG.DAT Unsupported for more information.

Configuring ISA Devices on the EISA Bus    ISA devices must be manually configured using the EISA Configuration Utility (ECU) which is run from the console. Devices must have a CFG file provided on a DOS floppy. The CFG file provides a string (up to 7 characters) as the device ID.

See your card manufacturer, or the EISA Bus Specification for details on CFG file format.

The ECU floppy (DOS format) contains an example ISA CFG file (ISA000.CFG) that may be used as a model for new configuration files. For more information, refer to the EISA Bus Support chapter in Writing OpenVMS Alpha Device Drivers in C .

Once the ECU has been run, the device can be configured using file-based autoconfiguration.


NoteISA devices cannot be easily autoconfigured on EISA bus systems on versions prior to OpenVMS Alpha Version 7.1 because the ID is not copied from the ECU data into the OpenVMS bus structures.

SYS$MANAGER:ISA_CONFIG.DAT Unsupported  

Support for using the SYS$MANAGER:ISA_CONFIG.DAT file to configure ISA devices was discontinued in OpenVMS Alpha Version 7.2. If you use this file, you should convert to using the ISACFG utility from the console and the file-based autoconfiguration method described in the following sections.

ISA_CONFIG.DAT Keywords and Equivalents contains a list of keywords from ISA_CONFIG.DAT and their equivalents in either file-based autoconfiguration or the ISACFG utility.

Table 2   ISA_CONFIG.DAT Keywords and Equivalents
ISA_CONFIG.DAT File-based Autoconfigure ISACFG
Not used
ID
-handle
NAME
NAME

DRIVER
DRIVER

IRQ

irqx
NODE

slot
DMA

dmachanx
PORT

iobasex
MEM

membasex
FLAGS
Bit 1 (unsupported)


Bit 2 (FLAG=NOVECTOR)

USER_PARAM
PRIVATE_DATA


An entry in ISA_CONFIG.DAT is matched to internal data kept for an ISA device using the number specified with the NODE keyword. When you use the SYS$USER_CONFIG.DAT file to configure an ISA device, however, the ID keyword is used to match the block, which defines the device, to data entered from the console with the ISACFG command. The value given to the ID keyword must be the same as the value specified with the ISACFG-handle keyword.

Any identification string can be used for an ISA device. It should be eight characters or less. The ISACFG command does not set the -handle value to upper case, so two methods can be used to force the value to match one specified using the configuration keyword ID. You can specify the ID value in the correct case inside of quotation marks (matching the case you used for the -handle value). Or you can use the configuration keyword FLAGS=CASE_BLIND, which will cause a blind comparison to be done.

For example, if you use the following in ISACFG:

>>>isacfg -slot 3 -dev 0 -mk -enadev 1 -type 1 -handle MyDevice
you can match that to the following entry in SYS$USER_CONFIG.DAT:
DEVICE   = "My Device"
ID = MYDEVICE
FLAGS = CASE_BLIND
            .
            .
            .
END_DEVICE
Descriptions of the conversion for each parameter in ISA_CONFIG.DAT are as follows:
NAME = xx Use the NAME keyword in SYS$USER_CONFIG.DAT. Use the same value, where xx is the device code. (The device code is usually 2 letters.)

Example: NAME = ER
DRIVER = driver_name
 Use the DRIVER keyword in SYS$USER_CONFIG.DAT. Use the same value for file-based autoconfiguration. driver_name is the name of the driver in SYS$LOADABLE_IMAGES.

Example: DRIVER = SYS$ERDRIVER
IRQ = i Use IRQx in the ISACFG utility. You can express four IRQs: -IRQ0 through -IRQ3. Use the same value used for ISA_CONFIG.DAT. The IRQ is a value from 0 to 15, which specifies which ISA IRQ the device uses to report interrupts.

Example:

This example assigns IRQs 10 and 5 to the device.
>>>isacfg -slot 3 -dev 0 -mk -handle MYDEV -enadev 1 -etyp 1  -irq0 10 -irq1 5
NODE = n Use -slot in the ISACFG utility. The slot number (n) does not represent the slot in which the device resides. It is a logical, not a physical number. However, the number must be between 1 and the maximum number of slots on the machine. Slot number 0 is not available to users.

Example:
>>>isacfg -slot 3 -dev 0 -mk -enadev 1 -etyp 1 -handle MYDEV -dmachan0 1 -irq0 10
This example assigned values to a device represented by slot 3. There must be at least 3 slots on the machine on which this command is executed. To see which logical slots are being used, enter the following command:
>>>isacfg -all
DMA = (j,k, ...)
 Use -dmachanx in the ISACFG utility. Values j,k, and so on are values 0 through 7, which specify the channels of the DMA controller that the device is using to relay information. Use the same values for j, k, and so on with ISACFG, but assign each one to a different DMA channel. You can specify four DMA channels, using the keywords -dmachan0 through -dmachan3.

Example:
            >>>isacfg -slot 3 -dev 0 -mk -enadev 1 -etyp 1 -handle MYDEV -irq0 10 -dmachan0 1 -dmachan1 3
This example assigned two dma channels, 1 and 3, to the device.
PORT = (aa:b, cc:d, ... )
 Use -iobasex in the ISACFG utility. You can specify six ports using the keywords -iobase0 through -iobase5. There is no equivalent for the length fields b, d etc. The ISACFG utility assumes that the driver knows the length of the port. Drivers that called the IOC$NODE_DATA routine with the keyword IOC$K_EISA_IO_PORT to obtain the length in the upper word of the returned longword should stop examining the upper word. With ISA_CONFIG.DAT, the length was returned; but with ISACFG, the length is always 8.

Example:
>>>isacfg -slot 3 -dev 0 -mk -enadev 1 -etyp 1 -handle AAA321 -irq0 10 -iobase0 2F8
This example assigned port 2F8 to the device.
MEM = (ee:f, gg:h, ...)
 Use the ISACFG keywords -membasex to specify the memory base, and -memlenx to specify the memory length. Use the same values for ee, gg etc. and f, h etc. as you used for ISA_CONFIG.DAT. You can specify three memory regions using the keywords membase0 through membase2 and memlen0 through memlen2.

Example:
        >>>isacfg -slot 3 -dev 0 -mk -enadev 1 -etyp 1 -handle MYDEV -irq0 10 -membase0 80000 -memlen0 20
FLAGS = n The FLAGS field in ISA_CONFIG.DAT had 2 meaningful bits:

Bit 0 indicates the device being configured is a SCSI adapter.

Bit 1 indicates that no interrupt is required for the device.

Because it was never possible to use bit 0, it is not currently supported in file-based autoconfiguration. Bit 1 can be expressed with the file-based autoconfiguration FLAGS=NOVECTOR statement.
USER_PARAM = text
 Use the PRIVATE_DATA keyword in file-based autoconfiguration to represent this value. If you used quotation marks with the USER_PARAM value, you must use BEGIN_PRIVATE and END_PRIVATE to continue to pass the quotation marks to the driver. For ISA devices, the PRIVATE_DATA values can be obtained the same way as USER_PARAM (that is, by using the IOC$NODE_DATA routine with the IOC$K_ISA_USER_PARAM keyword).

While using ISACFG, you must also be familiar with the following commands:

To return the configuration to its initial state:
>>>isacfg -init
To save your changes:
>>>init
To delete an entry:
>>>isacfg -slot 1 -dev 0 -rm
To see all the devices currently configured:
>>>isacfg -all
To modify a device, use -mod:
>>>isacfg -slot 2 -dev 0 -mod  (etc.)
The following keywords do not have equivalents in ISA_CONFIG.DAT:

-enadev a_number
Takes the numbers 0 (disabled) and 1 (enabled). It allows you to disable a device so that it will not be used in resource allocation calculations.
-etyp a_number
Defines an entry type for this entry. OpenVMS supports only the values 0 and 1. It should always be specified as a 1. It takes the following values:
  • 0 Causes the entry to be deleted


  • 1 Single option


  • 2 Embedded multiport device


  • 3 Multiport option device



go to previous page: Connecting Devices and Loading Device Drivers Connecting Devices and Loading Device Drivers
go to next page: Managing TerminalsManaging Terminals