| 1 | .. _readme:
|
| 2 |
|
| 3 | Linux kernel release 6.x <http://kernel.org/>
|
| 4 | =============================================
|
| 5 |
|
| 6 | These are the release notes for Linux version 6. Read them carefully,
|
| 7 | as they tell you what this is all about, explain how to install the
|
| 8 | kernel, and what to do if something goes wrong.
|
| 9 |
|
| 10 | What is Linux?
|
| 11 | --------------
|
| 12 |
|
| 13 | Linux is a clone of the operating system Unix, written from scratch by
|
| 14 | Linus Torvalds with assistance from a loosely-knit team of hackers across
|
| 15 | the Net. It aims towards POSIX and Single UNIX Specification compliance.
|
| 16 |
|
| 17 | It has all the features you would expect in a modern fully-fledged Unix,
|
| 18 | including true multitasking, virtual memory, shared libraries, demand
|
| 19 | loading, shared copy-on-write executables, proper memory management,
|
| 20 | and multistack networking including IPv4 and IPv6.
|
| 21 |
|
| 22 | It is distributed under the GNU General Public License v2 - see the
|
| 23 | accompanying COPYING file for more details.
|
| 24 |
|
| 25 | On what hardware does it run?
|
| 26 | -----------------------------
|
| 27 |
|
| 28 | Although originally developed first for 32-bit x86-based PCs (386 or higher),
|
| 29 | today Linux also runs on (at least) the Compaq Alpha AXP, Sun SPARC and
|
| 30 | UltraSPARC, Motorola 68000, PowerPC, PowerPC64, ARM, Hitachi SuperH, Cell,
|
| 31 | IBM S/390, MIPS, HP PA-RISC, Intel IA-64, DEC VAX, AMD x86-64 Xtensa, and
|
| 32 | ARC architectures.
|
| 33 |
|
| 34 | Linux is easily portable to most general-purpose 32- or 64-bit architectures
|
| 35 | as long as they have a paged memory management unit (PMMU) and a port of the
|
| 36 | GNU C compiler (gcc) (part of The GNU Compiler Collection, GCC). Linux has
|
| 37 | also been ported to a number of architectures without a PMMU, although
|
| 38 | functionality is then obviously somewhat limited.
|
| 39 | Linux has also been ported to itself. You can now run the kernel as a
|
| 40 | userspace application - this is called UserMode Linux (UML).
|
| 41 |
|
| 42 | Documentation
|
| 43 | -------------
|
| 44 |
|
| 45 | - There is a lot of documentation available both in electronic form on
|
| 46 | the Internet and in books, both Linux-specific and pertaining to
|
| 47 | general UNIX questions. I'd recommend looking into the documentation
|
| 48 | subdirectories on any Linux FTP site for the LDP (Linux Documentation
|
| 49 | Project) books. This README is not meant to be documentation on the
|
| 50 | system: there are much better sources available.
|
| 51 |
|
| 52 | - There are various README files in the Documentation/ subdirectory:
|
| 53 | these typically contain kernel-specific installation notes for some
|
| 54 | drivers for example. Please read the
|
| 55 | :ref:`Documentation/process/changes.rst <changes>` file, as it
|
| 56 | contains information about the problems which may result from upgrading
|
| 57 | your kernel.
|
| 58 |
|
| 59 | Installing the kernel source
|
| 60 | ----------------------------
|
| 61 |
|
| 62 | - If you install the full sources, put the kernel tarball in a
|
| 63 | directory where you have permissions (e.g. your home directory) and
|
| 64 | unpack it::
|
| 65 |
|
| 66 | xz -cd linux-6.x.tar.xz | tar xvf -
|
| 67 |
|
| 68 | Replace "X" with the version number of the latest kernel.
|
| 69 |
|
| 70 | Do NOT use the /usr/src/linux area! This area has a (usually
|
| 71 | incomplete) set of kernel headers that are used by the library header
|
| 72 | files. They should match the library, and not get messed up by
|
| 73 | whatever the kernel-du-jour happens to be.
|
| 74 |
|
| 75 | - You can also upgrade between 6.x releases by patching. Patches are
|
| 76 | distributed in the xz format. To install by patching, get all the
|
| 77 | newer patch files, enter the top level directory of the kernel source
|
| 78 | (linux-6.x) and execute::
|
| 79 |
|
| 80 | xz -cd ../patch-6.x.xz | patch -p1
|
| 81 |
|
| 82 | Replace "x" for all versions bigger than the version "x" of your current
|
| 83 | source tree, **in_order**, and you should be ok. You may want to remove
|
| 84 | the backup files (some-file-name~ or some-file-name.orig), and make sure
|
| 85 | that there are no failed patches (some-file-name# or some-file-name.rej).
|
| 86 | If there are, either you or I have made a mistake.
|
| 87 |
|
| 88 | Unlike patches for the 6.x kernels, patches for the 6.x.y kernels
|
| 89 | (also known as the -stable kernels) are not incremental but instead apply
|
| 90 | directly to the base 6.x kernel. For example, if your base kernel is 6.0
|
| 91 | and you want to apply the 6.0.3 patch, you must not first apply the 6.0.1
|
| 92 | and 6.0.2 patches. Similarly, if you are running kernel version 6.0.2 and
|
| 93 | want to jump to 6.0.3, you must first reverse the 6.0.2 patch (that is,
|
| 94 | patch -R) **before** applying the 6.0.3 patch. You can read more on this in
|
| 95 | :ref:`Documentation/process/applying-patches.rst <applying_patches>`.
|
| 96 |
|
| 97 | Alternatively, the script patch-kernel can be used to automate this
|
| 98 | process. It determines the current kernel version and applies any
|
| 99 | patches found::
|
| 100 |
|
| 101 | linux/scripts/patch-kernel linux
|
| 102 |
|
| 103 | The first argument in the command above is the location of the
|
| 104 | kernel source. Patches are applied from the current directory, but
|
| 105 | an alternative directory can be specified as the second argument.
|
| 106 |
|
| 107 | - Make sure you have no stale .o files and dependencies lying around::
|
| 108 |
|
| 109 | cd linux
|
| 110 | make mrproper
|
| 111 |
|
| 112 | You should now have the sources correctly installed.
|
| 113 |
|
| 114 | Software requirements
|
| 115 | ---------------------
|
| 116 |
|
| 117 | Compiling and running the 6.x kernels requires up-to-date
|
| 118 | versions of various software packages. Consult
|
| 119 | :ref:`Documentation/process/changes.rst <changes>` for the minimum version numbers
|
| 120 | required and how to get updates for these packages. Beware that using
|
| 121 | excessively old versions of these packages can cause indirect
|
| 122 | errors that are very difficult to track down, so don't assume that
|
| 123 | you can just update packages when obvious problems arise during
|
| 124 | build or operation.
|
| 125 |
|
| 126 | Build directory for the kernel
|
| 127 | ------------------------------
|
| 128 |
|
| 129 | When compiling the kernel, all output files will per default be
|
| 130 | stored together with the kernel source code.
|
| 131 | Using the option ``make O=output/dir`` allows you to specify an alternate
|
| 132 | place for the output files (including .config).
|
| 133 | Example::
|
| 134 |
|
| 135 | kernel source code: /usr/src/linux-6.x
|
| 136 | build directory: /home/name/build/kernel
|
| 137 |
|
| 138 | To configure and build the kernel, use::
|
| 139 |
|
| 140 | cd /usr/src/linux-6.x
|
| 141 | make O=/home/name/build/kernel menuconfig
|
| 142 | make O=/home/name/build/kernel
|
| 143 | sudo make O=/home/name/build/kernel modules_install install
|
| 144 |
|
| 145 | Please note: If the ``O=output/dir`` option is used, then it must be
|
| 146 | used for all invocations of make.
|
| 147 |
|
| 148 | Configuring the kernel
|
| 149 | ----------------------
|
| 150 |
|
| 151 | Do not skip this step even if you are only upgrading one minor
|
| 152 | version. New configuration options are added in each release, and
|
| 153 | odd problems will turn up if the configuration files are not set up
|
| 154 | as expected. If you want to carry your existing configuration to a
|
| 155 | new version with minimal work, use ``make oldconfig``, which will
|
| 156 | only ask you for the answers to new questions.
|
| 157 |
|
| 158 | - Alternative configuration commands are::
|
| 159 |
|
| 160 | "make config" Plain text interface.
|
| 161 |
|
| 162 | "make menuconfig" Text based color menus, radiolists & dialogs.
|
| 163 |
|
| 164 | "make nconfig" Enhanced text based color menus.
|
| 165 |
|
| 166 | "make xconfig" Qt based configuration tool.
|
| 167 |
|
| 168 | "make gconfig" GTK based configuration tool.
|
| 169 |
|
| 170 | "make oldconfig" Default all questions based on the contents of
|
| 171 | your existing ./.config file and asking about
|
| 172 | new config symbols.
|
| 173 |
|
| 174 | "make olddefconfig"
|
| 175 | Like above, but sets new symbols to their default
|
| 176 | values without prompting.
|
| 177 |
|
| 178 | "make defconfig" Create a ./.config file by using the default
|
| 179 | symbol values from either arch/$ARCH/configs/defconfig
|
| 180 | or arch/$ARCH/configs/${PLATFORM}_defconfig,
|
| 181 | depending on the architecture.
|
| 182 |
|
| 183 | "make ${PLATFORM}_defconfig"
|
| 184 | Create a ./.config file by using the default
|
| 185 | symbol values from
|
| 186 | arch/$ARCH/configs/${PLATFORM}_defconfig.
|
| 187 | Use "make help" to get a list of all available
|
| 188 | platforms of your architecture.
|
| 189 |
|
| 190 | "make allyesconfig"
|
| 191 | Create a ./.config file by setting symbol
|
| 192 | values to 'y' as much as possible.
|
| 193 |
|
| 194 | "make allmodconfig"
|
| 195 | Create a ./.config file by setting symbol
|
| 196 | values to 'm' as much as possible.
|
| 197 |
|
| 198 | "make allnoconfig" Create a ./.config file by setting symbol
|
| 199 | values to 'n' as much as possible.
|
| 200 |
|
| 201 | "make randconfig" Create a ./.config file by setting symbol
|
| 202 | values to random values.
|
| 203 |
|
| 204 | "make localmodconfig" Create a config based on current config and
|
| 205 | loaded modules (lsmod). Disables any module
|
| 206 | option that is not needed for the loaded modules.
|
| 207 |
|
| 208 | To create a localmodconfig for another machine,
|
| 209 | store the lsmod of that machine into a file
|
| 210 | and pass it in as a LSMOD parameter.
|
| 211 |
|
| 212 | Also, you can preserve modules in certain folders
|
| 213 | or kconfig files by specifying their paths in
|
| 214 | parameter LMC_KEEP.
|
| 215 |
|
| 216 | target$ lsmod > /tmp/mylsmod
|
| 217 | target$ scp /tmp/mylsmod host:/tmp
|
| 218 |
|
| 219 | host$ make LSMOD=/tmp/mylsmod \
|
| 220 | LMC_KEEP="drivers/usb:drivers/gpu:fs" \
|
| 221 | localmodconfig
|
| 222 |
|
| 223 | The above also works when cross compiling.
|
| 224 |
|
| 225 | "make localyesconfig" Similar to localmodconfig, except it will convert
|
| 226 | all module options to built in (=y) options. You can
|
| 227 | also preserve modules by LMC_KEEP.
|
| 228 |
|
| 229 | "make kvm_guest.config" Enable additional options for kvm guest kernel
|
| 230 | support.
|
| 231 |
|
| 232 | "make xen.config" Enable additional options for xen dom0 guest kernel
|
| 233 | support.
|
| 234 |
|
| 235 | "make tinyconfig" Configure the tiniest possible kernel.
|
| 236 |
|
| 237 | You can find more information on using the Linux kernel config tools
|
| 238 | in Documentation/kbuild/kconfig.rst.
|
| 239 |
|
| 240 | - NOTES on ``make config``:
|
| 241 |
|
| 242 | - Having unnecessary drivers will make the kernel bigger, and can
|
| 243 | under some circumstances lead to problems: probing for a
|
| 244 | nonexistent controller card may confuse your other controllers.
|
| 245 |
|
| 246 | - A kernel with math-emulation compiled in will still use the
|
| 247 | coprocessor if one is present: the math emulation will just
|
| 248 | never get used in that case. The kernel will be slightly larger,
|
| 249 | but will work on different machines regardless of whether they
|
| 250 | have a math coprocessor or not.
|
| 251 |
|
| 252 | - The "kernel hacking" configuration details usually result in a
|
| 253 | bigger or slower kernel (or both), and can even make the kernel
|
| 254 | less stable by configuring some routines to actively try to
|
| 255 | break bad code to find kernel problems (kmalloc()). Thus you
|
| 256 | should probably answer 'n' to the questions for "development",
|
| 257 | "experimental", or "debugging" features.
|
| 258 |
|
| 259 | Compiling the kernel
|
| 260 | --------------------
|
| 261 |
|
| 262 | - Make sure you have at least gcc 8.1 available.
|
| 263 | For more information, refer to :ref:`Documentation/process/changes.rst <changes>`.
|
| 264 |
|
| 265 | - Do a ``make`` to create a compressed kernel image. It is also possible to do
|
| 266 | ``make install`` if you have lilo installed or if your distribution has an
|
| 267 | install script recognised by the kernel's installer. Most popular
|
| 268 | distributions will have a recognized install script. You may want to
|
| 269 | check your distribution's setup first.
|
| 270 |
|
| 271 | To do the actual install, you have to be root, but none of the normal
|
| 272 | build should require that. Don't take the name of root in vain.
|
| 273 |
|
| 274 | - If you configured any of the parts of the kernel as ``modules``, you
|
| 275 | will also have to do ``make modules_install``.
|
| 276 |
|
| 277 | - Verbose kernel compile/build output:
|
| 278 |
|
| 279 | Normally, the kernel build system runs in a fairly quiet mode (but not
|
| 280 | totally silent). However, sometimes you or other kernel developers need
|
| 281 | to see compile, link, or other commands exactly as they are executed.
|
| 282 | For this, use "verbose" build mode. This is done by passing
|
| 283 | ``V=1`` to the ``make`` command, e.g.::
|
| 284 |
|
| 285 | make V=1 all
|
| 286 |
|
| 287 | To have the build system also tell the reason for the rebuild of each
|
| 288 | target, use ``V=2``. The default is ``V=0``.
|
| 289 |
|
| 290 | - Keep a backup kernel handy in case something goes wrong. This is
|
| 291 | especially true for the development releases, since each new release
|
| 292 | contains new code which has not been debugged. Make sure you keep a
|
| 293 | backup of the modules corresponding to that kernel, as well. If you
|
| 294 | are installing a new kernel with the same version number as your
|
| 295 | working kernel, make a backup of your modules directory before you
|
| 296 | do a ``make modules_install``.
|
| 297 |
|
| 298 | Alternatively, before compiling, use the kernel config option
|
| 299 | "LOCALVERSION" to append a unique suffix to the regular kernel version.
|
| 300 | LOCALVERSION can be set in the "General Setup" menu.
|
| 301 |
|
| 302 | - In order to boot your new kernel, you'll need to copy the kernel
|
| 303 | image (e.g. .../linux/arch/x86/boot/bzImage after compilation)
|
| 304 | to the place where your regular bootable kernel is found.
|
| 305 |
|
| 306 | - Booting a kernel directly from a storage device without the assistance
|
| 307 | of a bootloader such as LILO or GRUB, is no longer supported in BIOS
|
| 308 | (non-EFI systems). On UEFI/EFI systems, however, you can use EFISTUB
|
| 309 | which allows the motherboard to boot directly to the kernel.
|
| 310 | On modern workstations and desktops, it's generally recommended to use a
|
| 311 | bootloader as difficulties can arise with multiple kernels and secure boot.
|
| 312 | For more details on EFISTUB,
|
| 313 | see "Documentation/admin-guide/efi-stub.rst".
|
| 314 |
|
| 315 | - It's important to note that as of 2016 LILO (LInux LOader) is no longer in
|
| 316 | active development, though as it was extremely popular, it often comes up
|
| 317 | in documentation. Popular alternatives include GRUB2, rEFInd, Syslinux,
|
| 318 | systemd-boot, or EFISTUB. For various reasons, it's not recommended to use
|
| 319 | software that's no longer in active development.
|
| 320 |
|
| 321 | - Chances are your distribution includes an install script and running
|
| 322 | ``make install`` will be all that's needed. Should that not be the case
|
| 323 | you'll have to identify your bootloader and reference its documentation or
|
| 324 | configure your EFI.
|
| 325 |
|
| 326 | Legacy LILO Instructions
|
| 327 | ------------------------
|
| 328 |
|
| 329 |
|
| 330 | - If you use LILO the kernel images are specified in the file /etc/lilo.conf.
|
| 331 | The kernel image file is usually /vmlinuz, /boot/vmlinuz, /bzImage or
|
| 332 | /boot/bzImage. To use the new kernel, save a copy of the old image and copy
|
| 333 | the new image over the old one. Then, you MUST RERUN LILO to update the
|
| 334 | loading map! If you don't, you won't be able to boot the new kernel image.
|
| 335 |
|
| 336 | - Reinstalling LILO is usually a matter of running /sbin/lilo. You may wish
|
| 337 | to edit /etc/lilo.conf to specify an entry for your old kernel image
|
| 338 | (say, /vmlinux.old) in case the new one does not work. See the LILO docs
|
| 339 | for more information.
|
| 340 |
|
| 341 | - After reinstalling LILO, you should be all set. Shutdown the system,
|
| 342 | reboot, and enjoy!
|
| 343 |
|
| 344 | - If you ever need to change the default root device, video mode, etc. in the
|
| 345 | kernel image, use your bootloader's boot options where appropriate. No need
|
| 346 | to recompile the kernel to change these parameters.
|
| 347 |
|
| 348 | - Reboot with the new kernel and enjoy.
|
| 349 |
|
| 350 |
|
| 351 | If something goes wrong
|
| 352 | -----------------------
|
| 353 |
|
| 354 | If you have problems that seem to be due to kernel bugs, please follow the
|
| 355 | instructions at 'Documentation/admin-guide/reporting-issues.rst'.
|
| 356 |
|
| 357 | Hints on understanding kernel bug reports are in
|
| 358 | 'Documentation/admin-guide/bug-hunting.rst'. More on debugging the kernel
|
| 359 | with gdb is in 'Documentation/process/debugging/gdb-kernel-debugging.rst' and
|
| 360 | 'Documentation/process/debugging/kgdb.rst'.
|