Project Overview

Red Hat Enterprise Linux 5 (RHEL5) introduces a third party kernel module packaging process, as part of the Red Hat Enterprise Linux Driver Update Program. This is an ongoing effort to make life easier for third party driver vendors (often refered to as kISVs - for kernel ISV) packaging their Linux Kernel Modules for use on Red Hat Enterprise Linux systems. The project goes beyond RHEL5. Over time, you will see various additions in the lead up to RHEL6, and beyond. Everyone is encouraged to get involved, and we welcome your feedback as a user of the program. To get involved, check out some of the links on this site, or contact your existing Red Hat partner manager.

This site contains up-to-date resources relating to the RHEL Driver Update Program - everything from documentation, to presentations, to mailing lists, and tools and utilities for third parties to aid in packaging third party drivers for use with Red Hat Enterprise Linux. Other vendors have similar technologies. These are discussed at community-driven websites, such as kerneldrivers.org, while this site is intended solely for discussion and issues pertaining to Red Hat Enterprise Linux.

Latest News

  • Linux Foundation Collaboration Summit. As part of the Driver Backports Working Group of the Linux Foundation, Red Hat will be present at the Linux Foundation Collaboration Summit in Austin, TX from April 8-10 2008. At the summit, the backports group will discuss issues relating to third party driver updates, and future technologies.

What we provide today

Red Hat Enterprise Linux 5 (RHEL5) introduced the following:
  • Standardized packaging for kernel drivers.
  • A "whitelist" of stable kernel interfaces.
  • Support for modifying or replacing drivers needed at system boot time (bootpath).
  • Limited support for system certification.

Various drivers have already been shipped using the RHEL Driver Update Program. These include the Intel IPW3945 WiFi driver that has shipped since RHEL5.0, on the Supplementary CD. Although Red Hat has shipped a number of drivers itself, this program is primarily intended for third parties who wish to handle driver production and distribution, but make use of a Red Hat endorsed, standardized packaging process for their kernel drivers.

Project Briefings

Red Hat has created a variety of third party briefings, and technical documentation that you can use in order to determine whether this program is suitable for use with your Linux kernel driver. The quickstart section below even provides an online testing tool that you can use in order to quickly determine the compatibility of your driver.

Technical Documentation

Technical documentation on the RHEL Driver Update Program is being consolidated under this site, a central resource. The following documents may be of interest for those wishing to understand the technical implementation detail of the RHEL Driver Update Program. Note that you do not need to know precisely how the program works in order to use it!

Who's Who

The RHEL Driver Update Program is co-ordinated by a team of Red Hat engineers, and management. Everyone within the company who is involved with RHEL kernel development is aware of this program and its intended benefits to third parties. Our Linux kernel team uses a variety of tools to ensure that changes to the Red Hat Enterprise Linux kernel will remain compatible with the goals of this program.

Please use your existing partner management contacts whenever possible, as they are best suited to route your inquiry.

Quickstart Guide

To quickly get started with using this program:
  • Verify that your kernel module is compatible.
  • Create a new source RPM (based on the template).
  • Build your Driver Update RPM for selected targets.
  • (optionally) Override a Red Hat supplied driver.
  • (optionally) Build a Driver Update disk.
  • Ship your driver RPM as you would any other.

Verifying compatibility

Not all kernel modules can be packaged using the Red Hat Enterprise Linux Driver Update Program. Only those drivers that conform to using only those published interfaces supported by Red Hat can make full use of this program - limited use is available to others, and a process exists for requesting support for your driver, if it is current incompatible.

You can use a simple driver update kABI testing script to determine whether your module is compatible, or the online version of the same script via this page.

As a quick reference, you can upload a pre-built Linux kernel module via this page, and our automated tester will inform you as to the compatibility of this program with your chosen Linux kernel module.

Please note that:

  • The module must have been built on a Red Hat Enterprise Linux 5 system.
  • The module must have been built using the Red Hat Enterprise Linux 5 kernel sources.
  • You must test each possible target system using a different pre-built module.
    • That means one for i686, another for i686xen, another for ia64, or x86_64, and so on.
  • There are 10 different possible target kernels (listed in the selection box given).
    • But you only need to test modules built for those systems that you will ship for.
NOTE: By submitting your module here you authorize us to test it for compatibility with the Red Hat Enterprise Linux 5 kernel. The module will not be retained beyond the testing, but please do not submit confidential non-public modules using this interface (use the downloadable version of this tool instead). We may log the results of these tests, for survey purposes, and we will periodically audit this service to ensure it is being used for its intended purpose.

