kernel/linux.git/Documentation/admin-guide/README.rst, branch v6.12.80

docs: admin-guide: Update bootloader and installation instructions

2024-02-14T22:46:34+00:00

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 Signed-off-by: Jonathan Corbet [jc: repaired added whitespace warnings] Link: https://lore.kernel.org/r/20240207171007.45405-1-hunter.chasens18@ncf.edu

Merge tag 'docs-6.1' of git://git.lwn.net/linux

2022-10-03T17:23:32+00:00

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

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

2022-09-27T19:21:43+00:00

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 Link: https://lore.kernel.org/r/20220720041325.15693-3-lukas.bulwahn@gmail.com Signed-off-by: Jonathan Corbet

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

2022-09-27T19:21:43+00:00

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 Link: https://lore.kernel.org/r/20220720041325.15693-2-lukas.bulwahn@gmail.com Signed-off-by: Jonathan Corbet

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

2022-08-25T18:45:10+00:00

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 Link: https://lore.kernel.org/r/20220824080836.23087-1-lukas.bulwahn@gmail.com Signed-off-by: Jonathan Corbet

Drop some straggling mentions of gcc-4.9 as being stale

2021-09-13T17:29:44+00:00

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

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

2021-02-04T21:47:40+00:00

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 Link: https://lore.kernel.org/r/20210130014547.123006-2-andrealmeid@collabora.com Signed-off-by: Jonathan Corbet

docs: make reporting-bugs.rst obsolete

2020-12-08T17:33:27+00:00

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 Link: https://lore.kernel.org/r/3df7c2d16de112b47bb6e6158138608e78562bf5.1607063223.git.linux@leemhuis.info Signed-off-by: Jonathan Corbet

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

2020-09-24T16:50:31+00:00

"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 Acked-by: Martin Mares Cc: Karel Zak Cc: Paul Gortmaker Cc: Jens Axboe Cc: linux-block@vger.kernel.org Cc: Alexander Viro Cc: Martin Mares Cc: linux-video@atrey.karlin.mff.cuni.cz Cc: "H. Peter Anvin" Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Link: https://lore.kernel.org/r/20200918015640.8439-2-rdunlap@infradead.org Signed-off-by: Jonathan Corbet

Documentation: update for gcc 4.9 requirement

2020-07-08T19:28:44+00:00

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 Acked-by: Jonathan Corbet Signed-off-by: Linus Torvalds