Writing a Hardware Configuration File

If the device is non-self-identifying, the kernel requires a hardware configuration file for it. If the driver is called xx, the hardware configuration file for it should be called xx.conf. See the driver.conf(4), pseudo(4), sbus(4), scsi(4), and update_drv(1M) man pages for more information on hardware configuration files. On the Intel platform, device information is now supplied by the booting system. Hardware configuration files should no longer be needed, even for non-self-identifying devices.

Arbitrary properties can be defined in hardware configuration files by adding entries of the form property=value, where property is the property name, and value is its initial value. This enables devices to be configured by changing the property values.

Installing, Updating, and Removing Drivers

Before a driver can be used, the system must be informed that it exists. The add_drv(1M) utility must be used to correctly install the device driver. After the driver is installed, it can be loaded and unloaded from memory without using add_drv(1M) again.

Copying the Driver to a Module Directory

A device driver's module path (location) depends on the platform it runs on, the architecture it is compiled for, and whether it is needed at boot time. Platform-dependent device drivers reside in the following locations:

• /platform/`uname -i`/kernel/drv - Contains 32-bit drivers that run only on a specific platform (/platform/`uname -i`/kernel/drv/sparcv9 for 64-bit drivers).

• /platform/`uname -m`/kernel/drv - Contains 32-bit drivers that run on a family of platforms. This directory might not be present on some platforms (/platform/`uname -m`/kernel/drv/sparcv9 for 64-bit drivers).

Platform-independent drivers reside in either of these directories:

• /usr/kernel/drv - Contains 32-bit drivers not required for system booting (/usr/kernel/drv/sparcv9 for 64-bit drivers).

• /kernel/drv - Contains 32-bit drivers required for booting (/kernel/drv/sparcv9 for 64-bit drivers).

To install a 32-bit driver, the driver and its configuration file must be copied to a drv directory in the module path. For example, to copy a driver to /usr/kernel/drv, type:

$ su
# cp xx /usr/kernel/drv
# cp xx.conf /usr/kernel/drv

To install a 64-bit SPARC driver, copy the driver to a drv/sparcv9 directory in the module path. Copy the driver configuration file to the drv directory in the module path. For example, to copy a driver to /usr/kernel/drv, type:

$ su
# cp xx /usr/kernel/drv/sparcv9# cp xx.conf /usr/kernel/drv

Note - All driver configuration files (.conf files) must go in the drv directory in the module path. Even on 64-bit systems, the .conf file goes in the drv directory, not the drv/sparcv9 directory.

Installing Drivers with add_drv()

Run add_drv(1M) to install the driver in the system. If the driver installs successfully, add_drv(1M) will run devfsadm(1M) to create the logical names in /dev.

# add_drv xx

This is a simple case in which the device identifies itself as xx and the device special files will have default ownership and permissions (0600 root sys). add_drv(1M) also allows additional names for the device (aliases) to be specified. See add_drv(1M) to determine how to add aliases and set file permissions explicitly.

Note - add_drv(1M) should not be run when installing a STREAMS module. See the STREAMS Programming Guide for details.

If the driver creates minor nodes that do not represent disks, tapes, or ports (terminal devices), /etc/devlink.tab can be modified to cause devfsadm(1M) to create logical device names in /dev.

Alternatively, logical names can be created by a program run at driver installation time.

Updating Driver Information

Use the update_drv(1M) command to notify the system of any changes to an installed device driver. By default, the system re-reads the driver.conf(4) file and reloads the driver binary module.

Removing the Driver

To remove a driver from the system, use rem_drv(1M), then delete the driver module and configuration file from the module path. The driver cannot be used again until it is reinstalled with add_drv(1M). Removing a SCSI HBA driver will require a reboot to take effect.

Loading and Unloading Drivers

Opening a special file associated with the device driver causes the driver to be loaded. modload(1M) can also be used to load the driver into memory, but it does not call any routines in the module. Opening the device is the preferred method.

Normally, the system automatically unloads device drivers when they are no longer in use. During development, it might be necessary to use modunload(1M) to unload the driver explicitly. In order for modunload(1M) to be successful, the device driver must be inactive; there must be no outstanding references to the device, such as through open(2) or mmap(2).

modunload takes a runtime-dependentmodule_id as an argument. The module_id can be found by using grep to search the output of modinfo for the driver name in question and looking at the first column.

# modunload -i module_id

To unload all currently unloadable modules, specify module ID zero:

# modunload -i 0

In addition to being inactive, the driver must have working detach(9E) and _fini(9E) routines for modunload(1M) to succeed.

Driver Packaging

The normal delivery vehicle for software is to create a package with all the components of the software packaged together. A package provides a controlled mechanism for installation and removal of all the components of a software product. In addition to the files for using the product, the package includes control files for installing (and de-installing) the application. The postinstall and preremove installation scripts are two such control files.

Package Postinstall

After installing a package that includes a driver binary onto a system, the add_drv(1M) command must be run to complete the installation of the driver. Typically, add_drv is run a postinstall script as in the following example.

#!/bin/sh
#
#       @(#)postinstall 1.1

PATH="/usr/bin:/usr/sbin:${PATH}"
export PATH

#
# Driver info
#
DRV=<driver-name>
DRVALIAS="<company-name>,<driver-name>"
DRVPERM='* 0666 root sys'

ADD_DRV=/usr/sbin/add_drv

#
# Select the correct add_drv options to execute.
# add_drv touches /reconfigure to cause the
# next boot to be a reconfigure boot.
#
if [ "${BASEDIR}" = "/" ]; then
        #
        # On a running system, modify the
        # system files and attach the driver
        #
        ADD_DRV_FLAGS=""
else     
        #
        # On a client, modify the system files
        # relative to BASEDIR
        #
        ADD_DRV_FLAGS="-b ${BASEDIR}"
fi       
 
#
# Make sure add_drv has not been previously executed
# before attempting to add the driver.
#
grep "^${DRV} " $BASEDIR/etc/name_to_major > /dev/null 2>&1
if [ $? -ne 0 ]; then
        ${ADD_DRV} ${ADD_DRV_FLAGS} -m "${DRVPERM}" -i "${DRVALIAS}" ${DRV}
        if [ $? -ne 0 ]; then
                echo "postinstall: add_drv $DRV failed\n" >&2
                exit 1
        fi
fi
exit 0