Skip to content

Commit 6f38be8

Browse files
torvaldstorvalds
committed
Merge tag 'docs-5.17' of git://git.lwn.net/linux
Pull documentation updates from Jonathan Corbet: "This isn't a hugely busy cycle for documentation, but a few significant things still showed up: - A documentation section for ARC processors - Reworked and enhanced KUnit documentation - The ability to pick your own theme for HTML builds; if the default "Read the Docs" theme isn't ugly enough for you, you can now pick an uglier one. - More Chinese translation work Plus the usual assortment of fixes and cleanups" * tag 'docs-5.17' of git://git.lwn.net/linux: (53 commits) scripts: sphinx-pre-install: Fix ctex support on Debian docs: discourage use of list tables docs: 5.Posting.rst: describe Fixes: and Link: tags Documentation: kgdb: Replace deprecated remotebaud docs: automarkup.py: Fix invalid HTML link output and broken URI fragments Documentation: refer to config RANDOMIZE_BASE for kernel address-space randomization Documentation: kgdb: properly capitalize the MAGIC_SYSRQ config docs/zh_CN: Update and fix a couple of typos scripts: sphinx-pre-install: add required ctex dependency Documentation: KUnit: Restyled Frequently Asked Questions Documentation: KUnit: Restyle Test Style and Nomenclature page Documentation: KUnit: Rework writing page to focus on writing tests Documentation: kunit: Reorganize documentation related to running tests Documentation: KUnit: Added KUnit Architecture Documentation: KUnit: Rewrite getting started Documentation: KUnit: Rewrite main page docs/zh_CN: Add zh_CN/accounting/delay-accounting.rst Documentation/sphinx: fix typos of "its" docs/zh_CN: Add sched-domains translation doc: fs: remove bdev_try_to_free_page related doc ...
2 parents 1be5bdf + 87d6576 commit 6f38be8

59 files changed

