docs: admin-guide: Update bootloader and installation instructions

Updates the bootloader and installation instructions in
admin-guide/README.rst to align with modern practices.

Details of Changes:

- Added guidance on using EFISTUB for UEFI/EFI systems.
- Noted that LILO is no longer in active development and provides
alternatives.
- Kept LILO instructions but marked as Legacy LILO Instructions.
Suggest removal in future patch.

Signed-off-by: Hunter Chasens <hunter.chasens18@ncf.edu>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
[jc: repaired added whitespace warnings]
Link: https://lore.kernel.org/r/20240207171007.45405-1-hunter.chasens18@ncf.edu

docs: admin-guide: for kernel bugs refer to other kernel documentation

The current section 'If something goes wrong' makes a number of suggestions
for debugging, bug hunting and reporting issues, which are quite briefly
described in that section.

However, the suggestions are also well covered in other kernel
documentation or sometimes simply outdated. Here, each suggestion in that
section is summarized, and then followed with its assessment, and the
derived action for each suggestion:

- use MAINTAINERS and mailing list: covered in 'Reporting issues',
summarized in the short guide, detailed in its further section.
Reporting issues even provides some specific examples that guides
readers well through the needed steps. Refer to 'Reporting issues'.

- contact Linus Torvalds: probably outdated as currently described.
nevertheless covered in 'Reporting issues'. Reporting issues points out
to contact the relevant kernel maintainers first, and after some
patience and failed attempts with those maintainers, contacting Linus
Torvalds might be okay. Refer to 'Reporting issues'.

- tell what kernel, how to duplicate, the setup, if the problem is new
or old and when did you notice: covered in 'Reporting issues',
especially in Step-by-step guide how to report issues to the kernel
maintainers. Refer to 'Reporting issues'.

- duplicate kernel bug reports exactly: covered in 'Reporting issues',
especially in Write and send the report. Refer to 'Reporting issues'.

- read 'Bug hunting': keep this reference. Refer to 'Bug hunting'.

- compile the kernel with CONFIG_KALLSYMS: covered in 'Reporting issues',
especially in Decode failure messages. Refer to 'Reporting issues'.

- alternatively, use ksymoops: ksymoops at the mentioned URL seems not to
be maintained anymore. It was released roughly once a year until
version 2.4.11 in 2005, but has not seen a new release since then. The
information in ./scripts/ksymoops/README is from 1999, and does not
give more insight on its actual maintenance state either. Ksymoops is
mentioned as system utility in changes.rst, but also not recommended
there. Drop the explanation on using ksymoops.

- alternatively, lookup dump manually with the EIP and nm to determine
the function in which the kernel crashes: this method seems already a
quite advanced and low-level debugging method. Even all the further
references on bug hunting and debugging do not mention it. Drop this
alternative method and limit mentioning methods explained in the other
existing kernel documentation.

- read 'Reporting issues': keep this reference.
Refer to 'Reporting issues'.

- use gdb for debugging: some specific details, e.g., edit
arch/x86/Makefile, are probably outdated or limited to one (historic
important) setup. Using gdb is covered in 'Bug hunting', 'Debugging
kernel and modules via gdb' and 'Using kgdb, kdb and the kernel
debugger internals'. Refer to those three documents.

Overall, it is sufficient to refer to reporting-issues.rst,
bug-hunting.rst, gdb-kernel-debugging.rst and kgdb.rst and this way cover
the existing suggestions.

'Reporting issues' is quite new and probably up to date. 'Bug hunting',
'Debugging kernel and modules via gdb' and 'Using kgdb, kdb and the kernel
debugger internals' might need some revisit and update, but they are
generally in an acceptable state for referring to them.

Replace the existing suggestions by reference to other existing kernel
documentation covering those suggestions---partly even nicely summarized
and then explained in greater detail.

Signed-off-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
Link: https://lore.kernel.org/r/20220720041325.15693-3-lukas.bulwahn@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: admin-guide: do not mention the 'run a.out user programs' feature

Running a.out user programs with the latest kernel release is a very rare
and uncommon use case nowadays. The support of a.out user programs is only
remaining for the alpha architecture and is not defined and activated in
the architecture's Kconfig (so even the activation of this support requires
to modify the Kconfig file and not just kernel build configuration).

The discussion on a.out support in 2019 (see Link) shows that the support
of a.out user programs is just remaining for a special corner case from
some (alpha architecture) users.

There is no need to point out and mention this special feature to the
general audience of kernel users. Delete the reference to this historic and
special feature.

