RHEL5

From KernelDrivers

Jump to: navigation, search

Red Hat Enterprise Linux 5 introduced the Red Hat Driver Update Program, an effort to allow third parties to package and ship their own kernel modules for the Red Hat Enterprise Linux kernel. The packaging process is based upon the RedHatKernelModulePackages as first introduced in Fedora, but is more than simply a process for packaging of drivers. Broadly speaking, the RHEL5 Driver Update Program (DUP) can be broken down into these components:

  • Kernel ABI tracking
  • Packaging
  • Policy and Distribution

The purpose of this document is to provide references to documentation, scripts, utilities, and advice pertaining to each of these components. You can also contact your Red Hat Partner Manager with any additional comments or concerns, or contact Jon Masters (jcm@redhat.com) for more general implementation detail.

Contents

[edit]

Quickstart

To get started quickly, you will want to do the following:

  • Check your Linux Kernel Module is compatible with the RHEL5 implementation of the RHEL Driver Update Program.
  • Use one of the existing example modules (e.g. IPW3945) as a base for packaging your new driver.
  • Build a Driver Disk (using the latest ddiskit release) if you need installation-time support.
    • Only for SCSI and/or Networking Linux Kernel Modules.
    • Requires the user to have additional physical media.
  • Ship your driver as you would any other software.

You can also petition Red Hat to ship your driver on your behalf. There are various limitations to this process - in particular the number of such requests that Red Hat is able to handle between product updates - and so you are advised to make good use of your existing Red Hat contact in finding out more about this process.

[edit]

Kernel ABI tracking

Red Hat Enterprise Linux 5.0 introduced various changes to our internal kernel development process, which helped to formalize existing mechanisms for third party ABI preservation. As part of the development effort, Red Hat identified a subset of the kernel ABI (the binary version of specific kernel functions and data structures - collectively "the kernel ABI" or kABI) that was to be considered stable for third party use. These specific symbols were listed on various whitelists (available within corresponding kernel-devel packages, and named kabi_whitelist), which were tied into our internal build process such that all subsequent kernel builds automatically include verification against any compatibility breaks. Third parties using only those symbols on the whitelists should not need to rebuild their drivers on kernel updates.

Internal users of the Red Hat brew build system may notice that brew kernel builds will automatically include a test against the RHEL5 kernel ABI. If you are testing a patch, and it breaks kernel ABI in your test kernel built through brew, then the build will automatically FAIL (if you really need to disable this for a build - for example, while attempting to identify the cause of a potential ABI break - then you can disable the ABI checking flag). You will need to fix the listed ABI breaks before you can submit the build again, a pre-requiste to getting your patch proposed for the next Red Hat Enterprise Linux 5 kernel update.

There are 10 different whitelists, one per variant of the Red Hat Enterprise Linux 5 kernel:

  • i686
  • i686PAE
  • i686xen
  • ia64
  • ia64xen
  • ppc64
  • ppc64kdump
  • s390x
  • x86_64
  • x86_64xen

Most of these are similar, aside from some low-level symbols that do differ from one kernel variant to the next, but you will need to verify your module against each of those particular Red Hat Enterprise Linux 5 kernel variants that you are using. Simply testing against the i686 kernel alone will not suffice, unless your driver update will only ever be supplied for the i686 (no PAE, no Xen) kernel - a very unlikely situation in the current climate. If you are using ABI not on the published whitelist, then you will need to contact Red Hat (ideally through your Partner Manager) and ask that a future update include the symbol on its kernel ABI whitelist.

NOTE: Missing ABI symbols can only be added if an appropriate feature request is filed, in a generally timely fashion, prior to the next Red Hat Enterprise Linux 5 update. You will not be able to use the Driver Update Program for previous releases of RHEL5 prior to whitelisting of the required symbol.

[edit]

Red Hat's Kernel ABI Checker

In order to ensure that third parties are using only approved symbols, Red Hat have made available various scripts and documentation to partners to assist in the process of identifying those kernel symbols that are needed by their drivers (and other modules). You can verify compliance by building your RHEL5 kernel module on a test system, and then passing it to the abi_check.py script, or you can use an online version at http://www.kerneldrivers.org/abi_check.php. Examples follow below.

[edit]

Using the abi_check.php online script

This simple online service will enable you to quickly check your third party Linux Kernel Module (which must have been built on a RHEL5 system), against the appropriate symbol whitelist. To use the service, select your kernel from the drop-down box, and upload a module. The script will then automatically determine driver compatibility.

For example, you can check the Intel IPW3945 WiFi driver that shipped with RHEL5.0 (on the RHEL5 Supplemental CD) by uploading the ipw3945.ko file:

image:abi_check1.png

The online ABI checker will then test this against the chosen kernel (for example, in this case an i686 kernel variant).

Results will be displayed in a fashion similar to running the script on the command line:

image:abi_check2.png

These are suitable for use in correspondance with Red Hat about packaging your driver for use with RHEL5.

[edit]

Using the abi_check.py script

