summaryrefslogtreecommitdiff
path: root/Documentation/admin-guide/README.rst
AgeCommit message (Collapse)AuthorFilesLines
2024-02-15docs: admin-guide: Update bootloader and installation instructionsHunter Chasens1-24/+45
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
2022-10-03Merge tag 'docs-6.1' of git://git.lwn.net/linuxLinus Torvalds1-84/+7
Pull documentation updates from Jonathan Corbet: "There's not a huge amount of activity in the docs tree this time around, but a few significant changes even so: - A complete rewriting of the top-level index.rst file, which mostly reflects itself in a redone top page in the HTML-rendered docs. The hope is that the new organization will be a friendlier starting point for both users and developers. - Some math-rendering improvements. - A coding-style.rst update on the use of BUG() and WARN() - A big maintainer-PHP guide update. - Some code-of-conduct updates - More Chinese translation work Plus the usual pile of typo fixes, corrections, and updates" * tag 'docs-6.1' of git://git.lwn.net/linux: (66 commits) checkpatch: warn on usage of VM_BUG_ON() and other BUG variants coding-style.rst: document BUG() and WARN() rules ("do not crash the kernel") Documentation: devres: add missing IO helper Documentation: devres: update IRQ helper Documentation/mm: modify page_referenced to folio_referenced Documentation/CoC: Reflect current CoC interpretation and practices docs/doc-guide: Add documentation on SPHINX_IMGMATH docs: process/5.Posting.rst: clarify use of Reported-by: tag docs, kprobes: Fix the wrong location of Kprobes docs: add a man-pages link to the front page docs: put atomic*.txt and memory-barriers.txt into the core-api book docs: move asm-annotations.rst into core-api docs: remove some index.rst cruft docs: reconfigure the HTML left column docs: Rewrite the front page docs: promote the title of process/index.rst Documentation: devres: add missing SPI helper Documentation: devres: add missing PINCTRL helpers docs: hugetlbpage.rst: fix a typo of hugepage size docs/zh_CN: Add new translation of admin-guide/bootconfig.rst ...
2022-09-27docs: admin-guide: for kernel bugs refer to other kernel documentationLukas Bulwahn1-82/+7
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>
2022-09-27docs: admin-guide: do not mention the 'run a.out user programs' featureLukas Bulwahn1-2/+0
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>
2022-08-25docs: Update version number from 5.x to 6.x in README.rstLukas Bulwahn1-15/+15
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>
2021-09-13Drop some straggling mentions of gcc-4.9 as being staleLinus Torvalds1-1/+1
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>
2021-02-05Documentation: admin-guide: Update kvm/xen config optionAndré Almeida1-3/+4
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>
2020-12-08docs: make reporting-bugs.rst obsoleteThorsten Leemhuis1-2/+2
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>
2020-09-24Documentation/admin-guide: README & svga: remove use of "rdev"Randy Dunlap1-3/+3
"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>
2020-07-08Documentation: update for gcc 4.9 requirementRandy Dunlap1-1/+1
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>
2020-05-13streamline_config.pl: add LMC_KEEP to preserve some kconfigsChangbin Du1-2/+9
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>
2019-06-14docs: kbuild: convert docs to ReST and rename to *.rstMauro Carvalho Chehab1-1/+1
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>
2019-02-22Documentation: fix admin-guide/README.rst minimum gcc version requirementRandy Dunlap1-1/+1
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>
2019-02-18Documentation: change linux-4.x references to 5.xArnd Bergmann1-16/+16
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>
2018-09-10Drop all 00-INDEX files from Documentation/Henrik Austad1-2/+1
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>
2018-06-29Documentation/admin-guide/README.rst: add a label for cross-referencingMichael Rodin1-0/+2
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>
2018-04-03Merge tag 'docs-4.17' of git://git.lwn.net/linuxLinus Torvalds1-0/+7
Pull documentation updates from Jonathan Corbet: "There's been a fair amount of activity in Documentation/ this time around: - Lots of work aligning Documentation/ABI with reality, done by Aishwarya Pant. - The trace documentation has been converted to RST by Changbin Du - I thrashed up kernel-doc to deal with a parsing issue and to try to make the code more readable. It's still a 20+-year-old Perl hack, though. - Lots of other updates, typo fixes, and more" * tag 'docs-4.17' of git://git.lwn.net/linux: (82 commits) Documentation/process: update FUSE project website docs: kernel-doc: fix parsing of arrays dmaengine: Fix spelling for parenthesis in dmatest documentation dmaengine: Make dmatest.rst indeed reST compatible dmaengine: Add note to dmatest documentation about supported channels Documentation: magic-numbers: Fix typo Documentation: admin-guide: add kvmconfig, xenconfig and tinyconfig commands Input: alps - Update documentation for trackstick v3 format Documentation: Mention why %p prints ptrval COPYING: use the new text with points to the license files COPYING: create a new file with points to the Kernel license files Input: trackpoint: document sysfs interface xfs: Change URL for the project in xfs.txt char/bsr: add sysfs interface documentation acpi: nfit: document sysfs interface block: rbd: update sysfs interface Documentation/sparse: fix typo Documentation/CodingStyle: Add an example for braces docs/vm: update 00-INDEX kernel-doc: Remove __sched markings ...
2018-03-26Documentation: admin-guide: add kvmconfig, xenconfig and tinyconfig commandsMartin Kepplinger1-0/+7
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>
2018-03-26Documentation: arch-support: remove obsolete architecturesArnd Bergmann1-2/+2
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>
2018-01-27kconfig: Remove silentoldconfig from help and docs; fix kconfig/conf's helpMarc Herbert1-5/+0
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>
2017-10-12Documentation: fix admin-guide doc refsTom Saeger1-1/+1
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>
2017-05-16docs: update old references for DocBook from the documentationMauro Carvalho Chehab1-6/+0
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>
2017-05-11doc: replace FTP URL to kernel.org with HTTPS oneMichael Heimpold1-1/+1
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>
2017-05-01docs: remove all references to AVR32 architectureHans-Christian Noren Egtvedt1-1/+1
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>
2017-01-13Doc: clarify that GPL is GPL v2, not v2+Sanjeev1-2/+2
... and a minor missing period at EOL Signed-off-by: Sanjeev Gupta <ghane0@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-10-24docs: fix locations of several documents that got movedMauro Carvalho Chehab1-6/+7
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>
2016-10-24docs-rst: create an user's manual bookMauro Carvalho Chehab1-0/+410
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>