6 Producing Hardware Product Kits

This chapter describes how to produce a hardware product kit, what additional files are required, and how to test the kit installation.

Note

The information in this chapter describes how to produce hardware product kits.

If you want to create a user product kit, go to Chapter 4.

If you want to create a kernel product kit, go to Chapter 5.

Files for hardware product kits are release-specific. If you want to create a hardware product for a previous release of the operating system, use the instructions in that release's Guide to Preparing Product Kits.

Follow these steps to create and test a hardware product kit:

Read Chapter 1 for an overview of product kits.

Design the kit directory structure as described in Chapter 2.

Create subsets as described in Chapter 3. Hardware product kits require a subset control program (Section 3.4).

Create additional installation files as described in Section 6.2.

Rerun the newinv utility as described in Section 3.7 to update the master inventory file with the additional installation files.

Rerun the kits utility as described in Section 3.5 to produce updated subsets and control files.

Create the kit distribution media as described in Section 6.3.

Test the distribution media as described in Section 6.4.

6.1 Overview

A hardware product includes the kernel modules that let your operating system support new or upgraded hardware, letting you install hardware support without reinstalling or updating your base operating system. However, you must reboot your system to rebuild the kernel so that it includes the modules that support your new hardware. To support the new hardware and the hardware product kit software, the customer may need to install or update to a version of the operating system that supports hardware product kits before installing the hardware product kit software.

The kernel modules and the kit support files are distributed on CD-ROM as part of the hardware product kit, and can be installed either directly from the distribution media or loaded onto a Remote Installation Services (RIS) area for installation by RIS clients over a local area network (LAN).

Hardware product kits can be delivered by a process called new hardware distribution (NHD). The kit usually is provided on CD-ROM, and includes installation and testing instructions.

6.2 Creating Additional Installation Files

Figure 6-1 shows the files that make up the ODB product kit source directory. Additional hardware product files are highlighted.

Figure 6-1: Hardware Product Source Directory

/README.odb -- a text file containing general product information
This file is installed in the root ( / ) file system and is placed in the opt/OAT100 source directory.

/sbin/odb_recover -- a utility to recover corrupt ODB documents when the system boots. The odb_recover script executes when the system boots and the /usr file system may not be mounted.
This file is installed in the root ( / ) file system and is placed in the opt/OAT100/sbin source directory.

/usr/bin/odb_start -- the ODB tool startup script. The odb_start script is a user command.
This file is installed in the /usr file system and is placed in the usr/opt/OAT100/bin source directory.

/usr/var/templates/odb_template -- a document template that can be modified by a user.
This file is installed in the /var file system and is placed in the usr/var/opt/OAT100/templates source directory.

/usr/var/log_files/odb_log -- the context-dependent symbolic link (CDSL) for the odb_log file.
This symbolic link is installed in the /usr/var file system and is placed in the usr/var/opt/OAT100/log_files source directory.

/usr/var/cluster/members/member0/log_files/odb_log -- the file listing all of the ODB documents created by a user. The odb_log file can be modified by users.
This file is installed in the /usr/var file system and is placed in the usr/var/cluster/members/member0/opt/OAT100/log_files source directory.

files -- the files file fragment contains information about the location of the source code and modules associated with the driver, tags indicating when the driver is loaded into the kernel, and whether the source or binary form of the driver is supplied to the customer.

sysconfigtab -- the sysconfigtab file fragment contains device special file information, bus option data, and information on contiguous memory usage for statically and dynamically configured drivers. The sysconfigtab file fragment gets appended to the /etc/sysconfigtab database when the kernel product kit is installed. For more information, refer to the sysconfigtab(4) reference page.

odb_printer.mod -- the object module file containing the single binary module for the ODB kernel product.

The odb.kit files allow the target system's kernel to bootlink the new hardware support software modules. One stays resident on the distribution media, and one is installed onto the target system. Although their format is the same, module specifications differ within the two files. Section 6.2.6 provides more information about the name.kit files.

A hardware product kit requires that you include the following files on the distribution media to make the hardware product accessible during initial system installation and console-level reboots:

The files file fragment (Section 6.2.1)

The sysconfigtab file fragment (Section 6.2.2)

The driver.mod object module file (Section 6.2.3)

The *.c (source) and *.h (header) files (Section 6.2.4)

The device.mth method files (Section 6.2.5)

The name.kit files (Section 6.2.6)

The database.nhd file (Section 6.2.7)

The PRODCODE.root file (Section 6.2.8)

The kitname.kk file (Section 6.2.9)

6.2.1 The files File Fragment

The files file fragment contains information about the location of the source code and modules associated with the driver, tags indicating when the driver is loaded into the kernel, and whether the source or binary form of the driver is supplied to the customer. You need to edit this file if the kit development directory structure differs from the driver development directory structure or if you must change the driver name for any reason.

Caution

The files file fragment must be in the same directory as the kernel modules or the kreg and doconfig utilities will not work properly.

Figure 6-2 shows which fields within the files file fragment need to change.

Figure 6-2: Editing the files File Fragment

6.2.2 The sysconfigtab File Fragment

The sysconfigtab file fragment contains device special file information, bus option data information, and information on contiguous memory usage for statically and dynamically configured drivers. When the user installs a kernel product kit, the driver's sysconfigtab file fragment gets appended to the /etc/sysconfigtab database. You should place this file fragment in a product directory, such as /opt/OAT100/etc.

You do not need to change the sysconfigtab file fragment unless you change the driver (subsystem) name. The driver name appears in three places within the file, as shown in Figure 6-3. In the example, the driver runs on a TURBOchannel bus (indicated by the TC_Option entry), but a similar set of bus options would be specified for other bus types.

Figure 6-3: Editing the sysconfigtab File Fragment

This file is described in the sysconfigtab(4) reference page.

6.2.3 The Object Module File

The driver.mod object module file contains the single binary module for both statically and dynamically configured drivers. Include this file in a product directory, such as /opt/OAT100/sys/BINARY, in the root ( / ) file system.

