PR#47: Initial documentation for the kernel - fedora-docs/quick-docs

fedora-docs / quick-docs

#47 Initial documentation for the kernel

Merged 6 years ago by bex. Opened 6 years ago by jcline.

fedora-docs/ jcline/quick-docs kernel-docs into master

Initial documentation for the kernel

Jeremy Cline • 6 years ago

83bfbba

_topic_map.yml

file modified

+9 -4

		`@@ -80,6 +80,15 @@`
		`- 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 @@`
		`# 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 @@`
		`# 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`

en-US/build-custom-kernel.adoc

file removed

-170

		`@@ -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].`

en-US/kernel.adoc

file removed

-261

		`@@ -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.`

en-US/kernel/build-custom-kernel.adoc

file added

+294

		`@@ -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.6dave`
		`+ ----`
		`+`
		`+ 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`
		`+ ----`

en-US/kernel/overview.adoc

file added

+192

		`@@ -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.`

en-US/kernel/troubleshooting.adoc

file added

+97

		`@@ -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.`

jcline commented 6 years ago

This documentation is by no means complete, but it's a place to start
for solid 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.