Link: https://lore.kernel.org/all/CAHk-=wgt7M6yA5BJCJo0nF22WgPJnN8CvViL9CAJmd+S+Civ6w@mail.gmail.com/

Signed-off-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
Link: https://lore.kernel.org/r/20220720041325.15693-2-lukas.bulwahn@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: Update version number from 5.x to 6.x in README.rst

A quick 'grep "5\.x" . -R' on Documentation shows that README.rst,
2.Process.rst and applying-patches.rst all mention the version number "5.x"
for kernel releases.

As the next release will be version 6.0, updating the version number to 6.x
in README.rst seems reasonable.

The description in 2.Process.rst is just a description of recent kernel
releases, it was last updated in the beginning of 2020, and can be
revisited at any time on a regular basis, independent of changing the
version number from 5 to 6. So, there is no need to update this document
now when transitioning from 5.x to 6.x numbering.

The document applying-patches.rst is probably obsolete for most users
anyway, a reader will sufficiently well understand the steps, even it
mentions version 5 rather than version 6. So, do not update that to a
version 6.x numbering scheme.

Update version number from 5.x to 6.x in README.rst only.

Signed-off-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
Link: https://lore.kernel.org/r/20220824080836.23087-1-lukas.bulwahn@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Drop some straggling mentions of gcc-4.9 as being stale

Fix up the admin-guide README file to the new gcc-5.1 requirement, and
remove a stale comment about gcc support for the __assume_aligned__
attribute.

Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>

Documentation: admin-guide: Update kvm/xen config option