Caution

Compressed modules cannot be linked using RIS. Use the file command to determine if a file is compressed. You see output similar to the following:
# file odb_graphics.mod
odb_graphics.mod:
    alpha compressed COFF executable or object module not stripped

6.2.4 The Source and Header Files

The *.c (source) and *.h (header) files contain the source code for the device driver. Include these files in a product directory, such as /usr/opt/OAT100/src, when the driver is configured statically and distributed in source form.

6.2.5 The Method Files

The device.mth method files contain driver methods that are called during automatic configuration to create device special files for dynamically configured drivers. The subset control program creates links to these device special files in the customer's subsys directory when the driver is installed. The driver method files are on the distribution media and are not installed onto the customer's system. The device driver developer can tell you which method files the subset control program should link to, typically /subsys/device.mth. Link the method in a device driver kernel kit only if the driver needs to have device special files created for its devices.

6.2.6 The name.kit Files

The name.kit files allow the target system's kernel to bootlink the new hardware support software modules. The format of the distribution name.kit file and the installed name.kit files is the same, but the following list describes the differences:

In the distribution name.kit file, the modules are specified by their location on the distribution media. The distribution name.kit file must ship in the /usr/opt/PRODCODE/sys/hardware directory.
The distribution name.kit file is not part of the installed product and does not need to be part of the product inventory.

In the installed name.kit file, the modules are specified by their location on the installed system. The installed name.kit file resides in the root file system and must ship under the /opt directory.
The installed name.kit file is a required part of the installed product and must be part of the product inventory.

Commands in the distribution name.kit file direct the boot utility to modify the bootlink process and boot this kit off the distribution media. When the kernel is bootlinked, the distribution name.kit file controls where hardware product modules are found during the boot process. When bootlinking from a hardware product kit, the boot utility sets the default directory to the distribution media's root ( / ) directory. Commands in the distribution name.kit file indicate which modules should be added, removed, or replaced in the kernel.

Kernel modules must reside in the /opt/PRODCODE/sys/BINARY directory so that they can be accessed by the boot process. Kernel modules for the fictitious graphics device driver used in this chapter are located in /opt/OAT100/sys/BINARY.

Caution

Module files for hardware product kits must be compressed with the objZ utility. Do not use the compress or gzip utilities to compress module files for hardware product kits. See the objZ(1) reference page for more information.

Example 6-1 shows the format of the commands in the name.kit file.

Example 6-1: Sample Installed name.kit File

-/opt/OAT100/sys/BINARY/odb_printer.mod
+/opt/OAT100/sys/BINARY/odb_printer.mod

Each kernel module listed in the name.kit file first must be removed with the - operator and then added with the + operator. If kernel modules are just added and you already have an older version of the hardware product on the system, the bootlink will fail because the kernel module already exists. The + operator does not replace a module if it already exists. Therefore, to protect against this, it is recommended to first remove the module and then add it to make sure you get the latest version of the module in the kernel.

The hardware product kit for the odb_printer driver supplies a name.kit file, which first removes and then adds the single binary module odb_printer.mod to the kernel. In Example 6-1, the sample name.kit file is referencing the /opt/OAT100/sys/BINARY directory on the installed system, not on the distribution media.

Figure 6-4 shows how the distribution name.kit file works with boot utility software during the installation of a hardware product kit.

Figure 6-4: Using the Distribution name.kit File During Installation

In the figure, the kit contains a name.kit file called odb.kit. The odb.kit file instructs the system's boot utility to build and configure a temporary kernel that includes the odb_printer driver. Upon completion, this temporary kernel makes the odb_printer driver available to handle user and system requests of a specific hardware device during the installation of the operating system.

6.2.7 The database.nhd File

The database.nhd file, also known as the hardware database file, describes the hardware product kits residing on the distribution media. The installation process uses the database.nhd file to determine what software to load. This file contains one record for each hardware product kernel module. For example, if your distribution includes two hardware product kits, one with three kernel modules and another with five kernel modules, the database.nhd file would contain eight records.

There can be only one database.nhd file on each distribution media, located in the root ( / ) directory.

The syntax for the database.nhd file uses the following conventions:

