From 290d5388993eb40b9d5632aefb864cf1012a2bcc Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 22 Feb 2020 10:00:01 +0100 Subject: scripts: documentation-file-ref-check: improve :doc: handling There are some issues at the script with regards to :doc: tags: - It doesn't escape files under Documentation/sphinx, leading to false positives; - It doesn't handle root URLs, like :doc:`/x86/boot`; - It doesn't output the file with a bad reference. Address those things, in order to remove false positives from the list of problems. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/documentation-file-ref-check | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/documentation-file-ref-check b/scripts/documentation-file-ref-check index 7784c54aa38b..997202a18ddb 100755 --- a/scripts/documentation-file-ref-check +++ b/scripts/documentation-file-ref-check @@ -51,7 +51,9 @@ open IN, "git grep ':doc:\`' Documentation/|" or die "Failed to run git grep"; while () { next if (!m,^([^:]+):.*\:doc\:\`([^\`]+)\`,); + next if (m,sphinx/,); + my $file = $1; my $d = $1; my $doc_ref = $2; @@ -60,7 +62,12 @@ while () { $d =~ s,(.*/).*,$1,; $f =~ s,.*\<([^\>]+)\>,$1,; - $f ="$d$f.rst"; + if ($f =~ m,^/,) { + $f = "$f.rst"; + $f =~ s,^/,Documentation/,; + } else { + $f = "$d$f.rst"; + } next if (grep -e, glob("$f")); @@ -69,7 +76,7 @@ while () { } $doc_fix++; - print STDERR "$f: :doc:`$doc_ref`\n"; + print STDERR "$file: :doc:`$doc_ref`\n"; } close IN; -- cgit v1.2.3-59-g8ed1b From 021622df556b7213cffec1c0713f093fc7d045e3 Mon Sep 17 00:00:00 2001 From: Stephen Kitt Date: Wed, 19 Feb 2020 16:34:42 +0100 Subject: docs: add a script to check sysctl docs This script allows sysctl documentation to be checked against the kernel source code, to identify missing or obsolete entries. Running it against 5.5 shows for example that sysctl/kernel.rst has two obsolete entries and is missing 52 entries. Signed-off-by: Stephen Kitt Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/sysctl/kernel.rst | 3 + scripts/check-sysctl-docs | 181 ++++++++++++++++++++++++++++ 2 files changed, 184 insertions(+) create mode 100755 scripts/check-sysctl-docs (limited to 'scripts') diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst index 6586e0e0c11f..1c48ab4bfe30 100644 --- a/Documentation/admin-guide/sysctl/kernel.rst +++ b/Documentation/admin-guide/sysctl/kernel.rst @@ -2,6 +2,9 @@ Documentation for /proc/sys/kernel/ =================================== +.. See scripts/check-sysctl-docs to keep this up to date + + Copyright (c) 1998, 1999, Rik van Riel Copyright (c) 2009, Shen Feng diff --git a/scripts/check-sysctl-docs b/scripts/check-sysctl-docs new file mode 100755 index 000000000000..8bcb9e26c7bc --- /dev/null +++ b/scripts/check-sysctl-docs @@ -0,0 +1,181 @@ +#!/usr/bin/gawk -f +# SPDX-License-Identifier: GPL-2.0 + +# Script to check sysctl documentation against source files +# +# Copyright (c) 2020 Stephen Kitt + +# Example invocation: +# scripts/check-sysctl-docs -vtable="kernel" \ +# Documentation/admin-guide/sysctl/kernel.rst \ +# $(git grep -l register_sysctl_) +# +# Specify -vdebug=1 to see debugging information + +BEGIN { + if (!table) { + print "Please specify the table to look for using the table variable" > "/dev/stderr" + exit 1 + } +} + +# The following globals are used: +# children: maps ctl_table names and procnames to child ctl_table names +# documented: maps documented entries (each key is an entry) +# entries: maps ctl_table names and procnames to counts (so +# enumerating the subkeys for a given ctl_table lists its +# procnames) +# files: maps procnames to source file names +# paths: maps ctl_path names to paths +# curpath: the name of the current ctl_path struct +# curtable: the name of the current ctl_table struct +# curentry: the name of the current proc entry (procname when parsing +# a ctl_table, constructed path when parsing a ctl_path) + + +# Remove punctuation from the given value +function trimpunct(value) { + while (value ~ /^["&]/) { + value = substr(value, 2) + } + while (value ~ /[]["&,}]$/) { + value = substr(value, 1, length(value) - 1) + } + return value +} + +# Print the information for the given entry +function printentry(entry) { + seen[entry]++ + printf "* %s from %s", entry, file[entry] + if (documented[entry]) { + printf " (documented)" + } + print "" +} + + +# Stage 1: build the list of documented entries +FNR == NR && /^=+$/ { + if (prevline ~ /Documentation for/) { + # This is the main title + next + } + + # The previous line is a section title, parse it + $0 = prevline + if (debug) print "Parsing " $0 + inbrackets = 0 + for (i = 1; i <= NF; i++) { + if (length($i) == 0) { + continue + } + if (!inbrackets && substr($i, 1, 1) == "(") { + inbrackets = 1 + } + if (!inbrackets) { + token = trimpunct($i) + if (length(token) > 0 && token != "and") { + if (debug) print trimpunct($i) + documented[trimpunct($i)]++ + } + } + if (inbrackets && substr($i, length($i), 1) == ")") { + inbrackets = 0 + } + } +} + +FNR == NR { + prevline = $0 + next +} + + +# Stage 2: process each file and find all sysctl tables +BEGINFILE { + delete children + delete entries + delete paths + curpath = "" + curtable = "" + curentry = "" + if (debug) print "Processing file " FILENAME +} + +/^static struct ctl_path/ { + match($0, /static struct ctl_path ([^][]+)/, tables) + curpath = tables[1] + if (debug) print "Processing path " curpath +} + +/^static struct ctl_table/ { + match($0, /static struct ctl_table ([^][]+)/, tables) + curtable = tables[1] + if (debug) print "Processing table " curtable +} + +/^};$/ { + curpath = "" + curtable = "" + curentry = "" +} + +curpath && /\.procname[\t ]*=[\t ]*".+"/ { + match($0, /.procname[\t ]*=[\t ]*"([^"]+)"/, names) + if (curentry) { + curentry = curentry "/" names[1] + } else { + curentry = names[1] + } + if (debug) print "Setting path " curpath " to " curentry + paths[curpath] = curentry +} + +curtable && /\.procname[\t ]*=[\t ]*".+"/ { + match($0, /.procname[\t ]*=[\t ]*"([^"]+)"/, names) + curentry = names[1] + if (debug) print "Adding entry " curentry " to table " curtable + entries[curtable][curentry]++ + file[curentry] = FILENAME +} + +/\.child[\t ]*=/ { + child = trimpunct($NF) + if (debug) print "Linking child " child " to table " curtable " entry " curentry + children[curtable][curentry] = child +} + +/register_sysctl_table\(.*\)/ { + match($0, /register_sysctl_table\(([^)]+)\)/, tables) + if (debug) print "Registering table " tables[1] + if (children[tables[1]][table]) { + for (entry in entries[children[tables[1]][table]]) { + printentry(entry) + } + } +} + +/register_sysctl_paths\(.*\)/ { + match($0, /register_sysctl_paths\(([^)]+), ([^)]+)\)/, tables) + if (debug) print "Attaching table " tables[2] " to path " tables[1] + if (paths[tables[1]] == table) { + for (entry in entries[tables[2]]) { + printentry(entry) + } + } + split(paths[tables[1]], components, "/") + if (length(components) > 1 && components[1] == table) { + # Count the first subdirectory as seen + seen[components[2]]++ + } +} + + +END { + for (entry in documented) { + if (!seen[entry]) { + print "No implementation for " entry + } + } +} -- cgit v1.2.3-59-g8ed1b From c428cd52282dcc967b2a936d80f1eec4cb80d6d5 Mon Sep 17 00:00:00 2001 From: Tim Bird Date: Mon, 24 Feb 2020 18:34:41 -0700 Subject: scripts/sphinx-pre-install: add '-p python3' to virtualenv With Ubuntu 16.04 (and presumably Debian distros of the same age), the instructions for setting up a python virtual environment should do so with the python 3 interpreter. On these older distros, the default python (and virtualenv command) might be python2 based. Some of the packages that sphinx relies on are now only available for python3. If you don't specify the python3 interpreter for the virtualenv, you get errors when doing the pip installs for various packages Fix this by adding '-p python3' to the virtualenv recommendation line. Signed-off-by: Tim Bird Link: https://lore.kernel.org/r/1582594481-23221-1-git-send-email-tim.bird@sony.com Signed-off-by: Jonathan Corbet --- scripts/sphinx-pre-install | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index a8f0c002a340..fa3fb05cd54b 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -701,11 +701,26 @@ sub check_needs() } else { my $rec_activate = "$virtenv_dir/bin/activate"; my $virtualenv = findprog("virtualenv-3"); + my $rec_python3 = ""; $virtualenv = findprog("virtualenv-3.5") if (!$virtualenv); $virtualenv = findprog("virtualenv") if (!$virtualenv); $virtualenv = "virtualenv" if (!$virtualenv); - printf "\t$virtualenv $virtenv_dir\n"; + my $rel = ""; + if (index($system_release, "Ubuntu") != -1) { + $rel = $1 if ($system_release =~ /Ubuntu\s+(\d+)[.]/); + if ($rel && $rel >= 16) { + $rec_python3 = " -p python3"; + } + } + if (index($system_release, "Debian") != -1) { + $rel = $1 if ($system_release =~ /Debian\s+(\d+)/); + if ($rel && $rel >= 7) { + $rec_python3 = " -p python3"; + } + } + + printf "\t$virtualenv$rec_python3 $virtenv_dir\n"; printf "\t. $rec_activate\n"; printf "\tpip install -r $requirement_file\n"; deactivate_help(); -- cgit v1.2.3-59-g8ed1b From 2b4cbd5c950525b6d4d2cd384dcefdd95fedabe3 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Mon, 2 Mar 2020 15:24:04 -0700 Subject: docs: move gcc-plugins to the kbuild manual Information about GCC plugins is relevant to kernel building, so move this document to the kbuild manual. Acked-by: Masahiro Yamada Signed-off-by: Jonathan Corbet --- Documentation/core-api/gcc-plugins.rst | 97 ---------------------------------- Documentation/core-api/index.rst | 1 - Documentation/kbuild/gcc-plugins.rst | 97 ++++++++++++++++++++++++++++++++++ Documentation/kbuild/index.rst | 1 + MAINTAINERS | 2 +- scripts/gcc-plugins/Kconfig | 2 +- 6 files changed, 100 insertions(+), 100 deletions(-) delete mode 100644 Documentation/core-api/gcc-plugins.rst create mode 100644 Documentation/kbuild/gcc-plugins.rst (limited to 'scripts') diff --git a/Documentation/core-api/gcc-plugins.rst b/Documentation/core-api/gcc-plugins.rst deleted file mode 100644 index 4b1c10f88e30..000000000000 --- a/Documentation/core-api/gcc-plugins.rst +++ /dev/null @@ -1,97 +0,0 @@ -========================= -GCC plugin infrastructure -========================= - - -Introduction -============ - -GCC plugins are loadable modules that provide extra features to the -compiler [1]_. They are useful for runtime instrumentation and static analysis. -We can analyse, change and add further code during compilation via -callbacks [2]_, GIMPLE [3]_, IPA [4]_ and RTL passes [5]_. - -The GCC plugin infrastructure of the kernel supports all gcc versions from -4.5 to 6.0, building out-of-tree modules, cross-compilation and building in a -separate directory. -Plugin source files have to be compilable by both a C and a C++ compiler as well -because gcc versions 4.5 and 4.6 are compiled by a C compiler, -gcc-4.7 can be compiled by a C or a C++ compiler, -and versions 4.8+ can only be compiled by a C++ compiler. - -Currently the GCC plugin infrastructure supports only the x86, arm, arm64 and -powerpc architectures. - -This infrastructure was ported from grsecurity [6]_ and PaX [7]_. - --- - -.. [1] https://gcc.gnu.org/onlinedocs/gccint/Plugins.html -.. [2] https://gcc.gnu.org/onlinedocs/gccint/Plugin-API.html#Plugin-API -.. [3] https://gcc.gnu.org/onlinedocs/gccint/GIMPLE.html -.. [4] https://gcc.gnu.org/onlinedocs/gccint/IPA.html -.. [5] https://gcc.gnu.org/onlinedocs/gccint/RTL.html -.. [6] https://grsecurity.net/ -.. [7] https://pax.grsecurity.net/ - - -Files -===== - -**$(src)/scripts/gcc-plugins** - - This is the directory of the GCC plugins. - -**$(src)/scripts/gcc-plugins/gcc-common.h** - - This is a compatibility header for GCC plugins. - It should be always included instead of individual gcc headers. - -**$(src)/scripts/gcc-plugin.sh** - - This script checks the availability of the included headers in - gcc-common.h and chooses the proper host compiler to build the plugins - (gcc-4.7 can be built by either gcc or g++). - -**$(src)/scripts/gcc-plugins/gcc-generate-gimple-pass.h, -$(src)/scripts/gcc-plugins/gcc-generate-ipa-pass.h, -$(src)/scripts/gcc-plugins/gcc-generate-simple_ipa-pass.h, -$(src)/scripts/gcc-plugins/gcc-generate-rtl-pass.h** - - These headers automatically generate the registration structures for - GIMPLE, SIMPLE_IPA, IPA and RTL passes. They support all gcc versions - from 4.5 to 6.0. - They should be preferred to creating the structures by hand. - - -Usage -===== - -You must install the gcc plugin headers for your gcc version, -e.g., on Ubuntu for gcc-4.9:: - - apt-get install gcc-4.9-plugin-dev - -Or on Fedora:: - - dnf install gcc-plugin-devel - -Enable a GCC plugin based feature in the kernel config:: - - CONFIG_GCC_PLUGIN_CYC_COMPLEXITY = y - -To compile only the plugin(s):: - - make gcc-plugins - -or just run the kernel make and compile the whole kernel with -the cyclomatic complexity GCC plugin. - - -4. How to add a new GCC plugin -============================== - -The GCC plugins are in $(src)/scripts/gcc-plugins/. You can use a file or a directory -here. It must be added to $(src)/scripts/gcc-plugins/Makefile, -$(src)/scripts/Makefile.gcc-plugins and $(src)/arch/Kconfig. -See the cyc_complexity_plugin.c (CONFIG_GCC_PLUGIN_CYC_COMPLEXITY) GCC plugin. diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index b39dae276b57..9836a0ac09a3 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -102,7 +102,6 @@ Documents that don't fit elsewhere or which have yet to be categorized. :maxdepth: 1 librs - gcc-plugins ioctl .. only:: subproject and html diff --git a/Documentation/kbuild/gcc-plugins.rst b/Documentation/kbuild/gcc-plugins.rst new file mode 100644 index 000000000000..4b1c10f88e30 --- /dev/null +++ b/Documentation/kbuild/gcc-plugins.rst @@ -0,0 +1,97 @@ +========================= +GCC plugin infrastructure +========================= + + +Introduction +============ + +GCC plugins are loadable modules that provide extra features to the +compiler [1]_. They are useful for runtime instrumentation and static analysis. +We can analyse, change and add further code during compilation via +callbacks [2]_, GIMPLE [3]_, IPA [4]_ and RTL passes [5]_. + +The GCC plugin infrastructure of the kernel supports all gcc versions from +4.5 to 6.0, building out-of-tree modules, cross-compilation and building in a +separate directory. +Plugin source files have to be compilable by both a C and a C++ compiler as well +because gcc versions 4.5 and 4.6 are compiled by a C compiler, +gcc-4.7 can be compiled by a C or a C++ compiler, +and versions 4.8+ can only be compiled by a C++ compiler. + +Currently the GCC plugin infrastructure supports only the x86, arm, arm64 and +powerpc architectures. + +This infrastructure was ported from grsecurity [6]_ and PaX [7]_. + +-- + +.. [1] https://gcc.gnu.org/onlinedocs/gccint/Plugins.html +.. [2] https://gcc.gnu.org/onlinedocs/gccint/Plugin-API.html#Plugin-API +.. [3] https://gcc.gnu.org/onlinedocs/gccint/GIMPLE.html +.. [4] https://gcc.gnu.org/onlinedocs/gccint/IPA.html +.. [5] https://gcc.gnu.org/onlinedocs/gccint/RTL.html +.. [6] https://grsecurity.net/ +.. [7] https://pax.grsecurity.net/ + + +Files +===== + +**$(src)/scripts/gcc-plugins** + + This is the directory of the GCC plugins. + +**$(src)/scripts/gcc-plugins/gcc-common.h** + + This is a compatibility header for GCC plugins. + It should be always included instead of individual gcc headers. + +**$(src)/scripts/gcc-plugin.sh** + + This script checks the availability of the included headers in + gcc-common.h and chooses the proper host compiler to build the plugins + (gcc-4.7 can be built by either gcc or g++). + +**$(src)/scripts/gcc-plugins/gcc-generate-gimple-pass.h, +$(src)/scripts/gcc-plugins/gcc-generate-ipa-pass.h, +$(src)/scripts/gcc-plugins/gcc-generate-simple_ipa-pass.h, +$(src)/scripts/gcc-plugins/gcc-generate-rtl-pass.h** + + These headers automatically generate the registration structures for + GIMPLE, SIMPLE_IPA, IPA and RTL passes. They support all gcc versions + from 4.5 to 6.0. + They should be preferred to creating the structures by hand. + + +Usage +===== + +You must install the gcc plugin headers for your gcc version, +e.g., on Ubuntu for gcc-4.9:: + + apt-get install gcc-4.9-plugin-dev + +Or on Fedora:: + + dnf install gcc-plugin-devel + +Enable a GCC plugin based feature in the kernel config:: + + CONFIG_GCC_PLUGIN_CYC_COMPLEXITY = y + +To compile only the plugin(s):: + + make gcc-plugins + +or just run the kernel make and compile the whole kernel with +the cyclomatic complexity GCC plugin. + + +4. How to add a new GCC plugin +============================== + +The GCC plugins are in $(src)/scripts/gcc-plugins/. You can use a file or a directory +here. It must be added to $(src)/scripts/gcc-plugins/Makefile, +$(src)/scripts/Makefile.gcc-plugins and $(src)/arch/Kconfig. +See the cyc_complexity_plugin.c (CONFIG_GCC_PLUGIN_CYC_COMPLEXITY) GCC plugin. diff --git a/Documentation/kbuild/index.rst b/Documentation/kbuild/index.rst index 0f144fad99a6..82daf2efcb73 100644 --- a/Documentation/kbuild/index.rst +++ b/Documentation/kbuild/index.rst @@ -19,6 +19,7 @@ Kernel Build System issues reproducible-builds + gcc-plugins .. only:: subproject and html diff --git a/MAINTAINERS b/MAINTAINERS index 083fcf1a151c..8c5712079412 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -6934,7 +6934,7 @@ S: Maintained F: scripts/gcc-plugins/ F: scripts/gcc-plugin.sh F: scripts/Makefile.gcc-plugins -F: Documentation/core-api/gcc-plugins.rst +F: Documentation/kbuild/gcc-plugins.rst GASKET DRIVER FRAMEWORK M: Rob Springer diff --git a/scripts/gcc-plugins/Kconfig b/scripts/gcc-plugins/Kconfig index e3569543bdac..f8ca236d6165 100644 --- a/scripts/gcc-plugins/Kconfig +++ b/scripts/gcc-plugins/Kconfig @@ -23,7 +23,7 @@ menuconfig GCC_PLUGINS GCC plugins are loadable modules that provide extra features to the compiler. They are useful for runtime instrumentation and static analysis. - See Documentation/core-api/gcc-plugins.rst for details. + See Documentation/kbuild/gcc-plugins.rst for details. if GCC_PLUGINS -- cgit v1.2.3-59-g8ed1b