UnixWare/OpenServer Hardware Developers Kit (HDK) Release Notes

This is Release 7.1 of the UnixWare/OpenServer Hardware Developers Kit (HDK). It includes documentation, code samples, and test suites for developing drivers for UnixWare 7 and OpenServer. Note that the actual driver interfaces and standard utilities used for driver development are included in the standard operating system products.

These release notes contain:

We welcome your comments and suggestions. Please write to us at hdkinfo@sco.com.

These notes will be supplemented with additional information that will be published at the Hardware Developer Services Page (http://www.caldera.com/developers/ihv.htm) as it becomes available.

See also the Late News in the Product Documentation, which contains the latest information about known limitations on the UnixWare 7 platform, including the HDK.

What's new in this HDK release

The following components are new or updated in this HDK release:

See individual package descriptions for details.

Descriptions of individual packages are available from the Driver Development Web Site and on the HDK distribution media. To mount the CD and read the pre-installation information for HDK packages:

  1. Log in as root.
  2. Insert the CD-ROM in the drive.
  3. Create a cdrom directory if it does not already exist:
    mkdir  /cdrom
  4. Mount the CD-ROM by typing:
  5. Run your web browser (for example, Netscape Communicator), select Open File from the File menu, and enter:
    /cdrom/info/readme.htm

Note that the CD must be mounted before you start the browser in order to access this file.

Product set contents

The UnixWare/OpenServer Hardware Developers Kit (HDK) product media consists of one CD-ROM ``set'', which installs all packages on the appropriate platform, as well individual packages for UnixWare7 and OpenServer platforms. For more information about set installation, see: The HDK contains these packages:

Package Description Host Platforms
HDKdoc UnixWare Hardware Developer Documentation UnixWare 7
HDKman Hardware Developer Manual Pages dual platform
O5hbacert OpenServer HBA Testsuite OpenServer
O5hbacert OpenServer HBA Testsuite OpenServer
O5hcptest Hardware Compatibility Program Tests OpenServer
O5ndsampl OpenServer NIC Driver Samples OpenServer
O5ndtests OpenServer NIC Driver Testsuite OpenServer
O5xlinkit OpenServer 5 NFB Graphics Driver Development Kit OpenServer
ddi8samp Sample DDI8 Driver UnixWare 7
hbacert HBA Certification Tests UnixWare 7
hbasample Sample HBA Drivers UnixWare 7
hpcdsamp Sample HPCD Driver UnixWare 7
i2oSample I2O Sample Source and Headers UnixWare 7
loadtests UnixWare System Load Tests UnixWare 7
ndsample Sample MDI Network Drivers UnixWare 7
ndtests Network Driver Test Suite UnixWare 7
psk Platform Support Development Kit UnixWare 7
xlinkkit NFB Graphics Driver Development Kit UnixWare 7
xtests X11 Graphics Tests for UnixWare 7 and OpenServer 5 dual platform

Documentation

The HDK documentation is available from:

To access the HDK documentation from any of these sources, select Hardware and Driver Development from the list of topics.

Preparing for installation

HDK 7.1 installs on the following platforms:

Some UnixWare 7 HDK packages require that some packages from the UDK be installed on UnixWare 7 before installing the HDK. See the information for each package for detailed requirements.

Installing the HDK

To install the HDK software:
  1. Insert the HDK CD in the CD drive.
  2. On OpenServer systems, run custom(ADM), select Install new, and follow the instructions to install the O5patch that is required.
  3. Issue the pkgadd(1M) command, specifying the CD driver where the CD is loaded:
  4. The contents of the set for the platform (either UnixWare 7 or OpenServer) will be displayed. Select the packages to be installed and follow the instructions on the screen to complete the installation.

Most packages from either set will install on the alternate platform with the pkgadd command issued to the mounted CD:

pkgadd  -d  /cdrom

Follow the instructions to install the package(s) you want.

Compatibility Notes

Change to sc_time in Release 7.1.1

The definition of the sc_time member of the scb(D4sdi) structure will change in UnixWare 7 Release 7.1.1 so that it is in seconds; previous releases of UnixWare 7 (including Release 7.1.0) defined this value in milliseconds.

We don't believe that this affects any of our customers in a negative way but we felt that we should make this decision known to our development partners.

First, some background. SCSI command timeouts in SDI were originally only supported on those pieces of HA hardware that supported an on-board watchdog timer for a command. There was no concept of the HBA driver itself managing timeouts thru some watchdog routine in the driver. At this stage, HBA drivers treated the value contained in the sc_time member of the scb structure as being in units of milliseconds. All of the target drivers in the system consistently supplied timeout values in milliseconds.

For UnixWare 7 Release 7.0.0, variable command timeouts were implemented in the disk target driver (sd01). This is the ability to have different timeout values for different commands based on a table contained in a flat file in /etc/scsi. At the same time, software based timeouts were implemented in our sample HBA driver using a watchdog timer. The developers implementing this feature chose to use units of seconds for sc_time instead of milliseconds. This resulted in disk timeouts working just fine. Unfortunately, this choice broke timeouts for all other target devices because the rest of the target drivers still supplied millisecond values for sc_time.

Since the reference implementation in the sample HBA driver was now broken with respect to all targets except disk targets, any IHV who followed the sample driver also had the same problem.

In addition, any pass-through application was broken at this point as well. Using pass-through is just like using a target driver in that the pass-through application also supplies a value in sc_time for the HBA drivers. The manual page for scb(D4sdi) says the units of sc_time are milliseconds. So pass-through applications that rigorously followed the manual pages were coding in milliseconds as well.

At this stage the net result was that disk timeouts worked fine but there was no hope in ever timing out a command on a tape or CDROM if that command came from the normal I/O path or on any device if the command came to the HBA via passthrough.

We have decided to try and make the best of this confused state of affairs by changing the definition of sc_time to seconds uniformly throughout SDI, both kernel and commands, as well as in all documentation. This change will take place in UnixWare 7 Release 7.1.1. We have updated the scb(D4sdi) manual page in this version of the HDK to match the sc_time definition used in Release 7.1.1.

We have surveyed all HBA drivers that are known to us and only found one example where a driver was treating sc_time in milliseconds instead of seconds; we have already updated that IHV. It is our belief that every other HBA driver treats this value as being in seconds.

All HBA drivers that claim to support timeouts have been re-tested for Release 7.1.1 to make sure that everything is working as planned and documented.