hank-test/quick-docs
1
0
Fork 0
mirror of https://pagure.io/fedora-docs/quick-docs.git synced 2024-11-24 21:35:17 +00:00
Code Issues 1 Projects Releases Packages Wiki Activity Actions

Initial documentation for the kernel

Browse source 
This documentation is by no means complete, but it's a place to start
for pretty user-facing documentation for the kernel in Fedora. In
addition to the basic export from the wiki, this includes various other
related articles in the wiki which I thought might be good user-facing
documentation.

Signed-off-by: Jeremy Cline <jeremy@jcline.org>
This commit is contained in:
Jeremy Cline 2018-04-12 17:03:44 -04:00
parent 3b82eef7b3
commit 83bfbba379
No known key found for this signature in database
GPG key ID: 9223308FA9B246DB
6 changed files with 592 additions and 435 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
_topic_map.yml
View file

@ -80,6 +80,15 @@ Topics:
- Name: Fedora Release Life Cycle
File: fedora-life-cycle
- Name: NVIDIA Optimus Bumblebee
- Name: Kernel
Dir: kernel
Topics:
- Name: Overview
File: overview
- Name: Troubleshooting
File: troubleshooting
- Name: Building a Custom Kernel
File: build-custom-kernel
File: bumblebee
- Name: Creating GPG Keys
File: create-gpg-keys
@ -93,8 +102,6 @@ Topics:
# File: grub2
# - Name: (FIX ME!) AutoUpdates
# File: autoupdates
# - Name: (CHECK) Building a custom kernel
# File: build-custom-kernel
# - Name: (FIX ME!) How to debug Dracut problems
# File: debug-dracut-problems
# - Name: (FIX ME!) How to debug Systemd problems
@ -109,8 +116,6 @@ Topics:
# File: fedora-life-cycle
# - Name: (CHECK) Flash
# File: flash
# - Name: (FIX ME!) Kernel
# File: kernel
# - Name: (FIX ME!) Mirroring
# File: mirroring
# - Name: (FIX ME!) OpenH264

170
en-US/build-custom-kernel.adoc
View file

@ -1,170 +0,0 @@
[[ch-build-custom-kernel]]
= Building a Custom Kernel
[NOTE]
====
This document provides instructions for advanced users who want to rebuild the kernel from source.
Any issues with a custom kernel build are *not supported* by the Fedora kernel team.
====
[[sect-why-build-a-custom-kernel]]
== Why Build a Custom Kernel?
Some common reasons to build a custom kernel are to:
.. Change configuration options
.. Troubleshoot issues
.. Add patches
[[sect-preparing-to-build-a-custom-kernel]]
== Preparing to build a custom kernel
The Fedora kernel is just another package in Fedora and can be compiled like any other application.
The easiest way to compile the kernel is to use the tools provided by the `fedora-packager` package.
This will install basic tools like `fedpkg` which is used to download the kernel source code onto your computer.
To install `fedora-packager` from the command-line, enter:
[source,bash]
----
sudo dnf install fedora-packager
----
`fedpkg` will make a clone of the Fedora kernel from link:++http://pkgs.fedoraproject.org/cgit/rpms/kernel.git/++[pkg-git] into a directory called ‘kernel’.
By default, the source that is "checked out" will be the link:++https://fedoraproject.org/wiki/Releases/Rawhide++[Rawhide] kernel.
Each Fedora release has its own branch and you can change branches using `git` commands.
For example, to "check out" the source for Fedora 27, we would run the following commands:
[source,bash]
----
fedpkg co -a kernel
cd kernel
git checkout -b my_kernel origin/f27
----
This creates a git branch named 'my_kernel' containing the kernel source for Fedora 27.
[NOTE]
====
Be sure to change the version number to whatever version of Fedora you are using.
====
[[sect-building-the-kernel]]
== Building the kernel
The kernel has a number of build dependencies that can be installed with:
[source,bash]
----
sudo dnf builddep kernel.spec
----
Changes to kernel configuration options can be added to the file `config-local`.
When building a kernel for testing, it is best to use an identifiable name.
This makes it easy to distinguish your custom kernel from the official Fedora kernel builds.
Find the line in the `kernel.spec` file that says:
`# define buildid .local`
and change it to:
`%define buildid .my_kernel`
This will add _my_kernel_ to the the RPM package file names and will look something like this:
`kernel-4.15.3-300.my_kernel.fc27.src.rpm`
To build the packages enter:
[source,bash]
----
fedpkg local
----
This will create all the kernel packages in the `x86_64` directory (or the name of the architecture you are building for).
This will take a long time as it is creating all the kernel, module and debug packages.
Also, it will require over 12 GB of disk space.
If you want to create only the kernel and modules packages, you can use the `fast-build.sh` script.
First enter:
[source,bash]
----
fedpkg srpm
----
The result should look something like this:
`Wrote /current/path/kernel-4.15.3-300.my_kernel.fc27.src.rpm`
Now enter:
[source,bash]
----
./scripts/fast-build.sh x86_64 kernel-4.15.3-300.my_kernel.fc27.src.rpm
----
If you need to add patches use the script `newpatch.sh` like this:
[source,bash]
----
./scripts/newpatch.sh my-patch.patch
----
(where `my-patch.patch` is the file name of the patch.)
Once it is complete, you can install/update your system with your custom kernel build.
`cd` into the directory created in the kernel build process (`x86_64`, `x86`, etc.) and type:
[source,bash]
----
sudo dnf update kernel*.rpm
----
It will update any kernel packages you currently have installed on your computer.
[[sect-additional-resources]]
== Additional Resources:
For more information on building a custom kernel refer to the link:++https://fedoraproject.org/wiki/Building_a_custom_kernel++[Fedora Wiki: Building a Custom Kernel].
[[sect-credit]]
== Credits:
This document is an updated and edited version of the article link:++https://fedoramagazine.org/building-fedora-kernel/++[Building the Fedora Kernel] from the link:++https://fedoramagazine.org++[Fedora Magazine].

