Brief description of DriverDisc version 3
==========================================

For a new major release we decided to introduce a new version of DriverDisc
feature to ensure the smoothest vendor and user experience possible. We had
many reasons for it:

- the old DD didn't support multiple architectures
- the old DD wasn't particulary easy to create
- the old DD had two copys of modules, one for anaconda and one for
  instalation
- the modules in old DD weren't checked for kernel version 

We also changed the feature internal code to enable some functionality that
was missing from the old version. More about it below.

Devices which can contain DDs
-----------------------------

The best place to save your DriverDisc to is USB flash device. We also support
(or plan to) IDE and SATA block devices with or without partitions, DriverDisc
image stored on block device, initrd overlay (see documentation below) and for
special cases even network retrieval of DriverDisc image.

What can be updated using DDs?
------------------------------

All drivers for block devices, which weren't used for retrieving DriverDiscs,
the same applies also for network drivers eg. you cannot upgrade network
driver for device, which was used prior the DriverDisc extraction.

RPMs for installation. If the DriverDisc repo contains newer package, than the
official repository, the newer package will get used.

We also plan to support anaconda's updates.img placement on the DriverDisc to
update stage2 behaviour of anaconda.

Selecting DD manually
---------------------

There are two ways of triggering DD mode and loading updated drivers manually.

The first is using 'dd=<location>' argument on the kernel command line during
installation boot.

Second way is by using only 'dd' argument on the command line and then using
the TUI provided by anaconda to select DriverDisc's source location.

Documentation for current release will provide more details as this wasn't
changed.

Automatic DriverDisc detection
------------------------------

Anaconda can be told to look for driverdisc automatically by using 'dlabel=on'
kernel command line argument. This is enabled by default in Red Hat Enterprise
Linux version of Anaconda.

The DriverDisc has to be on partition or filesystem which has been labeled
with 'oemdrv' label.


DDv3 structure
--------------

The new DriverDisc format uses simple layout which can be created on top of
any anaconda's supported filesystem (vfat, squashfs, ext2 and ext3).

/
|rhdd3   - DD marker, contains the DD's description string
/rpms
|  /i386 - contains RPMs for this arch and acts as Yum repo
|  /i586
|  /x86_64
|  /ppc
|  /...  - any other architecture the DD provides drivers for

There is a special requirement for the RPMs used to update drivers. Anaconda
picks up only RPMs which provide kernel-modules-<running kernel version>.

Initrd overlay driverdisc image
-------------------------------

We have designed another possible way of providing updates in network boot
environments. It is possible to update all modules this way, so if special
storage module (which gets used early) needs to be updated, this is the
preffered way.

This kind of driverdisc image is applied over the standard initrd and so has
to respect some rules.

- All updated modules belong to /lib/modules/<kernel version>/..  according to
  their usual location
- All new modules belong to /tmp/DD/lib/modules
- All new firmware files belong to /tmp/DD/lib/firmware
- The rpm repo with updated packages belongs to /tmp/DD-initrd/
- The (empty) trigger file /.rundepmod must be present

Firmware and module update
--------------------------

The firmware files together with all .ko files from the RPMs are exploded to
special module location, which has preference over built-in Anaconda modules.

Anaconda doesn't use built-in modules (except some storage modules needed for
the DD to function properly) during the DriverDisc mode, so even in case when
you are updating some modules with second (or later) DriverDisc, the updated
modules will be loaded. There is one exception though, if your module depends
on a module which is only present in built-in module directory, that built-in
module gets also loaded.

Package installation
--------------------

It is also possible to include arbitrary packages on the DriverDisc media and
mark them for installation. You just have to include the package name in the
Yum repo for correct architecture and mark it as mandatory.


Summary
-------

This new DriverDisc format should simplify the DD creation and usage a lot. We
will gladly hear any comments as this is partially still work in progress.

