Packaging & Distribution Format

31

31.1 Overview

This chapter defines the UDI packaging and distribution format for both source and binary distributions of UDI drivers.

31.2 Packaging Format

The UDI packaging format specification describes a directory hierarchy that is used to contain the various components of a UDI driver "package"; i.e. all the files necessary to be provided with a driver to make it usable. This directory structure is then encapsulated in a "pax" archive to create a distributable UDI package. A single package can contain multiple drivers and/or libraries.

Each environment implementation shall provide a utility program called udisetup, that is used to install a driver once the UDI package has been somehow transported to the target system and possibly extracted from distribution media. This utility converts the driver files into appropriate native form, installs copies of them into environment-specific locations, and performs any other operations necessary to make the driver available for use.

When presented with a distribution containing multiple independent drivers, it is implementation-dependent whether udisetup installs all of the drivers or prompts the user for the name of a driver package to install.

31.2.1 Directory Structure

In the directory structure shown below, all UDI files are contained under a standard top-level directory ("udi-pkg.1"). If the directory structure were to change in a future version of this specification, a new top-level directory name would be used.

One or more completely independent driver packages may be included in this directory, each rooted at a sub-directory referred to below as drv_xxx (which may be any arbitrary name). For example, if a vendor ships multiple network interface controller drivers for different kinds of network adapters, each driver would be packaged under a different drv_xxx directory. Environments may choose to install all driver packages in a distribution or to present the user with a choice of driver package names.

One or more alternate versions of the same logical driver package may be included within the drv_xxx directory, each rooted at a sub-directory referred to below as alt_yyy (which may be any arbitrary name). Environments will install only one alternate version for any driver package. Alternates will be selected based on the UDI specification version on which they depend, as well as the versions of other interfaces, such as metalanguages. Only alternates that require only supported interface versions will be considered. If multiple alternates use supported interfaces, it is unspecified which one will be selected.

One or more components (individual UDI drivers or libraries) may be included with in the alt_yyy directory, each rooted at a sub-directory referred to below as comp_zzz (which may be any arbitrary name). Environments will install all components of a driver package for the selected alternate. This is useful for grouping internal metalanguage libraries with the drivers that use them, sets of cooperating drivers, etc.

Static driver properties must be provided for each component, as specified in Chapter 30, "Static Driver Properties". If this component distribution contains the source form, the static properties will be contained in the udiprops.txt file in the src subdirectory along with the driver source. If this component distribution contains the binary form, the driver binaries are contained in the bin directory, with the contents of udiprops.txt embedded in the primary module's object file in an ABI-specific fashion.

Beneath the bin directory, the <abi> subdirectories contain the driver binaries built to conform to a particular Architected Binary Interface. The <abi> subdirectory names are defined in each ABI, with typically one subdirectory defined for binaries which can be used generically within the ABI, and an additional subdirectory defined for each supported processor subclass. For example, take a fictitious CPU architecture called, "3CPU", with specific processor models "3CPU1", "3CPU2" and so on. bin/3CPU would contain generic 3CPU binaries that would run on any processor in the family; bin/3CPU1 would contain binaries specifically optimized for the 3CPU1 processors and might not even run on other processors in the family.

The optional rfiles directory contains files readable by the driver. These are usually microcode files for downloading to a particular adapter or device. The optional msg directory contains text for messages used by the driver.

The resulting package directory hierarchy for one component would look like the following:

udi-pkg.1/<drv_xxx>/<alt_yyy>/<comp_zzz>/
 
			src/udiprops.txt
 
			    <source files>...
 
			bin/<abi>/<primary module file>
 
			          <secondary modules>...
 
			rfiles/<readable files>...
 
			msg/<message files>...
 

Each of the src, bin, rfiles, and msg subdirectories are optional. They are required only if one or more of the corresponding type of file is included in the package. At least one of src or bin must be present.

31.3 Archive Format

In order to create a UDI driver package, the entire package directory hierarchy described above is encapsulated in a "pax" archive, as defined in the IEEE Std. 1003.1-1988 "Archive/Interchange File Format", with relative pathnames. The resultant archive file, referred to as a UDI package file, can be given as an argument to the udisetup utility to install the driver on a target system.

All UDI build environments shall support a "udimkpkg" utility, which takes a collection of UDI driver files and creates a UDI package file.

31.4 Distribution Format

The UDI distribution format specification defines how UDI driver packages may be placed on various distribution media. Environments are not required to support any of these media types. However, for any listed media type from which an environment supports installation of UDI drivers, the storage format and layout specified herein must be supported.

All UDI distribution formats simply use one or more UDI package files (output from udimkpkg), stored on the media in a specified storage format at a specified location. In order to allow the target environment to locate the UDI package files, which may be interspersed with other files on the same media, UDI package files stored on physical distribution media must be placed (directly) in a top-level directory named "/udi-dist.1", referred to as the distribution directory.

Further, since some media formats are limited to 8.3 filenames (up to 8 characters, optionally followed by a dot (`.') and 1-3 additional characters), UDI package files stored on physical distribution media must be named "xxxxxxxx.udi", where "xxxxxxxx" is replaced by 1-8 characters chosen by the driver developer (or distributor). There must be no other files ending with the ".udi" extension in the distribution directory, except other UDI package files.

31.4.1 Floppy Storage Format

For floppy disks, the storage format shall be a DOS FAT12 filesystem. This filesystem supports directory hierarchies, but the directory and file names are limited to 8.3 format (up to 8 characters, optionally followed by a dot (`.') and 1-3 additional characters) and are case-insensitive but stored as upper case. The UDI distribution directory, "udi-dist.1", must be placed in the root of the DOS filesystem.

31.4.2 CD-ROM Storage Format

For CD-ROMs, the storage format shall be an ISO-9660 filesystem. (RockRidge extensions are allowed, but not required since the UDI package file names will fit in 8.3). The UDI distribution directory, "udi-dist.1", must be placed in the root of the directory hierarchy identified by the Primary Volume Descriptor.