- 18 Oct, 2022 2 commits
-
-
Jonathan Corbet authored
Remove the ancient support for the Sphinx "classic" theme; everybody will have alabaster, so that fallback is no longer needed. While in the neighborhood: get rid of lots of useless comment lines. They describe the state of Sphinx options when we first created that file and are just clutter now. Suggested-by:
Mauro Carvalho Chehab <mchehab@kernel.org> Acked-by:
Jonathan Corbet <corbet@lwn.net>
-
Jonathan Corbet authored
Make a few changes to cause functions documented by kerneldoc to stand out better in the rendered documentation. Specifically, change kernel-doc to put the description section into a ".. container::" section, then add a bit of CSS to indent that section relative to the function prototype (or struct or enum definition). Tweak a few other CSS parameters while in the neighborhood to improve the formatting. Acked-by:
-
- 13 Oct, 2022 6 commits
-
-
Jonathan Corbet authored
We don't default to the RTD theme anymore, so sphinx-pre-install need not insist on installing it. Acked-by:
-
Jonathan Corbet authored
We don't default to Read The Docs anymore; update the docs to match. Acked-by:
-
Jonathan Corbet authored
This is just the beginning: tighten up the layout a bit to improve the information density in the browser. Also reconfigure the page width in terms of character units (em) rather than pixels, making it more display-independent. To that end, add a custom.css file to tweak Alabaster CSS settings. Acked-by:
-
Jonathan Corbet authored
The read-the-docs theme is not entirely attractive and doesn't give us control over the left column. "Alabaster" is deemed the default Sphinx theme, it is currently maintained and shipped bundled with Sphinx itself, so there is no need to install it separately. Switch over to this theme as the default for building kernel documentation; the DOCS_THEME environment variable can still be used to select a different theme. Acked-by:
-
Jonathan Corbet authored
-
Pierre Gondois authored
The '-t/-T' parameters seem to have been swapped: -t/--trace[=file]: save the stopped trace to [file|timerlat_trace.txt] -T/--thread us: stop trace if the thread latency is higher than the argument in us Swap them back. Signed-off-by:
Pierre Gondois <pierre.gondois@arm.com> Acked-by:
Daniel Bristot de Oliveira <bristot@kernel.org> Link: https://lore.kernel.org/r/20221006084409.3882542-1-pierre.gondois@arm.comSigned-off-by:
-
- 11 Oct, 2022 5 commits
-
-
Jonathan Corbet authored
-
Wu XiangCheng authored
update to commit 48987606 ("docs: add a man-pages link to the front page") Signed-off-by:
Wu XiangCheng <bobwxc@email.cn> Reviewed-by:
Yanteng Si <siyanteng@loongson.cn> Link: https://lore.kernel.org/r/6e289528ed1b40c1fcc03ea5e854e7c8ba264e67.1665467392.git.bobwxc@email.cnSigned-off-by:
-
Wu XiangCheng authored
update to commit 0c7b4366 ("docs: Rewrite the front page") Signed-off-by:
-
Wu XiangCheng authored
Add an entry for all zh arch documents. Signed-off-by:
-
Wu XiangCheng authored
update to commit 9d0f5cd1 ("docs: promote the title of process/index.rst") Signed-off-by:
-
- 10 Oct, 2022 8 commits
-
-
Jonathan Corbet authored
-
Yanteng Si authored
1)Update to commit 8f0efa81 ("mm/page_owner.c: add llseek for page_owner") 2)Translate some words into Chinese. Signed-off-by:
Alex Shi <alexs@kernel.org> Link: https://lore.kernel.org/r/52bc8df87618af951b34759487f05775416cb4d4.1664360331.git.siyanteng@loongson.cnSigned-off-by:
-
Yanteng Si authored
Update to commit bc6a2828a963 ("ksm: add the ksm prefix to the names of the ksm private structures") Signed-off-by: -
Akira Yokosawa authored
Somehow, there remains a link to gmane.org, which stopped working in 2016, in howto.rst. Replace it with the one at lore.kernel.org. Do the same changes under translations/ as well. Signed-off-by:
Akira Yokosawa <akiyks@gmail.com> Cc: Federico Vaga <federico.vaga@vaga.pv.it> Cc: Alex Shi <alexs@kernel.org> Cc: Yanteng Si <siyanteng@loongson.cn> Cc: Hu Haowen <src.res@email.cn> Reviewed-by:
-
Joel Stanley authored
Clearly the author meant 'on the fly'. Signed-off-by:
Joel Stanley <joel@jms.id.au> Link: https://lore.kernel.org/r/20221005030904.65604-1-joel@jms.id.auSigned-off-by:
-
Yixuan Cao authored
The kernel size changes due to many factors, such as compiler version, configuration, and the build environment. This makes size comparison figures irrelevant to reader's setup. Remove these figures and describe the effects of page owner to the kernel size in general instead. Thanks for Jonathan Corbet, Bagas Sanjaya and Mike Rapoport's constructive suggestions. Signed-off-by:
Yixuan Cao <caoyixuan2019@email.szu.edu.cn> Link: https://lore.kernel.org/r/20221005145525.10359-1-caoyixuan2019@email.szu.edu.cnSigned-off-by:
-
Yanteng Si authored
Since a patch set in my translation devicetree introduce some build warnings: Warning: Documentation/translations/zh_CN/devicetree/changesets.rst references a file that doesn't exist: Documentation/Devicetree/changesets.rst ... Change the first letter of Devicetree to lowercase. Fixes: 9485acfd ("docs/zh_CN: add dt kernel-api translation") Fixes: f773455c ("docs/zh_CN: add dt overlay-notes translation") Fixes: 5e38432d ("docs/zh_CN: add dt dynamic-resolution-notes translation") Fixes: 330f5a30 ("docs/zh_CN: add dt changesets translation") Reported-by:
kernel test robot <lkp@intel.com> Signed-off-by:
-
Leo Yan authored
The documentation gives an example for opening trace marker with write-only mode, but the flag WR_ONLY is not defined by glibc. Use O_WRONLY to replace it. Signed-off-by:
Leo Yan <leo.yan@linaro.org> Acked-by:
Steven Rostedt (Google) <rostedt@goodmis.org> Link: https://lore.kernel.org/r/20221008083250.3160-1-leo.yan@linaro.orgSigned-off-by:
-
- 29 Sep, 2022 18 commits
-
-
Jonathan Corbet authored
-
David Hildenbrand authored
checkpatch does not point out that VM_BUG_ON() and friends should be avoided, however, Linus notes: VM_BUG_ON() has the exact same semantics as BUG_ON. It is literally no different, the only difference is "we can make the code smaller because these are less important". [1] So let's warn on VM_BUG_ON() and other BUG variants as well. While at it, make it clearer that the kernel really shouldn't be crashed. As there are some subsystem BUG macros that actually don't end up crashing the kernel -- for example, KVM_BUG_ON() -- exclude these manually. [1] https://lore.kernel.org/r/CAHk-=wg40EAZofO16Eviaj7mfqDhZ2gVEbvfsMf6gYzspRjYvw@mail.gmail.comSigned-off-by:David Hildenbrand <david@redhat.com> Link: https://lore.kernel.org/r/20220923113426.52871-3-david@redhat.comSigned-off-by:
-
David Hildenbrand authored
Linus notes [1] that the introduction of new code that uses VM_BUG_ON() is just as bad as BUG_ON(), because it will crash the kernel on distributions that enable CONFIG_DEBUG_VM (like Fedora): VM_BUG_ON() has the exact same semantics as BUG_ON. It is literally no different, the only difference is "we can make the code smaller because these are less important". [2] This resulted in a more generic discussion about usage of BUG() and friends. While there might be corner cases that still deserve a BUG_ON(), most BUG_ON() cases should simply use WARN_ON_ONCE() and implement a recovery path if reasonable: The only possible case where BUG_ON can validly be used is "I have some fundamental data corruption and cannot possibly return an error". [2] As a very good approximation is the general rule: "absolutely no new BUG_ON() calls _ever_" [2] ... not even if something really shouldn't ever happen and is merely for documenting that an invariant always has to hold. However, there are sill exceptions where BUG_ON() may be used: If you have a "this is major internal corruption, there's no way we can continue", then BUG_ON() is appropriate. [3] There is only one good BUG_ON(): Now, that said, there is one very valid sub-form of BUG_ON(): BUILD_BUG_ON() is absolutely 100% fine. [2] While WARN will also crash the machine with panic_on_warn set, that's exactly to be expected: So we have two very different cases: the "virtual machine with good logging where a dead machine is fine" - use 'panic_on_warn'. And the actual real hardware with real drivers, running real loads by users. [4] The basic idea is that warnings will similarly get reported by users and be found during testing. However, in contrast to a BUG(), there is a way to actually influence the expected behavior (e.g., panic_on_warn) and to eventually keep the machine alive to extract some debug info. Ingo notes that not all WARN_ON_ONCE cases need recovery. If we don't ever expect this code to trigger in any case, recovery code is not really helpful. I'd prefer to keep all these warnings 'simple' - i.e. no attempted recovery & control flow, unless we ever expect these to trigger. [5] There have been different rules floating around that were never properly documented. Let's try to clarify. [1] https://lkml.kernel.org/r/CAHk-=wiEAH+ojSpAgx_Ep=NKPWHU8AdO3V56BXcCsU97oYJ1EA@mail.gmail.com [2] https://lore.kernel.org/r/CAHk-=wg40EAZofO16Eviaj7mfqDhZ2gVEbvfsMf6gYzspRjYvw@mail.gmail.com [3] https://lkml.kernel.org/r/CAHk-=wit-DmhMfQErY29JSPjFgebx_Ld+pnerc4J2Ag990WwAA@mail.gmail.com [4] https://lore.kernel.org/r/CAHk-=wgF7K2gSSpy=m_=K3Nov4zaceUX9puQf1TjkTJLA2XC_g@mail.gmail.com [5] https://lore.kernel.org/r/YwIW+mVeZoTOxn%2F4@gmail.comReviewed-by:John Hubbard <jhubbard@nvidia.com> Signed-off-by:
-
Yang Yingliang authored
Add missing devm_request_free_mem_region() to devres.rst. It's introduced by commit 0092908d ("mm: factor out a devm_request_free_mem_region helper"). Signed-off-by:
Yang Yingliang <yangyingliang@huawei.com> Link: https://lore.kernel.org/r/20220927080215.1359979-1-yangyingliang@huawei.comSigned-off-by:
-
Yang Yingliang authored
devm_irq_sim_init() has been changed to devm_irq_domain_create_sim() in commit 337cbeb2 ("genirq/irq_sim: Simplify the API"). Signed-off-by:
-
Vernon Yang authored
Since commit b3ac0413 ("mm/rmap: Turn page_referenced() into folio_referenced()") the page_referenced function name was modified, so fix it up to use the correct one. Signed-off-by:
Vernon Yang <vernon2gm@gmail.com> Reviewed-by:
Mike Rapoport <rppt@linux.ibm.com> Link: https://lore.kernel.org/r/20220926152032.74621-1-vernon2gm@gmail.comSigned-off-by:
-
Kristen Carlson Accardi authored
The Code of Conduct interpretation does not reflect the current practices of the CoC committee or the TAB. Update the documentation to remove references to initial committees and boot strap periods since it is past that time, and note that the this document does serve as the documentation for the CoC committee processes. Signed-off-by:
Kristen Carlson Accardi <kristen@linux.intel.com> Reviewed-by:
Shuah Khan <skhan@linuxfoundation.org> Reviewed-by:
Greg Kroah-Hartman <gregkh@linuxfoundation.org> Link: https://lore.kernel.org/r/20220926211149.2278214-1-kristen@linux.intel.comSigned-off-by:
-
Akira Yokosawa authored
Now that building html docs with math expressions does not need texlive packages, remove the note on the requirement in the "Sphinx Install" section. Instead, add sections of "Math Expressions in HTML" and "Choice of Math Renderer". Describe the effect of setting SPHINX_IMGMATH in the latter section. Signed-off-by:
-
Thorsten Leemhuis authored
Bring the description on when to use the Reported-by: tag found in Documentation/process/5.Posting.rst more in line with the description in Documentation/process/submitting-patches.rst: before this change the two were contradicting each other, as the latter is way more permissive and only states '[...] if the bug was reported in private, then ask for permission first before using the Reported-by tag.' Signed-off-by:
Thorsten Leemhuis <linux@leemhuis.info> Link: https://lore.kernel.org/r/2fc7162dfb76e04da5ea903c9c170d913e735dad.1664372256.git.linux@leemhuis.infoSigned-off-by:
-
Tiezhu Yang authored
After commit 22471e13 ("kconfig: use a menu in arch/Kconfig to reduce clutter"), the location of Kprobes is under "General architecture-dependent options" rather than "General setup". Signed-off-by:
Tiezhu Yang <yangtiezhu@loongson.cn> Acked-by:
-
Jonathan Corbet authored
The top-level index.rst file is the entry point for the kernel's documentation, especially for readers of the HTML output. It is currently a mess containing everything we thought to throw in there. Firefox says it would require 26 pages of paper to print it. That is not a user-friendly introduction. This series aims to improve our documentation entry point with a focus on rewriting index.rst. The result is, IMO, simpler and more approachable. For anybody who wants to see the rendered results without building the docs, have a look at: https://static.lwn.net/kerneldoc/ This time around I've rendered the pages using the "Read The Docs" theme, since that's what everybody will get by default. That theme ignores the directives regarding the left column, so the results are not as good there. I have a series proposing a default-theme change in the works, but that's a separate topic. This is only a beginning; I think this kind of organizational effort has to be pushed down into the lower layers of the docs tree itself. But one has to start somewhere.
-
Jonathan Corbet authored
Readers looking for user-oriented information may benefit from it. Signed-off-by:
David Vernet <void@manifault.com> Acked-by:
Randy Dunlap <rdunlap@infradead.org> Link: https://lore.kernel.org/r/20220927160559.97154-8-corbet@lwn.netSigned-off-by:
-
Jonathan Corbet authored
These files describe part of the core API, but have never been converted to RST due to ... let's say local oppposition. So, create a set of special-purpose wrappers to ..include these files into a separate page so that they can be a part of the htmldocs build. Then link them into the core-api manual and remove them from the "staging" dumping ground. Acked-by:
Jani Nikula <jani.nikula@intel.com> Signed-off-by:
-
Jonathan Corbet authored
This one file should not really be in the top-level documentation directory. core-api/ may not be a perfect fit but seems to be best, so move it there. Adjust a couple of internal document references to make them location-independent, and point checkpatch.pl at the new location. Cc: Jiri Slaby <jirislaby@kernel.org> Cc: Joe Perches <joe@perches.com> Reviewed-by:
-
Jonathan Corbet authored
There is some useless boilerplate text that was added by sphinx when this file was first created; take it out. Reviewed-by:
-
Jonathan Corbet authored
Use the html_sidebars directive to get a more useful set of links in the left column. Unfortunately, this is a no-op with the default RTD theme, but others observe it. Reviewed-by:
-
Jonathan Corbet authored
The front page is the entry point to the documentation, especially for people who read it online. It's a big mess of everything we could think to toss into it. Rewrite the page with an eye toward simplicity and making it easy for readers to get going toward what they really want to find. This is only a beginning, but it makes our docs more approachable than before. Acked-by:
-
Jonathan Corbet authored
...otherwise Sphinx won't cooperate when trying to list it explicitly in the top-level index.rst file Reviewed-by:
-
- 27 Sep, 2022 1 commit
-
-
Jonathan Corbet authored
-