Lines beginning with a pound sign ( # ) are comments and are ignored. Blank lines are also ignored.

Each entry must be enclosed in {} (curly braces).

Each field in an entry must be enclosed in {} (curly braces).

Entries and fields can span lines without the use of a line continuation character.

An entry in the database.nhd file contains eight fields:

Vendor name

Hardware name

List of subsets to be loaded, separated by spaces

List of releases under which the product is supported, separated by spaces, without V preceding the version numbers

Kernel build flag
Valid values are 0 for no kernel build required, and 1 for kernel build required

Module name including the full path as specified in the name.kit file

Kit directory, including the full path as located on the distribution media

Kit file name, including the full path as located on the distribution media

Each vendor name and hardware name must form a unique combination. Each product release supported by the kit must map to at least one release of the operating system, as shown in Example 6-2. Operating system versions use the format: {MajorNumber}{MinorNumber}[VariantLetter].

Example 6-2: Sample database.nhd File

#
# New hardware support
#
{
    {Orpheus Document Builders}
    {ODB Device Driver}
    {OATBASE100 OATDOC100}
    {4.0F}
    {1}
    {/V4.0F/sys/BINARY/asynchhw_stub.mod}
    {/V4.0F/kit}
    {/v4.0F/usr/sys/hardware/base.kit}
}

6.2.8 The .root File

When building a Direct CD-ROM (DCD) distribution media, the gendisk utility also generates a PRODCODE.root file, where PRODCODE is the three-letter product code and the version number, for example: OAT100.root.

This file must ship in the instctrl directory and contains the path to the expanded subset files starting from the kit directory (for example, /mnt/ODB/kit).

This file is created automatically by the gendisk utility when a Direct CD-ROM (DCD) distribution media is built.

6.2.9 The kitname.kk File

By default, all hardware product kits should contain a hardware product indicator file (kitname.kk) in the instctrl directory. The file can be empty, but it must exist. This file indicates to RIS that a hardware product kit exists on the distribution media. When the ris utility finds this file, you are prompted for a hardware product kit name to add to the RIS area. This file is created automatically by the gendisk utility when it finds the kk=true option in the /etc/kitcap file.

6.3 Producing Distribution Media

After you have created the subsets and the additional installation files, you can move the subsets onto the distribution media. This consists of the following tasks:

Rerunning the newinv utility to update the master inventory file with the additional installation files. (Section 3.7)

Rerunning the kits utility to produce updated subsets and control files. (Section 3.5)

Editing the /etc/kitcap file. (Section 6.3.1)

Using the gendisk utility to build the hardware product kit on disk media. (Section 6.3.2)

6.3.1 Editing the /etc/kitcap File

The gendisk utility refers to the /etc/kitcap file, a database containing information about the kits to be built on the system. Each record contains a product code and the names of the directories, files, and subsets that make up the product kit. Before you can build your kit, you must add a media descriptor record to the /etc/kitcap database.

Note

If you use the gendisk utility to produce your kit on disk distribution media, you can specify an alternate kit descriptor database. Refer to the gendisk(1) reference page for additional information.

Use the following conventions when you add a record to the /etc/kitcap file:

Separate the first field from the rest of the record by a colon ( : ) for disk media descriptors and by a pipe character ( | ) for tape media descriptors.

Separate all other fields with colons ( : ).

Indicate continuation with a backslash ( \ ) at the end of the line.

Lines starting with a pound sign ( # ) are comments and are ignored.

Comments within the record start with pound sign ( # ) and end with a colon ( : ). Use this feature sparingly.

The contents of the record can depend on the product type you are delivering. For example, the kitcap record for a hardware product must contain the kk=true parameter and may require the use of the rootdd= option.

The kitcap record for disk media contains the following elements:

The kit name, consisting of two parts:
- The product code, consisting of the product code and version number specified in the CODE and VERS fields of the kit's key file.
- The media code HD to indicate disk media. This element is followed by a colon ( : ).

The partition on the disk media where the product should be placed. The partition is a letter between a and h. Partition c is used most often, as it spans the entire disk.

The destination directory for the subsets on the disk media. This allows a hierarchical structure so you can put multiple products on one disk, or put parts of one product on different areas of the same disk. You can use multiple destination directories in a kitcap record.
The destination directory field may also include these parameters:
- kk=true
  Indicates that the kit is needed during the boot process. When the gendisk utility finds this option, it generates a kitname.kk file automatically.
- rootdd=dirname
  Specifies kit file placement on the distribution media, relative to the kit-specific directory such as /OAT100/kit. For example, rootdd=.. would place the kit's root under the /OAT100 directory.

The product description. This entry is taken from key file NAME field. Replace any spaces with an underscore ( _ ) character, for example: Product Description becomes Product_Description.

The name of the output directory where you created the kit, where the gendisk utility can find the product subsets.

The instctrl directory, relative to the output directory specification.

The names of the subsets that make up the kit.

Refer to the kitcap(4) reference page for more information about the disk media record format.

Refer to Section 3.3 for information about the key file.

Example 6-3 shows the record to be added to the /etc/kitcap file to produce the ODB hardware product kit. Notice the use of the kk=true and rootdd= options.

Example 6-3: Sample Disk Media Descriptor

OAT100HD:c:\
  dd=/ODB/kit,kk=true,rootdd=..:Orpheus_Document_Builder:\
  /mykit/output:instctrl:OATBASE100

Example 6-4 shows a sample kitcap record for a CD-ROM with multiple hardware products. In Example 6-4, the rootdd=.. entry overrides the default and places the expanded subset files in the product-specific directory of /ODB. By default, expanded subset files (in DCD format) are placed at the top of the media's file system.

Example 6-4: Sample Disk Media Descriptor for Multiple Hardware Product Kits

OAT100HD:c:\
  dd=/OAT100/kit,kk=true,rootdd=..:ODB_Driver_V1:\
  /odb100/output:instctrl:OATBASE100:\
  dd=/OAT200/kit,kk=true,rootdd=..:ODB_Driver_V2:\
  /odb200/output:instctrl:OATBASE200:

Refer to the kitcap(4) reference page for more information about the disk media descriptor format.

Note

Each kit must be contained in a separate directory located in the distribution media's root directory. For example, a kit is located in /mnt/ODBprinter where /mnt is the mount point and ODBprinter is the subdirectory under which the kit files are located.

6.3.2 Building a Hardware Product Kit on Disk Media

When the product subsets are located in the output area of the kit directory structure, you produce a master copy of the hardware product kit on a hard disk and use this master disk to copy the kit onto a CD-ROM.

Follow this sample procedure to produce a master disk for the OAT100 hardware product kit:

Log in as root or use the su command to gain superuser privileges.

Make sure that you have an entry for your system's root account in the /.rhosts file. For example, if your system name is system01, your entry in the /.rhosts file would look similar to the following:
```
system01 root
 
```
If this entry is not present, the gendisk utility will fail with a Permission denied error.

Follow these steps to prepare the master disk for the hardware product kit:
1. Determine the device where the master media is to be written. This sample procedure uses an RZ26 disk associated with the /dev/disk/dsk1 device special file.
2. Use the disklabel command to erase any existing label or data. For example:
```
# disklabel -z /dev/disk/dsk1
```
3. Use the disklabel command to write a new disk label. For example:
```
# disklabel -wr /dev/disk/dsk1 rz26L
```

Use the gendisk utility to create the master disk for the hardware product kit.
Use the following syntax for the gendisk command:
gendisk [-d] [-i] [-k filename] [-w] [-v] [hostname:] prodID devname

-d

Creates a distribution disk in direct CD (DCD) format. This means that the distribution disk contains uncompressed file systems that are arranged in the same way as the software will be installed on the system.

-i

Creates a distribution disk in ISO 9660 format. This means that the distribution disk contains an ISO 9660-compliant CD-ROM file system (CDFS).

-k filename

Uses an alternate kit descriptor database, filename, on the local system. You may use either a full absolute pathname or a relative pathname from the directory where you run the gendisk utility. You do not have to name the file kitcap.

-w

If used without the -v option, writes the product media without verification. If used with the -w option, the gendisk utility writes and then verifies the product media.

-v

If used without the -w option, verifies the product media without writing it first. This assumes that you already have written kit files to the distribution media. If used with the -w option, the gendisk utility writes and then verifies the product media.

hostname:

The optional hostname: operand is the name of a remote machine that contains the kitcap file. The utility searches the /etc/kitcap file on the remote machine for the prodID and uses it for creating the media. The colon (:) is a required delimiter for TCP/IP networks, and space is permitted between the colon and the prodID. For example, if the product code is OAT100 and you are using the kit descriptor database on node mynode, use mynode:OAT100 for this option.

prodID

The mandatory prodID operand is a kit identifier consisting of the product code and version number specified in the CODE and VERS fields of the kit's key file. Refer to Section 3.3 for information about the key file.

devname

The mandatory devname operand specifies the device special file name for a raw or character disk device such as /dev/rdisk/dsk1. The gendisk utility uses the disk partition specified in the kit descriptor and ignores any partition specified on the command line.

Note

If you do not use either the -w or -v options, the gendisk utility writes and then verifies the product media.

In this sample procedure, the system name is system01. For example:
```
# gendisk -d OAT100 /dev/disk/dsk1a
Generating OAT100 Kit from system01 on /dev/disk/dsk1a
 
WARNING:  this will remove any information stored in 
/dev/disk/dsk1a
Are you sure you want to do this? (y/n): y
Do you want to clean the entire disk first? (y/n): n
 
 
```
Caution

When the gendisk utility asks if you want to clean the disk, always answer n or the gendisk replaces the current disk label with a default label.

The gendisk utility output is similar to the following:
```
Preparing /dev/disk/dsk1a
done.
 
Checking /dev/disk/dsk1a
/sbin/usf_fdck /dev/disk/dsk1a
** /dev/disk/dsk1a
File system unmounted cleanly - no fsck needed
 
Mounting /dev/disk/dsk1a on /usr/tmp/cd_mdt8344
 
Writing Images (dd=/).
 
	Image instctrl...done.
	Image OATBASE100...done.
 
Verifying Images (dd=/).
 
	Image instctrl...done.
	Image OATBASE100...done.
 
Kit OAT100 done.
 
Cleaning up working directories.
Unmounting /dev/disk/dsk1a
```

Follow these steps to copy the additional installation files to the master disk:
1. Mount the master copy's hard disk. For example:
```
# mount /dev/disk/dsk1a /mnt
# cd /mnt
```
2. Verify that the .kk and .root files exist in the master disk's instctrl directory. For example:
```
# cd ./ODB/kit/instctrl
# ls *.kk *.root
OAT100.kk
OAT100.root
```
3. Copy the database.nhd file to the master disk's root area. For example:
```
# cp /mykit/database.nhd /mnt
```
4. If it was not included in the inventory, copy the distribution name.kit file to the proper directory on the master disk. For example:
```
# cp /mykit/odb.kit \
    /mnt/ODB/usr/opt/OAT100/sys/hardware/odb.kit
```
5. Copy the distribution name.kit file and the database.nhd file from the kit-building area to the master disk. For example:
```
# cp /kitarea/odb.kit \
    /mnt/ODB/usr/opt/OAT100/sys/hardware/odb.kit
# cp /kitarea/database.nhd /mnt/database.nhd
```
  Note
  
  The backslash ( \ ) in this example represents line continuation. Do not include it in the command line.
6. Unmount the disk. For example:
```
# umount /mnt
```

Use this master disk to copy the hardware product kit onto a CD-ROM by following the instructions that came with your CD-ROM burner.

6.4 Testing the Distribution Media

Before shipping a hardware product kit to customers, you should test the kit with the same procedures that your customers will use on hardware configurations that resemble your customers' systems.

Run the following tests, in sequence, to test a hardware product kit:

Use the setld utility to verify that the subsets have been built correctly and that the files get installed into the correct locations on the target system. (Section 6.4.1)

Use the bootlink process to test that all of the modules are in the correct locations to allow the system to add support to the bootlinked kernel. (Section 6.4.2)

Use the hw_check utility to verify that the database.nhd file is in the correct location and that it contains the correct information. (Section 6.4.3)

Use the ris utility to add a hardware product kit into a RIS area to verify that the correct files are present on the kit. (Section 6.4.4)

Register a client for the RIS area containing the hardware product kit and start a Full Installation on the client system. (Section 6.4.5)

When testing a hardware product kit in DCD format, reference the kit media at its mount point. For example, if you decide to use a spare disk for creating a media master area, you must reference your kit to that devices's mount point.

6.4.1 Testing a Hardware Product Kit with the setld Utility

To test a hardware product kit using the setld utility, the system where you conduct the test must be running the same version of the operating system for which the hardware product kit was built.

Follow these steps to test the hardware product kit using the setld utility. The purpose of this test is so that you can test the location of the installed product files as you defined them in the master inventory file.

Log in to the system as root or use the su command to gain superuser privileges.

Place the CD-ROM in the drive.

Create a directory to be the media mount point, such as /cdrom:
```
# mkdir /mnt
```

Mount the CD-ROM on /mnt. For example, if the CD-ROM device is located on the c partition of cdrom0, enter the following command:
```
# mount -r /dev/disk/cdrom0c /mnt
```

Use the following setld command syntax to install each subset on the distribution media:

# setld -l /mnt/OAT100/kit OATBASE100

Checking file system space required to install specified subsets:
 
File system space checked OK.
 
1 subset(s) will be installed.
 
Loading 1 of 1 subset(s)...
 
ODB Device Driver Files
  Copying from /mnt/ODB/kit (disk)
  Verifying
 
1 of 1 subset(s) installed successfully.
 
Configuring "ODB Device Driver Files " (OATBASE100)

If there is an error during subset installation, the setld utility displays a message explaining the error. Details for verification errors are in the /var/adm/smlogs/fverify.log file.

When the installation is complete, unmount the CD-ROM:
```
# umount /mnt
```

After the setld utility has finished installing and configuring each subset, verify that the files for each subset (including the /usr/sys/hardware/database.nhd files) have been installed in the correct locations.

6.4.2 Testing a Hardware Product Kit on a Running System

This section contains procedures for testing the installation of a hardware product kit on a system that already is running a version of the operating system that supports this feature.

Figure 6-5 shows how the boot utility builds a kernel to include a hardware product kit.

Figure 6-5: Bootlinking with a Hardware Product Kit

Follow these steps to use the bootlink process to install a hardware product kit onto a system that is running a version of the operating system that supports this feature:

Log in as the user root or use the su command to gain superuser privileges.

Back up the operating system.

Use the shutdown command to halt your system and bring it down to console mode:
```
# shutdown -h now
```

Enter the following command to turn off automatic reboots at the console prompt:
```
>>> set auto_action halt
```

Power down your system.

Install the new hardware.

Power up your system. You see the console prompt:
```
>>>
```

Enter the following boot command:
```
>>> boot -flag fa -file "/GENERIC" sys_disk
```
In the previous example:
- The -flag fa defines the boot flags: f for a hardware product kit and a for multiuser mode.
- The -file "/GENERIC" tells the kernel to bootlink using the file /GENERIC.
- The optional sys_disk argument is the console device name of the system disk of the system that is running. You only need this argument if your bootdef_dev console variable is not set to your running system disk.
You see the following prompt:
```
Enter Device Name:
```

Enter the CD-ROM console device name, for example, DKA500. You see a prompt similar to the following:
```
Insert media for kit 'device:hwkitname', press Return when ready:
```

Insert the hardware product kit CD-ROM and press [Return]. You see the following prompt:
```
Enter Kit Name:
 
```

Enter the name of the hardware product kit you want to install, using the full pathname of the distribution name.kit file on the distribution media. You see the following prompt:
```
Insert media for kit 'device:hwkitname', press Return when ready:
```
In this example, device:hwkitname is the device name you entered in Step 9 and the hardware product kit name you entered in Step 11

Insert the CD-ROM containing the hardware product kit into the CD-ROM drive and press [Return]. The boot utility reads the selected hardware product kit file into memory, and you see the following prompt:
```
Enter Kit Name:
```

Take one of the following actions:
- If you are installing another hardware product kit from the same CD-ROM, enter the kit name, press [Return], and return to Step 12.
- If you are not installing another hardware product kit from the same CD-ROM just press [Return] and continue.
  You see the following prompt:
```
Enter Device Name:
```

Take one of the following actions:
- If you are installing another hardware product kit from a different CD-ROM, enter the CD-ROM device name, press [Return], and go back to Step 11.
- If you are not installing another hardware product kit, just press [Return] and continue.
  You see the following prompt:
```
Insert boot media, hit <return> when ready:
 
```

Press [Return], because you are adding hardware support to a running system and the system disk is your boot media.
The boot utility reads the generic kernel modules and links the kernel objects, and you see the following prompt:
```
Insert media for kit 'dev_name:hwkitname', press Return when ready:
 
```
In the previous prompt, dev_name is the CD-ROM device name you entered in Step 9 and hwkitname is the hardware product kit name that you entered in Step 11.

Insert the CD-ROM into the drive and press [Return].

Note

Do this step for every device and every kit name entered in Step 9 through Step 14.

You see the following prompt:
```
Insert boot media, press Return when ready:
 
```
Press [Return], because you are adding hardware support to a running system and the system disk is your boot media. The boot utility loads and configures the hardware product kit.

Note

If you installed more than one hardware product kit from different media on the same device, the boot utility may prompt you for the location of some of the hardware support subsets. If you see this prompt, load the appropriate CD-ROM into the CD-ROM drive and enter the appropriate console device name.

You see the following prompt:
```
Enter a name for the kernel configuration file. [SYSNAME]: 
 
 
```
SYSNAME is the name of your existing kernel configuration file, usually your system name in upper case characters.

Enter the name of the kernel configuration file or press [Return] to accept the default.

You may see one or more of the following sequences:

If you select the existing kernel configuration file name, you are asked to confirm your selection. If you confirm your selection of the existing file name, the old kernel configuration file is backed up to SYSNAME.bck.

If the boot utility prompts you to rebuild the kernel, you see a prompt similar to the following:

*** KERNEL OPTION SELECTION ***
 
    Selection   Kernel Option
--------------------------------------------------------------
        1       System V Devices
        2       Logical Volume Manager (LVM)
        3       NTP V3 Kernel Phase Lock Loop (NTP_TIME)
        4       Kernel Breakpoint Debugger (KDEBUG)
        5       Packetfilter driver (PACKETFILTER)
        6       Point-to-Point Protocol (PPP)
        7       STREAMS pckt module (PCKT)
        8       Data Link Bridge (DLPI V2.0 Service Class 1)
        9       X/Open Transport Interface (XTISO, TIMOD, TIRDWR)
        10      ISO 9660 Compact Disc File System (CDFS)
        11      Audit Subsystem
        12      ACL Subsystem
        13      Logical Storage Manager (LSM)
        14      Advanced File System (ADVFS)
        15      All of the above
        16      None of the above
        17      Help
        18      Display all options again
--------------------------------------------------------------
 
Enter the selection number for each kernel option you want.
For example, 1 3 [16]:

The options you see depend upon the software subsets that you have installed. See the Installation Guide for information about selecting kernel options and the doconfig(8) reference page for information about the kernel build process.

Select kernel options from the list and press [Return]. You see a prompt similar to the following:

You selected the following kernel options:
 
	System V Devices
	Logical Volume Manager (LVM)
	NTP V3 Kernel Phase Lock Loop (NTP_TIME)
	Kernel Breakpoint Debugger (KDEBUG)
	Packetfilter driver (PACKETFILTER)
	Point-to-Point Protocol (PPP)
	STREAMS pckt module (PCKT)
	Data Link Bridge (DLPI V2.0 Service Class 1)
	X/Open Transport Interface (XTISO, TIMOD, TIRDWR)
	ISO 9660 Compact Disc File System (CDFS)
	Audit Subsystem
	ACL Subsystem
	Logical Storage Manager (LSM)
	Advanced File System (ADVFS)
 
Is that correct? (y/n) [y]:

Do one of the following:
- If the list is correct, enter y and continue to the next step.
- If the list is not correct, enter n to return to Step 17a and select kernel options again.
The boot utility asks if you want to edit the /usr/sys/conf/SYSNAME kernel configuration file. For information about editing this file, refer to the Installation Guide. Usually, there is no reason to edit this file.

The boot utility rebuilds your operating system kernel and reboots with the new kernel. After a successful reboot, you see the operating system login window.

Log in as root.

Use the setld -i command to verify that your hardware product kit is installed.

Check to make sure that the installed files are where you want them to be and that the hardware product is operational.

Check to make sure that the /GENERIC file was rebuilt correctly by issuing the following command for each module file that was loaded:
```
# cat /GENERIC | grep -e modname.mod
```
In the previous example, modname.mod represents the name of the module file that was loaded. If the .mod file was supplied in the /opt directory, the full path and file name should be in the /GENERIC file.

6.4.3 Using the hw_check Utility to Test a Hardware Product Kit

When you perform an Update Installation, the process checks for any installed hardware product kits automatically and reports the following information:

If an existing hardware product kit will continue to operate correctly with the new version of the operating system.

If an existing hardware product kit is integrated into the new version of the operating system. If so, the hardware product kit will be removed as part of the Update Installation and will be replaced by the functionality shipped with the operating system.

If an existing kit is not supported in the new version of the operating system.

This section describes two test cases to test the validity of a hardware product kit during an Update Installation.

Note

The following test assumes that you already have done the bootlink test described in Section 6.4.2.

Follow these steps to test the format of the database.nhd files:

Log in as root to the same system where you performed the boot link test.

Mount the operating system CD-ROM from multiuser mode:
```
# mount -r /dev/disk/dsk9a /mnt
```

Run the hw_check utility:
```
# /usr/lbin/hw_check /mnt
```
You see output similar to the following for a successful test:
```
Checking for installed supplemental hardware support...
 
The following hardware was installed using a supplemental
hardware kit and will continue to work under the new
operating system without any modifications.
 
        ODB Device Driver
 
Press RETURN to continue...
 
 
```
If you do not see a message similar to this, the most likely cause of the error is an incorrect value in the supported release field of the /usr/sys/hardware/database.nhd file on the system. This file is generated or updated from the database.nhd file on the distribution media. Refer to Section 6.2.7 for information about the format of this file.

Next, follow these steps to run the hw_check utility, testing the kit as if you were performing an Update Installation. This test sets up a scenario where an existing kit is not supported in the new release of the operating system. This procedure assumes that you already have tested the kit with the bootlink utility as described in Section 6.4.2.

Log in as root to the same system where you tested the kit with the setld utility.

Use the editor of your choice to modify the installed system's /usr/sys/hardware/database.nhd file and change the value in the supported release field to XXX. For example, if this is the original installed database.nhd file:
```
{
    {Orpheus Document Builders}
    {ODB Device Driver}
    {OATBASE100 OATDOC100}
    {4.0F}
    {1}
    {/V4.0F/sys/BINARY/asynchhw_stub.mod}
    {/V4.0F/kit}
    {/V4.0F/usr/sys/hardware/base.kit}
}
```
Change the supported release field as shown in this example:
```
{
    {Orpheus Document Builders}
    {ODB Device Driver}
    {OATBASE100 OATDOC100}
    {XXX}
    {1}
    {/V4.0F/sys/BINARY/asynchhw_stub.mod}
    {/V4.0F/kit}
    {/V4.0F/usr/sys/hardware/base.kit}
}
```
Changing the supported release field to XXX indicates that the hardware product kit is supported only under operating system version XXX. Changing this field should trigger the appropriate warning logic in the Update Installation process because XXX is not a valid release format.

Run the hw_check utility to start the test:

# /usr/lbin/hw_check /mnt

You see output similar to the following:

Checking for installed hardware product kits...
 
The update installation has detected that the hardware 
product kit listed below is loaded on your system and 
is not supported in the new release of the operating 
system (V5.0A). In order for the update to
complete successfully, you must provide the distribution 
media that contains the V5.0A version of the hardware 
product listed below.  The update install process will 
verify that the media you provide contains
the correct software.
 
      Orpheus Document Builders ODB Device Driver
 
Enter kit location (e.g.: /dev/disk/dsk3c or /mnt)

Enter the kit location, for example /mnt, and press the [Return] key.

The output is similar to the following:

The kit located at /mnt contains support for hardware 
that is currently installed on your system and is not 
supported under the new version of the operating 
system V5.0A.  In order for your hardware
to continue to function properly you will be asked 
to supply the following kit file names when the update 
installation reboots the system for the first time.  
Be sure to record these file names for future use 
within the update install process.  Each kit file 
will only need to be entered once for all of the 
associated hardware support to be loaded.
 
  Orpheus Document Builders ODB Device Driver 
 (Kit File: /ODB/usr/opt/OAT100/sys/hardware/odb.kit)
 
Press <RETURN> to continue...

If you see this message, the hw_check test is successful. Otherwise, the hw_check utility displays an error message to describe the problem. You must correct the problem and run the test again.

6.4.4 Testing a Hardware Product Kit in a RIS Area

To install a hardware product kit into a RIS area, you must extract the base operating system into the RIS area first. Follow these steps to extract the base operating system into a new RIS area and then add the hardware product kit to the new area:

Log in to the RIS server as root or use the su command to gain superuser privileges.

Enter /usr/sbin/ris to start the ris utility. You see the RIS Utility Main Menu:

*** RIS Utility Main Menu ***
 
Choices without key letters are not available.
 
    a) ADD a client
    d) DELETE software products
    i) INSTALL software products
     ) LIST registered clients
     ) MODIFY a client
     ) REMOVE a client
    s) SHOW software products in remote installation 
       environments
    x) EXIT
 
