Index of /download/400-000-020DL

[ICO]NameLast modifiedSize

[PARENTDIR]Parent Directory   -
[TXT]udiinstall.html 2001-01-04 13:49 892
[   ]udifs.1.0.pkg.Z 2001-01-02 13:36 4.9M

UDI Overview and Configuration

UDI Overview and Configuration

This document describes the features of the UDI 1.01 Feature Supplement, it's installation, use, and configuration:

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.

UDI Overview

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.

Benefits of UDI

The UDI specification is intended to provide the following benefits and features to IHVs and operating system vendors:

Installing UDI

UDI is provided in a single set, udifs, with four packages:


udienv
contains core functionality and utilities to support UDI on the runtime system

udidk
contains the UDI development kit

udidoc
contains the documentation for the UDI feature supplement

udisid
contains an image for the UDI SID Floppy, required for doing an installation of UnixWare 7 on a UDI-supported HBA device

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:

  1. Login as root.
  2. Install ptf7430 (version ``g'' or later) before attempting to install the UDI 1.01 Feature Supplement. You can get the latest version of ptf7430 from the SCO FTP Download Site at: ftp://ftp.sco.com/SLS. For example, version ``g'' of ptf7430 consists of two files in this directory:
       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.).

  3. Copy the udifs.1.0.pkg.Z compressed data steam from the SCO or Project UDI web sites to /var/spool/pkg, or some other directory on your local machine; you can use any directory that has at least 6MB of free space [use df(1M) to determine the amount of free space on a file system].
  4. Install the data stream by entering:
       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.

  5. Reboot the system after installing all desired packages.
  6. If you installed the udidoc package, enter:
       /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.


NOTE: Although it is not required during package installation, the uccs (UDK Optimizing C Compilation System) package must be installed (either before or after UDI) in order to use the udibuild(1) command (part of udidk), or to use the udisetup(1M) command (part of udienv) to install a source packaged UDI driver. Other uses of udisetup, such as installing a binary packaged UDI driver, do not require the uccs package.

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.

Removing 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).


NOTE: Before removing the UDI supplement, you should first remove any UDI drivers you may have previously installed; see ``Removing UDI drivers'' for instructions.

To remove the entire UDI supplement:

  1. Login as root.
  2. Enter:
       pkgrm udifs
    
  3. Reboot your system.

Contents of the UDI supplement

The UDI 1.01 Feature Supplement:

UDI limitations

Please be aware of the following limitations of the UDI Feature Supplement Development Kit:


laptops
The UDI 1.01 Feature Supplement was not tested on laptop computers.

static properties
Custom declarations accepts only a device argument of ``0'', meaning that these declarations apply to all types.

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.


generic I/O metalanguage
Enumeration attributes: gio_privileged_ops and gio_destructive_ops will be supported in a future version that provides user-level ABI bindings to the GIO interface. See Enumeration Attributes in the UDI Core Specification.

management metalanguage
Multiple parents on the Management Agent channel are not supported.

interrupt regions
Interrupt regions are not fully supported. See Extensions to Driver Properties in the UDI Physical I/O Specification and udi_intr_attach_req(3udi).

SCSI sample driver and SCSI mapper
It is not possible for the UDI driver to control one instance of an HBA while a DDI (UnixWare Device Driver Interface) driver controls another instance of the same HBA.

Also observe these limitations of the udi_dpt SCSI HBA sample driver:

These problems will be fixed in the next version of the driver.


NIC sample driver
The Osicom 2300 is the only card supported. Full duplex operation, imperfect (> 16 address) multicast filtering, and expedited delivery are not implemented. Tracing and logging are only partially implemented.

performance
Performance of UDI drivers under the UnixWare UDI Feature Supplement has been measured for the sample DPT driver as well as some third-party Network drivers. In all cases, throughput is comparable with drivers written to the UnixWare Device Driver Interface (DDI). However, testing has been limited to only a small sample of configurations, typically UP and 2 or 4 CPU MP systems. In addition, under heavy load, throughput of UDI Network drivers may degrade.

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.


