Application Packaging Developer's Guide

Installing a Driver Using the sed Class and Procedure Scripts

This case study describes how to install a driver using the sed class and procedure scripts. It is also different from the previous case study (see "Installing and Removing a Driver With Procedure Scripts") because this package is made up of both absolute and relocatable objects.

Techniques

This case study demonstrates the following techniques:

Approach

Case Study Files

The pkginfo File

PKG=SUNWsst
NAME=Simple SCSI Target Driver
VERSION=1
CATEGORY=system
ARCH=sparc
VENDOR=Sun Microsystems
BASEDIR=/opt
CLASSES=sed

The prototype File

For example, this case study uses the hierarchical layout of the package objects shown in Figure 5-1.

Figure 5-1 Hierarchical Package Directory Structure

Graphic

The package objects are installed in the same places as they are in the pkg directory above. The driver modules (sst and sst.conf) are installed into /usr/kernel/drv and the include file is installed into /usr/include/sys/scsi/targets. The sst, sst.conf, and sst_def.h files are absolute objects. The test program, sstest.c, and its directory SUNWsst are relocatable; their installation location is set by the BASEDIR parameter.

The remaining components of the package (all the control files) go in the top directory of the package on the development machine, except the sed class script. This is called devlink.tab after the file it modifies, and goes into etc, the directory containing the real devlink.tab file.

From the pkg directory, run the pkgproto command as follows:


find usr SUNWsst -print | pkgproto > prototype

The output from the above command looks like this:

d none usr 0775 pms mts
d none usr/include 0775 pms mts
d none usr/include/sys 0775 pms mts
d none usr/include/sys/scsi 0775 pms mts
d none usr/include/sys/scsi/targets 0775 pms mts
f none usr/include/sys/scsi/targets/sst_def.h 0444 pms mts
d none usr/kernel 0775 pms mts
d none usr/kernel/drv 0775 pms mts
f none usr/kernel/drv/sst 0664 pms mts
f none usr/kernel/drv/sst.conf 0444 pms mts
d none SUNWsst 0775 pms mts
f none SUNWsst/sstest.c 0664 pms mts

This prototype file is not yet complete. To complete this file, you need to make the following modifications:

This is the final prototype file:

i pkginfo
i postinstall
i preremove
i copyright
e sed /etc/devlink.tab ? ? ?
f none /usr/include/sys/scsi/targets/sst_def.h 0644 bin bin
f none /usr/kernel/drv/sst 0755 root sys
f none /usr/kernel/drv/sst.conf 0644 root sys
d none SUNWsst 0775 root sys
f none SUNWsst/sstest.c 0664 root sys

The questions marks in the entry for the sed script indicate that the access permissions and ownership of the existing file on the installation machine should not be changed.

The sed Class Action Script (/etc/devlink.tab)

In the driver example, a sed class script is used to add an entry for the driver to the file /etc/devlink.tab. This file is used by the devlinks command to create symbolic links from /dev into /devices. This is the sed script:

# sed class script to modify /etc/devlink.tab
!install
/name=sst;/d
$i\
type=ddi_pseudo;name=sst;minor=character	rsst\\A1

!remove
/name=sst;/d

The pkgrm command does not run the removal part of the script. You may need to add a line to the preremove script to run sed directly to remove the entry from /etc/devlink.tab.

The postinstall Installation Script

In this example, all the script needs to do is run the add_drv command.

# Postinstallation script for SUNWsst
# This does not apply to a client.
if [$PKG_INSTALL_ROOT = "/" -o -z $PKG_INSTALL_ROOT]; then
   SAVEBASE=$BASEDIR
   BASEDIR=""; export BASEDIR
   /usr/sbin/add_drv sst
   STATUS=$?
   BASEDIR=$SAVEBASE; export BASEDIR
   if [ $STATUS -eq 0 ]
   then
	     exit 20
   else
	     exit 2
   fi
else
   echo "This cannot be installed onto a client."
   exit 2
fi

Note -

This example will probably not work correctly if you install it onto a diskless client from a server, since there is no reliable way to run the add_drv and rem_drv commands on that client from the pkgadd command executing on the server. You may be better off splitting the package on the root (/) and /usr boundaries.


The add_drv command uses the BASEDIR parameter, so the script has to unset BASEDIR before running the command, and restore it afterwards.

One of the actions of the add_drv command is to run devlinks, which uses the entry placed in /etc/devlink.tab by the sed class script to create the /dev entries for the driver.

The exit code from the postinstall script is significant. The exit code 20 tells the pkgadd command to tell the user to reboot the system (necessary after installing a driver), and the exit code 2 tells the pkgadd command to tell the user that the installation partially failed.

The preremove Removal Script

In the case of this driver example, it removes the links in /dev and runs the rem_drv command on the driver.

# Pre removal script for the sst driver
echo "Removing /dev entries"
/usr/bin/rm -f /dev/rsst*

echo "Deinstalling driver from the kernel"
SAVEBASE=$BASEDIR
BASEDIR=""; export BASEDIR
/usr/sbin/rem_drv sst
BASEDIR=$SAVEBASE; export BASEDIR

exit 

The script removes the /dev entries itself; the /devices entries are removed by the rem_drv command.

The copyright File

This is a simple ASCII file containing the text of a copyright notice. The notice is displayed at the beginning of package installation exactly as it appears in the file.


	Copyright (c) 1998 Drivers-R-Us, Inc.
	10 Device Drive, Thebus, IO 80586

All rights reserved. This product and related documentation is
protected by copyright and distributed under licenses 
restricting its use, copying, distribution and decompilation. 
No part of this product or related documentation may be 
reproduced in any form by any means without prior written 
authorization of Drivers-R-Us and its licensors, if any.