Since commit 9bba03d4473d ("kconfig: remove 'kvmconfig' and 'xenconfig'
shorthands") kvm/xen config shortcuts are not available anymore. Update
the file to reflect how they should be used, with the full filename.

Signed-off-by: André Almeida <andrealmeid@collabora.com>
Link: https://lore.kernel.org/r/20210130014547.123006-2-andrealmeid@collabora.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: make reporting-bugs.rst obsolete

Make various places which point to
Documentation/admin-guide/reporting-bugs.rst point to
Documentation/admin-guide/reporting-issues.rst instead. That document is
brand new and as of now is not completely finished. But even at this
stage it's a lot more helpful and accurate than reporting-bugs.rst.
Hence also add a note to reporting-bugs.rst, telling people they're
better off reading reporting-issues.rst instead.

reporting-bugs.rst is scheduled for removal once reporting-issues.rst
is considered ready.

Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
Link: https://lore.kernel.org/r/3df7c2d16de112b47bb6e6158138608e78562bf5.1607063223.git.linux@leemhuis.info
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation/admin-guide: README & svga: remove use of "rdev"

"rdev" is considered antiquated, ancient, archaic, obsolete, deprecated
{choose any or all}.

Remove use of "rdev" and "vidmode" (a symlink to rdev) in
admin-guide/README.rst and admin-guide/svga.rst.

"rdev" was removed from util-linux in 2010:
https://git.kernel.org/pub/scm/utils/util-linux/util-linux.git/commit/?id=a3e40c14651fccf18e7954f081e601389baefe3f

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Martin Mares <mj@ucw.cz>
Cc: Karel Zak <kzak@redhat.com>
Cc: Paul Gortmaker <paul.gortmaker@windriver.com>
Cc: Jens Axboe <axboe@kernel.dk>
Cc: linux-block@vger.kernel.org
Cc: Alexander Viro <viro@zeniv.linux.org.uk>
Cc: Martin Mares <mj@ucw.cz>
Cc: linux-video@atrey.karlin.mff.cuni.cz
Cc: "H. Peter Anvin" <hpa@zytor.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Link: https://lore.kernel.org/r/20200918015640.8439-2-rdunlap@infradead.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: update for gcc 4.9 requirement

Update Documentation for the gcc v4.9 upgrade requirement.

Fixes: 5429ef62bcf3 ("compiler/gcc: Raise minimum GCC version for kernel builds to 4.8")
Fixes: 6ec4476ac825 ("Raise gcc version requirement to 4.9")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>

streamline_config.pl: add LMC_KEEP to preserve some kconfigs

Sometimes it is useful to preserve batches of configs when making
localmodconfig. For example, I usually don't want any usb and fs
modules to be disabled. Now we can do it by:

$ make LMC_KEEP="drivers/usb:fs" localmodconfig

Signed-off-by: Changbin Du <changbin.du@gmail.com>
Acked-by: Steven Rostedt (VMware) <rostedt@goodmis.org>
Signed-off-by: Masahiro Yamada <masahiroy@kernel.org>

docs: kbuild: convert docs to ReST and rename to *.rst

The kbuild documentation clearly shows that the documents
there are written at different times: some use markdown,
some use their own peculiar logic to split sections.

Convert everything to ReST without affecting too much
the author's style and avoiding adding uneeded markups.

The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.

At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: fix admin-guide/README.rst minimum gcc version requirement

Fix minimum gcc version as specified in Documentation/process/changes.rst.

Suggested-by: Matthew Wilcox <willy@infradead.org>
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: change linux-4.x references to 5.x

As linux-5.0.x is coming up soon, the documentation should match,
in particular the README.rst file, so change all 4.x references
accordingly. There was a mix of lowercase and uppercase X here,
which I changed to using lowercase consistently.

Signed-off-by: Arnd Bergmann <arnd@arndb.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Drop all 00-INDEX files from Documentation/

This is a respin with a wider audience (all that get_maintainer returned)
and I know this spams a *lot* of people. Not sure what would be the correct
way, so my apologies for ruining your inbox.

The 00-INDEX files are supposed to give a summary of all files present
in a directory, but these files are horribly out of date and their
usefulness is brought into question. Often a simple "ls" would reveal
the same information as the filenames are generally quite descriptive as
a short introduction to what the file covers (it should not surprise
anyone what Documentation/sched/sched-design-CFS.txt covers)

A few years back it was mentioned that these files were no longer really
needed, and they have since then grown further out of date, so perhaps
it is time to just throw them out.

A short status yields the following _outdated_ 00-INDEX files, first
counter is files listed in 00-INDEX but missing in the directory, last
is files present but not listed in 00-INDEX.

List of outdated 00-INDEX:
Documentation: (4/10)
Documentation/sysctl: (0/1)
Documentation/timers: (1/0)
Documentation/blockdev: (3/1)
Documentation/w1/slaves: (0/1)
Documentation/locking: (0/1)
Documentation/devicetree: (0/5)
Documentation/power: (1/1)
Documentation/powerpc: (0/5)
Documentation/arm: (1/0)
Documentation/x86: (0/9)
Documentation/x86/x86_64: (1/1)
Documentation/scsi: (4/4)
Documentation/filesystems: (2/9)
Documentation/filesystems/nfs: (0/2)
Documentation/cgroup-v1: (0/2)
Documentation/kbuild: (0/4)
Documentation/spi: (1/0)
Documentation/virtual/kvm: (1/0)
Documentation/scheduler: (0/2)
Documentation/fb: (0/1)
Documentation/block: (0/1)
Documentation/networking: (6/37)
Documentation/vm: (1/3)

Then there are 364 subdirectories in Documentation/ with several files that
are missing 00-INDEX alltogether (and another 120 with a single file and no
00-INDEX).

I don't really have an opinion to whether or not we /should/ have 00-INDEX,
but the above 00-INDEX should either be removed or be kept up to date. If
we should keep the files, I can try to keep them updated, but I rather not
if we just want to delete them anyway.

As a starting point, remove all index-files and references to 00-INDEX and
see where the discussion is going.

Signed-off-by: Henrik Austad <henrik@austad.us>
Acked-by: "Paul E. McKenney" <paulmck@linux.vnet.ibm.com>
Just-do-it-by: Steven Rostedt <rostedt@goodmis.org>
Reviewed-by: Jens Axboe <axboe@kernel.dk>
Acked-by: Paul Moore <paul@paul-moore.com>
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Acked-by: Mark Brown <broonie@kernel.org>
Acked-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
Cc: [Almost everybody else]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation/admin-guide/README.rst: add a label for cross-referencing

Add a label to the top of the file to allow cross-referencing.
Currently it's not possible to cross-reference this file from
Documentation/process/howto.rst because of the missing label.

Signed-off-by: Michael Rodin <michael-git@rodin.online>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: admin-guide: add kvmconfig, xenconfig and tinyconfig commands

Add kvmconfig, xenconfig and tinyconfig to the list of alternative
configuration commands. Descriptions are directly taken from the Makefile.

Signed-off-by: Martin Kepplinger <martink@posteo.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: arch-support: remove obsolete architectures

A number of architecture ports are obsolete and getting dropped,
so we no longer want to track the respective features.

We already removed the lines for metag and mn10300, this does
the same edits for all the others.

For the remaining 21 architectures, this shows how many are known
to implement each given feature:

19 time/modern-timekeeping/arch-support.txt
19 time/clockevents/arch-support.txt
15 core/tracehook/arch-support.txt
14 core/generic-idle-thread/arch-support.txt
13 locking/lockdep/arch-support.txt
12 io/dma-api-debug/arch-support.txt
11 debug/kgdb/arch-support.txt
10 time/virt-cpuacct/arch-support.txt
9 debug/kretprobes/arch-support.txt
9 debug/kprobes/arch-support.txt
8 vm/THP/arch-support.txt
8 vm/pte_special/arch-support.txt
8 vm/numa-memblock/arch-support.txt
8 io/sg-chain/arch-support.txt
7 perf/kprobes-event/arch-support.txt
7 locking/rwsem-optimized/arch-support.txt
7 debug/gcov-profile-all/arch-support.txt
7 core/jump-labels/arch-support.txt
7 core/BPF-JIT/arch-support.txt
6 vm/ELF-ASLR/arch-support.txt
6 time/context-tracking/arch-support.txt
6 seccomp/seccomp-filter/arch-support.txt
6 debug/stackprotector/arch-support.txt
5 time/irq-time-acct/arch-support.txt
5 io/dma-contiguous/arch-support.txt
5 debug/uprobes/arch-support.txt
4 vm/ioremap_prot/arch-support.txt
4 time/arch-tick-broadcast/arch-support.txt
4 perf/perf-stackdump/arch-support.txt
4 perf/perf-regs/arch-support.txt
3 debug/KASAN/arch-support.txt
2 vm/PG_uncached/arch-support.txt
2 vm/huge-vmap/arch-support.txt
2 sched/numa-balancing/arch-support.txt
2 sched/membarrier-sync-core/arch-support.txt
2 locking/cmpxchg-local/arch-support.txt
2 debug/optprobes/arch-support.txt
2 debug/kprobes-on-ftrace/arch-support.txt
1 vm/TLB/arch-support.txt
1 locking/queued-spinlocks/arch-support.txt
1 locking/queued-rwlocks/arch-support.txt
1 debug/user-ret-profiler/arch-support.txt
0 lib/strncasecmp/arch-support.txt

Note that the list does not include riscv or nds32 yet, these still
need to be added.

Signed-off-by: Arnd Bergmann <arnd@arndb.de>

kconfig: Remove silentoldconfig from help and docs; fix kconfig/conf's help

As explained by Michal Marek at https://lkml.org/lkml/2011/8/31/189
silentoldconfig has become a misnomer. It has become an internal interface
so remove it from "make help" and Documentation/ to stop confusing people
using it as seen for instance at
https://chromium-review.googlesource.com/835632 Don't remove it from
kconfig/Makefile yet not to break any (other) tool using it.

On the other hand, correct and expand its description in the help of
the (internal) scripts/kconfig/conf.c

Signed-off-by: Marc Herbert <marc.herbert@intel.com>
Signed-off-by: Masahiro Yamada <yamada.masahiro@socionext.com>

Documentation: fix admin-guide doc refs

Make admin-guide document refs valid.

Signed-off-by: Tom Saeger <tom.saeger@oracle.com>
Acked-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: update old references for DocBook from the documentation

DocBook is mentioned several times at the documentation. Update
the obsolete references from it at the DocBook.

Acked-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc: replace FTP URL to kernel.org with HTTPS one

FTP services were shutdown some weeks ago, so the FTP URL
does not work anymore. Fix this by replacing it with
corresponding HTTPS URL.

Signed-off-by: Michael Heimpold <michael.heimpold@i2se.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: remove all references to AVR32 architecture

The AVR32 architecture support has been removed from the Linux kernel,
hence remove all references to it from Documentation.

Signed-off-by: Hans-Christian Noren Egtvedt <egtvedt@samfundet.no>
Signed-off-by: Håvard Skinnemoen <hskinnemoen@gmail.com>
Signed-off-by: Nicolas Ferre <nicolas.ferre@microchip.com>
Acked-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Acked-by: Boris Brezillon <boris.brezillon@free-electrons.com>

Doc: clarify that GPL is GPL v2, not v2+

... and a minor missing period at EOL

Signed-off-by: Sanjeev Gupta <ghane0@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: fix locations of several documents that got moved

The previous patch renamed several files that are cross-referenced
along the Kernel documentation. Adjust the links to point to
the right places.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

docs-rst: create an user's manual book

Place README, REPORTING-BUGS, SecurityBugs and kernel-parameters
on an user's manual book.

As we'll be numbering the user's manual, remove the manual
numbering from SecurityBugs.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>