RFC: kernel-modules in Fedora Extras
Thorsten Leemhuis
fedora at leemhuis.info
Fri Jan 6 10:30:56 UTC 2006
Hi all!
After looking at several kernel module proposals in the wiki and long
discussions on mailing lists and during IRC meetings the Fedora Extras
Steering Committee (also known as FESCo) agreed on a standard for
packaging kernel modules in Fedora Extras. Find the details below for
a last discussion on this mailing list before this proposal is being
used.
Please note that this is a result of a lot of work and experiments. We
had to make compromises here and there -- Read this as "everyone
involved in creating this standard had to accept something in it that
he did not like in the beginning". Please remember that in the
flamewar ^w discussion that follows this mail. A simple "I don't like
it" won't change anything -- even I did not/don't like parts of it,
but I think it's a compromise that works and solves most problems
fine.
Find the details below; they are written in a way that makes it
possible to put them in the wiki later.
----------
Kernel modules are a special case in rpm packaging and need careful
handling. There are a lot of ways to package kernel modules, but for
Fedora Extras the following solution must be used. That avoids
confusion for packagers and reviewers. It hopefully also solves many
pitfalls earlier standards in other repos had. It also should allow
package installers/updaters/removers like yum to work smoothly with
kernel module packages.
The most important rule for packages with kernel modules: There are
always at least two SRPMS -- one builds a userland package (tools,
documentation, license, udev configuration etc) of the source, the other
builds packages with *only* the kernel-module(s). The packager is free
to split the userland-package further into one with a the general
userland parts, that works fine without the kernel-modules, one with
the kernel-module related parts and one with the kernel-module(s).
The userland package with the parts that are related to the
kernel-module(s) must follow follow the standard guidelines for Fedora
Extras packages with one additional rule:
- MUST: The package needs to require the belonging kernel-module
with something like "Requires: kmod-%{name} = %{version}"
Of course all rules that apply to rpm packaging in Fedora Extras apply
for the kernel module package, too -- especially those around the
licensing. But there are several additional rules -- instead of
writing all those down FESCo created a specfile template and a
rpm macro that is used by the specfile that handles most things
automatically. Both are described in detail below.
All kernel module packages should use the template as a
base. Reviewers of kernel modules should diff the proposed
kernel module packages against the template. Only the names and the
way the modules itself are build should differ. There shouldn't be
other differences without a good reason.
Besides rules around the packaging there is one additional *before*
you start packaging a kernel module for Fedora Extras: Open a Review
bug in http://bugzilla.redhat.com and ask FESCo for permission if this
module is allowed for Extras. This requires that you give at least the
following informations:
- Name of the package
- URL of the project and a tarball of the latest version
- License
- A publishable explanation from the author(s) why the module is not
merged with the mainline kernel yet and when it's planed to get
merged. You of course can ask the author to explain it directly in the
bug report.
FESCo will look at those informations on the next meeting (those are
normally every thursday) and will vote if the kernel module is suitable
for Fedora Extras. If not it will explain the reason in the bug report
for further discussion.
For example ndiswrapper is not suitable for Fedora Extras -- yes, it is
GPLed software, but it taints the kernel and most windows drivers won't
work in the Fedora Kernel anyway due to 4K Stacks.
Why all this?
- The Fedora Project wants to encourage driver developers to merge their
sources in the kernel
- It easier for everyone if the modules are in the main kernel
- There is often a good reason why the kernel developers refuse to merge
a driver. If it's not good enough for the kernel, why should it be
good enough for Fedora?
- Most modules that are maintained independently of the kernel have
licensing issues that also make it impossible to ship them in Fedora
Extras.
If the package is permitted for Fedora Extras start to write the
specfile and post a review request. Everyone can review such a
package, but after is was set to APPROVED by the reviewer a Fedora
Extras Sponsor or someone experienced with kernel modules has to take
a quick look at the package and post an additional approved notice
before it is allowed to import the package into CVS.
----------
The RPM-Macro looks like this:
{{{
# usage: %kmod_package $kmod_name $kver $kvariant(optional, empty for UP)
# defines: %{kmod_build_($kvariant|up)}
%define kmod_package() \
%{expand: %%global kmod_build_%{?3}%{!?3:up} 1} \
%package -n kmod-%{1}%{?3:-%3} \
Summary: %{1} kernel module \
Group: System Environment/Kernel \
Provides: kernel-module = %{2}%{?3} \
%{?3:Provides: kmod-%{1} = %{version}-%{release}} \
Requires: kernel-%{_target_cpu} = %{2}%{?3} \
Requires: %{1} = %{version} \
Requires(post): /sbin/depmod \
Requires(postun): /sbin/depmod \
BuildRequires: kernel-devel-%{_target_cpu} = %{2}%{?3} \
%description -n kmod-%{1}%{?3:-%3} \
This package provides the %{1} kernel modules built for the Linux \
kernel %{2}%{?3} for the %{_target_cpu} family of processors. \
%post -n kmod-%{1}%{?3:-%3} \
/sbin/depmod -aeF /boot/System.map-%{2}%{?3} %{2}%{?3} > /dev/null || : \
%postun -n kmod-%{1}%{?3:-%3} \
/sbin/depmod -aF /boot/System.map-%{2}%{?3} %{2}%{?3} &> /dev/null || : \
%files -n kmod-%{1}%{?3:-%3} \
%defattr(644,root,root,755) \
/lib/modules/%{2}%{?3}/extra/%{1}/ \
%{nil}
}}}
If will be added to the macros file in Fedora Core 5 but can be used
directly in specfile itself if you are building for older Versions
and/or other distros. This macro later expands to something like the
following (with kmod_name foo, Version 1.5, kver
2.6.14-1.1776_FC4, uniprocessor Build for i686):
%package -n kmod-foo
Summary: foo kernel module
Group: System Environment/Kernel
Provides: kernel-module = 2.6.14-1.1776_FC4
Requires: kernel-i686 = 2.6.14-1.1776_FC4
Requires: foo = 1.5
Requires(post): /sbin/depmod
Requires(postun): /sbin/depmod
BuildRequires: kernel-devel-i686 = 2.6.14-1.1776_FC4
%description -n kmod-foo
This package provides the foo kernel modules built for the Linux
kernel 2.6.14-1.1776_FC4 for the i686 family of processors.
%post -n kmod-foo
/sbin/depmod -aeF /boot/System.map-2.6.14-1.1776_FC4 2.6.14-1.1776_FC4
> /dev/null || :
%postun -n kmod-foo
/sbin/depmod -aF /boot/System.map-2.6.14-1.1776_FC4 2.6.14-1.1776_FC4
&> /dev/null || :
%files -n kmod-foo
%defattr(644,root,root,755)
/lib/modules/2.6.14-1.1776_FC4/extra/foo/
Why all that? Let's go though the interesting bits in detail:
>%package -n kmod-foo
All kernel modules need to have the prefix kmod (that's a bit shorter
than kernel-module)
>Provides: kernel-module = 2.6.14-1.1776_FC4
With the explicit Provides depsolvers such as yum can know that it's
working with a kernel module. You also easily can get the kver the
module was build for with this.
>Requires: kernel-i686 = 2.6.14-1.1776_FC4
A kernel module without the kernel it was built for is useless.
Don't use /boot/vmlinuz-*, it's not portable.
>Requires: foo = 1.5
Kernel modules without the userland part is useless in most
cases. There are rare packages when kernel modules don't need a part
in userland, but we require it anyway -- the license, docs, udev
configuration
and such stuff needs to be placed somewhere in any case and a userland
package
probably is the best place.
>BuildRequires: kernel-devel-i686 = 2.6.14-1.1776_FC4
Needed for building the kernel-module
>%defattr(644,root,root,755)
Kernel modules shall not be executable -- but they need to be after
%install to allow /usr/lib/rpm/find-debuginfo.sh to strip them.
>/lib/modules/2.6.14-1.1776_FC4/extra/foo/
Separate location -- don't mess up with the rest of the
kernel. "extra" was picked because of upstream kernel documentation.
Only kernel modules in that dir are allowed -- nothing else, because
otherwise they might conflict between different versions!
----------
The kernel module specfile itself looks like this:
{{{
%define kmod_name foo
%{!?kver: %global kver %(uname -r | sed 's/\(smp\|xen-hypervisor\|
xen-guest%{?variant:\|%{variant}}\)//')}
Name: %{kmod_name}-kmod
Summary: %{kmod_name} kernel modules
Version: 1.5
Release: 1.%(echo %{kver} | tr - _ )
URL: http://foo.sourceforge.net
Source0: http://dl.sf.net/foo/foo-%{version}.tar.gz
License: GPL
Group: System Environment/Kernel
BuildRoot:
%{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n)
ExclusiveArch: i586 i686 x86_64 ppc ppc64
%description
This package provides %{kmod_name} kernel modules.
%if 0%{?variant:1}
%if "%{variant}" == "up"
%kmod_package %{kmod_name} %{kver}
%else
%kmod_package %{kmod_name} %{kver} %{variant}
%endif
%else
%kmod_package %{kmod_name} %{kver}
%ifnarch i586
%kmod_package %{kmod_name} %{kver} smp
%endif
%ifnarch i586 x86_64 ppc ppc64
%kmod_package %{kmod_name} %{kver} xen-guest
%kmod_package %{kmod_name} %{kver} xen-hypervisor
%endif
%endif
%prep
%setup -q -T -c
kmod_prep()
{
mkdir ${1} ; tar -C ${1} -xzf %{SOURCE0}
pushd ${1}/%{kmod_name}-%{version}
# fix/patch foo
popd
}
%if 0%{?variant:1}
kmod_prep %{variant}
%else
%{?kmod_build_up: kmod_prep up}
%{?kmod_build_smp: kmod_prep smp}
%{?kmod_build_xen-guest:kmod_prep xen-guest}
%{?kmod_build_xen-hypervisor:kmod_prep xen-hypervisor}
%endif
%build
kmod_build()
{
kvar=${1#up}
make %{?_smp_mflags} -C ${1}/%{kmod_name}-%{version} \
KSRC="%{_usrsrc}/kernels/%{kver}${kvar}-%{_target_cpu}" \
KVERS=%{kver}
}
%if 0%{?variant:1}
kmod_build %{variant}
%else
%{?kmod_build_up: kmod_build up}
%{?kmod_build_smp: kmod_build smp}
%{?kmod_build_xen-guest:kmod_build xen-guest}
%{?kmod_build_xen-hypervisor:kmod_build xen-hypervisor}
%endif
%install
rm -rf $RPM_BUILD_ROOT
kmod_install()
{
kvar=${1#up}
make -C ${1}/%{kmod_name}-%{version} install \
INST_DIR=
$RPM_BUILD_ROOT/lib/modules/%{kver}${kvar}/extra/%{kmod_name}
# Temporarily executable for stripping, fixed later in %%files.
chmod u+x
$RPM_BUILD_ROOT/lib/modules/%{kver}${kvar}/extra/%{kmod_name}/*
}
%if 0%{?variant:1}
kmod_install %{variant}
%else
%{?kmod_build_up: kmod_install up}
%{?kmod_build_smp: kmod_install smp}
%{?kmod_build_xen-guest:kmod_install xen-guest}
%{?kmod_build_xen-hypervisor:kmod_install xen-hypervisor}
%endif
%clean
rm -rf $RPM_BUILD_ROOT
%changelog
}}}
So how does it work? let's go through important parts to describe that:
>%define kmod_name foo
The name of the belonging userland package/the original name of the
software. It is used in several places, therefore we define a macro
for it.
>%{!?kver: %global kver %(uname -r | sed 's/\(smp\|xen-hypervisor\|
xen-guest%{?variant:\|%{variant}}\)//')}
The version of the kernel is also used in several places. The version
is normally passed by the buildsys to rpmbuild via '--define kver
2.6.14-1.1776_FC4' -- if not assume the current kernel, but strip of
name variant name (smp,...), including the possibly user passed
%{variant}.
>Name: %{kmod_name}-kmod
This is only the name for the SRPM -- the kernel module package itself
is named the other way around, e.g. "Name: kmod-%{kmod_name}" (see
the rpm macro). This might be a bit confusing in the beginning, but
solves some problems nicely.
>Version: 1.5
This needs to be the same as in the userland package.
>Release: 3.%(echo %{kver} | tr - _ )
This results in 3.2.6.14_1.1776_FC4 (e.g. the whole src.rpm is named
"foo-kmod-1.5-3.2.6.14_1.1776_FC4" (or something like that).
The kver needs to be in the release to get proper debuginfo packages
later. With this scheme we of course get a SRPM for each kernel we
build the modules for. Therefore it might be better to create a
stripped down tarball of the original source (e.g. remove the userland
parts) to avoid wasting a lot of disk space. This is one of the
drawbacks in this scheme, but it works.
>ExclusiveArch: i586 i686 x86_64 ppc ppc64
This one is important for the buildsys. i386 should never be in the
list because there is no i386 kernel in Fedora -- the buildsys would
not find the BuildRequire and fail at that point. If a kernel module
is only of interest for some of those archs of course feel free to
list only those.
>%if 0%{?variant:1}
> %if "%{variant}" == "up"
> %kmod_package %{kmod_name} %{kver}
> %else
> %kmod_package %{kmod_name} %{kver} %{variant}
> %endif
>%else
> %kmod_package %{kmod_name} %{kver}
> %ifnarch i586
> %kmod_package %{kmod_name} %{kver} smp
> %endif
> %ifnarch i586 x86_64 ppc ppc64
> %kmod_package %{kmod_name} %{kver} xen-guest
> %kmod_package %{kmod_name} %{kver} xen-hypervisor
> %endif
>%endif
Here the rpm macro from above does it work -- for example the
"%kmod_package %{kmod_name} %{kver}" expands to the part we have
shown above.
This might look a bit complicated on a first sight. Here are the
details:
>%if 0%{?variant:1}
is needed to allow passing a one variant as build time parameter --
for example: "rpmbuild -ba SPECS/foo.spec --define 'kver
2.6.14-1.1776_FC4'
--define 'variant smp'" will then only build the module for the smp
variant
of 2.6.14-1.1776_FC4. Note that arbitrary variants can be passed in for
eg.
custom kernels and things will just work, provided that the custom
kernel
is compatibly packaged with the FC kernel.
But normally the srpm will rebuild for all known variants:
> %kmod_package %{kmod_name} %{kver}
> %ifnarch i586
> %kmod_package %{kmod_name} %{kver} smp
> %endif
> %ifnarch i586 x86_64 ppc ppc64
> %kmod_package %{kmod_name} %{kver} xen-guest
> %kmod_package %{kmod_name} %{kver} xen-hypervisor
> %endif
This part probably often needs to be modified a bit -- for example if
the module is not smp-safe one would remove this:
> %ifnarch i586
> %kmod_package %{kmod_name} %{kver} smp
> %endif
Or if xen is not of interest remove this:
> %ifnarch i586 x86_64 ppc ppc64
> %kmod_package %{kmod_name} %{kver} xen-guest
> %kmod_package %{kmod_name} %{kver} xen-hypervisor
> %endif
This scheme has also a drawback: If for example the xen-* kernels and
the up/smp-kernels are not in sync (as currently in
rawhide:kernel-xen-{hypervisor,guest} are at 2.6.14-1.21_FC5 and
kernel{,smp} at 2.6.14-1.1783_FC5) it won't work. But that hopefully
will be fixed before FC5 and can be worked around in Extras-CVS, too.
>%prep
>%setup -q -T -c
Don't extract sources, just create a subdir for build
>kmod_prep()
>{
> mkdir ${1} ; tar -C ${1} -xzf %{SOURCE0}
> pushd ${1}/%{kmod_name}-%{version}
> # fix/patch foo
> popd
>}
A bash function that will extract and patch the sources that is called
multiple times by the next part.
>%if 0%{?variant:1}
> kmod_prep %{variant}
User passed a variant -- only extract it.
>%else
> %{?kmod_build_up: kmod_prep up}
> %{?kmod_build_smp: kmod_prep smp}
> %{?kmod_build_xen-guest:kmod_prep xen-guest}
> %{?kmod_build_xen-hypervisor:kmod_prep xen-hypervisor}
>%endif
Do stuff for all variants in case they are defined (similar things are
in %build in %install, too) -- If you are wondering where those
kmod_build_{up,smp,xen-guest,xen-hypervisor} come from: They are
defines by the kmod_package macro.
>%build
>kmod_build()
>{
> kvar=${1#up}
> make %{?_smp_mflags} -C ${1}/%{kmod_name}-%{version} \
> KSRC="%{_usrsrc}/kernels/%{kver}${kvar}-%{_target_cpu}" \
> KVERS=%{kver}
>}
Build the module -- this or similar commands should work with most
modern kernel modules.
>%install
>rm -rf $RPM_BUILD_ROOT
>kmod_install()
>{
> kvar=${1#up}
> make -C ${1}/%{kmod_name}-%{version} install \
> INST_DIR=
$RPM_BUILD_ROOT/lib/modules/%{kver}${kvar}/extra/%{kmod_name}
> # Temporarily executable for stripping, fixed later in %%files.
> chmod u+x
$RPM_BUILD_ROOT/lib/modules/%{kver}${kvar}/extra/%{kmod_name}/*
>}
Install the module and mark it executable for stripping.
----------
Mini-FAQ:
Will there be further enhancements for the kernel module proposal?
Probably yes. We probably didn't consider every possible scenario out
there.
But the general scheme/direction probably will stay.
Will other repos use the same scheme?
You have to ask those repos, but some people from a major 3rd party
repo that enhances core and extras indicated that they want to use the
same standard.
Does it work with yum?
Not perfectly (yet). We need a plugin for yum that will handles some
special cases for kernel module packages. There are no concrete plans
who works on that ATM. Are you interested to help?
Does it work in the Extras Buildsys?
Not perfectly (yet). We need a plugin or enhancement that will search
for the latest kernel version and then will pass this to the rpmbuild
command with "--define 'kver foo'". There are no concrete plans
who works on that ATM. Are you interested to help?
Will this proposal be used for the GFS stuff in Fedora Core, too?
Probably.
Is it possible to compile against self compiled kernels?
Yes, if self compiled means "packaged in a manner compatible with FC
kernels". Otherwise: no. Well, it's _possible_, but not supported
nor documented. Just create a FC compatible kernel package of your
custom kernel, and compile the module packages for it by passing
--define 'variant foo' to rpmbuild.
This standard is stupid.
Maybe. Post a better one (FYI: some older ones are in the history of
the wiki). And do it quickly, be concise, strictly to the point, and
convince us why it is better.
----------
Find attached a template for a kernel-module package.
Two real-life examples can be found at:
Lirc; Userland (in addition to the lirc package in cvs; note this
practically results in three SRPMS for lirc -- the lirc-kmod-common part
was split out for other maintaining reasons, normally it should be a
subpackage of the normal lirc package)
http://cachalot.mine.nu/5/SRPMS/lirc-kmod-common-0.8.0-2.src.rpm
Kernel-Module:
http://cachalot.mine.nu/5/SRPMS/lirc-kmod-0.8.0-0.6.pre3.2.6.15_1.1819_FC5.src.rpm
Thinkpad; Useland:
http://cachalot.mine.nu/5/SRPMS/thinkpad-kmod-common-5.8-5.src.rpm
Kernel-Module:
http://cachalot.mine.nu/5/SRPMS/thinkpad-kmod-5.8-6.2.6.15_1.1819_FC5.src.rpm
I also have updated openafs packages on my harddisk based on the SRPMS
from Matthew Miller. But they are untested ATM and not 100% up2date to
the lastest proposal (there were some last minute changes).
Okay, let the flamewar ^w discussion begin!
CU
thl
--
Thorsten Leemhuis <fedora at leemhuis.info>
-------------- next part --------------
%define kmod_name foo
%{!?kver: %global kver %(uname -r | sed 's/\(smp\|xen-hypervisor\|xen-guest%{?variant:\|%{variant}}\)//')}
# this block will be added to the rpm macros in core
# usage: %kmod_package $kmod_name $kver $kvariant(optional, empty for UP)
# defines: %{kmod_build_($kvariant|up)}
%define kmod_package() \
%{expand: %%global kmod_build_%{?3}%{!?3:up} 1} \
%package -n kmod-%{1}%{?3:-%3} \
Summary: %{1} kernel module \
Group: System Environment/Kernel \
Provides: kernel-module = %{2}%{?3} \
%{?3:Provides: kmod-%{1} = %{version}-%{release}} \
Requires: kernel-%{_target_cpu} = %{2}%{?3} \
Requires: %{1}-kmod-common = %{version} \
Requires(post): /sbin/depmod \
Requires(postun): /sbin/depmod \
BuildRequires: kernel-devel-%{_target_cpu} = %{2}%{?3} \
%description -n kmod-%{1}%{?3:-%3} \
This package provides the %{1} kernel modules built for the Linux \
kernel %{2}%{?3} for the %{_target_cpu} family of processors. \
%post -n kmod-%{1}%{?3:-%3} \
/sbin/depmod -aeF /boot/System.map-%{2}%{?3} %{2}%{?3} > /dev/null || : \
%postun -n kmod-%{1}%{?3:-%3} \
/sbin/depmod -aF /boot/System.map-%{2}%{?3} %{2}%{?3} &> /dev/null || : \
%files -n kmod-%{1}%{?3:-%3} \
%defattr(644,root,root,755) \
/lib/modules/%{2}%{?3}/extra/%{1}/ \
%{nil}
Name: %{kmod_name}-kmod
Summary: %{kmod_name} kernel modules
Version: 1.5
Release: 3.%(echo %{kver} | tr - _ )
URL: http://foo.sourceforge.net
Source0: http://dl.sf.net/foo/foo-%{version}.tar.gz
License: GPL
Group: System Environment/Kernel
BuildRoot: %{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n)
ExclusiveArch: i586 i686 x86_64 ppc ppc64
%description
This package provides %{kmod_name} kernel modules.
%if 0%{?variant:1}
%if "%{variant}" == "up"
%kmod_package %{kmod_name} %{kver}
%else
%kmod_package %{kmod_name} %{kver} %{variant}
%endif
%else
%kmod_package %{kmod_name} %{kver}
%ifnarch i586
%kmod_package %{kmod_name} %{kver} smp
%endif
%ifnarch i586 x86_64 ppc ppc64
%kmod_package %{kmod_name} %{kver} xen-guest
%kmod_package %{kmod_name} %{kver} xen-hypervisor
%endif
%endif
%prep
%setup -q -T -c
kmod_prep()
{
mkdir ${1} ; tar -C ${1} -xzf %{SOURCE0}
pushd ${1}/%{kmod_name}-%{version}
# fix/patch foo
popd
}
%if 0%{?variant:1}
kmod_prep %{variant}
%else
%{?kmod_build_up: kmod_prep up}
%{?kmod_build_smp: kmod_prep smp}
%{?kmod_build_xen-guest:kmod_prep xen-guest}
%{?kmod_build_xen-hypervisor:kmod_prep xen-hypervisor}
%endif
%build
kmod_build()
{
kvar=${1#up}
make %{?_smp_mflags} -C ${1}/%{kmod_name}-%{version} \
KSRC="%{_usrsrc}/kernels/%{kver}${kvar}-%{_target_cpu}" \
KVERS=%{kver}
}
%if 0%{?variant:1}
kmod_build %{variant}
%else
%{?kmod_build_up: kmod_build up}
%{?kmod_build_smp: kmod_build smp}
%{?kmod_build_xen-guest:kmod_build xen-guest}
%{?kmod_build_xen-hypervisor:kmod_build xen-hypervisor}
%endif
%install
rm -rf $RPM_BUILD_ROOT
kmod_install()
{
kvar=${1#up}
make -C ${1}/%{kmod_name}-%{version} install \
INST_DIR=$RPM_BUILD_ROOT/lib/modules/%{kver}${kvar}/extra/%{kmod_name}
# Temporarily executable for stripping, fixed later in %%files.
chmod u+x $RPM_BUILD_ROOT/lib/modules/%{kver}${kvar}/extra/%{kmod_name}/*
}
%if 0%{?variant:1}
kmod_install %{variant}
%else
%{?kmod_build_up: kmod_install up}
%{?kmod_build_smp: kmod_install smp}
%{?kmod_build_xen-guest:kmod_install xen-guest}
%{?kmod_build_xen-hypervisor:kmod_install xen-hypervisor}
%endif
%clean
rm -rf $RPM_BUILD_ROOT
%changelog
More information about the fedora-extras-list
mailing list