From 83bfbba379913425efe48bf32b66bcfa07ecb953 Mon Sep 17 00:00:00 2001 From: Jeremy Cline Date: Thu, 12 Apr 2018 17:03:44 -0400 Subject: [PATCH] Initial documentation for the kernel 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 --- _topic_map.yml | 13 +- en-US/build-custom-kernel.adoc | 170 --------------- en-US/kernel.adoc | 261 ----------------------- en-US/kernel/build-custom-kernel.adoc | 294 ++++++++++++++++++++++++++ en-US/kernel/overview.adoc | 192 +++++++++++++++++ en-US/kernel/troubleshooting.adoc | 97 +++++++++ 6 files changed, 592 insertions(+), 435 deletions(-) delete mode 100644 en-US/build-custom-kernel.adoc delete mode 100644 en-US/kernel.adoc create mode 100644 en-US/kernel/build-custom-kernel.adoc create mode 100644 en-US/kernel/overview.adoc create mode 100644 en-US/kernel/troubleshooting.adoc diff --git a/_topic_map.yml b/_topic_map.yml index d397db5..4103b04 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -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 diff --git a/en-US/build-custom-kernel.adoc b/en-US/build-custom-kernel.adoc deleted file mode 100644 index 13fce35..0000000 --- a/en-US/build-custom-kernel.adoc +++ /dev/null @@ -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]. diff --git a/en-US/kernel.adoc b/en-US/kernel.adoc deleted file mode 100644 index 6598e87..0000000 --- a/en-US/kernel.adoc +++ /dev/null @@ -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. diff --git a/en-US/kernel/build-custom-kernel.adoc b/en-US/kernel/build-custom-kernel.adoc new file mode 100644 index 0000000..cd9ef31 --- /dev/null +++ b/en-US/kernel/build-custom-kernel.adoc @@ -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`. 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 .` +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 +---- + +=== 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 +git checkout master +./build_configs.sh # Ensure the latest configuration files are generated +cp kernel-.config .config +---- + +The debug versions of the configuration files are in +`kernel--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 +---- diff --git a/en-US/kernel/overview.adoc b/en-US/kernel/overview.adoc new file mode 100644 index 0000000..0f39926 --- /dev/null +++ b/en-US/kernel/overview.adoc @@ -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 <>. + + +[[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. diff --git a/en-US/kernel/troubleshooting.adoc b/en-US/kernel/troubleshooting.adoc new file mode 100644 index 0000000..680eff7 --- /dev/null +++ b/en-US/kernel/troubleshooting.adoc @@ -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 <> +required to build the kernel + +. Next, <>. + +. 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 `. + +. <>. Sometimes +commits cannot be built. If this happens, skip the commit with `git bisect +skip`. + +. <>. + +. 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.