This document also appears in the SCO online documentation. See ``UDI 1.01 Feature Supplement New Features'', under UnixWare 7 Features in the scohelp(X1) online documentation, for a list of all the documents delivered with the UDI 1.01 Feature Supplement. Note that this version of the document you are reading contains links into the SCO online documentation (like the two above in this paragraph) that will not work outside of the scohelp environment.
The Uniform Driver Interface (UDI) is an operating system-neutral device driver standard. It defines a relatively autonomous, low-level I/O subsystem that completely surrounds conforming device driver modules, providing them with a consistent interface to and from the host operating system and among cooperating device drivers.
A device driver is a collection of routines that associate the generic I/O functionality provided by an operating system with specific I/O hardware. The writing of device drivers accounts for a large portion of the engineering effort needed to create or port an operating system or I/O card product to a new platform or interconnect. When an I/O card is designed for a common interconnect such as PCI, new or modified device drivers may be required for each platform operating system combination. This can multiply by manyfold the time and expense of developing and supporting a device. Standard, open, driver-interface definitions are a key ingredient in leveraging third-party driver development.
The UDI specification allows a single device driver to support an I/O card across the platforms and operating systems appropriate for its interconnect. The goal is to accelerate the availability, and lower the costs, of I/O solutions, increasing the competitiveness of supporting systems.
Great care has been taken to isolate drivers from the impedance matching required for an I/O card to perform well on a given operating system or platform. The driver is always invoked by procedure calls and interacts with the embedding operating system and hardware via environment calls, providing the driver with full isolation from the details of its environment while retaining sufficient flexibility and performance in the operating system.
The UDI specification is intended to provide the following benefits and features to IHVs and operating system vendors:
UDI is provided in a single set, udifs, with four packages:
Use the
pkgadd(1M)
command to install either the whole set or the individual packages:
pkgadd -d device_name package_name
where device_name is the name of the file or directory containing the set or package image and package_name is either omitted or is one (or more) of the UDI packages.
To perform a default installation of the entire UDI Feature Supplement:
ptf7430g.txt installation instructions ptf7430g.Z compressed archive of ptf7430 version g
New versions of ptf7430, as they are released, will use successive ASCII characters as the version designator (e.g., ptf7430h, ptf7430i, etc.).
zcat /var/spool/pkg/udifs.1.0.pkg.Z | pkgadd -d -
The installation scripts will install all the packages by default, or you can select the packages you want to install from a menu.
/usr/man/bin/config_search -f
This command updates the SCOhelp search engine's index files to include the documents installed by this supplement.
You can also install individual packages from the udifs.1.0.pkg image. For example, to install the udidk package only from the above data stream (located in /var/spool/pkg):
zcat /var/spool/pkg/udifs.1.0.pkg.Z | pkgadd -d - udidk
Upon installing the udienv and udidk packages, you can proceed to the section ``Building and using sample drivers'' to build and use the sample drivers on your system.
If you installed the udisid package, you can also follow the directions found under ``ISL of the UnixWare 7 operating system using a UDI SCSI driver'' to use the sample SCSI HBA driver to install the operating system on your machine.
If you installed the udidoc package, see ``UDI 1.01 Feature Supplement New Features'', under UnixWare 7 Features in the scohelp(X1) online documentation for a list of the documents delivered with the UDI 1.01 Feature Supplement, including: the document you are reading now, the UDI Specifications, UDI manual pages, a UDI Driver Writer's Guide, and more.
The udidk package also installs an ASCII copy of the document you are reading now in the directory /usr/src/hdk/udi.
Use the
pkgrm(1M)
command (as root)
to remove either the whole UDI set or the individual packages:
pkgrm name
where name is either udifs (to remove the entire set) or one (or more) of the individual UDI packages (see ``Installing UDI'' for a list of packages).
To remove the entire UDI supplement:
pkgrm udifs
The UDI 1.01 Feature Supplement:
The source code of the udi_cmos, pseudod, and shrkudi drivers is explained in the UDI Driver Writer's Guide.
Please be aware of the following limitations of the UDI Feature Supplement Development Kit:
Although it is allowed in the specification, support for removing the whitespace at the beginning of a continued line is not yet provided. Currently, any whitespace at the beginning of a continued line will not be removed.
For UDI NIC drivers, the length of attr_name, in custom declarations, is limited to 13 characters.
Also observe these limitations of the udi_dpt SCSI HBA sample driver:
These problems will be fixed in the next version of the driver.
As with any new technology, it is expected that continuing improvements will be made and supplied to the UDI user community. Users downloading the UDI feature supplement and measuring UDI performance are encouraged to report their performance measurements to udidk@sco.com.
Note the following changes to the UDI Core Specification that were too late to be included in the UDI 1.01 Feature Supplement:
| As distributed | After editing |
|---|---|
/*
* Ops vector initialization structure
*/
typedef void udi_op_t(void);
typedef udi_op_t * const udi_ops_vector_t;
typedef const struct {
udi_index_t ops_idx;
udi_index_t meta_idx;
udi_index_t meta_ops_num;
udi_size_t chan_context_size;
udi_ops_vector_t *ops_vector;
udi_ubit8_t *op_flags;
} udi_ops_init_t;
|
typedef void udi_op_t(void);
typedef udi_op_t * const udi_ops_vector_t;
typedef const struct {
udi_index_t ops_idx;
udi_index_t meta_idx;
udi_index_t meta_ops_num;
udi_size_t chan_context_size;
udi_ops_vector_t *ops_vector;
const udi_ubit8_t *op_flags;
} udi_ops_init_t;
|
/*
* Primary region initialization structure
*/
typedef const struct {
udi_mgmt_ops_t *mgmt_ops;
udi_ubit8_t *mgmt_op_flags;
udi_size_t mgmt_scratch_requirement;
udi_ubit8_t enumeration_attr_list_length;
udi_size_t rdata_size;
udi_size_t child_data_size;
udi_ubit8_t per_parent_paths;
} udi_primary_init_t;
|
/*
* Primary region initialization structure
*/
typedef const struct {
udi_mgmt_ops_t *mgmt_ops;
const udi_ubit8_t *mgmt_op_flags;
udi_size_t mgmt_scratch_requirement;
udi_ubit8_t enumeration_attr_list_length;
udi_size_t rdata_size;
udi_size_t child_data_size;
udi_ubit8_t per_parent_paths;
} udi_primary_init_t;
|
This Feature Supplement of UDI includes headers and samples of the udi_cmos driver, udi_dpt driver, shrkudi driver, and the GIO pseudodriver called pseudod. Following are instructions for building and using each driver.
See the UDI Driver Writer's Guide for more information on the sample drivers.
To compile and test the udi_cmos sample source code driver, do the following as root:
Notice that the first 2 bytes of output (which represent the seconds increment of the realtime clock) change between invocations.
When you have finished using the udi_cmos driver, remove it by entering:
pkgrm udi-cmos
This helps prevent resmgr(1M) resource conflicts after subsequent kernel reboots.
To compile and use the UDI SCSI (udi_dpt) sample driver, do the following as root:
If an entry for "udi_dpt" does not exist:
See ``Supported DPT controllers'' for a listing of DPT controllers supported by the udi_dpt driver.
and reboot the system.
or (if you have filesystems created on one of the devices),
mount -F vxfs /dev/dsk/c1b0t0d0s1 /mnt
ls -l /mnt
The following DPT controllers are supported by the udi_dpt driver:
For developers of UDI on SCO operating systems, DPT has made limited quantities of these products available at reduced pricing. Please refer to /usr/src/hdk/udi/driver/udi_dpt/README for DPT's contact information as well as information regarding the Technical Partner Program and the SCO UDI Developer Program.
To use the shrkudi sample source code driver, do the following as root:
Please refer to /usr/src/hdk/udi/driver/shrkudi/README for Osicom's contact information, as well as a link to related technical information.
To compile and test the pseudod driver, do the following as root:
modadmin -l pseudod
dd if=/dev/pseudod0 bs=50 count=1
Notice that the output contains a sequence of numbers which is incremented during each read from /dev/pseudod.
If you reboot your system or if your system crashes, it will be necessary to redo the above procedure starting at Step 3.
To remove a UDI driver which has previously been installed with udisetup, enter the following command as root:
pkgrm namewhere name is the static property shortname for the driver, and all underscore characters are replaced with dashes. For example, to remove the udi_dpt driver, enter the following command:
pkgrm udi-dpt
The floppy image udisid.img file is available to do an ISL (initial system load) of the UnixWare 7 operating system via a UDI SCSI driver. This requires that the udisid package of the udifs set be installed, which will place the udisid.img in the /usr/src/hdk/udi directory.
The udisid.img file is a filesystem image which loads the UDI SCSI drivers during the ISL of the operating system.
To do an initial system load of the UnixWare 7 operating system using a UDI SCSI driver, you will need two floppy disks in addition to the boot and HBA disks provided with UnixWare 7:
This procedure tells you how to create the floppies you need and use them during ISL of UnixWare 7.
dd bs=36k if=udisid.img of=/dev/dsk/f03ht
Label the floppy "UDI Supplement Diskette (v1.0)".
dosformat /dev/rdsk/f03ht
mount -F dosfs /dev/dsk/f03ht /mnt
mkdir /mnt/udi-dist.1
umount /mnt
You must now insert the SID diskette labeled UDI Supplement Diskette (v1.0)
The UDI build and runtime environments provide build tools and utilities to create driver binaries (the udibuild utility) and to create driver source and/or binary installation packages (the udimkpkg utility). The runtime environment consists of the tools necessary to install (the udisetup) driver packages, as well as the software modules necessary to configure and execute UDI drivers.
This Feature Supplement includes a utility called udibuild which builds driver modules from source files according to the build rules set in the udiprops.txt static properties file. This command is typically run from a source file directory, or run by udisetup to build a source distributed driver.
For syntax and usage information, see udibuild(1).
The udimkpkg utility is included in the UDI build environment of this Feature Supplement. udimkpkg uses the static driver properties file udiprops.txt to find various pieces of a UDI driver or library component and gathers them into a UDI package directory structure ready for distribution or installation. This command is run from the directory in which the source files are kept. It parses the udiprops.txt file contained in that directory and creates UDI packaging in directory format in a new directory, udi-pkg.1, also in the current directory.
Depending on what user id is used when udimkpkg was run to create the UDI driver, warning messages like these may be displayed while using udisetup to install the package:
UX: cpio: WARNING: Cannot get passwd information for someuser UX: cpio: WARNING: udi-pkg.1/drv/alt/comp: owner not changed UX: cpio: WARNING: Cannot get group information for someuser UX: cpio: WARNING: udi-pkg.1/drv/alt/comp: group not changed
To avoid this problem from showing up during udisetup, it is suggested (but not mandatory) that you run udimkpkg as root for the final packaging of the UDI driver during development.
For further syntax and usage information, see udimkpkg(1).
The udisetup utility installs a udimkpkg-packaged driver on its intended target system. This utility extracts driver files from the UDI package file, installs them in environment-specific locations, and prepares the driver for use on the target system.
For syntax and usage, see udisetup(1M).
The udibuild, udisetup, and udimkpkg commands can use the following environment variables to override certain command defaults:
Project UDI maintains a public web page at http://www.project-udi.org where you will find the latest UDI Development Kit, introductory materials, the official UDI specification documents, list of participants, and other information relevant to UDI.
For the latest UnixWare 7 UDI 1.01 Feature Supplement release notes, warnings, caveats, and limitations discovered too late to be included in the document you are reading now, see the Late News link at the UnixWare 7 Doc Web Site.
Conditions
1. THE SANTA CRUZ OPERATION ("SCO") MAKES THE INITIAL VERSION AVAILABLE TO YOU STRICTLY ON AN "AS IS" BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, WITHOUT LIMITATION, WARRANTIES THAT THE INITIAL VERSION IS FREE OF DEFECTS, MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE OR NON-INFRINGING. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE INITIAL VERSION IS WITH YOU. SHOULD ANY PART OF THE INITIAL VERSION PROVE DEFECTIVE IN ANY RESPECT, YOU ASSUME THE ENTIRE BURDEN AND COST OF ANY APPLICABLE SERVICING, REPAIR OR CORRECTION.
2. UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY, WHETHER TORT (INCLUDING NEGLIGENCE), CONTRACT, OR OTHERWISE, SHALL SCO OR ITS SUPPLIERS BE LIABLE TO YOU OR ANY OTHER PERSON FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, OR ANY AND ALL OTHER COMMERCIAL DAMAGES OR LOSSES, EVEN IF SCO OR ANY OF ITS SUPPLIERS HAVE BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGES.
3. Neither SCO nor its suppliers shall provide you with any support for the Initial Version.
4. If and when SCO decides, in its sole business judgment, to make any subsequent version of the UDI Developer kit available, either alone or together with any associated software in source and/or binary form (collectively "Subsequent Version") in any medium including but not limited to any electronic medium, the conditions under which you may access and use such Subsequent Version may differ in material respects from the above conditions (1) - (3) applicable to the Initial Version.
(r) Copyright 2000, The Santa Cruz Operation, Inc.