Enter your choice:

Enter i to select INSTALL software products. You see the RIS Software Installation Menu:

RIS Software Installation Menu:
 
    1)  Install software into a new area
    2)  Add software into an existing area
    3)  Return to previous menu
 
Enter your choice:

Enter 1 to select Install software into a new area. You see the following prompt:

You have chosen to establish new remote installation
environment.
 
Enter the device special file name or the path of the
directory where the software is located (for example,
/mnt/ALPHA/BASE) or press <Return> to exit:

Enter the location of the base operating system distribution media, for example: /mnt/ALPHA/BASE. You see the following prompt:

Select the type of Tru64 UNIX base product to create.
If the software you are offering supports add-on hardware that is needed
to boot the client system, select "boot-link" as the type of RIS area to
create. Otherwise, select "standard". If you select "boot-link", the
software will be extracted (or copied) to the RIS area, because symbolically
linked RIS areas do not support this feature.
 
Choose one of the following options:
    1)  Standard boot method
    2)  Boot-Link method
 
Enter your choice:

Enter 2 to select Boot-Link method. You see messages similar to the following:

       Media extraction complete
The new environment is in /var/adm/ris/ris0.alpha
 
Building Network Bootable Kernel........Done
 
The following software now exists in RIS product area
/var/adm/ris/ris0.alpha:
     1   'Tru64 UNIX V5.0A Operating System ( Rev nnn )'

