Vendor Driver CD

Purpose

With the vendor driver CD extension of YaST2, the user can install software (i.e. device drivers) from a vendor CD at the end of the installation.

This gives an easy tool esp. to re-construct a damaged pre-installed system.

In the forthcoming documentation, the notion driver is used throughout. Keep in mind, that any kind of software (i.e. rpm packages, shell scripts, etc.) can be installed by the vendor driver CD mechanism.

Current limitations

only accepts /dev/cdrom (by default)
mounts it on /var/adm/mount
all directories and files are expected in lower case, this must be taken into account if case-preserving file systems are used.

the functionality to load the software from another device (i.e. floppy) is built-in but not accessible on the desktop.

Expected directory layout

The directory layout is choosen to support multiple distributions, architectures, and product versions on a single vendor CD.
This document only describes the layout for YaST2 as available on SuSE Linux 7.1

On the CD-ROM, a toplevel directory linux must exist.

Below linux, a directory named suse must exist.

Below linux/suse, a directory describing the architecture and SuSE version must exists.

The following architectures are currently known:

i386 sparc sparc64 ppc axp s390 ia64

The version is the product version of SuSE Linux, i.e 7.1

Example:

The complete directory path for the SuSE Linux 7.1 (i386) would be:

linux/suse/i386-7.1/

The complete directory path for (a future) SuSE Linux 7.2 (sparc64) would be:

linux/suse/sparc64-7.2/

Files

In the aforementioned directory, the driver description and data files reside. YaST2 only checks the architecture and SuSE Linux version.
YaST2 does not check the running kernel version.

BEWARE: With SuSE 7.1, the user might have choosen two kernels (2.2.18, 2.4.x) for installation. By default, kernel 2.2.18 is running.
In order to support both kernels, vendors should check /boot/vmlinuz* and/or /lib/modules/* to determine which kernels are actually installed !!

Each driver must be accompanied by at least two files. One (or more) description file (which contains descriptive text) and one installation (script) file.

There should be multiple description files for each driver, one per supported language. At least a default (in english) should be provided.

YaST2 first looks at all files with an .inst extension. These are the installation script files, one per driver.

The file name (without the .inst extension) serves as a key to identify the driver and the accompanying description files. This makes it possible to put multiple drivers into one directory.

The description files have .desc as the extension start with the name (key) of the corresponding .inst file.

Example:

The driver is named modem.
The installation script must be named modem.inst.
The default description file must be named modem.desc.

Remark: The choosen name is only mandatory for the .inst and .desc file. The installation script might reference any other file on the CD.

In order to support translation description files, YaST2 appends the ISO language code to the driver name before loading the default description file. (see Example)

Example:

For german as spoken in austria, the ISO language code is de_AT.

The austrian(-german) description file for driver modem would be modem-de_AT.desc.

If the full (5-char) ISO code cannot be found, YaST2 falls back to the 2-char language code.
With this mechanism, several languages (i.e. de_AT for austrian, de_CH for swiss, and de_DE for german) can be supported by a single description file: modem-de.desc.

In order to support non ISO-1 (non western europe / us) languages (like japanese), the description file must be coded in UTF8.
UTF8 is the standard coding used in Linux, a good introduction can be found on czyborra.com
On Linux, several UTF8 editors are available. One prominent example is yudit.

Complete example:

Two drivers, one called modem with chinese (zh_CN) and japanese (ja_JP) description files, one called speedblazer with german (de), french (fr), and portuguese (as spoken in brazil, pt_BR) description files. All for SuSE Linux 7.1 (i386)

Directory on CD

linux/suse/i386-7.1

Files in this directory

modem.inst
modem.desc
modem-zh_CN.desc
modem-ja_JP.desc
speedblazer.inst
speedblazer.desc
speedblazer-de.desc
speedblazer-fr.desc
speedblazer-pt_BR.desc

The .desc files without a language code should contain the default description in english.

Workflow

YaST2 always runs with root permissions.

Start

When started up, the vendor driver CD module of YaST2 tries to mount /dev/cdrom to /var/adm/mount. If it fails, the user is asked to insert the vendor driver CD.

Mounting and checking the media

After a successful mount, YaST2 tries to find the correct directory as described above. For a SuSE Linux 7.1 (i386) distribution, YaST2 would look for the linux/suse on the CD.
If this fails, the CD is rejected with the message "Couldn't find driver data on the CD-ROM"
Then the directory linux/suse/i386-7.1 is searched. YaST2 will fail with "CD-ROM data doesn't match running SuSE Linux" if this directory doesn't exist.
This and all further error messages will be presented in the correct language the user has choosen at start of the installation.

Scanning the directory

Next, YaST2 scans the directory for installation script files (files ending in .ins).
Attention: YaST2 only checks for a matching 3 character extension in order to support DOS compatible file systems.
If no files with extension .ins can be found, YaST2 rejects the CD with "Couldn't find driver data on the CD-ROM".

Reading descriptions

For each installation script file, a matching description file is searched. The match algorithm is described above.
If no matching description file can be found, the driver is silently skipped.

For each driver, the first matching description file is read in and presented to the user in a pop-up window. The window has two buttons, one labled Yes, install ... and one labled No.
The button labels will be properly translated by YaST2.

User interaction

If the user clicks on the No button, the driver is skipped.
If the user clicks on the Yes, install ... button, the installtion script file is copied to the /tmp directory of the running SuSE Linux system. This copying is done to prevent errors when executing files from mounted media, which is normally not allowed by default.
YaST2 does a chmod 774 to the file in order to force read, write, and execute permissions for root.
Then the working directory is set to /tmp and the installation script is executed with the full directory path as the argument.
There is no automatic mode, the user is asked separately for each driver.

Example

The modem and speedblazer are present on the CD just like the example above.
Lets say the user has choosen german language as spoken in switzerland (ISO code de_CH).

For driver modem the default description file is read, since neither modem-de_CH.desc not modem-de.desc exist.
If the user clicks Yes, install ..., the file linux/suse/i386-7.1/modem.inst is copied to /tmp, made executable (by running /bin/chmod 744 /tmp/modem.inst), the working directory changed to /tmp (by executing cd /tmp), and the installation script is started with the directory path as argument (./modem.inst /var/adm/mount/linux/suse/i386-7.1).

Installation script

The script is free to do what it wants to do. Keep in mind that only standard linux tools will be available. For example, perl is considered a standard tool, tcl is not.

Usually, the script should check if it's applicable. Probing the hardware and checking the kernel version are minimum requirements to be checked by the script.

Based on the director path passed as parameter, the script can easily extract further data from the CD (rpm package files) and install required software (by calling rpm).
Attention: The script together with any data on the CD should be self-complete, i.e. it must not have any package dependencies which exceed a minimal SuSE Linux Personal installation.

Cleaning up

After execution, the installation script is removed from /tmp. The script should remove any temporary files created during execution.

Error processing

YaST2 evaluates the exit code of the script. If it is non-zero, a popup with the message "Installation failed" is presented to the user.

Order of installation

YaST2 can not guarantee a fixed order of installation with multiple .inst files. It's up to the installation script to ensure necessary pre- and post- installation requirements.

End of installation

After all .inst files have been processed, YaST2 present a summary with the number of successfully installed drivers.
If no drivers could be successfully installed, YaST2 pops up a message reading "Couldn't find driver data on the CD-ROM".

As the final step, the cdrom will be unmounted.