261
en-US/kernel.adoc
View file

@ -1,261 +0,0 @@
= Kernel
'''
[IMPORTANT]
======
This page was automatically converted from https://fedoraproject.org/wiki/Kernel
It is probably
* Badly formatted
* Missing graphics and tables that do not convert well from mediawiki
* Out-of-date
* In need of other love
Pull requests accepted at https://pagure.io/fedora-docs/quick-docs
Once you've fixed this page, remove this notice, and update
`_topic_map.yml`.
Once the document is live, go to the original wiki page and replace its text
with the following macro:
....
{{#fedoradocs: https://docs.fedoraproject.org/whatever-the-of-this-new-page}}
....
======
'''
Assorted information related to the Fedora Linux kernel.
[[current-versions]]
Current versions
----------------
[cols=",,,",]
|=======================================================================
|Release |Version |MotM |Comments
|F25 |4.13.x |labbott |
|F26 |4.13.x |labbott |
|F27 |4.13.x |labbott |
|Rawhide |Latest mainline (4.14.x) |jforbes |Pretty much always the
latest mainline tree.
|=======================================================================
Each upstream major kernel release has a maintainer that follows the
release through from merge window until it is no longer in a supported
Fedora release. The field above shows which kernel releases match up
with current Fedora releases, and who is maintaining that particular
kernel. For example, labbott is maintaining 4.4 kernels in Fedora 22 and
23, jforbes is maintaining 4.5 kernels in F24, and will maintain F22 and
F23 as they are rebased to 4.5. If in doubt, send mail to the kernel
list (info below) rather than individuals. The maintainers are part of
the link:Fedora_Engineering[Fedora Engineering] team.
[[fedora-kernel-mailing-list]]
Fedora kernel mailing list
--------------------------
For discussion about Fedora related kernel package issues only. For "my
kernel module doesn't work" type messages, see the
http://kernelnewbies.org list, or linux-kernel.
[[irc]]
IRC
---
Join the channel on freenode.net.
[[source-checkout-info]]
Source checkout info
--------------------
....
fedpkg co kernel
....
This gets you the git checkout and sets up branches for the current
releases and master (devel). Once you have switched to the branch you
care about (with git checkout branchname), fedpkg prep will create a
tree.
You'll then be left with a kernel-3.X.? directory, containing both an
unpatched 'vanilla-3.X.?' dir, and a linux-3.X.?-noarch hardlinked dir
which has the Fedora patches applied.
The above command will require you to have SSH access to the Fedora
pkg-git archives. If you want to do an anonymous checkout of the
sources, you can use:
....
fedpkg co -a kernel
....
[[contributing-to-the-fedora-kernel]]
Contributing to the Fedora kernel
---------------------------------
* If you are sending patches for the first time, there is a
link:Kernel/FirstKernelPatch[ guide] to help you.
* For one-off fixes, send them to the Fedora kernel mailing list, or if
they are relevant upstream, send them directly to
linux-kernel@vger.kernel.org and Fedora will inherit them on the next
rebase
* If you are sending lots of changes to the Fedora kernel, then it may
make more sense for you to get commit access. (Note, for most things,
sending them upstream is far more preferable).
* To request commit access to the Fedora kernel:
* Get a link:PackageMaintainers/Join[fedora account] if you don't
already have one
* Visit https://admin.fedoraproject.org/pkgdb/acls/name/kernel[the
package db entry for the kernel] and request access for the branch(es)
which interest you.
* *Please* subscribe to the mailing list above. Important announcements
regarding rebases, builds, patches being disabled, and much more happen
there.
* If you're interested in adding an out-of-tree driver or similar to the
Fedora kernel, please read KernelDriverPolicy first. See
KernelStagingPolicy also.
* Here is a brief overview of the link:Kernel/Spec[kernel.spec] file
[[building]]
Building
--------
Fedora's kernels are signed during the build via the pesign client on a
specific set of machines. To limit exposure of officially signed builds,
only certain people can successfully submit builds that will be tagged
into the various koji target tags. If you are not in this ACL then your
build will start, but it will fail in the final tagging step. Scratch
builds are not subject to this, so it is recommended to use that. If you
want the ability to build kernels that go out to end-users when you
'fedpkg build', you need to be in the ACLs that allow builds to be
tagged.
Please note the caveats on official builds.
* The kernel package currently builds many rpms, which means it ties up
the build system for hours at a time. For this reason, coordinate with
other developers on irc/fedora-kernel-list to be sure there isn't more
than one build happening at once.
* Rawhide gets pushed once a day. If you think a build may occur later
in the day for some reason, hold off on building. If in doubt, ask.
* If you are checking in patches for any branch other than rawhide, the
build won't automatically go out to users, it needs to be processed
through http://bodhi.fedoraproject.org[bodhi] . Consider the negative
effect of flooding end-users with too many updates, and coordinate your
builds with others so that we push updates containing more than one fix.
* For the end-user who wants to build a custom kernel, we offer a
separate wiki page link:Building_a_custom_kernel[ with complete
instructions].
[[updates]]
Updates
-------
[[process]]
Process
^^^^^^^
As mentioned above, updates have to go through bodhi. Below is the
process we use for filing a kernel update in bodhi.
* Fill in the package NVR, the bugs it fixes, and any notes you would
like to include. Normally this is simply "The stable update contains a
number of important fixes across the tree", or for a rebase "The rebase
contains improved hardware support, a number of new features, and many
important fixes across the tree."
* Ensure 'Suggest Reboot' is selected
* Ensure 'Enable karma automatism' is *not* selected
* Watch the commentary on the update, ensure bugs are filed for negative
karma, etc
* After the update has been in updates-testing for a decent amount of
time and has significantly positive karma (these are relative), push it
to stable.
With the wide variety of hardware and use cases Fedora users have, we
have found that enabling auto-karma can be detrimental. Often testers
will give positive karma for their use cases, hit the auto-karma limit,
and the update will be queued for stable before it even hits
updates-testing. That significantly reduces the tester pool and can
cause an update that introduces issues for a significant number of
people to be pushed to stable. We delay intentionally to try and catch
these cases. While we will never achieve a perfect update, it has helped
quite a bit.
[[schedule]]
Schedule
^^^^^^^^
For stable Fedora branches, the updates essentially follow the upstream
stable release schedule. Those tend to be released once a week or
slightly less frequently. We do the minor update, build and submit,
making sure that the N-1 update is in stable before pushing that release
(unless N-1 is very broken.) E.g. When 3.19.2 is released, we push it to
testing and make sure 3.19.1 is at least queued for stable. That way
bodhi doesn't obsolete the 3.19.1 update. When we have a major rebase
for a stable Fedora branch, we follow the same guidelines as above but
simply allow more time for people to test.
For a Fedora release in link:Releases/Branched[Branched] state, we tend
to file updates at each relevant upstream milestone release. E.g. if
that branch is working through the 4.0-rcX releases, we file an update
once per -rc. As the Fedora release gets closer to GA, the kernel being
shipped will transition to a stable upstream release. Then we
essentially follow the same steps as above.
As mentioned in the previous section, Rawhide does not use bodhi for
updates.
[[policies]]
Policies
--------
Below are some of the policies we use when it comes to various aspects
of the Fedora kernel
* KernelRebases
* KernelDriverPolicy
* KernelStagingPolicy
* KernelBuiltinPolicy
* Information on the various debugging options used in Fedora kernels
can be found at KernelDebugStrategy
[[other-handy-links]]
Other handy links
-----------------
* link:Kernel/TaskWishList[ Contribution ideas for the Fedora kernel ]
* link:Kernel/SubmittingUpstream[ How to submit a patch upstream]
* link:Kernel/DayToDay[ How to do various day to day tasks]
* KernelCommonProblems
* KernelBugTriage
* link:Building_a_custom_kernel[Building a custom kernel]
* link:Building_a_custom_kernel#Building_a_non-debugging_kernel[
Building a non-debugging kernel ]
* link:How_to_use_kdump_to_debug_kernel_crashes[How to use kdump to
debug kernel crashes]
* link:Kernel/EarlyDebugging[ How to debug very early kernel panics]
* Information on building upstream kernels by hand for testing can be
found at link:Building_a_custom_kernel#Building_Vanilla_upstream_kernel[
Building a vanilla kernel]
* https://admin.fedoraproject.org/updates/kernel[Kernel Updates]
* KernelTestingInitiative
* QA:Testcase_kernel_regression
* RawhideKernelNodebug The repository for rawhide kernels built without
debugging enabled.
* link:Kernel/UsbmonOuput[ Capturing USBMON output]
'''
See a typo, something missing or out of date, or anything else which can be
improved? Edit this document at https://pagure.io/fedora-docs/quick-docs.

294
en-US/kernel/build-custom-kernel.adoc Normal file
View file

@ -0,0 +1,294 @@
[[ch-build-custom-kernel]]
= Building a Custom Kernel
:toc:
This document provides instructions for advanced users who want to rebuild the
kernel from some source.
[NOTE]
====
When building or running a custom kernel, one should *not* expect support from
the Fedora kernel team.
====
Some common reasons to build a custom kernel are:
* To apply patches for testing that they either generated or obtained from
another source
* To reconfigure the existing kernel
* To learn more about the kernel and kernel development
== Get the Dependencies
The easiest way to install all the build dependencies for the kernel is to use
the Fedora kernel spec file:
[source,bash]
----
sudo dnf install fedpkg
fedpkg clone -a kernel
cd kernel
sudo dnf builddep kernel.spec
----
Make sure you add the user doing the build to `/etc/pesign/users` and run the
authorize user script:
[source,bash]
----
sudo /usr/libexec/pesign/pesign-authorize
----
It's also recommended that you install `ccache`, which can help speed up
rebuilds:
[source,bash]
----
sudo dnf install ccache
----
== Building a Kernel from the Fedora dist-git
The kernel, like any other Fedora package, has a branch per Fedora release.
`master` corresponds to Rawhide and each version of Fedora has a branch called
`f<version>`. For example, to build a Fedora 28 kernel, you would first need
to check out that branch with:
1. Check out the branch for which you would like to build a kernel (`master`
corresponds to Rawhide):
[source,bash]
----
git checkout origin/f28
----
2. To avoid conflicts with existing kernels, you can set a custom buildid by
changing `# define buildid .local` to `%define buildid .<your_custom_id_here>`
in `kernel.spec`.
3. Make whatever changes or customizations you need.
4. Build the RPMs:
[source,bash]
----
fedpkg local
----
5. Install the new kernel:
[source,bash]
----
sudo dnf install --nogpgcheck ./x86_64/kernel-$version.rpm
----
=== Building a non-debugging kernel
Most Rawhide kernels are built with debugging enabled by default. To make a
kernel with debugging options disabled, you can follow the above instructions,
but before you run `fedpkg local`, disable the debugging options with:
[source,bash]
----
make release
----
=== Enabling configuration options
If there are configuration options that need to be adjusted for your build, you
can add changes in the kernel-local file. These changes will get picked up when
you build.
== Building a kernel from the exploded git trees
Fedora keeps a git tree containing Fedora patches applied on top of the vanilla sources.
[source,bash]
----
git clone git://git.kernel.org/pub/scm/linux/kernel/git/jwboyer/fedora.git
git checkout -b my_branch kernel-4.7.4-200.fc24
----
You can now build the kernel following regular kernel instructions. This tree
is useful for generating patches that can be applied to the kernel.spec.
== Building a vanilla upstream kernel
Sometimes a Fedora developer may ask you to try building and installing an
upstream kernel (possibly with a patch added) for testing. If there are
multiple iterations, it may be quicker for you to do this than for the
developer to turn around several RPMs.
[NOTE]
====
There is an effort underway for packaging vanilla kernels.
https://fedoraproject.org/wiki/Kernel_Vanilla_Repositories[See if this meets
your needs first]
====
=== Getting the Sources
Clone the kernel tree from kernel.org. If you don't know what tree you need,
you should get Linus' tree:
[source,bash]
----
git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
cd linux
----
You may also want the stable tree (4.y.z releases), which you can add with:
[source,bash]
----
git remote add -f stable git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git
----
=== Applying patches
To apply patch files, you can use git-am:
[source,bash]
----
git am -3 <patch file>
----
=== Configuring the kernel
If the developer has pointed you at a specific config file to use, save it in
the linux directory with the filename `.config`
Otherwise, you'll need to pick a configuration file to start from. The Linux
kernel has thousands of configuration options, so you don't want to start from
scratch unless you know what you're doing.
==== Starting from an installed kernel configuration
If you want to tweak the configuration of a kernel you already have installed,
you can start with its configuration which is stored in /boot/. For example,
to start with the configuration of the currently running kernel:
[source,bash]
----
cp /boot/config-`uname -r`* .config
----
==== Starting from dist-git
If you want to use the configuration for a kernel you do not have installed,
you can get the configuration from the Fedora dist-git repository. For example,
to start with the latest Rawhide configuration:
[source,bash]
----
cd <dist-git directory>
git checkout master
./build_configs.sh # Ensure the latest configuration files are generated
cp kernel-<arch>.config <linux kernel directory>.config
----
The debug versions of the configuration files are in
`kernel-<arch>-debug.config` if you would like to build a kernel with debugging
options enabled.
=== Changing the configuration
There are several ways to change the configuration. You can run `make help` and
look at the `Configuration targets` for the full list, but `make menuconfig`
is a good place to start. You can also just edit the `.config` file directly.
[NOTE]
====
If you plan to run `make xconfig`:
[source,bash]
----
sudo dnf install qt3-devel libXi-devel gcc-c++
----
====
=== Building the kernel
Once you've configured the kernel, you're ready to build it. Before you do so,
you'll want to change the `EXTRAVERSION` in the `Makefile` to something you'll
recognize later. For example, if it reads `EXTRAVERSION = -rc5` change it to
`EXTRAVERSION = -rc5-dave`:
[source,bash]
----
$EDITOR Makefile
----
Now you're ready to build the kernel:
[source,bash]
----
make oldconfig
make bzImage
make modules
----
=== Installing the kernel
Installing the kernel is as simple as:
[source,bash]
----
sudo make modules_install
sudo make install
----
=== Rebuilding
If you have been asked to try several different things, the procedure once you
have already built the tree once is mostly the same. Running `make clean` is
recommended between builds. This will leave the `.config` in place, so you can
skip that step above and proceed straight to the `make bzImage` part of the steps
above. Because we installed `ccache` in the first step, subsequent builds may go
a lot faster as the compiler hits files that haven't changed since the last
time it built them.
=== Cleaning up
Once you have tested the kernel, and you've booted back to one of your kernels
installed from an RPM, you can clean up the files that the above procedure
installed.
[WARNING]
====
When running the following commands, be sure to get the kernel version correct!
====
Because you changed `EXTRAVERSION` in the `Makefile` to add a 'tag', all the
files it installed will have this as part of the filename. So you should be
able to use wildcards to delete them safely using commands similar to those
below (just replace 'dave' with whatever tag you chose):
[source,bash]
----
rm -f /boot/config-2.6.*dave* /boot/initrd-2.6.*dave* /boot/vmlinuz-*dave* /boot/System.map-*dave*
rm -rf /lib/modules/2.6*dave*
----
Finally, you will need to remove the kernel as an option to your bootloader.
This will change from architecture to architecture. For x86, (as root), edit
`/boot/grub2/grub.cfg` or `/boot/efi/EFI/fedora/grub.cfg` if you have EFI enabled
and delete the four lines relating to your kernel (They should be easy to spot,
they'll be the ones with your tag). They'll look something like:
----
title Fedora Core (2.6.22-rc3-dave)
root (hd0,0)
kernel /vmlinuz-2.6.22-rc3-dave ro root=/dev/md0
initrd /initrd-2.6.22-rc3-dave.img
----

192
en-US/kernel/overview.adoc Normal file
View file

@ -0,0 +1,192 @@
= Fedora Linux Kernel Overview
:toc:
[[section-update-schedule]]
== Update Schedule
The https://src.fedoraproject.org/rpms/kernel[Fedora Linux kernel] closely
follows the upstream https://www.kernel.org/[kernel releases]. To see the
current versions in Fedora, https://apps.fedoraproject.org/packages/kernel[check
out the packages application].
=== Stable Releases
Stable releases of Fedora receive two types of kernel updates.
==== Stable kernel updates
The upstream kernel community support the latest major version with stable
updates (4.y.z releases). These updates are released approximately once a week,
although they can occur more or less frequently. Once the upstream kernel
community makes a stable release, Fedora builds it and submits it as an update
to https://bodhi.fedoraproject.org/updates/?packages=kernel[Bodhi]. These
updates are typically left in Bodhi for testing for several days before being
submitted to the stable updates repository.
==== Major kernel updates
The Linux kernel releases new major versions (4.y releases)
http://phb-crystal-ball.org/[every few months]. When this occurs, Fedora updates
to the new major version after a couple upstream stable releases. When the
updates are submitted to Bodhi, more time is allowed for testing than stable
updates to ensure there are no serious regressions.
=== Development Releases
The development versions of Fedora include Rawhide and the Branched release.
==== Rawhide
The Rawhide kernel is the latest git snapshot of Linus'
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/[upstream
kernel.org tree]. On a frequent (often daily) basis, a new snapshot is built.
==== Branched
https://fedoraproject.org/wiki/Releases/Branched[Branched releases] receive
updates at less frequent intervals than Rawhide. Early on in the Branched
release, it is typically using a pre-release version of the kernel, so each
Release Candidate (RC) is built for Branched releases. Once the kernel is
released, it receives stable updates just like the stable Fedora releases.
[[debug-kernels]]
== Debug Kernels
The Linux kernel offers a number of configuration options to make debugging
problems easier. However, some of these options have a performance cost so
Fedora does not always turn these options on. When the debugging options have
been turned off in the ``kernel`` package, a separate ``kernel-debug`` package
is produced with those options on.
=== Stable and Branched Kernels
Stable and Branched kernels always disable the debugging options.
=== Rawhide
Rawhide kernels enable the debugging options. However, each release candidate
kernel is built with debugging options disabled. Release candidate kernels
can be recognized by their release field, which always has the git revision set
to 0. For example, ``kernel-4.16.0-0.rc7.git0.1.fc28`` is the 7th release
candidate kernel for Fedora 28.
== Policies
=== Out-of-tree Drivers
The simplest method by far is for the driver to get merged upstream in Linus'
kernel. Fedora constantly rebases to newer upstream releases, so inherits these
changes "for free" with little overhead for the Fedora kernel maintainers.
Adding external drivers to the Fedora kernel that aren't accepted upstream
requires an ongoing effort for the Fedora kernel team, so where possible, we
try to avoid doing so. In the few situations where it makes sense to do so,
there are several criteria that must be met.
* There must be reasonable demand for the feature for us taking on the burden
of carrying the code until it gets upstream.
* Passes basic sanity checks (has been reviewed by at least one Fedora kernel
maintainer).
* Has an upstream developer actively trying to get their code merged into Linus'
tree.
* Has a Fedora developer responsible for keeping it up to date in Fedora.
* Causes no discernible overhead for Fedora kernel maintainers. Code that must
be continually fixed up tends to end up getting dropped.
* Doesn't add new system calls or similar ABI defining characteristics. This is
to avoid a situation where we could end up with incompatibilities between
distros/upstream.
* How a symbol is exported needs to be accepted upstream first. This includes:
** Adding an EXPORT_SYMBOL to export something that previously wasn't exported
** Changing an EXPORT_SYMBOL_GPL to EXPORT_SYMBOL
** Changing an EXPORT_SYMBOL to EXPORT_SYMBOL_GPL
* In the rare case where we add exports that aren't upstream, we err on the side
of caution and use EXPORT_SYMBOL_GPL to export them. This is done partly as a
deterrent for 3rd-party modules not to use them. (As they may go away in the
future). The only exception to all of the above is in new not-yet-merged
upstream code that's being added. New symbols get to be exported however the
author intended.
=== Staging
The drivers in the staging directory of the Linux kernel are known to be in a
rough and incomplete state. For the vast majority of these drivers, the kernel
team considers it unsafe to build and ship them. We do not have the confidence
in the existing code, nor do we have the time to debug issues in known
problematic drivers.
As with every policy, there are exceptions. Fedora ships a few staging drivers
at the moment for various pieces of hardware. For the Fedora kernel team to
enable a staging driver, the following conditions must be satisfied:
* There must be substantive code review and improvement upstream. This means
actual fixes, and not just stylistic changes.
* There must be a contributor willing to be assigned bug reports and deal with
upstream.
* The contributor must be actively involved improving the driver upstream.
* The driver must not result in an undue burden on the kernel team. This means
that if a large number of bug reports result from the driver, then fixes are
not occurring upstream quickly enough.
* It must be understood that if any of these conditions are not met, or
eventually fail to be met, the driver will be disabled.
=== Builtin Features
From time to time, the Fedora kernel maintainers get asked to build something
into the kernel. That is, the functionality is included in the vmlinux binary
that every Fedora machine runs as opposed to being built as a module that is
only loaded if needed. Given that it is loaded on every machine, we tend to
build functionality as modules as much as possible. While one person might need
the driver for an ATI card, another will not and having that built into the
kernel is wasteful for really no reason.
There are no set criteria that map exactly to whether something is built-in or
not, but they generally follow these guidelines:
* The option cannot be built as a module and is widely used
* The option is not a driver/filesystem and used by something that is a Fedora
default
* The option is a driver and used by a wide variety of machines (keyboard/mouse
drivers, VT support)
* The option is a filesystem and is used by all machines or is the default
Fedora filesystem (tmpfs, ext4).
Again, the above are general guidelines but for the most part we try and limit
the overall size of the vmlinux that is loaded to a core set of functionality.
If you find that the Fedora configuration options are not sufficient for your
needs, you can rebuild the kernel and change options as you see fit. See the
documentation on <<build-custom-kernel.adoc#,building a custom kernel>>.
[[community]]
== Getting Involved
If you're interested in contributing to the development and maintenance of the
Fedora kernel, check out the https://fedoraproject.org/wiki/Kernel[kernel wiki]
for more information.
[[mailing-lists]]
=== Mailing Lists
The mailto:kernel@lists.fedoraproject.org[Fedora kernel mailing list] is for
Fedora-related kernel topics only. This includes Fedora-specific packaging and
kernel configuration settings. For discussions about Linux itself see the
https://kernelnewbies.org/ML[Kernelnewbies mailing lists] or the
http://vger.kernel.org/vger-lists.html[Linux Kernel mailing lists].
You can subscribe to the Fedora kernel mailing list and view the archive on
https://lists.fedoraproject.org/archives/list/kernel@lists.fedoraproject.org/[
Hyperkitty].
[[irc]]
=== IRC
Users interested in the Fedora kernel hang out in the ``#fedora-kernel`` channel
on https://freenode.net[freenode].
'''
See a typo, something missing or out of date, or anything else which can be
improved? Edit this document at https://pagure.io/fedora-docs/quick-docs.