You see the RIS Utility Main Menu:

*** RIS Utility Main Menu ***
 
    a) ADD a client
    d) DELETE software products
    i) INSTALL software products
     ) LIST registered clients
     ) MODIFY a client
     ) REMOVE a client
    s) SHOW software products in remote installation 
       environments
    x) EXIT
 
Enter your choice:

Enter i to select INSTALL software products. You see the RIS Software Installation Menu:

RIS Software Installation Menu:
 
    1)  Install software into a new area
    2)  Add software into an existing area
    3)  Return to previous menu
 
Enter your choice:

Enter 2 to select Add software into an existing area. You see a prompt similar to the following:

You have chosen to add a product to an existing environment.
 
Select the remote installation environment:
 
    1) /usr/var/adm/ris/ris0.alpha
         'Tru64 UNIX V5.0A Operating System ( Rev nnn )
 
Enter your choice or press RETURN to quit:

Enter 1 (in this example) to select the new RIS environment where you just extracted the base operating system. You see a prompt similar to the following:

Enter the device special file name or the path of the
directory where the software is located (for example,
/mnt/ALPHA/BASE) or press <Return> to exit:

Enter the location of the hardware product kit that you want to install, for example: /mnt/kit. This is the kit directory under the top-level directory of the hardware product kit on the distribution media.
The ris utility searches the distribution media for the kitname.kk file that indicates that the distribution media contains a hardware product kit.
You see a prompt similar to the following:
```
The kit you have specified has been identified as a Tru64 UNIX
kernel kit. This type of kit may contain software which is
needed during the booting of the kernel for the installation, due
to required hardware support. If you need to add this kit to the
base, select the option to integrate the kit. You may otherwise
choose to add this kit to the RIS area as a separate product.
 
1)  Integrate with Base product and include product
2)  Include as separate product
3)  Return to Main Menu
 
Enter your choice:
```
Note