To get started, we need to know which version of the kernel you want to test against:

Select a RHEL5 kernel variant:

Upload a kernel module, built on RHEL5:

Incompatible modules?

Should our testing tool tell you that your existing module is incompatible with the RHEL Driver Update Program, don't panic! You will receive suggestions about next steps, including how to contact Red Hat about adding new symbols to our published whitelists in order to support your module (this commits us to supporting new interfaces, something that we cannot always undertake to do - every request is reviewed on its own merits by our internal kernel engineering team).

Creating a package

Creating a package involves a few simple steps, depending upon the type of package being produced. Red Hat is actively working with other vendors to support cross-distribution packaging, and in that spirit is endorsing such packaging here, but there are still some limitations that might make it more appropriate to base complex examples upon existing packages in RHEL5, such as the IPW3945 WiFi driver - the ipw3945-kmod package.

You can download the following example package, which uses the cross-vendor packaging option:

A typical Driver Update Program SPEC file is very small indeed:

		Name: redhat-example
		License: GPL
		Group: System/Kernel
		Summary: Example RHEL5 Driver Update Program Package
		Version: 1.5
		Release: 0
		Source0: %name-%version.tar.bz2
		BuildRoot: %{_tmppath}/%{name}-%{version}-build
		BuildRequires: %kernel_module_package_buildreqs
		%kernel_module_package
		%description
		This is an example RHEL5 Driver Update Program Package.
		%prep
		%setup
		set -- *
		mkdir source
		mv "$@" source/
		mkdir obj
		%build
		export EXTRA_CFLAGS='-DVERSION=\"%version\"'
		for flavor in %flavors_to_build ; do
		   rm -rf obj/$flavor
		   cp -r source obj/$flavor
		   make -C %{kernel_source $flavor} M=$PWD/obj/$flavor
		done
		%install
		export INSTALL_MOD_PATH=$RPM_BUILD_ROOT
		export INSTALL_MOD_DIR=extra/%{name}
		for flavor in %flavors_to_build ; do 
		   make -C %{kernel_source $flavor} modules_install \
		           M=$PWD/obj/$flavor
		done
		%clean
		rm -rf %{buildroot}
		%changelog
		* Tue Oct  9 2007 Jon Masters 
		- Updated original examples
                

The SPEC file makes use of the cross-vendor %kernel_module_package macro to do most of the necessary heavy lifting required, and otherwise contains the regular meta-data associated with any other RPM package. This SPEC file is broadly compatible with other Linux vendors, although some small cosmetic differences may exist.

Building your driver

Building your RHEL5 Driver Update Program RPM is almost the same as building any other, with the caveat that you might need to use the "target" option parameter to rpmbuild, if you are using an Intel-compatible system. There is no way for rpmbuild to know that kernel RPMs are always built for i686, whereas regular packages are built for i386.

To build your rpm, use rpmbuild. On an Intel-compatible machine, this command becomes (replace rpm/SPECS with the path to the SPEC file on your system - e.g. /usr/src/redhat/SPECS/ by default):

		rpmbuild -ba --target i686 rpm/SPECS/redhat-example.spec
		

The use of a "--target" command is necessary in order to avoid rpmbuild trying to find an i386 kernel on your system. This is something it will more than likely be unable to do, which will cause somewhat bizzare appearing error messages. If you are unable to build the example, please do check for this situation.

The build process will produce a binary RPM, and a source package that you can use to rebuild the example. On a particular Intel-compatible computer, the following example package was build for an i686 CPU target:

  • rpm/RPMS/i686/kmod-redhat-example-1.5-0.i686.rpm

The build process will also produce a source RPM:

  • rpm/SRPMS/redhat-example-1.5-0.src.rpm
You can experiment with building your own packages.

Overriding a Red Hat supplied driver

Red Hat's Driver Update Program is intended to be used for new hardware and other "driver" (where this may be pure software) enablement, and is not generally intended to be used in order to replace a Red Hat supplied driver. In most cases, it is preferable to request a feature enhancement or bugfix as an alternative to replacing and supporting an alternative driver that is maintained completely independently of Red Hat itself.

