HP OpenVMS System Manager's Manual, Volume 1:... |
Managing Peripheral Devices |
|
|
| |
Automatically Configuring Devices for OpenVMS Alpha and I64 Systems
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).
| The 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 = valuewhere 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_DEVICEIn 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 = 1These 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:
SDA> CLUE CONFIG
. . .
Adapter Configuration:
----------------------
TR Adapter ADP Hose Bus BusArrayEntry Node Device Name/HW-Id
-- ----------- -------- ---- -------------------- ---- -----------------
. . .
4 PCI 80949900 60 PCI
80949B50 1 MERCURY
80949BC0 GQA: 3 S3 Trio32/64
80949C30 EWA: 5 NI (Tulip)
| Flag | Description |
|---|---|
|
NOVECTOR
|
Device has no interrupt
vector.
|
|
CASE_BLIND
|
Causes the ID to be treated
as an ASCII string and converted to uppercase. In addition, the
ID from the hardware will also be converted to uppercase before comparing.
This flag is useful for ISA device strings because the console ISACFG command
will not convert the HANDLE to uppercase. If this flag is specified,
the ID must be entered in the description as a string, and not as
a number, or an error will be displayed and the description ignored.
|
|
EXTENDED_ID
|
The flag is valid only for
devices on the PCI bus. Normally, only 32-bit hardware IDs are used
for PCI. If you have a PCI board that supports the V2.1 PCI bus specification,
set this flag. The upper 32 bits of the hardware ID should contain the
subsystem ID and the subsystem vendor ID. For example, in the following example,
1133 is the subsystem ID, and 10DF is the subsystem vendor ID. FLAGS = EXTENDED_ID
ID = 0x906D1OB5, 0 x 113310DF If the EXTENDED_ID flag will be used to load a
special driver, but the same ID without the EXTENDED_ID bit will
be defined to load a generic driver, the description with the EXTENDED_ID
should be located before the generic description.
|
|
ISA_ON_EISA
|
This flag is valid only when the value
EISA is given to the ADAPTER keyword, and the device is an ISA device.
ISA devices should set this flag to ensure that the value given
to the ID keyword is interpreted correctly. For ISA devices, the
system keeps the ID value as an ASCII string. When the system believes
that this is an EISA device, the ID value is compressed into binary
format.
|
USER_PARAM = "some data"must be converted to
BEGIN_PRIVATE "some data" END_PRIVATEThe USER_PARAM keyword in ISA_CONFIG.DAT passes the quotation marks, so PRIVATE_DATA cannot be used to do the conversion.
Keyword Summary indicates keywords that can be included in the configuration file.
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 AUTOCONFIGURENote 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.
| Beginning 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.
| ISA 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.
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 MyDeviceyou can match that to the following entry in SYS$USER_CONFIG.DAT:
DEVICE = "My Device"
ID = MYDEVICE
FLAGS = CASE_BLIND
.
.
.
END_DEVICEDescriptions 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 10This 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 3This 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 2F8This 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 -initTo save your changes: >>>initTo delete an entry: >>>isacfg -slot 1 -dev 0 -rmTo see all the devices currently configured: >>>isacfg -allTo modify a device, use -mod: >>>isacfg -slot 2 -dev 0 -mod (etc.)The following keywords do not have equivalents in ISA_CONFIG.DAT:
| ||||||
|
|