Author: jtr
Update of /cvs/docs/release-notes/FC4 In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv1201
Modified Files: kernel.xml Log Message: Added info about both real and virtual kernels. Corrected source-exploding instructions. Added info about "kernel-devel" binary RPMs.
Index: kernel.xml =================================================================== RCS file: /cvs/docs/release-notes/FC4/kernel.xml,v retrieving revision 1.3 retrieving revision 1.4 diff -u -r1.3 -r1.4 --- kernel.xml 30 May 2005 18:16:22 -0000 1.3 +++ kernel.xml 30 May 2005 23:27:45 -0000 1.4 @@ -1,156 +1,209 @@ -<section id="sn-kernel"> - <title><filename>kernel</filename></title> - <!-- still don't entirely grok the use of these sections, leaving them --> -<!-- for now commented out but available. - <remark os="test">%%% <ulink - url="https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=135269%22%3Ehttps://bug...</ulink> - %%%</remark> +<!-- $Id: --> +<!-- +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ + + <!ENTITY BOILERPLATE "These FAKE ENTITIES are just to make editing easier" > + <!ENTITY FC "FC" > + <!ENTITY LOCALVER "LOCALVER" > + <!ENTITY DISTRO "DISTRO" > + <!ENTITY DISTROVER "DISTROVER" > + +]> --> +<section id="sn-kernel"> + <title> + Linux Kernel + </title> + <section id="sn-kernel-lotsa"> + <title>Version</title> + <para> + The &DISTRO; is based on a 2.6.11 kernel. + &FC; may include additional patches for improvements, bug fixes, or additional features. + For this reason, the &FC; kernel may not be line-for-line equivalent to the so-called vanilla kernel from the <ulink url="http://ww.kernel.org"><filename>kernel.org</filename></ulink> web site. + </para> + <para> + You may obtain a list of any such patches by using the command on the &FC; package: + </para> + <screen width="56"><prompt>$ </prompt><command>rpm</command> <parameter class="option">-qpl</parameter> <filename>kernel-</filename><replaceable><version></replaceable><filename>.src.rpm</filename></screen> + </section> + <section id="sn-kernel-flavors"> + <title>Kernel Flavors</title> + <para> + &FC; includes the following kernel builds: + </para> + <itemizedlist> + <listitem> + <para> + Native kernel, in both uniprocessor and <abbrev>SMP</abbrev> varieties. + </para> + <para> + Configured sources are available in the <filename>kernel-devel-</filename><replaceable><version></replaceable><filename>.</filename><replaceable><arch></replaceable><filename>.rpm</filename> package. + </para> + </listitem> + <listitem> + <para> + Virtual kernel for use with the <wordasword>XEN</wordasword> emulator package. + </para> + <para> + Configured sources are available in the <filename>kernel-xen0-devel-</filename><replaceable><version></replaceable><filename>.</filename><replaceable><arch></replaceable><filename>.rpm</filename> package. + </para> + </listitem> + </itemizedlist> + <para> + Sources for both kernel flavors may be installed at the same time. + The files will be installed into the <filename>/usr/src/kernels/</filename><replaceable><version></replaceable>[<filename>-xen0</filename>]<filename>-</filename><replaceable><arch></replaceable><filename>/</filename> tree. + Use the command: + </para> + <screen width="56"><prompt># </prompt><command>rpm</command> <parameter class="option">-Uvh</parameter> <filename>kernel-devel[-xen0]-</filename><replaceable><version></replaceable><filename>.</filename><replaceable><arch></replaceable><filename>.rpm</filename></screen> + <para> + as appropriate. + </para> + <tip> + <title>Following Generic Textbooks</title> + <para> + Many of the tutorials, examples, and textbooks about Linux kernel development assume the kernel sources are installed under the <filename>/usr/src/linux</filename> directory. + If you make a symbolic link, as shown below, you should be able to use those learning materials with the &FC; packages. + Install the appropriate kernel sources, as shown earlier, and then: + </para> + <screen width="56"><prompt># </prompt><command>ln</command> <parameter class="option">-s</parameter> <filename>/usr/src/kernels/kernel-</filename><replaceable><all-the-rest></replaceable> <filename>/usr/src/linux</filename></screen> + </tip> + </section> + <!-- <tip> <title>Using <command>yum</command> to Uninstall Kernel Packages</title> <para> - &FC; &LOCALVER; contains support for clustering systems using CMAN - and GFS. These kernels require assistance from some user-space - packages. These packages are not removed when using <command>rpm - -e</command> to uninstall older versions of the kernel packages. + &FC; &LOCALVER; contains support for clustering systems using CMAN and GFS. + These kernels require assistance from some user-space packages. + These packages are not removed when using <command>rpm -e</command> to uninstall older versions of the kernel packages. </para> <para> - When using <command>rpm -e - kernel-<replaceable><version></replaceable></command> to - uninstall the kernel, you must also remove the assisting - user-space packages. You may wish to consider a dependecy - resolving tool such as <command>yum remove - kernel-<replaceable><version></replaceable></command>. + When using <command>rpm -e kernel-<replaceable><version></replaceable> </command> to uninstall the kernel, you must also remove the assisting user-space packages. You may wish to consider a dependecy resolving tool such as <command>yum remove kernel-<replaceable><version></replaceable> </command>. This automatically removes any dependant packages. </para> </tip> - <para> - In order to eliminate the redundancy inherent in providing a - separate package for the kernel source code when that source code - already exists in the kernel's <filename>.src.rpm</filename> file, - &DISTRO; &DISTROVER; no longer includes the - <filename>kernel-source</filename> package. Users that require - access to the kernel sources can find them in the - <filename>kernel</filename> <filename>.src.rpm</filename> file. To - create an exploded source tree from this file, perform the following - steps (note that - <filename><replaceable><version></replaceable></filename> - refers to the version specification for your currently-running - kernel): - </para> - <procedure> - <step> - <para> - Obtain the - <filename>kernel-<replaceable><version></replaceable>.src.rpm</filename> - file from one of the following sources: - </para> - <itemizedlist> - <listitem> - <para> - The <filename>SRPMS</filename> directory on the appropriate - "SRPMS" CD iso image - </para> - </listitem> - <listitem> - <para> - The FTP site where you got the kernel package - </para> - </listitem> - <listitem> - <para> - By running the following command: - </para> - <para> - <command>up2date --get-source kernel</command> - </para> - </listitem> - </itemizedlist> - </step> - <step> - <para> - Install - <filename>kernel-<replaceable><version></replaceable>.src.rpm</filename> - (given the default RPM configuration, the files this package - contains will be written to - <filename>/usr/src/redhat/</filename>) - </para> - </step> - <step> - <para> - Change directory to <filename>/usr/src/redhat/SPECS/</filename>, - and issue the following command: - </para> - <para> - <command>rpmbuild -bp - --target=<replaceable><arch></replaceable> - kernel.spec</command> - </para> - <para> - (Where - <command><replaceable><arch></replaceable></command> is - the desired target architecture.) - </para> - <para> - On a default RPM configuration, the kernel tree will be located - in <filename>/usr/src/redhat/BUILD/</filename>. - </para> - </step> - <step> - <para> - In the resulting tree, the configurations for the specific - kernels shipped in &DISTRO; &DISTROVER; are in the - <filename>/configs/</filename> directory. For example, the i686 - SMP configuration file is named - <filename>/configs/kernel-<replaceable><version></replaceable>-i686-smp.config</filename>. - Issue the following command to place the desired configuration - file in the proper place for building: - </para> - <para> - <command>cp <replaceable><desired-file></replaceable> - ./.config</command> - </para> - </step> - <step> - <para> - Issue the following command: - </para> - <para> - <command>make oldconfig</command> - </para> - </step> - </procedure> - <para> - You can then proceed as usual. + --> + <section id="sn-kernel-exploding"> + <title> + Preparing for Kernel Development + </title> + <para> + &DISTRO; &DISTROVER; does not include the <filename>kernel-source</filename> package provided by older versions. + Instead, configured sources are available as described in <xref linkend="sn-kernel-flavors"/>. + Users that require access to &FC; original kernel sources can find them in the <filename>kernel</filename> <filename>.src.rpm</filename> package. + To create an exploded source tree from this file, perform the following steps: </para> - <tip> - <title>Source not required to build kernel modules</title> + <warning> + <title>These Instructions Refer The Currently-running Kernel!</title> + <para> + To simplify the following directions, we have assumed that you want to configure the kernel sources to match your currently-running kernel. + In the steps below, you must understand that the phrase <wordasword><version></wordasword> refers to the kernel version shown by the: + </para> + <screen width="56"><prompt>$ </prompt><command>uname</command> <parameter class="option">-r</parameter></screen> + <para> + command. + </para> + </warning> + <procedure id="sn-kernel-exploding-steps"> + <step> + <para> + Obtain the <filename>kernel-<replaceable><version></replaceable>.src.rpm</filename> file from one of the following sources: + </para> + <itemizedlist> + <listitem> + <para> + The <filename>SRPMS</filename> directory on the appropriate <wordasword>SRPMS</wordasword> <abbrev>CD</abbrev> <filename>iso</filename> image. + </para> + </listitem> + <listitem> + <para> + The FTP site where you got the kernel package. + </para> + </listitem> + <listitem> + <para> + By running the following command: + </para> + <screen width="56"><prompt># </prompt><command>up2date</command> <parameter class="option">--get-source</parameter> <filename>kernel</filename></screen> + </listitem> + </itemizedlist> + </step> + <step> + <para> + Install <filename>kernel-<replaceable><version></replaceable>.src.rpm</filename> using the command: + </para> + <screen width="56"><prompt># </prompt><command>rpm</command> <parameter class="option">-Uvh</parameter> <filename>kernel-</filename><replaceable><version></replaceable><filename>.src.rpm</filename></screen> + <para> + This writes the <abbrev>RPM</abbrev> contents into <filename>/usr/src/redhat/SOURCES</filename> and <filename>/usr/src/redhat/SPECS</filename>. + </para> + </step> + <step> + <para> + Prepare the kernel sources using the commands: + </para> + <screen width="56"><prompt># </prompt><command>cd</command> <filename>/usr/src/redhat/SPECS</filename> +<prompt># </prompt><command>rpmbuild</command> <parameter class="option">-bp --target $(arch)</parameter> <filename>kernel.spec</filename></screen> + <para> + The kernel source tree will be located in the <filename>/usr/src/redhat/BUILD/kernel-</filename><replaceable><version></replaceable> directory. + It is common practice to move the resulting <filename>linux-</filename><replaceable><version></replaceable> directory to the <filename>/usr/src</filename> tree; while not strictly necessary, we suggest that you do this to match the generally-available documentation. + </para> + <screen width="56"><prompt># </prompt><command>cd</command> <filename>/usr/src/redhat/BUILD/kernel-</filename><replaceable><version></replaceable> <filename>/usr/src/</filename> +<prompt># </prompt><command>mv</command> <filename>linux-</filename><replaceable><version></replaceable> <filename>/usr/src/</filename> +<prompt># </prompt><command>cd</command> <filename>/usr/src</filename> +<prompt># </prompt><command>ln</command> <parameter class="option">-s</parameter> <filename>./linux-</filename><replaceable><version></replaceable> <filename>linux</filename> +<prompt># </prompt><command>cd</command> <filename>/usr/src/linux</filename></screen> + </step> + <step> + <para> + The configurations for the specific kernels shipped in &DISTRO; &DISTROVER; are in the <filename>configs/</filename> directory. + For example, the i686 SMP configuration file is named <filename>configs/kernel-<replaceable><version></replaceable>-i686-smp.config</filename>. + Issue the following command to place the desired configuration file in the proper place for building: + </para> + <screen width="56"><prompt># </prompt><command>cp</command> <filename>configs/</filename><replaceable><desired-config-file></replaceable> <filename>.config</filename></screen> + </step> + <step> + <para> + Issue the following command: + </para> + <screen width="56"><prompt># </prompt><command>make oldconfig</command></screen> + </step> + </procedure> + <para> + You can then proceed as usual. + </para> + </section> + <section id="sn-kernel-3rdparty"> + <title>Building Only Kernel Modules</title> <para> - An exploded source tree is <emphasis>not</emphasis> required to - build kernel modules against the currently in-use kernel. + An exploded source tree is <emphasis>not</emphasis> required to build a kernel module, such as your own device driver, against the currently in-use kernel. </para> <para> - For example, to build the <filename>foo.ko</filename> module, - create the following file (named <filename>Makefile</filename>) in - the directory containing the <filename>foo.c</filename> file: + For example, to build the <filename>foo.ko</filename> module, create the following <filename>Makefile</filename> in the directory containing the <filename>foo.c</filename> file: </para> -<screen> -<computeroutput> -obj-m := foo.o +<programlisting width="56"> +obj-m := foo.o
-KDIR := /lib/modules/$(shell uname -r)/build -PWD := $(shell pwd) +KDIR := /lib/modules/$(shell uname -r)/build +PWD := $(shell pwd)
default: - $(MAKE) -C $(KDIR) SUBDIRS=$(PWD) modules -</computeroutput> -</screen> - <para> + $(MAKE) -C $(KDIR) M=$(PWD) modules +</programlisting> + <para> Issue the <command>make</command> command to build the <filename>foo.ko</filename> module. </para> - </tip> + </section> + <section id="sn-kernel-coop"> + <title>Userspace Dependancies on the Kernel</title> + <para> + &DISTRO; adds support for clustered systems. + This requires a special kernel that works in conjunction with some user-space utilities, such as management daemons. + Consequently, to remove such a kernel, perhaps after an update, you <emphasis>cannot</emphasis> simply use the <command>rpm -e kernel-</command><replaceable><version></replaceable> command as in earlier distributions because these userspace packages depend on the kernel package. + You may either list both the kernel package and its userspace dependant packages on the <command>rpm -e</command> command, or you may wish to use the <command>yum remove kernel-</command><replaceable><version></replaceable> command instead since <command>yum</command> automatically removes dependant packages if necesssary. + </para> + </section> </section> <!-- Local variables:
docs-commits@lists.fedoraproject.org