Non-Stop Clusters (NSC) and UDI
The UDI Feature Supplement can be installed on systems running UnixWare 7.1.1b NSC. Testing of UDI on NSC, however, has been limited to developer-level testing and is not recommended at this time for production use.

MEI services
For custom metalanguages, udi_mei_enumerate_rank is not supported and udi_mei_driver_error(3udi) is implemented as a no-op.

Late Changes to the UDI 1.01 Specifications

Note the following changes to the UDI Core Specification that were too late to be included in the UDI 1.01 Feature Supplement:

Building and using sample drivers

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.

udi_cmos driver

To compile and test the udi_cmos sample source code driver, do the following as root:

  1. Run udibuild(1) and udimkpkg(1) in the same directory as the driver's source.
  2. Run the udisetup(1M) command to install the driver.
  3. Run the addcmos shell script to add the udi_cmos driver entry in the resmgr(1M) database.
  4. Load the driver into the kernel with the following command:

    modadmin -l udi_cmos

  5. To exercise the driver, enter the following command:

    hd /dev/udi_cmos0

    Notice that the first 2 bytes of output (which represent the seconds increment of the realtime clock) change between invocations.

If you reboot your system or your system crashes, it will be necessary to redo steps 3 and 4.

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.

udi_dpt driver

To compile and use the UDI SCSI (udi_dpt) sample driver, do the following as root:

  1. Run udibuild(1) and udimkpkg(1) in the same directory as the driver's source.
  2. Run the udisetup(1M) command to install the driver.
  3. Enter the following command to bind the driver to the hardware:

    dcu -S

  4. Enter the following command to make sure that a "udi_dpt" entry exists in the resmgr database:

    resmgr | grep udi_dpt

    If an entry for "udi_dpt" does not exist:

  5. Load the udi_dpt driver into the kernel using the following command:

    modadmin -l udi_dpt

To list the devices found on the system, run the sdiconfig -l command. You can now use any command to read/write/mount the devices attached to the DPT controller. For example,

dd if=/dev/rdsk/c1b0t0d0s0 of=/dev/null count=5000

or (if you have filesystems created on one of the devices),

mount -F vxfs /dev/dsk/c1b0t0d0s1 /mnt
ls -l /mnt


NOTE: The device node name (/dev/dsk/c1b0t0d0s0) shown above is an example and may differ on your system depending upon the controller number assigned to your DPT controller by the system and the SCSI target ID of the devices. See disk(7) for more information on device node naming conventions.

Supported DPT controllers

The following DPT controllers are supported by the udi_dpt driver:

Please refer to www.dpt.com for more information on these supported controllers.

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.

shrkudi driver

To use the shrkudi sample source code driver, do the following as root:

  1. Shut down the machine, insert the Osicom 2300 adapter into the system, and boot the machine.
  2. Make sure that the PCI Osicom 2300 NIC (with PCI board ID 0x10110009) is installed on your system. To check for the existence of the NIC controller, enter the following command:

    resmgr | grep 0x10110009

  3. Run udibuild(1) and udimkpkg(1) in the same directory as the driver's source.
  4. Run the udisetup(1M) command to install the driver.
  5. Run netcfg(1M) to access the Network Configuration Manager, and select the shrkudi Network Driver (the adapter should be autodetected by netcfg).

Please refer to /usr/src/hdk/udi/driver/shrkudi/README for Osicom's contact information, as well as a link to related technical information.

pseudod driver

To compile and test the pseudod driver, do the following as root:

  1. Read the udiprops.txt file and supply a #device declaration to match your system. See ``Device Declarations'' in the UDI Driver Writer's Guide for more on this file and device declarations.
  2. Run udibuild(1) and udimkpkg(1) in the same directory as the driver's source.
  3. Run the udisetup(1M) command to install the driver.
  4. Load the driver into the kernel with the following command:
       modadmin -l pseudod
    
  5. To exercise the driver, enter the following command:
       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.

Removing UDI drivers

To remove a UDI driver which has previously been installed with udisetup, enter the following command as root:

   pkgrm name
where 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