This simple python script will compare those kernel symbols used by your third party Linux Kernel Module (which must have been built on a RHEL5 system), against the appropriate symbol whitelist. For example, you can test the ABI compliance of the Intel IPW3945 WiFi driver included on the RHEL5 Supplementary CD by running the following command: 

$ ./abi_check.py -k 2.6.18-45.el5 /lib/modules/2.6.18-8.1.4.el5/extra/ipw3945/ipw3945.ko
Red Hat Enterprise Linux 5 ABI Checker
--------------------------------------

ABI Checker version: 1.1

Module:    /lib/modules/2.6.18-8.1.4.el5/extra/ipw3945/ipw3945.ko
Kernel:    2.6.18-45.el5
Whitelist: /usr/src/kernels/2.6.18-45.el5-i686/kabi_whitelist

NOTE: Your module seems to use only official ABI.

NOTE: This does not constitute Red Hat certification
NOTE: Red Hat does not support third party modules.

This confirms that the Intel IPW3945 module supplied by Red Hat on the Red Hat Enterprise Linux 5.0 Supplementary CD for Intel IA32 (i686) conforms to the published whitelist.

Sometimes, you will find that your module uses kernel ABI that has not been explicitly guaranteed by Red Hat: 

$ ./abi_check.py -k 2.6.18-45.el5 uhci-hcd.ko
Red Hat Enterprise Linux 5 ABI Checker
--------------------------------------

ABI Checker version: 1.1

Module:    uhci-hcd.ko
Kernel:    2.6.18-45.el5
Whitelist: /usr/src/kernels/2.6.18-45.el5-i686/kabi_whitelist

WARNING: The following symbols are used by your module
WARNING: and are not on the ABI whitelist.

symbol: uhci_check_and_reset_hc
symbol: uhci_reset_hc

In this case, your first point of call should be to ask Red Hat to include these symbols on the next update to the whitelists. In order to do this, you must justify the need for each symbol (so that Red Hat's kernel engineering team can evaluate each individual request), and put forward a feature request. If Red Hat are unable to satisfy a given request, then alternative options can be suggested, depending upon the specific situation.

[edit]

Packaging

In order to package a driver using the Red Hat Enterprise Linux 5 Driver Update Program (DUP), a third party will generally utilize the instructions given for creating any RedHatKernelModulePackage. A kmod should be created, based upon the examples provided, and should be built upon the same type of target system as will be used for deployment (in other words, Red Hat does not provide cross-compilation capability for Driver Updates, or any other RPM packages at this moment in the lifetime of RHEL). The act of building the Driver Update package will cause the various automated dependency kABI tracking data to be added to the package.

[edit]

Driver Update Disks

Red Hat Enterprise Linux 5.1 (RHEL5.1) and later includes a specially modified Driver Update Disk format, as supported in more recent releases of the Red Hat Driver Update Disk toolkit [ddiskit]. Driver Update Disks must be built against the specific Red Hat Enterprise Linux kernel version in use at install time (since the Red Hat Installer - Anaconda - must load the drivers prior to being able to unpack the RPM packages containing them) but can now also contain a generic RPM-based Driver Update RPM that will persist across all subsequent updates made to the customer's system, to later updates of RHEL5.

The special modifications made to Driver Update Disks enable third parties to first package their drivers using the Driver Update Program (as described above), and then to subsequently copy those driver sources (the RPM SPECS and SOURCES) in place within the ddiskit sources to create a driver update disk with only minimal effort. Further information on creation of RHEL5.1 Driver Update Disks is available within newer releases of ddiskit, with an example for the QLogic QLA2XXX driver module (and updated firmware) included in the latest ddiskit distribution.

[edit]

Policy and Distribution

Red Hat has various policy pertaining to the use and provision of Driver Updates that use the Driver Update Program (DUP), depending upon who is providing the driver. In a limited number of cases, Red Hat will package, supply, and support the Driver Update. This has already occured in the case of the Intel IPW drivers, and in certain other cases. When Red Hat supply the driver:

  • The update is fully supported by Red Hat
  • The update may involve certified systems
  • The update may be delivered via pre-existing channels, such as the Red Hat Network (RHN)

In most cases, Red Hat will not be delivering the Driver Update directly. Rather, a third party will elect to use the program as a means to provide updated drivers for their own systems, often in consultation with Red Hat for direction and general guidance as a partner. Whenever a third party delivers a driver update themselves:

  • The update is NOT usually supported by Red Hat (without special provision)
  • The update may involve certification (subject to status)
  • The update must be delivered via the third party

Additionally, Red Hat generally does not support or endorse the use of (and in fact, explicitly advises against) overriding parts of the kernel supplied by Red Hat. Replacing a Red Hat supplied kernel component should only be done as a limited resort, and always in consultation with Red Hat directly. However, it is technically possible to override a driver that has been supplied by Red Hat, by supplying a special depmod configuration file (as documented elsewhere).

Retrieved from "http://www.kerneldrivers.org/RHEL5"
Personal tools