1 .. _readme:
2
3 Linux kernel release 6.x <http://kernel.org/>
4 =============================================
5
6 These are the release notes for Linux version
7 as they tell you what this is all about, expla
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 Uni
14 Linus Torvalds with assistance from a loosel
15 the Net. It aims towards POSIX and Single UN
16
17 It has all the features you would expect in
18 including true multitasking, virtual memory,
19 loading, shared copy-on-write executables, p
20 and multistack networking including IPv4 and
21
22 It is distributed under the GNU General Publ
23 accompanying COPYING file for more details.
24
25 On what hardware does it run?
26 -----------------------------
27
28 Although originally developed first for 32-b
29 today Linux also runs on (at least) the Comp
30 UltraSPARC, Motorola 68000, PowerPC, PowerPC
31 IBM S/390, MIPS, HP PA-RISC, Intel IA-64, DE
32 ARC architectures.
33
34 Linux is easily portable to most general-pur
35 as long as they have a paged memory manageme
36 GNU C compiler (gcc) (part of The GNU Compil
37 also been ported to a number of architecture
38 functionality is then obviously somewhat lim
39 Linux has also been ported to itself. You ca
40 userspace application - this is called UserM
41
42 Documentation
43 -------------
44
45 - There is a lot of documentation available b
46 the Internet and in books, both Linux-speci
47 general UNIX questions. I'd recommend look
48 subdirectories on any Linux FTP site for th
49 Project) books. This README is not meant t
50 system: there are much better sources avail
51
52 - There are various README files in the Docum
53 these typically contain kernel-specific ins
54 drivers for example. Please read the
55 :ref:`Documentation/process/changes.rst <ch
56 contains information about the problems, wh
57 your kernel.
58
59 Installing the kernel source
60 ----------------------------
61
62 - If you install the full sources, put the ke
63 directory where you have permissions (e.g.
64 unpack it::
65
66 xz -cd linux-6.x.tar.xz | tar xvf -
67
68 Replace "X" with the version number of the
69
70 Do NOT use the /usr/src/linux area! This ar
71 incomplete) set of kernel headers that are
72 files. They should match the library, and
73 whatever the kernel-du-jour happens to be.
74
75 - You can also upgrade between 6.x releases b
76 distributed in the xz format. To install b
77 newer patch files, enter the top level dire
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 th
83 source tree, **in_order**, and you should b
84 the backup files (some-file-name~ or some-f
85 that there are no failed patches (some-file
86 If there are, either you or I have made a m
87
88 Unlike patches for the 6.x kernels, patches
89 (also known as the -stable kernels) are not
90 directly to the base 6.x kernel. For examp
91 and you want to apply the 6.0.3 patch, you
92 and 6.0.2 patches. Similarly, if you are ru
93 want to jump to 6.0.3, you must first rever
94 patch -R) **before** applying the 6.0.3 pat
95 :ref:`Documentation/process/applying-patche
96
97 Alternatively, the script patch-kernel can
98 process. It determines the current kernel
99 patches found::
100
101 linux/scripts/patch-kernel linux
102
103 The first argument in the command above is
104 kernel source. Patches are applied from th
105 an alternative directory can be specified a
106
107 - Make sure you have no stale .o files and de
108
109 cd linux
110 make mrproper
111
112 You should now have the sources correctly i
113
114 Software requirements
115 ---------------------
116
117 Compiling and running the 6.x kernels requi
118 versions of various software packages. Con
119 :ref:`Documentation/process/changes.rst <ch
120 required and how to get updates for these p
121 excessively old versions of these packages
122 errors that are very difficult to track dow
123 you can just update packages when obvious p
124 build or operation.
125
126 Build directory for the kernel
127 ------------------------------
128
129 When compiling the kernel, all output files
130 stored together with the kernel source code
131 Using the option ``make O=output/dir`` allo
132 place for the output files (including .conf
133 Example::
134
135 kernel source code: /usr/src/linux-6.x
136 build directory: /home/name/build/kern
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 modul
144
145 Please note: If the ``O=output/dir`` option
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
152 version. New configuration options are add
153 odd problems will turn up if the configurat
154 as expected. If you want to carry your exi
155 new version with minimal work, use ``make o
156 only ask you for the answers to new questio
157
158 - Alternative configuration commands are::
159
160 "make config" Plain text interface.
161
162 "make menuconfig" Text based color menus
163
164 "make nconfig" Enhanced text based co
165
166 "make xconfig" Qt based configuration
167
168 "make gconfig" GTK+ based configurati
169
170 "make oldconfig" Default all questions
171 your existing ./.confi
172 new config symbols.
173
174 "make olddefconfig"
175 Like above, but sets n
176 values without prompti
177
178 "make defconfig" Create a ./.config fil
179 symbol values from eit
180 or arch/$ARCH/configs/
181 depending on the archi
182
183 "make ${PLATFORM}_defconfig"
184 Create a ./.config fil
185 symbol values from
186 arch/$ARCH/configs/${P
187 Use "make help" to get
188 platforms of your arch
189
190 "make allyesconfig"
191 Create a ./.config fil
192 values to 'y' as much
193
194 "make allmodconfig"
195 Create a ./.config fil
196 values to 'm' as much
197
198 "make allnoconfig" Create a ./.config fil
199 values to 'n' as much
200
201 "make randconfig" Create a ./.config fil
202 values to random value
203
204 "make localmodconfig" Create a config bas
205 loaded modules (lsm
206 option that is not
207
208 To create a localmo
209 store the lsmod of
210 and pass it in as a
211
212 Also, you can prese
213 or kconfig files by
214 parameter LMC_KEEP.
215
216 target$ lsmod > /tmp/mylsmo
217 target$ scp /tmp/mylsmod ho
218
219 host$ make LSMOD=/tmp/mylsm
220 LMC_KEEP="drivers/u
221 localmodconfig
222
223 The above also work
224
225 "make localyesconfig" Similar to localmod
226 all module options
227 also preserve modul
228
229 "make kvm_guest.config" Enable addition
230 support.
231
232 "make xen.config" Enable additional opt
233 support.
234
235 "make tinyconfig" Configure the tiniest
236
237 You can find more information on using the
238 in Documentation/kbuild/kconfig.rst.
239
240 - NOTES on ``make config``:
241
242 - Having unnecessary drivers will make the
243 under some circumstances lead to problem
244 nonexistent controller card may confuse
245
246 - A kernel with math-emulation compiled in
247 coprocessor if one is present: the math
248 never get used in that case. The kernel
249 but will work on different machines rega
250 have a math coprocessor or not.
251
252 - The "kernel hacking" configuration detai
253 bigger or slower kernel (or both), and c
254 less stable by configuring some routines
255 break bad code to find kernel problems (
256 should probably answer 'n' to the questi
257 "experimental", or "debugging" features.
258
259 Compiling the kernel
260 --------------------
261
262 - Make sure you have at least gcc 5.1 availab
263 For more information, refer to :ref:`Docume
264
265 - Do a ``make`` to create a compressed kernel
266 ``make install`` if you have lilo installed
267 install script recognised by the kernel's i
268 distributions will have a recognized instal
269 check your distribution's setup first.
270
271 To do the actual install, you have to be ro
272 build should require that. Don't take the n
273
274 - If you configured any of the parts of the k
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
280 totally silent). However, sometimes you or
281 to see compile, link, or other commands exa
282 For this, use "verbose" build mode. This i
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 reas
288 target, use ``V=2``. The default is ``V=0`
289
290 - Keep a backup kernel handy in case somethin
291 especially true for the development release
292 contains new code which has not been debugg
293 backup of the modules corresponding to that
294 are installing a new kernel with the same v
295 working kernel, make a backup of your modul
296 do a ``make modules_install``.
297
298 Alternatively, before compiling, use the ke
299 "LOCALVERSION" to append a unique suffix to
300 LOCALVERSION can be set in the "General Set
301
302 - In order to boot your new kernel, you'll ne
303 image (e.g. .../linux/arch/x86/boot/bzImage
304 to the place where your regular bootable ke
305
306 - Booting a kernel directly from a storage de
307 of a bootloader such as LILO or GRUB, is no
308 (non-EFI systems). On UEFI/EFI systems, how
309 which allows the motherboard to boot direct
310 On modern workstations and desktops, it's g
311 bootloader as difficulties can arise with m
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
316 active development, though as it was extrem
317 in documentation. Popular alternatives incl
318 systemd-boot, or EFISTUB. For various reaso
319 software that's no longer in active develop
320
321 - Chances are your distribution includes an i
322 ``make install`` will be all that's needed.
323 you'll have to identify your bootloader and
324 configure your EFI.
325
326 Legacy LILO Instructions
327 ------------------------
328
329
330 - If you use LILO the kernel images are speci
331 The kernel image file is usually /vmlinuz,
332 /boot/bzImage. To use the new kernel, save
333 the new image over the old one. Then, you M
334 loading map! If you don't, you won't be abl
335
336 - Reinstalling LILO is usually a matter of ru
337 to edit /etc/lilo.conf to specify an entry
338 (say, /vmlinux.old) in case the new one doe
339 for more information.
340
341 - After reinstalling LILO, you should be all
342 reboot, and enjoy!
343
344 - If you ever need to change the default root
345 kernel image, use your bootloader's boot op
346 to recompile the kernel to change these par
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 ke
355 instructions at 'Documentation/admin-guide/rep
356
357 Hints on understanding kernel bug reports are
358 'Documentation/admin-guide/bug-hunting.rst'. M
359 with gdb is in 'Documentation/dev-tools/gdb-ke
360 'Documentation/dev-tools/kgdb.rst'.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.