ISL of the UnixWare 7 operating system using a UDI SCSI driver

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.

  1. Create a floppy containing the udisid.img image by issuing the following command:
       dd bs=36k if=udisid.img of=/dev/dsk/f03ht
    

    Label the floppy "UDI Supplement Diskette (v1.0)".

  2. Create a floppy containing the UDI drivers you need following these steps:
    1. Insert a new floppy disk into the drive and create a dosfs file system on it:
         dosformat /dev/rdsk/f03ht
      
    2. Mount the floppy in a temporary directory:
         mount -F dosfs /dev/dsk/f03ht /mnt
      
    3. Create a directory on the floppy to store the UDI drivers:
         mkdir /mnt/udi-dist.1
      
    4. Copy any UDI SCSI drivers which will be needed during ISL, in UDI package format, into the directory /mnt/udi-dist.1. For each driver, this is the file named shortname.udi, created by udimkpkg(1), where shortname is the value of the shortname declaration in the driver's udiprops.txt file. For the sample SCSI HBA driver, this file would be named udi_dpt.udi.
    5. Unmount the floppy from the temporary directory:
         umount /mnt
      
    6. Label this floppy as a "UDI HBA Driver Diskette", with the names of the UDI drivers on it.
  3. Begin an ISL of the UnixWare 7 operating system using the boot floppies supplied with the product. When you are prompted by the install procedure for the first HBA diskette, insert the diskette you created above labelled "UDI Supplement Diskette (v1.0)".


    NOTE: Please note these limitations during ISL:

  4. Once the installation has read the "UDI Supplement Diskette (v1.0)" diskette, you will be prompted for a UDI HBA diskette. Insert the "UDI HBA Driver Diskette" diskette(s) you created above. Do this for each UDI driver diskette you need.
  5. When all of the UDI HBA diskettes have been loaded, select "Proceed with installation", and you will be prompted for your first HBA diskette again. Insert the HBA diskette supplied with the UnixWare 7 operating distribution this time and proceed with the installation.
  6. Near the end of the installation, insert the "UDI Supplement Diskette (v1.0)" again at the following prompt:
       You must now insert the SID diskette labeled
       UDI Supplement Diskette (v1.0)
    

UDI tools: udibuild, udimkpkg, and udisetup

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.

The udibuild utility

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).


NOTE: The uccs (UDK Optimizing C Compilation System) package must also be installed in order to use the udibuild(1) command.

The udimkpkg utility

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

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).


NOTE: The uccs (UDK Optimizing C Compilation System) package must also be installed in order to use the udisetup(1M) command to install a source packaged UDI driver (other uses of udisetup, such as installing a binary packaged UDI driver, do not require the uccs package).

Environment variables for udibuild, udisetup, and udimkpkg

The udibuild, udisetup, and udimkpkg commands can use the following environment variables to override certain command defaults:


UDI_CC
Contains the full pathname to the C compiler, as well as to any additional compiler options. The UnixWare 7 default is "cc -Xa".

UDI_DRV
This specifies the drv_xxx directory. The UnixWare 7 default is the "shortname" declaration in the static properties file.

UDI_ALT
This specifies the alt_yyy directory. The UnixWare 7 default is the "release" declaration in the static properties file.

UDI_COMP
This specifies the comp_zzz directory. The UnixWare 7 default is the "module" declaration in the static properties file. Please refer to the UDI Core Specification, Section 32.2.1 for more information on the use of the drv_xxx, alt_yyy, and comp_zzz.

UDI_PUB_INCLUDE
Contains the full pathname to the directory where the UDI header files are stored. The UnixWare 7 default is /usr/include/udi.

UDI_BLDTMPDIR
This specifies the temporary directory for the UDI utilities to use. The UnixWare 7 default is /tmp.

UDI Future Directions and UnixWare 7 Late News

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.

Notes and conditions


NOTE: THIS VERSION OF THE UDI DEVELOPMENT KIT FOR UNIXWARE 7, RELEASE 7.1.1 SOFTWARE (HEREAFTER "INITIAL VERSION"), IS MADE AVAILABLE UNDER THE FOLLOWING CONDITIONS. IF YOU DO NOT AGREE TO SUCH CONDITIONS, DO NOT USE THE INITIAL VERSION, AND REMOVE IT FROM YOUR SYSTEM IMMEDIATELY.

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.