I suppose since these are commented out they don't affect anything
except ... well, I can't figure what. I'm soooo curious, how do they
make editing easier? Is it to keep track of the entities used?
BTW, I think your <screen> style is off from the style guidelines ...
http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-scre...
Some of your check-ins have funky indenting ... the <para> content is
two characters from the left. We all seem to have subtle differences.
Not sure how to resolve that.
When I get a chance, I'm going to first reformat kernel.xml, then
commit, then edit the content, all to make for a saner, happier diff.
This worked great, btw. Everyone formed like Voltron, really brought a
lot of good content and shine to the relnotes.
- Karsten
On Mon, 2005-05-30 at 19:27 -0400, Tommy Reynolds wrote:
+<!-- $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:
--
Fedora-docs-commits mailing list
Fedora-docs-commits(a)redhat.com
https://www.redhat.com/mailman/listinfo/fedora-docs-commits --
Karsten Wade, RHCE * Sr. Tech Writer *
http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41
Red Hat SELinux Guide
http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/