97
en-US/kernel/troubleshooting.adoc Normal file
View file

@ -0,0 +1,97 @@
= Troubleshooting
The kernel, like any software, has bugs. It's a large, complex project and it
can be difficult to troubleshoot problems. This document covers some basic
troubleshooting techniques to help narrow down the root cause of an issue.
== Boot failures
Sometimes the kernel fails to boot. Depending on where the problem is in the
boot process, there may or may not be any output. Some good first steps are:
* Remove `quiet` (enable more log messages) and `rhgb` (disable graphical boot)
from the boot flags. If the text output is too fast to read, add
`boot_delay=1000` (the number of milliseconds to delay in
between printk during boot). You can use a camera to take pictures of the
output.
* Booting with vga=791 (or even just vga=1 if the video card won't support 791)
will put the framebuffer into high resolution mode to get more lines of text
on screen, allowing more context for bug analysis.
* Add `initcall_debug` parameter, which traces the initcalls as they are
executed.
* If you get no output at all from the kernel, sometimes booting with
`earlyprintk=vga` can sometimes yield something of interest.
== Hangs and freezes
* Checking whether or not the CapsLock key (or NumLock or ScrollLock) causes
the light on the keyboard to change state can be used as an indication of
whether or not the kernel has hung completely, or if there is something else
going on.
* The SysRq magic keys may still work. You may need to add
`sysrq_always_enabled=1` to the kernel boot command line. See
https://fedoraproject.org/wiki/QA/Sysrq[the wiki article on SysRq on usage
details].
* Setting `nmi_watchdog=1` on the kernel command line will cause a panic when
an NMI watchdog timeout occurs.
== Bisecting the kernel
If the problem you've encountered isn't present in older versions of the
kernel, it is very helpful to use `git-bisect` to find the commit that
introduced the problem. For a general overview of `git-bisect`, see its
https://git-scm.com/docs/git-bisect[documentation]. An outline on how to bisect
the kernel is included in the
https://www.kernel.org/doc/html/latest/admin-guide/bug-bisect.html[kernel
documentation]. This guide contains Fedora-specific details.
[NOTE]
====
Bisecting is a time-consuming task, but it's very straightforward and is
often the best way to find the cause of a problem. If you're really interested
in getting the problem you're seeing fixed, bisecting will speed up the process
considerably in most cases.
====
. Find the newest version you can that works. This will be the initial "good"
version. The first version you find that doesn't work will be the initial "bad"
version.
. Install the <<build-custom-kernel.adoc#get-the-dependencies,dependencies>>
required to build the kernel
. Next, <<build-custom-kernel.adoc#getting-the-sources,get the source code>>.
. Prepare a `.config` file. Assuming you've got both the good and bad kernel
installed, the config for both will be in `/boot/`.footnote:[When bisecting
between major versions (e.g. `v4.16` and `v4.15`) new configuration options
will be added and removed as you bisect. It's _usually_ safe to select the
default.]
. Start a new `git-bisect` with `git bisect start <bad> <good>`.
. <<build-custom-kernel.adoc#building-the-kernel,Build the kernel>>. Sometimes
commits cannot be built. If this happens, skip the commit with `git bisect
skip`.
. <<build-custom-kernel.adoc#installing-the-kernel,Install the kernel>>.
. Reboot into the new kernel and test to see if the it works.
. If the new kernel works, mark it as good with `git bisect good`. Otherwise,
mark it as bad with `git bisect bad`.
. Check out the next commit to test by running `git bisect next`.
. Repeat the previous five steps until you've found the commit that introduced
the problem.