If you do not see this message, the hardware product kit is not structured correctly. The most likely cause is a missing ./kit/instctrl/*.kk file or specifying an invalid location in the previous step. Make sure all kit files are located in the appropriate directories and restart this test.

Enter 1 to select Integrate with Base product and include product. You see a prompt similar to the following:

Please select one of the following products to add the kit to.
 
    1   'Tru64 UNIX V5.0A Operating System ( Rev nnn )'
 
 Enter your selection or <return> to quit:

Enter 1 (in this example) to select the version of the base operating system where you want to integrate the kit. You see a prompt similar to the following:

Choose one of the following options:
 
    1)  Extract software from   /mnt/OAT100/kit
    2)  Create symbolic link to /mnt/OAT100/kit
 
 Enter your choice:

Decide whether you want to either extract the software onto the system or just create symbolic links to the software. In this example, enter 1 to select Extract software.

The ris utility lists all the subsets associated with the software kit. In this example, the OAT100 kit contains only one subset, and you see a prompt similar to the following:

The subsets listed below are optional:
 
     There may be more optional subsets than can be presented 
     on a single screen. If this is the case, you can choose 
     subsets screen by screen or all at once on the last 
     screen. All of the choices you make will be collected 
     for your confirmation before any subsets are extracted.
 
     1) ODB Device Driver Version 1
 
 Or you may choose one of the following options:
 
     2) ALL of the above 
     3) CANCEL selections and redisplay menus
     4) EXIT without extracting any subsets 
 
Enter your choices or press RETURN to redisplay menus.
 
Choices (for example, 1 2 4-6):

Enter 1 (in this example) to select ODB Device Driver Version 1, or you can enter 2 to select ALL of the above. You see a prompt similar to the following:
```
You are installing the following optional subsets:
 
        ODB Device Driver Version 1
 
 Is this correct? (y/n):
```

Enter y to confirm your software selection.

The ris utility integrates the hardware product kit software and the base system. No user interaction is needed at this time.

You see messages similar to the following:

Checking file system space required to extract selected 
subsets:
 
File system space checked OK.
Extracting OATBASE100...
Media extraction complete.
 
The following software now exists in the RIS product area
/var/adm/ris/ris0.alpha:
1   'Tru64 UNIX V5.0A Operating System ( Rev nnn )' with
    'ODB Device Driver Version 1'
 
2   'ODB Device Driver Version 1'

The hardware product has been extracted into the RIS area and integrated into a new version of the base operating system.

If you choose SHOW software products in remote installation environments from the RIS Utility Main Menu, you see that there are now two products in the new RIS area: the current version of the operating system with support for the ODB device driver and the OATBASE100 hardware product kit.

6.4.5 Registering a RIS Client and Installing a Hardware Product Kit

After adding the base operating system and hardware product kit to a RIS area, the hardware product subsets are now available. However, before a client can perform a Full Installation from this RIS area, you must register the client. You need to know the RIS client's hardware network address.

If you do not know your RIS client's hardware network address, do one of the following:

Log in to the RIS client as root or use the su command to gain superuser privileges, then shut down the system to the console prompt ( >>> ).
Use the show dev command to show all devices, and look for the hardware address of your network interface in the form xx-xx-xx-xx-xx-xx. For example:
```
>>> show dev
        
.
.
.
ewa0.0.0.0.1000.0	EWA0	xx-xx-xx-xx-xx-xx
        
.
.
.
```

Log in to the RIS client as root or use the su command to gain superuser privileges.
Use the uerf -r 300 command and look for the string hardware address in the ouput. Either that line or the next one contains the hardware network address. For example:
```
# uerf -r 300 | grep -i "hardware address" | uniq
_hardware address: xx-xx-xx-xx-xx-xx
```
If the hardware address is not on the line that contains the string hardware address, search the output from the uerf command to find the correct hardware address. For example:
```
# uerf -r 300 | more
        
.
.
.
_Interface, hardware address:
			_xx-xx-xx-xx-xx-xx 
        
.
.
.
```

Log in to the RIS server as root or use the su command to gain superuser privileges.

Use the ping and arp commands to determine the hardware address of a running client from the RIS server. For example, to determine the hardware address of the RIS client atlanta, enter a command similar to the following example:

# /usr/sbin/ping -q -c1 atlanta ; arp atlanta
PING atlanta.cities.xsamplex.com (nn.nn.nnn.nnn): 56 data bytes
----atlanta.cities.xsamplex.com PING Statistics----
1 packets transmitted, 1 packets received, 0% packet loss
round-trip (ms)  min/avg/max = 0/0/0 ms
atlanta (nn.nn.nnn.nnn) at xx-xx-xx-xx-xx-xx

Follow these steps to register your RIS client:

Log in to the RIS server as root or use the su command to gain superuser privileges.

Enter /usr/sbin/ris to start the ris utility. You see the RIS Utility Main Menu:

*** RIS Utility Main Menu ***
 
Choices without key letters are not available.
 
    a) ADD a client
    d) DELETE software products
    i) INSTALL software products
     ) LIST registered clients
     ) MODIFY a client
     ) REMOVE a client
    s) SHOW software products in remote installation 
       environments
    x) EXIT
 
Enter your choice:

Enter a to select Add a client. You see the following messages:

You have chosen to add a client for remote installation 
services.
 
The following conditions must be met to add a client:
 
        1. You must know the client processor's hostname
        2. The client's hostname must be in your system's 
           host database(s).
        3. You must know whether the client is on an 
           Ethernet, FDDI, or Token Ring network.
        4. You must know the client's hardware Ethernet, 
           FDDI, or Token Ring address if the client is 
           registering to install operating system software.
        5. If the client and the server reside on different 
           subnets, you will need the address of the 
           gateway(s) that the client can use to 
           communicate with the server.
 
Do you want to continue? (y/n) [y]:

Enter y to continue if you have the information you need. You see the following prompt:
```
Enter the client processor's hostname or press RETURN 
to quit:
```

Enter the client's host name. In this example, client02. You see a prompt similar to the following:

The existing environment is /usr/var/adm/ris/ris0.alpha
 
Select one or more products for the client to install
from /usr/var/adm/ris/ris0.alpha:
 
Product    Description
    1    'Tru64 UNIX V5.0A Operating System ( Rev nnn )' w/ 
         'ODB Device Driver Version 1'
    2    'ODB Device Driver Version 1' 
 
Enter one or more choices as a space-separated list
(for example, 1 2 3):

Enter 1 2 (in this example) to select the products you want the client system to be able to install. This includes the base system that includes kernel support for the ODB device driver as well as the hardware product kit. You see a prompt similar to the following:
```
You chose the following products: 
 
   1    'Tru64 UNIX V5.0A Operating System ( Rev nnn )' w/ 
        'ODB Device Driver Version 1' 
   2    'ODB Device Driver Version 1'
 
Is that correct? (y/n) [y]:
```

Enter y to confirm your selection. You see the following prompt:

Network type:
        1) Ethernet or FDDI
        2) Token Ring
 
Enter your choice:

Enter the network type. You see the following prompt:

Enter the client processor's hardware network address.  
For example, 08-00-2b-02-67-e1: xx-xx-xx-xx-xx-xx

Enter the RIS client's hardware network address. You see the RIS Utility Main Menu:

*** RIS Utility Main Menu ***
 
    a) ADD a client
    d) DELETE software products
    i) INSTALL software products
    l) LIST registered clients
    m) MODIFY a client
    r) REMOVE a client
    s) SHOW software products in remote installation 
       environments
    x) EXIT
 
Enter your choice:

Enter x to exit from the ris utility.

The client system can now boot over the network from the RIS area with the kernel that contains the hardware product subsets. For example:

>>> boot -flag fa boot_device

In the previous example:

The -flag fa defines boot flags f for a hardware product kit and a for multiuser mode.

The boot_device represents the console network boot device name. The device name depends on the processor type, but it usually is ewa0. Use the show dev command at the console mode prompt to determine the boot device for your processor.

The boot procedure installs the kernel from the RIS area and then performs a Full Installation by loading the operating system subsets and the subsets from the hardware product kit.

For more information about RIS, see the guide to Sharing Software on a Local Area Network. For more information about booting a system over the network, see the Installation Guide.