Lines changed: 4221 additions & 826 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎Documentation/Makefile‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,8 @@ endif
1919
SPHINXBUILD = sphinx-build
2020
SPHINXOPTS =
2121
SPHINXDIRS = .
22+
DOCS_THEME =
23+
DOCS_CSS =
2224
_SPHINXDIRS = $(sort $(patsubst $(srctree)/Documentation/%/index.rst,%,$(wildcard $(srctree)/Documentation/*/index.rst)))
2325
SPHINX_CONF = conf.py
2426
PAPER =
@@ -84,7 +86,10 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
8486
-D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \
8587
$(ALLSPHINXOPTS) \
8688
$(abspath $(srctree)/$(src)/$5) \
87-
$(abspath $(BUILDDIR)/$3/$4)
89+
$(abspath $(BUILDDIR)/$3/$4) && \
90+
if [ "x$(DOCS_CSS)" != "x" ]; then \
91+
cp $(if $(patsubst /%,,$(DOCS_CSS)),$(abspath $(srctree)/$(DOCS_CSS)),$(DOCS_CSS)) $(BUILDDIR)/$3/_static/; \
92+
fi
8893

8994
htmldocs:
9095
@$(srctree)/scripts/sphinx-pre-install --version-check
@@ -154,4 +159,8 @@ dochelp:
154159
@echo ' make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build'
155160
@echo ' configuration. This is e.g. useful to build with nit-picking config.'
156161
@echo
162+
@echo ' make DOCS_THEME={sphinx-theme} selects a different Sphinx theme.'
163+
@echo
164+
@echo ' make DOCS_CSS={a .css file} adds a DOCS_CSS override file for html/epub output.'
165+
@echo
157166
@echo ' Default location for the generated documents is Documentation/output'

‎Documentation/admin-guide/hw-vuln/spectre.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -468,7 +468,7 @@ Spectre variant 2
468468
before invoking any firmware code to prevent Spectre variant 2 exploits
469469
using the firmware.
470470

471-
Using kernel address space randomization (CONFIG_RANDOMIZE_SLAB=y
471+
Using kernel address space randomization (CONFIG_RANDOMIZE_BASE=y
472472
and CONFIG_SLAB_FREELIST_RANDOM=y in the kernel configuration) makes
473473
attacks on the kernel generally more difficult.
474474

‎Documentation/arc/arc.rst‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
.. SPDX-License-Identifier: GPL-2.0
2+
3+
Linux kernel for ARC processors
4+
*******************************
5+
6+
Other sources of information
7+
############################
8+
9+
Below are some resources where more information can be found on
10+
ARC processors and relevant open source projects.
11+
12+
- `<https://embarc.org>`_ - Community portal for open source on ARC.
13+
Good place to start to find relevant FOSS projects, toolchain releases,
14+
news items and more.
15+
16+
- `<https://github.com/foss-for-synopsys-dwc-arc-processors>`_ -
17+
Home for all development activities regarding open source projects for
18+
ARC processors. Some of the projects are forks of various upstream projects,
19+
where "work in progress" is hosted prior to submission to upstream projects.
20+
Other projects are developed by Synopsys and made available to community
21+
as open source for use on ARC Processors.
22+
23+
- `Official Synopsys ARC Processors website
24+
<https://www.synopsys.com/designware-ip/processor-solutions.html>`_ -
25+
location, with access to some IP documentation (`Programmer's Reference
26+
Manual, AKA PRM for ARC HS processors
27+
<https://www.synopsys.com/dw/doc.php/ds/cc/programmers-reference-manual-ARC-HS.pdf>`_)
28+
and free versions of some commercial tools (`Free nSIM
29+
<https://www.synopsys.com/cgi-bin/dwarcnsim/req1.cgi>`_ and
30+
`MetaWare Light Edition <https://www.synopsys.com/cgi-bin/arcmwtk_lite/reg1.cgi>`_).
31+
Please note though, registration is required to access both the documentation and
32+
the tools.
33+
34+
Important note on ARC processors configurability
35+
################################################
36+
37+
ARC processors are highly configurable and several configurable options
38+
are supported in Linux. Some options are transparent to software
39+
(i.e cache geometries, some can be detected at runtime and configured
40+
and used accordingly, while some need to be explicitly selected or configured
41+
in the kernel's configuration utility (AKA "make menuconfig").
42+
43+
However not all configurable options are supported when an ARC processor
44+
is to run Linux. SoC design teams should refer to "Appendix E:
45+
Configuration for ARC Linux" in the ARC HS Databook for configurability
46+
guidelines.
47+
48+
Following these guidelines and selecting valid configuration options
49+
up front is critical to help prevent any unwanted issues during
50+
SoC bringup and software development in general.
51+
52+
Building the Linux kernel for ARC processors
53+
############################################
54+
55+
The process of kernel building for ARC processors is the same as for any other
56+
architecture and could be done in 2 ways:
57+
58+
- Cross-compilation: process of compiling for ARC targets on a development
59+
host with a different processor architecture (generally x86_64/amd64).
60+
- Native compilation: process of compiling for ARC on a ARC platform
61+
(hardware board or a simulator like QEMU) with complete development environment
62+
(GNU toolchain, dtc, make etc) installed on the platform.
63+
64+
In both cases, up-to-date GNU toolchain for ARC for the host is needed.
65+
Synopsys offers prebuilt toolchain releases which can be used for this purpose,
66+
available from:
67+
68+
- Synopsys GNU toolchain releases:
69+
`<https://github.com/foss-for-synopsys-dwc-arc-processors/toolchain/releases>`_
70+
71+
- Linux kernel compilers collection:
72+
`<https://mirrors.edge.kernel.org/pub/tools/crosstool>`_
73+
74+
- Bootlin's toolchain collection: `<https://toolchains.bootlin.com>`_
75+
76+
Once the toolchain is installed in the system, make sure its "bin" folder
77+
is added in your ``PATH`` environment variable. Then set ``ARCH=arc`` &
78+
``CROSS_COMPILE=arc-linux`` (or whatever matches installed ARC toolchain prefix)
79+
and then as usual ``make defconfig && make``.
80+
81+
This will produce "vmlinux" file in the root of the kernel source tree
82+
usable for loading on the target system via JTAG.
83+
If you need to get an image usable with U-Boot bootloader,
84+
type ``make uImage`` and ``uImage`` will be produced in ``arch/arc/boot``
85+
folder.

‎Documentation/arc/features.rst‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
.. SPDX-License-Identifier: GPL-2.0
2+
3+
.. kernel-feat:: $srctree/Documentation/features arc

‎Documentation/arc/index.rst‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
===================
2+
ARC architecture
3+
===================
4+
5+
.. toctree::
6+
:maxdepth: 1
7+
8+
arc
9+
10+
features
11+
12+
.. only:: subproject and html
13+
14+
Indices
15+
=======
16+
17+
* :ref:`genindex`

‎Documentation/arch.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ implementation.
99
.. toctree::
1010
:maxdepth: 2
1111

12+
arc/index
1213
arm/index
1314
arm64/index
1415
ia64/index

‎Documentation/conf.py‎

Lines changed: 80 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -208,16 +208,86 @@
208208
# The theme to use for HTML and HTML Help pages. See the documentation for
209209
# a list of builtin themes.
210210

211-
# The Read the Docs theme is available from
212-
# - https://github.com/snide/sphinx_rtd_theme
213-
# - https://pypi.python.org/pypi/sphinx_rtd_theme
214-
# - python-sphinx-rtd-theme package (on Debian)
215-
try:
216-
import sphinx_rtd_theme
217-
html_theme = 'sphinx_rtd_theme'
218-
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
219-
except ImportError:
220-
sys.stderr.write('Warning: The Sphinx \'sphinx_rtd_theme\' HTML theme was not found. Make sure you have the theme installed to produce pretty HTML output. Falling back to the default theme.\n')
211+
# Default theme
212+
html_theme = 'sphinx_rtd_theme'
213+
html_css_files = []
214+
215+
if "DOCS_THEME" in os.environ:
216+
html_theme = os.environ["DOCS_THEME"]
217+
218+
if html_theme == 'sphinx_rtd_theme' or html_theme == 'sphinx_rtd_dark_mode':
219+
# Read the Docs theme
220+
try:
221+
import sphinx_rtd_theme
222+
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
223+
224+
# Add any paths that contain custom static files (such as style sheets) here,
225+
# relative to this directory. They are copied after the builtin static files,
226+
# so a file named "default.css" will overwrite the builtin "default.css".
227+
html_css_files = [
228+
'theme_overrides.css',
229+
]
230+
231+
# Read the Docs dark mode override theme
232+
if html_theme == 'sphinx_rtd_dark_mode':
233+
try:
234+
import sphinx_rtd_dark_mode
235+
extensions.append('sphinx_rtd_dark_mode')
236+
except ImportError:
237+
html_theme == 'sphinx_rtd_theme'
238+
239+
if html_theme == 'sphinx_rtd_theme':
240+
# Add color-specific RTD normal mode
241+
html_css_files.append('theme_rtd_colors.css')
242+
243+
except ImportError:
244+
html_theme = 'classic'
245+
246+
if "DOCS_CSS" in os.environ:
247+
css = os.environ["DOCS_CSS"].split(" ")
248+
249+
for l in css:
250+
html_css_files.append(l)
251+
252+
if major <= 1 and minor < 8:
253+
html_context = {
254+
'css_files': [],
255+
}
256+
257+
for l in html_css_files:
258+
html_context['css_files'].append('_static/' + l)
259+
260+
if html_theme == 'classic':
261+
html_theme_options = {
262+
'rightsidebar': False,
263+
'stickysidebar': True,
264+
'collapsiblesidebar': True,
265+
'externalrefs': False,
266+
267+
'footerbgcolor': "white",
268+
'footertextcolor': "white",
269+
'sidebarbgcolor': "white",
270+
'sidebarbtncolor': "black",
271+
'sidebartextcolor': "black",
272+
'sidebarlinkcolor': "#686bff",
273+
'relbarbgcolor': "#133f52",
274+
'relbartextcolor': "white",
275+
'relbarlinkcolor': "white",
276+
'bgcolor': "white",
277+
'textcolor': "black",
278+
'headbgcolor': "#f2f2f2",
279+
'headtextcolor': "#20435c",
280+
'headlinkcolor': "#c60f0f",
281+
'linkcolor': "#355f7c",
282+
'visitedlinkcolor': "#355f7c",
283+
'codebgcolor': "#3f3f3f",
284+
'codetextcolor': "white",
285+
286+
'bodyfont': "serif",
287+
'headfont': "sans-serif",
288+
}
289+
290+
sys.stderr.write("Using %s theme\n" % html_theme)
221291

222292
# Theme options are theme-specific and customize the look and feel of a theme
223293
# further. For a list of options available for each theme, see the
@@ -246,20 +316,8 @@
246316
# Add any paths that contain custom static files (such as style sheets) here,
247317
# relative to this directory. They are copied after the builtin static files,
248318
# so a file named "default.css" will overwrite the builtin "default.css".
249-
250319
html_static_path = ['sphinx-static']
251320

252-
html_css_files = [
253-
'theme_overrides.css',
254-
]
255-
256-
if major <= 1 and minor < 8:
257-
html_context = {
258-
'css_files': [
259-
'_static/theme_overrides.css',
260-
],
261-
}
262-
263321
# Add any extra paths that contain custom files (such as robots.txt or
264322
# .htaccess) here, relative to this directory. These files are copied
265323
# directly to the root of the documentation.

‎Documentation/dev-tools/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ Documentation/dev-tools/testing-overview.rst
3232
kgdb
3333
kselftest
3434
kunit/index
35+
ktap
3536

3637

3738
.. only:: subproject and html

‎Documentation/dev-tools/kgdb.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -402,7 +402,7 @@ This is a quick example of how to use kdb.
402402
2. Enter the kernel debugger manually or by waiting for an oops or
403403
fault. There are several ways you can enter the kernel debugger
404404
manually; all involve using the :kbd:`SysRq-G`, which means you must have
405-
enabled ``CONFIG_MAGIC_SysRq=y`` in your kernel config.
405+
enabled ``CONFIG_MAGIC_SYSRQ=y`` in your kernel config.
406406

407407
- When logged in as root or with a super user session you can run::
408408

@@ -461,7 +461,7 @@ This is a quick example of how to use kdb with a keyboard.
461461
2. Enter the kernel debugger manually or by waiting for an oops or
462462
fault. There are several ways you can enter the kernel debugger
463463
manually; all involve using the :kbd:`SysRq-G`, which means you must have
464-
enabled ``CONFIG_MAGIC_SysRq=y`` in your kernel config.
464+
enabled ``CONFIG_MAGIC_SYSRQ=y`` in your kernel config.
465465

466466
- When logged in as root or with a super user session you can run::
467467

@@ -557,7 +557,7 @@ Connecting with gdb to a serial port
557557
Example (using a directly connected port)::
558558

559559
% gdb ./vmlinux
560-
(gdb) set remotebaud 115200
560+
(gdb) set serial baud 115200
561561
(gdb) target remote /dev/ttyS0
562562

563563

0 commit comments

Comments
 (0)