HP OpenVMS Systems Documentation

On Alpha systems, commands for connecting devices and loading their drivers are in the System Management utility (SYSMAN). All SYSMAN commands that control and display the I/O configuration on an Alpha system contain the prefix IO.

Whenever possible, it is preferable to use the IO AUTOCONFIGURE command to connect standard devices and load device drivers.

IO AUTOCONFIGURE does not connect or load the device driver for the network communications logical device. In addition, other devices and drivers might exist that IO AUTOCONFIGURE does not connect and load.

You can connect unattached devices and devices that have nonstandard names, as well as load device drivers with the SYSMAN commands IO CONNECT and IO LOAD.

For more information, refer to the SYSMAN section of the OpenVMS System Management Utilities Reference Manual and Writing OpenVMS Alpha Device Drivers in C.

Network Communication Device

To connect the network communications logical device on Alpha, run the appropriate startup files for the particular network protocol. For example, three common net stack startups are:

Example

The commands in the following example autoconfigure the devices physically attached to the Alpha system, load their drivers, and connect the network software device:

SYSMAN> IO AUTOCONFIGURE ALL
SYSMAN> EXIT
$ @SYS$MANAGER:STARTNET

Virtual Terminals

For information about connecting virtual terminals and loading their driver, see Section 8.6.2.

For information about configuring virtual terminals in conjunction with TCP/IP Services Telnet, see Compaq TCP/IP Services for OpenVMS Management.

8.4.3 Suppressing the Autoconfiguration of Devices

Autoconfiguration of devices saves effort and reduces the possibility of error. However, you might want to suppress autoconfiguration for the following reasons:

• To customize the order in which you configure devices
• To troubleshoot booting problems
• To allow Small Computer System Interface (SCSI) based workstations to use devices on another workstation's SCSI bus without causing conflicts during boot time

To suppress autoconfiguration, add the following command as the last line of SYS$MANAGER:SYCONFIG.COM:

$ STARTUP$AUTOCONFIGURE_ALL == 0

$ STARTUP$AUTOCONFIGURE_ALL == 0
$ @SYS$SYSTEM:STARTUP CONFIGURE
$ EXIT

%RUN-F-CREPRC, process creation failed
-SYSTEM-F-DUPLNAM, duplicate name

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 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 operating system disk. By adding simple descriptions of their devices in the appropriate ASCII text file, third parties and end users can configure non-Compaq 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-Compaq supported devices.

8.5.1 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, 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.

Section 8.5.2 describes how to use the SYS$SYSTEM:SYS$USER_CONFIG.DAT file to autoconfigure devices.

8.5.2 Using File-Based Autoconfiguration

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

SYS$SYSTEM:SYS$USER_CONFIG.DAT
SYS$SYSTEM:SYS$CONFIG.DAT

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

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.

8.5.2.2 Configuration File Syntax

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

• All white space is equivalent to a single space. Blank lines, multiple spaces, and tabs may be used for clarity, but they are treated by the parser as a single space.
• All strings are converted to uppercase unless within quotes.
• A quotation mark cannot be passed within a string (it will be deleted).
• All numbers are in the C language format: the default is decimal, octal may be specified by providing a leading "0", hex by providing a leading "0x".
• Comments can occur anywhere in the file and can begin with an exclamation point (!). All text on the line from the exclamation point to the end of the line is ignored.

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:

• DEVICE = string
  The DEVICE keyword starts a device description. The DEVICE keyword takes a string argument, which is an arbitrary description of the device being defined.
  Example: DEVICE = "NI (Tulip)"
  The string argument is used by utilities such as the CLUE CONFIG command in $ANALYZE/SYSTEM. It should be kept short enough to look correct.

  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)

• END_DEVICE
  The END_DEVICE terminates the current device description, and causes the parser to create a new table entry if all required keywords have been supplied. No parameters are required.
• ID = {number {, number} | string}
  The ID keyword specifies the hardware ID of the device. The hardware ID is a 64-bit quantity and can be specified by a pair of 32-bit values (low-order, high-order), or can be specified as an ASCII string of up to 8 characters. If only one numeric value is provided, the high-order 32 bits are set to zero.
  Example: ID = 0x00051000 ! HW ID of NCR810 in hex
  Example: ID = FLOPPY ! HW ID of Floppy in ASCII
  Example: ID = 0x906010B5, 0x113310DF ! 64-bit ID => low-32, high-32
  The number of bits used by the system depends on the adapter type. EISA and PCI use 32 bits. ISA uses 64 bits. PCI can be extended to 64 bits by using the FLAGS=EXTENDED_ID keyword.
• NAME = string
  The NAME keyword specifies the mnemonic for the device. This is usually a two-character name, but it can be more.
  Example: NAME = PK
• DRIVER = string
  The DRIVER keyword specifies the file name of the device driver for the device.
  Example: DRIVER = SYS$PKEDRIVER
• ADAPTER = string
  The ADAPTER keyword indicates the bus type of the device. The current adapters are: PCI, EISA, ISA, TC (TURBOchannel).
  Example: ADAPTER = PCI
• UNITS = number
  The UNITS keyword indicates the number of units (UCBs) that are created for the controller. If not specified, the default is 1.
  Example: UNITS = 1
• FLAGS = string
  The FLAGS keyword shows optional information about how to load the driver. More than one flag may be specified, separated by a comma (,).
  Example: FLAGS = NOVECTOR, CASE_BLIND, EXTENDED_ID, ISA_ON_EISA

  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.

• PRIVATE_DATA = string
  This keyword is supported only when the value ISA is given to the ADAPTER keyword. The statement may not span lines. If the string contains more than one word, the string should be in quotes. The quotes are not passed as part of the string. An ISA driver can retrieve this string by calling IOC$NODE_DATA and passing the function code IOC$K_ISA_USER_PARAM.
• BEGIN_PRIVATE
  This keyword is supported only when the value ISA is given to the ADAPTER keyword. The BEGIN_PRIVATE and END_PRIVATE keywords can be used instead of PRIVATE_DATA. They are not used as part of a PRIVATE_DATA statement. When using BEGIN_PRIVATE and END_PRIVATE, all data contained between the keywords is passed to the driver. The data may contain special characters like quotation marks. The data may span multiple lines. When multiple lines are used, the driver will find a line-feed character to indicate a new line.
  BEGIN_PRIVATE and END_PRIVATE must be used when trying to convert some entries in ISA_CONFIG.DAT to file; for example, the statement in ISA_CONFIG.DAT:

  USER_PARAM = "some data"

  
  must be converted to

  BEGIN_PRIVATE "some data" END_PRIVATE

  
  The USER_PARAM keyword in ISA_CONFIG.DAT passes the quotation marks, so PRIVATE_DATA cannot be used to do the conversion.
  An ISA driver can retrieve the data between BEGIN_PRIVATE and END_PRIVATE by calling IOC$NODE_DATA with the function code IOC$K_ISA_USER_PARAM.
• END_PRIVATE
  The END_PRIVATE keyword can only be used to terminate data that is added after a BEGIN_PRIVATE statement.
• NUM_VECTORS = number
  The NUM_VECTORS keyword specifies the number of vectors that the device uses. The default if not specified is 1.
  Example: NUM_VECTORS = 4

Table 8-1 indicates keywords that can be included in the configuration 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.

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

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