Sometimes, however, third parties really do feel a need to replace a Red Hat driver, for a variety of reasons, including a backport from a later RHEL5 release to a prior RHEL5 release. In this case, the Driver Update Program can still be used, thanks to the use of a configurable priority for driver preference - the system can be instructed to favor a non-Red Hat driver even if there is already a version of the driver supplied by Red Hat. Before trying this, you should note:

  • Drivers are generally referenced by name in this document. There is an implicit assumption that you wish to replace Red Hat driver "foo" with your version "foo", and not a differently named driver.
  • It is possible to replace on a pure device ID basis, however this will require additional blacklisting of device IDs supplied by the Red Hat kernel. This is not recommended in most cases and is not documented.
  • Red Hat kernels contain GPG signed modules. Whenever these are replaced, a special flag in the /proc/modules file indicates this, and this is used by our support organization, who are able to determine that third party replacement drivers are in use. Although we will make a best efforts basis for support, Red Hat do not in general support drivers that were not supplied by Red Hat.

Building a driver update that overrides a Red Hat supplied driver is done as previously shown, however an additional file is required on the customer system (it can be added to the RPM containing the driver update). Since Linux uses the module-init-tools package extensively to handle the loading of kernel modules, it has been extended to handle the priority of driver modules. The system contains a system-wide default file in /etc/depmod.d/depmod.conf.dist:

#
# depmod.conf
#

# override default search ordering for kmod packaging
search updates extra built-in weak-updates
		

This instructs the depmod utility to prefer "updates" manually installed by the system administrator, followed by driver updates built against the exact kernel installed, followed by those that Red Hat have supplied, and then all other driver updates. The format of this file is further documented in the depmod.conf "man" manual page.

Overriding the default search order is not advised, and is instead explicitly discouraged. However, it is possible to create a per-module configuration file instead. This file will instruct the module-init-tools utility depmod as to whichever preference ordering is to be used when it encounters a module of a given name.

You can create an /etc/depmod.d/mydriver.conf file, where mydriver is the name of your module, as follows:

#
# mydriver.conf
#

# override default search ordering for kmod packaging
override mydriver * weak-updates/mydriver
		

This instructs the module-init-tools depmod utility to favor any module named "mydriver" supplied as a driver update over and above a module of the same name that is already supplied within the distribution itself.

Building a Driver Update Disk

Red Hat Driver Update Disks are built using ddiskit.

Driver Update Disks have been modified in RHEL5.1 and a new version of ddiskit has been released that supports the use of the RHEL Driver Update Program. Driver Update Disks are only ever used in the specific case that either a SCSI or NETwork device must be used in order to facilitate an install, but are not otherwise needed (drivers can be added to a system after installation).

Creating a Driver Update Disk now works as before (see the documentation and examples in the ddiskit sources - specifically the qla2xxx example that has been included for this purpose), however you have the option of using your RPM sources, rather than raw module source. During installation, if the installer sees an RPM version of your driver on the disk (in the new disk format), then it will copy the driver RPM onto the target and install it. The RHEL Driver Update Program will retain this driver across future kernel updates.

Please note that it is still necessary to build the driver disk itself against a specific kernel version, since the disk contains an unpacked version of your module that is used by the installer itself - it is unable to use an RPM package directly at the "stage 1" part of the system installation. This means that, although your module will persist once installed, you still need a driver disk for each release of RHEL5 that you want to support - i.e. one disk for RHEL5.0, one for RHEL5.1, etc.

Shipping your package

Once you have successfully built your Driver Update package for your chosen RHEL5 target systems, you will need to actually ship the driver update RPM. Red Hat does not generally undertake to do this on your behalf (in a limited number of cases, we may provide for distribution of your driver, please contact us with your request via your partner manager), and so you will need to use one of a variety of possible distribution mechanisms:
  • Supply the RPM packages on your website
  • Provide a Yum repository to your customers
  • Ship a Driver Update Disk (in limited cases).

Further Information

Thank you for your interest in the RHEL Driver Update Program. If you would like to get more involved in future development, please contact Jon Masters. We have various exiting plans for the future - some of which have been made public. Rest assured that the Driver Update Program will evolve over time - so your feedback is both encouraged and will directly affect the next generation of the Driver Update Program technology.

For generic questions about Red Hat, or for partner specific issues, please contact your Red Hat partner manager, or other existing Red Hat contact.

A non-supported engineering service provided for convenience only. This page is maintained by Jon Masters <jcm@redhat.com> and was last updated on Monday, March 17th 2008.