summaryrefslogtreecommitdiff
path: root/scripts
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2019-12-02 11:51:02 -0800
committerLinus Torvalds <torvalds@linux-foundation.org>2019-12-02 11:51:02 -0800
commit937d6eefc716a9071f0e3bada19200de1bb9d048 (patch)
tree7b2b8e94d157ddbacc2b0712fd5d20a8b4d79c27 /scripts
parent2c97b5ae83dca56718774e7b4bf9640f05d11867 (diff)
parent36bb9778fd11173f2dd1484e4f6797365e18c1d8 (diff)
Merge tag 'docs-5.5a' of git://git.lwn.net/linux
Pull Documentation updates from Jonathan Corbet: "Here are the main documentation changes for 5.5: - Various kerneldoc script enhancements. - More RST conversions; those are slowing down as we run out of things to convert, but we're a ways from done still. - Dan's "maintainer profile entry" work landed at last. Now we just need to get maintainers to fill in the profiles... - A reworking of the parallel build setup to work better with a variety of systems (and to not take over huge systems entirely in particular). - The MAINTAINERS file is now converted to RST during the build. Hopefully nobody ever tries to print this thing, or they will need to load a lot of paper. - A script and documentation making it easy for maintainers to add Link: tags at commit time. Also included is the removal of a bunch of spurious CR characters" * tag 'docs-5.5a' of git://git.lwn.net/linux: (91 commits) docs: remove a bunch of stray CRs docs: fix up the maintainer profile document libnvdimm, MAINTAINERS: Maintainer Entry Profile Maintainer Handbook: Maintainer Entry Profile MAINTAINERS: Reclaim the P: tag for Maintainer Entry Profile docs, parallelism: Rearrange how jobserver reservations are made docs, parallelism: Do not leak blocking mode to other readers docs, parallelism: Fix failure path and add comment Documentation: Remove bootmem_debug from kernel-parameters.txt Documentation: security: core.rst: fix warnings Documentation/process/howto/kokr: Update for 4.x -> 5.x versioning Documentation/translation: Use Korean for Korean translation title docs/memory-barriers.txt: Remove remaining references to mmiowb() docs/memory-barriers.txt/kokr: Update I/O section to be clearer about CPU vs thread docs/memory-barriers.txt/kokr: Fix style, spacing and grammar in I/O section Documentation/kokr: Kill all references to mmiowb() docs/memory-barriers.txt/kokr: Rewrite "KERNEL I/O BARRIER EFFECTS" section docs: Add initial documentation for devfreq Documentation: Document how to get links with git am docs: Add request_irq() documentation ...
Diffstat (limited to 'scripts')
-rwxr-xr-xscripts/jobserver-exec66
-rwxr-xr-xscripts/kernel-doc27
-rwxr-xr-xscripts/sphinx-pre-install30
3 files changed, 109 insertions, 14 deletions
diff --git a/scripts/jobserver-exec b/scripts/jobserver-exec
new file mode 100755
index 000000000000..0fdb31a790a8
--- /dev/null
+++ b/scripts/jobserver-exec
@@ -0,0 +1,66 @@
+#!/usr/bin/env python
+# SPDX-License-Identifier: GPL-2.0+
+#
+# This determines how many parallel tasks "make" is expecting, as it is
+# not exposed via an special variables, reserves them all, runs a subprocess
+# with PARALLELISM environment variable set, and releases the jobs back again.
+#
+# https://www.gnu.org/software/make/manual/html_node/POSIX-Jobserver.html#POSIX-Jobserver
+from __future__ import print_function
+import os, sys, errno
+import subprocess
+
+# Extract and prepare jobserver file descriptors from envirnoment.
+claim = 0
+jobs = b""
+try:
+ # Fetch the make environment options.
+ flags = os.environ['MAKEFLAGS']
+
+ # Look for "--jobserver=R,W"
+ # Note that GNU Make has used --jobserver-fds and --jobserver-auth
+ # so this handles all of them.
+ opts = [x for x in flags.split(" ") if x.startswith("--jobserver")]
+
+ # Parse out R,W file descriptor numbers and set them nonblocking.
+ fds = opts[0].split("=", 1)[1]
+ reader, writer = [int(x) for x in fds.split(",", 1)]
+ # Open a private copy of reader to avoid setting nonblocking
+ # on an unexpecting process with the same reader fd.
+ reader = os.open("/proc/self/fd/%d" % (reader),
+ os.O_RDONLY | os.O_NONBLOCK)
+
+ # Read out as many jobserver slots as possible.
+ while True:
+ try:
+ slot = os.read(reader, 8)
+ jobs += slot
+ except (OSError, IOError) as e:
+ if e.errno == errno.EWOULDBLOCK:
+ # Stop at the end of the jobserver queue.
+ break
+ # If something went wrong, give back the jobs.
+ if len(jobs):
+ os.write(writer, jobs)
+ raise e
+ # Add a bump for our caller's reserveration, since we're just going
+ # to sit here blocked on our child.
+ claim = len(jobs) + 1
+except (KeyError, IndexError, ValueError, OSError, IOError) as e:
+ # Any missing environment strings or bad fds should result in just
+ # not being parallel.
+ pass
+
+# We can only claim parallelism if there was a jobserver (i.e. a top-level
+# "-jN" argument) and there were no other failures. Otherwise leave out the
+# environment variable and let the child figure out what is best.
+if claim > 0:
+ os.environ['PARALLELISM'] = '%d' % (claim)
+
+rc = subprocess.call(sys.argv[1:])
+
+# Return all the reserved slots.
+if len(jobs):
+ os.write(writer, jobs)
+
+sys.exit(rc)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 81dc91760b23..f2d73f04e71d 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1062,7 +1062,7 @@ sub dump_struct($$) {
my $x = shift;
my $file = shift;
- if ($x =~ /(struct|union)\s+(\w+)\s*\{(.*)\}(\s*(__packed|__aligned|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*/) {
+ if ($x =~ /(struct|union)\s+(\w+)\s*\{(.*)\}(\s*(__packed|__aligned|____cacheline_aligned_in_smp|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*/) {
my $decl_type = $1;
$declaration_name = $2;
my $members = $3;
@@ -1073,10 +1073,11 @@ sub dump_struct($$) {
# strip comments:
$members =~ s/\/\*.*?\*\///gos;
# strip attributes
- $members =~ s/\s*__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)//gi;
- $members =~ s/\s*__aligned\s*\([^;]*\)//gos;
- $members =~ s/\s*__packed\s*//gos;
- $members =~ s/\s*CRYPTO_MINALIGN_ATTR//gos;
+ $members =~ s/\s*__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)/ /gi;
+ $members =~ s/\s*__aligned\s*\([^;]*\)/ /gos;
+ $members =~ s/\s*__packed\s*/ /gos;
+ $members =~ s/\s*CRYPTO_MINALIGN_ATTR/ /gos;
+ $members =~ s/\s*____cacheline_aligned_in_smp/ /gos;
# replace DECLARE_BITMAP
$members =~ s/DECLARE_BITMAP\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
# replace DECLARE_HASHTABLE
@@ -1449,6 +1450,10 @@ sub push_parameter($$$$) {
# handles unnamed variable parameters
$param = "...";
}
+ elsif ($param =~ /\w\.\.\.$/) {
+ # for named variable parameters of the form `x...`, remove the dots
+ $param =~ s/\.\.\.$//;
+ }
if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
$parameterdescs{$param} = "variable arguments";
}
@@ -1936,6 +1941,18 @@ sub process_name($$) {
sub process_body($$) {
my $file = shift;
+ # Until all named variable macro parameters are
+ # documented using the bare name (`x`) rather than with
+ # dots (`x...`), strip the dots:
+ if ($section =~ /\w\.\.\.$/) {
+ $section =~ s/\.\.\.$//;
+
+ if ($verbose) {
+ print STDERR "${file}:$.: warning: Variable macro arguments should be documented without dots\n";
+ ++$warnings;
+ }
+ }
+
if (/$doc_sect/i) { # case insensitive for supported section names
$newsection = $1;
$newcontents = $2;
diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
index 3b638c0e1a4f..470ccfe678aa 100755
--- a/scripts/sphinx-pre-install
+++ b/scripts/sphinx-pre-install
@@ -124,11 +124,13 @@ sub add_package($$)
sub check_missing_file($$$)
{
- my $file = shift;
+ my $files = shift;
my $package = shift;
my $is_optional = shift;
- return if(-e $file);
+ for (@$files) {
+ return if(-e $_);
+ }
add_package($package, $is_optional);
}
@@ -343,10 +345,11 @@ sub give_debian_hints()
);
if ($pdf) {
- check_missing_file("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
+ check_missing_file(["/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"],
"fonts-dejavu", 2);
- check_missing_file("/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc",
+ check_missing_file(["/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc",
+ "/usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc"],
"fonts-noto-cjk", 2);
}
@@ -413,7 +416,7 @@ sub give_redhat_hints()
}
if ($pdf) {
- check_missing_file("/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc",
+ check_missing_file(["/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc"],
"google-noto-sans-cjk-ttc-fonts", 2);
}
@@ -498,7 +501,7 @@ sub give_mageia_hints()
$map{"latexmk"} = "texlive-collection-basic";
if ($pdf) {
- check_missing_file("/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc",
+ check_missing_file(["/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc"],
"google-noto-sans-cjk-ttc-fonts", 2);
}
@@ -517,6 +520,7 @@ sub give_arch_linux_hints()
"dot" => "graphviz",
"convert" => "imagemagick",
"xelatex" => "texlive-bin",
+ "latexmk" => "texlive-core",
"rsvg-convert" => "extra/librsvg",
);
@@ -528,7 +532,7 @@ sub give_arch_linux_hints()
check_pacman_missing(\@archlinux_tex_pkgs, 2) if ($pdf);
if ($pdf) {
- check_missing_file("/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc",
+ check_missing_file(["/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc"],
"noto-fonts-cjk", 2);
}
@@ -549,11 +553,11 @@ sub give_gentoo_hints()
"rsvg-convert" => "gnome-base/librsvg",
);
- check_missing_file("/usr/share/fonts/dejavu/DejaVuSans.ttf",
+ check_missing_file(["/usr/share/fonts/dejavu/DejaVuSans.ttf"],
"media-fonts/dejavu", 2) if ($pdf);
if ($pdf) {
- check_missing_file("/usr/share/fonts/noto-cjk/NotoSansCJKsc-Regular.otf",
+ check_missing_file(["/usr/share/fonts/noto-cjk/NotoSansCJKsc-Regular.otf"],
"media-fonts/noto-cjk", 2);
}
@@ -645,6 +649,12 @@ sub check_distros()
# Common dependencies
#
+sub deactivate_help()
+{
+ printf "\tIf you want to exit the virtualenv, you can use:\n";
+ printf "\tdeactivate\n";
+}
+
sub check_needs()
{
# Check for needed programs/tools
@@ -686,6 +696,7 @@ sub check_needs()
if ($need_sphinx && scalar @activates > 0 && $activates[0] ge $min_activate) {
printf "\nNeed to activate a compatible Sphinx version on virtualenv with:\n";
printf "\t. $activates[0]\n";
+ deactivate_help();
exit (1);
} else {
my $rec_activate = "$virtenv_dir/bin/activate";
@@ -697,6 +708,7 @@ sub check_needs()
printf "\t$virtualenv $virtenv_dir\n";
printf "\t. $rec_activate\n";
printf "\tpip install -r $requirement_file\n";
+ deactivate_help();
$need++ if (!$rec_sphinx_upgrade);
}