From b0d60bfbb60cef1efd699a65e29a94487f8c7b1f Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Fri, 24 May 2019 14:52:01 -0600 Subject: kernel-doc: always name missing kerneldoc sections The "no structured comments found" warning is not particularly useful if there are several invocations, one of which is looking for something wrong. So if something specific has been requested, make it clear that it's the one we weren't able to find. Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 3350e498b4ce..c0cb41e65b9b 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -285,7 +285,7 @@ use constant { OUTPUT_INTERNAL => 4, # output non-exported symbols }; my $output_selection = OUTPUT_ALL; -my $show_not_found = 0; +my $show_not_found = 0; # No longer used my @export_file_list; @@ -435,7 +435,7 @@ while ($ARGV[0] =~ m/^--?(.*)/) { } elsif ($cmd eq 'enable-lineno') { $enable_lineno = 1; } elsif ($cmd eq 'show-not-found') { - $show_not_found = 1; + $show_not_found = 1; # A no-op but don't fail } else { # Unknown argument usage(); @@ -2163,12 +2163,14 @@ sub process_file($) { } # Make sure we got something interesting. - if ($initial_section_counter == $section_counter) { - if ($output_mode ne "none") { - print STDERR "${file}:1: warning: no structured comments found\n"; + if ($initial_section_counter == $section_counter && $ + output_mode ne "none") { + if ($output_selection == OUTPUT_INCLUDE) { + print STDERR "${file}:1: warning: '$_' not found\n" + for keys %function_table; } - if (($output_selection == OUTPUT_INCLUDE) && ($show_not_found == 1)) { - print STDERR " Was looking for '$_'.\n" for keys %function_table; + else { + print STDERR "${file}:1: warning: no structured comments found\n"; } } } -- cgit v1.2.3 From 44f42165177e6c32f3a6aaceeaf7d9cd1c95595f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 29 May 2019 20:09:24 -0300 Subject: scripts/sphinx-pre-install: make activate hint smarter It is possible that multiple Sphinx virtualenvs are installed on a given kernel tree. Change the logic to get the latest version of those, as this is probably what the user wants. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/sphinx-pre-install | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) (limited to 'scripts') diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index 8c2d1bcf2e02..11239eb29695 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -1,7 +1,7 @@ #!/usr/bin/perl use strict; -# Copyright (c) 2017 Mauro Carvalho Chehab +# Copyright (c) 2017-2019 Mauro Carvalho Chehab # # This program is free software; you can redistribute it and/or # modify it under the terms of the GNU General Public License @@ -15,6 +15,7 @@ use strict; my $conf = "Documentation/conf.py"; my $requirement_file = "Documentation/sphinx/requirements.txt"; +my $virtenv_prefix = "sphinx_"; # # Static vars @@ -28,7 +29,8 @@ my $need_symlink = 0; my $need_sphinx = 0; my $rec_sphinx_upgrade = 0; my $install = ""; -my $virtenv_dir = "sphinx_"; +my $virtenv_dir = ""; +my $min_version; # # Command line arguments @@ -229,7 +231,6 @@ sub get_sphinx_fname() sub check_sphinx() { - my $min_version; my $rec_version; my $cur_version; @@ -255,7 +256,7 @@ sub check_sphinx() die "Can't get recommended sphinx version from $requirement_file" if (!$min_version); - $virtenv_dir .= $rec_version; + $virtenv_dir = $virtenv_prefix . $rec_version; my $sphinx = get_sphinx_fname(); return if ($sphinx eq ""); @@ -612,18 +613,23 @@ sub check_needs() which("sphinx-build-3"); } if ($need_sphinx || $rec_sphinx_upgrade) { - my $activate = "$virtenv_dir/bin/activate"; - if (-e "$ENV{'PWD'}/$activate") { + my $min_activate = "$ENV{'PWD'}/${virtenv_prefix}${min_version}/bin/activate"; + my @activates = glob "$ENV{'PWD'}/${virtenv_prefix}*/bin/activate"; + + @activates = sort {$b cmp $a} @activates; + + if (scalar @activates > 0 && $activates[0] ge $min_activate) { printf "\nNeed to activate virtualenv with:\n"; - printf "\t. $activate\n"; + printf "\t. $activates[0]\n"; } else { + my $rec_activate = "$virtenv_dir/bin/activate"; my $virtualenv = findprog("virtualenv-3"); $virtualenv = findprog("virtualenv-3.5") if (!$virtualenv); $virtualenv = findprog("virtualenv") if (!$virtualenv); $virtualenv = "virtualenv" if (!$virtualenv); printf "\t$virtualenv $virtenv_dir\n"; - printf "\t. $activate\n"; + printf "\t. $rec_activate\n"; printf "\tpip install -r $requirement_file\n"; $need++ if (!$rec_sphinx_upgrade); -- cgit v1.2.3 From c4c562defedb7634a717293a5192071983e79781 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 29 May 2019 20:09:25 -0300 Subject: scripts/sphinx-pre-install: get rid of RHEL7 explicity check RHEL8 was already launched. This test won't get it, and will do the wrong thing. Ok, we could fix it, but now we check Sphinx version to ensure that it matches the minimal (1.3), so there's no need for an explicit check there. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/sphinx-pre-install | 13 ------------- 1 file changed, 13 deletions(-) (limited to 'scripts') diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index 11239eb29695..ded3e2ef3f8d 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -581,19 +581,6 @@ sub check_needs() print "Unknown OS\n"; } - # RHEL 7.x and clones have Sphinx version 1.1.x and incomplete texlive - if (($system_release =~ /Red Hat Enterprise Linux/) || - ($system_release =~ /CentOS/) || - ($system_release =~ /Scientific Linux/) || - ($system_release =~ /Oracle Linux Server/)) { - $virtualenv = 1; - $pdf = 0; - - printf("NOTE: On this distro, Sphinx and TexLive shipped versions are incompatible\n"); - printf("with doc build. So, use Sphinx via a Python virtual environment.\n\n"); - printf("This script can't install a TexLive version that would provide PDF.\n"); - } - # Check for needed programs/tools check_sphinx(); check_perl_module("Pod::Usage", 0); -- cgit v1.2.3 From 9b88ad5464af1bf7228991f1c46a9a13484790a4 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 29 May 2019 20:09:26 -0300 Subject: scripts/sphinx-pre-install: always check if version is compatible with build Call the script every time a make docs target is selected, on a simplified check mode. With this change, the script will set two vars: $min_version - obtained from `needs_sphinx` var inside conf.py (currently, '1.3') $rec_version - obtained from sphinx/requirements.txt. With those changes, a target like "make htmldocs" will do: 1) If no sphinx-build/sphinx-build3 is found, it will run the script on normal mode as before, checking for all system dependencies and providing install hints for the needed programs and will abort the build; 2) If no sphinx-build/sphinx-build3 is found, but there is a sphinx_${VER}/bin/activate file, and if ${VER} >= $min_version (string comparation), it will run in full mode, and will recommend to activate the virtualenv. If there are multiple virtualenvs, it will string sort the versions, recommending the highest version and will abort the build; 3) If Sphinx is detected but has a version lower than $min_version, it will run in full mode - with will recommend creating a virtual env using sphinx/requirements.txt, and will abort the build. 4) If Sphinx is detected and version is lower than $rec_version, it will run in full mode and will recommend creating a virtual env using sphinx/requirements.txt. In this case, it **won't** abort the build. 5) If Sphinx is detected and version is equal or righer than $rec_version it will return just after detecting the version ("quick mode"), not checking if are there any missing dependencies. Just like before, if one wants to install Sphinx from the distro, it has to call the script manually and use `--no-virtualenv` argument to get the hints for his OS: You should run: sudo dnf install -y python3-sphinx python3-sphinx_rtd_theme While here, add a small help for the three optional arguments for the script. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/Makefile | 5 +++++ scripts/sphinx-pre-install | 40 +++++++++++++++++++++++++++------------- 2 files changed, 32 insertions(+), 13 deletions(-) (limited to 'scripts') diff --git a/Documentation/Makefile b/Documentation/Makefile index e889e7cb8511..380e24053d6f 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -70,12 +70,14 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) $(abspath $(BUILDDIR)/$3/$4) htmldocs: + @./scripts/sphinx-pre-install --version-check @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) linkcheckdocs: @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var))) latexdocs: + @./scripts/sphinx-pre-install --version-check @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var))) ifeq ($(HAVE_PDFLATEX),0) @@ -87,14 +89,17 @@ pdfdocs: else # HAVE_PDFLATEX pdfdocs: latexdocs + @./scripts/sphinx-pre-install --version-check $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit;) endif # HAVE_PDFLATEX epubdocs: + @./scripts/sphinx-pre-install --version-check @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var))) xmldocs: + @./scripts/sphinx-pre-install --version-check @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var))) endif # HAVE_SPHINX diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index ded3e2ef3f8d..f001fc2fcf12 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -38,6 +38,7 @@ my $min_version; my $pdf = 1; my $virtualenv = 1; +my $version_check = 0; # # List of required texlive packages on Fedora and OpenSuse @@ -277,20 +278,22 @@ sub check_sphinx() die "$sphinx didn't return its version" if (!$cur_version); - printf "Sphinx version %s (minimal: %s, recommended >= %s)\n", - $cur_version, $min_version, $rec_version; - if ($cur_version lt $min_version) { - print "Warning: Sphinx version should be >= $min_version\n\n"; + printf "ERROR: Sphinx version is %s. It should be >= %s (recommended >= %s)\n", + $cur_version, $min_version, $rec_version;; $need_sphinx = 1; return; } if ($cur_version lt $rec_version) { + printf "Sphinx version %s\n", $cur_version; print "Warning: It is recommended at least Sphinx version $rec_version.\n"; - print " To upgrade, use:\n\n"; $rec_sphinx_upgrade = 1; + return; } + + # On version check mode, just assume Sphinx has all mandatory deps + exit (0) if ($version_check); } # @@ -575,14 +578,18 @@ sub check_distros() sub check_needs() { + # Check for needed programs/tools + check_sphinx(); + if ($system_release) { - print "Detected OS: $system_release.\n"; + print "Detected OS: $system_release.\n\n"; } else { - print "Unknown OS\n"; + print "Unknown OS\n\n"; } + print "To upgrade Sphinx, use:\n\n" if ($rec_sphinx_upgrade); + # Check for needed programs/tools - check_sphinx(); check_perl_module("Pod::Usage", 0); check_program("make", 0); check_program("gcc", 0); @@ -601,13 +608,14 @@ sub check_needs() } if ($need_sphinx || $rec_sphinx_upgrade) { my $min_activate = "$ENV{'PWD'}/${virtenv_prefix}${min_version}/bin/activate"; - my @activates = glob "$ENV{'PWD'}/${virtenv_prefix}*/bin/activate"; + my @activates = glob "$ENV{'PWD'}/${virtenv_prefix}*/bin/activate"; - @activates = sort {$b cmp $a} @activates; + @activates = sort {$b cmp $a} @activates; - if (scalar @activates > 0 && $activates[0] ge $min_activate) { - printf "\nNeed to activate virtualenv with:\n"; + 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"; + exit (1); } else { my $rec_activate = "$virtenv_dir/bin/activate"; my $virtualenv = findprog("virtualenv-3"); @@ -646,8 +654,14 @@ while (@ARGV) { $virtualenv = 0; } elsif ($arg eq "--no-pdf"){ $pdf = 0; + } elsif ($arg eq "--version-check"){ + $version_check = 1; } else { - print "Usage:\n\t$0 <--no-virtualenv> <--no-pdf>\n\n"; + print "Usage:\n\t$0 <--no-virtualenv> <--no-pdf> <--version-check>\n\n"; + print "Where:\n"; + print "\t--no-virtualenv\t- Recommend installing Sphinx instead of using a virtualenv\n"; + print "\t--version-check\t- if version is compatible, don't check for missing dependencies\n"; + print "\t--no-pdf\t- don't check for dependencies required to build PDF docs\n\n"; exit -1; } } -- cgit v1.2.3 From 9e78e7fc0b20bcc0d5599f71d297b6fa1a2e7c5f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 29 May 2019 20:09:27 -0300 Subject: scripts/documentation-file-ref-check: better handle translations Only seek for translation renames inside the translation directory. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/documentation-file-ref-check | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) (limited to 'scripts') diff --git a/scripts/documentation-file-ref-check b/scripts/documentation-file-ref-check index 63e9542656f1..6b622b88f4cf 100755 --- a/scripts/documentation-file-ref-check +++ b/scripts/documentation-file-ref-check @@ -141,6 +141,10 @@ print "Auto-fixing broken references. Please double-check the results\n"; foreach my $ref (keys %broken_ref) { my $new =$ref; + my $basedir = "."; + # On translations, only seek inside the translations directory + $basedir = $1 if ($ref =~ m,(Documentation/translations/[^/]+),); + # get just the basename $new =~ s,.*/,,; @@ -161,18 +165,18 @@ foreach my $ref (keys %broken_ref) { # usual reason for breakage: file renamed to .rst if (!$f) { $new =~ s/\.txt$/.rst/; - $f=qx(find . -iname $new) if ($new); + $f=qx(find $basedir -iname $new) if ($new); } # usual reason for breakage: use dash or underline if (!$f) { $new =~ s/[-_]/[-_]/g; - $f=qx(find . -iname $new) if ($new); + $f=qx(find $basedir -iname $new) if ($new); } # Wild guess: seek for the same name on another place if (!$f) { - $f = qx(find . -iname $new) if ($new); + $f = qx(find $basedir -iname $new) if ($new); } my @find = split /\s+/, $f; -- cgit v1.2.3 From aeaacbfed853c17b8ac5e73c21f54d7f0805d899 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 29 May 2019 20:09:28 -0300 Subject: scripts/documentation-file-ref-check: exclude false-positives There are at least two cases where a documentation file was gone for good, but the text still mentions it: 1) drivers/vhost/vhost.c: the reference for Documentation/virtual/lguest/lguest.c is just to give credits to the original work that vhost replaced; 2) Documentation/scsi/scsi_mid_low_api.txt: It gives credit and mentions the old Documentation/Configure.help file that used to be part of Kernel 2.4.x As we don't want to keep the script to keep pinpoint to those every time, let's add a logic at the script to allow it to ignore valid false-positives like the above. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/documentation-file-ref-check | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'scripts') diff --git a/scripts/documentation-file-ref-check b/scripts/documentation-file-ref-check index 6b622b88f4cf..05235775cc71 100755 --- a/scripts/documentation-file-ref-check +++ b/scripts/documentation-file-ref-check @@ -8,6 +8,14 @@ use warnings; use strict; use Getopt::Long qw(:config no_auto_abbrev); +# NOTE: only add things here when the file was gone, but the text wants +# to mention a past documentation file, for example, to give credits for +# the original work. +my %false_positives = ( + "Documentation/scsi/scsi_mid_low_api.txt" => "Documentation/Configure.help", + "drivers/vhost/vhost.c" => "Documentation/virtual/lguest/lguest.c", +); + my $scriptname = $0; $scriptname =~ s,.*/([^/]+/),$1,; @@ -122,6 +130,11 @@ while () { next if (grep -e, glob("$path/$ref $path/$fulref")); } + # Discard known false-positives + if (defined($false_positives{$f})) { + next if ($false_positives{$f} eq $fulref); + } + if ($fix) { if (!($ref =~ m/(scripts|Kconfig|Kbuild)/)) { $broken_ref{$ref}++; -- cgit v1.2.3 From 4904aeed9f686c90dba72980f0067ac1a7dbbfb6 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 29 May 2019 20:09:29 -0300 Subject: scripts/documentation-file-ref-check: improve tools ref handling There's a false positive on perf/util: tools/perf/util/s390-cpumsf.c: Documentation/perf.data-file-format.txt The file is there at tools/perf/Documentation/, but the logic with detects relative documentation references inside tools is not capable of detecting it. So, improve it. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/documentation-file-ref-check | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/documentation-file-ref-check b/scripts/documentation-file-ref-check index 05235775cc71..5d775ca7469b 100755 --- a/scripts/documentation-file-ref-check +++ b/scripts/documentation-file-ref-check @@ -127,7 +127,7 @@ while () { if ($f =~ m/tools/) { my $path = $f; $path =~ s,(.*)/.*,$1,; - next if (grep -e, glob("$path/$ref $path/$fulref")); + next if (grep -e, glob("$path/$ref $path/../$ref $path/$fulref")); } # Discard known false-positives -- cgit v1.2.3 From 0ca862e6f1c7e58e4eb9758fdb09255e6104d6a0 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 29 May 2019 20:09:30 -0300 Subject: scripts/documentation-file-ref-check: teach about .txt -> .yaml renames At DT, files are being renamed to jason. Teach the script how to handle such renames when used in fix mode. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/documentation-file-ref-check | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) (limited to 'scripts') diff --git a/scripts/documentation-file-ref-check b/scripts/documentation-file-ref-check index 5d775ca7469b..ff16db269079 100755 --- a/scripts/documentation-file-ref-check +++ b/scripts/documentation-file-ref-check @@ -165,13 +165,22 @@ foreach my $ref (keys %broken_ref) { # usual reason for breakage: DT file moved around if ($ref =~ /devicetree/) { - my $search = $new; - $search =~ s,^.*/,,; - $f = qx(find Documentation/devicetree/ -iname "*$search*") if ($search); + # usual reason for breakage: DT file renamed to .yaml if (!$f) { - # Manufacturer name may have changed - $search =~ s/^.*,//; + my $new_ref = $ref; + $new_ref =~ s/\.txt$/.yaml/; + $f=$new_ref if (-f $new_ref); + } + + if (!$f) { + my $search = $new; + $search =~ s,^.*/,,; $f = qx(find Documentation/devicetree/ -iname "*$search*") if ($search); + if (!$f) { + # Manufacturer name may have changed + $search =~ s/^.*,//; + $f = qx(find Documentation/devicetree/ -iname "*$search*") if ($search); + } } } -- cgit v1.2.3 From b1663d7e3a7961fc45262fd68a89253f2803036c Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 4 Jun 2019 09:26:27 -0300 Subject: docs: Kbuild/Makefile: allow check for missing docs at build time While this doesn't make sense for production Kernels, in order to avoid regressions when documents are touched, let's add a check target at the make file. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/Kconfig | 13 +++++++++++++ Documentation/Makefile | 5 +++++ Kconfig | 2 ++ scripts/documentation-file-ref-check | 9 +++++++++ 4 files changed, 29 insertions(+) create mode 100644 Documentation/Kconfig (limited to 'scripts') diff --git a/Documentation/Kconfig b/Documentation/Kconfig new file mode 100644 index 000000000000..66046fa1c341 --- /dev/null +++ b/Documentation/Kconfig @@ -0,0 +1,13 @@ +config WARN_MISSING_DOCUMENTS + + bool "Warn if there's a missing documentation file" + depends on COMPILE_TEST + help + It is not uncommon that a document gets renamed. + This option makes the Kernel to check for missing dependencies, + warning when something is missing. Works only if the Kernel + is built from a git tree. + + If unsure, select 'N'. + + diff --git a/Documentation/Makefile b/Documentation/Makefile index 2df0789f90b7..e145e4db508b 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -4,6 +4,11 @@ subdir-y := devicetree/bindings/ +# Check for broken documentation file references +ifeq ($(CONFIG_WARN_MISSING_DOCUMENTS),y) +$(shell $(srctree)/scripts/documentation-file-ref-check --warn) +endif + # You can set these variables from the command line. SPHINXBUILD = sphinx-build SPHINXOPTS = diff --git a/Kconfig b/Kconfig index 48a80beab685..990b0c390dfc 100644 --- a/Kconfig +++ b/Kconfig @@ -30,3 +30,5 @@ source "crypto/Kconfig" source "lib/Kconfig" source "lib/Kconfig.debug" + +source "Documentation/Kconfig" diff --git a/scripts/documentation-file-ref-check b/scripts/documentation-file-ref-check index ff16db269079..440227bb55a9 100755 --- a/scripts/documentation-file-ref-check +++ b/scripts/documentation-file-ref-check @@ -22,9 +22,16 @@ $scriptname =~ s,.*/([^/]+/),$1,; # Parse arguments my $help = 0; my $fix = 0; +my $warn = 0; + +if (! -d ".git") { + printf "Warning: can't check if file exists, as this is not a git tree"; + exit 0; +} GetOptions( 'fix' => \$fix, + 'warn' => \$warn, 'h|help|usage' => \$help, ); @@ -139,6 +146,8 @@ while () { if (!($ref =~ m/(scripts|Kconfig|Kbuild)/)) { $broken_ref{$ref}++; } + } elsif ($warn) { + print STDERR "Warning: $f references a file that doesn't exist: $fulref\n"; } else { print STDERR "$f: $fulref\n"; } -- cgit v1.2.3 From 54002b56b04bc83f8961c8751f6bfef07461d587 Mon Sep 17 00:00:00 2001 From: Bjorn Helgaas Date: Thu, 30 May 2019 16:59:14 -0500 Subject: scripts/sphinx-pre-install: fix "dependenties" typo Fix typo ("dependenties" for "dependencies"). Signed-off-by: Bjorn Helgaas Signed-off-by: Jonathan Corbet --- scripts/sphinx-pre-install | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index f001fc2fcf12..158f522f12ed 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -632,7 +632,7 @@ sub check_needs() } printf "\n"; - print "All optional dependenties are met.\n" if (!$optional); + print "All optional dependencies are met.\n" if (!$optional); if ($need == 1) { die "Can't build as $need mandatory dependency is missing"; -- cgit v1.2.3 From 869ee58b82680dae6e0b1d4b37e8c36561b2d2d6 Mon Sep 17 00:00:00 2001 From: Mathieu Malaterre Date: Wed, 29 May 2019 10:04:34 +0200 Subject: kbuild: Remove -Waggregate-return from scripts/Makefile.extrawarn It makes little sense to pass -Waggregate-return these days since large part of the linux kernel rely on returning struct(s). For instance: ../include/linux/timekeeping.h: In function 'show_uptime': ../include/linux/ktime.h:91:34: error: function call has aggregate value [-Werror=aggregate-return] #define ktime_to_timespec64(kt) ns_to_timespec64((kt)) ^~~~~~~~~~~~~~~~~~~~~~ ../include/linux/timekeeping.h:166:8: note: in expansion of macro 'ktime_to_timespec64' *ts = ktime_to_timespec64(ktime_get_coarse_boottime()); Remove this warning from W=2 completely. Signed-off-by: Mathieu Malaterre Signed-off-by: Masahiro Yamada --- scripts/Makefile.extrawarn | 1 - 1 file changed, 1 deletion(-) (limited to 'scripts') diff --git a/scripts/Makefile.extrawarn b/scripts/Makefile.extrawarn index 3ab8d1a303cd..98081ab300e5 100644 --- a/scripts/Makefile.extrawarn +++ b/scripts/Makefile.extrawarn @@ -34,7 +34,6 @@ warning-1 += $(call cc-option, -Wstringop-truncation) warning-1 += -Wno-missing-field-initializers warning-1 += -Wno-sign-compare -warning-2 := -Waggregate-return warning-2 += -Wcast-align warning-2 += -Wdisabled-optimization warning-2 += -Wnested-externs -- cgit v1.2.3 From e0a2668665a5f59e210f09385cd2d29833e5f9fa Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Mon, 27 May 2019 23:37:21 +0900 Subject: kconfig: remove always false ifeq ($(KBUILD_DEFCONFIG,) conditional With the following two commits applied, all the arch Makefiles define KBUILD_DEFCONFIG. - Commit f3e20ad67b4c ("s390: move arch/s390/defconfig to arch/s390/configs/defconfig") - Commit 986a13769c4b ("alpha: move arch/alpha/defconfig to arch/alpha/configs/defconfig") The first conditional in the defconfig rule is always false. Signed-off-by: Masahiro Yamada --- scripts/kconfig/Makefile | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'scripts') diff --git a/scripts/kconfig/Makefile b/scripts/kconfig/Makefile index 3f327e21f60e..059642bd6584 100644 --- a/scripts/kconfig/Makefile +++ b/scripts/kconfig/Makefile @@ -74,9 +74,7 @@ savedefconfig: $(obj)/conf $< $(silent) --$@=defconfig $(Kconfig) defconfig: $(obj)/conf -ifeq ($(KBUILD_DEFCONFIG),) - $< $(silent) --defconfig $(Kconfig) -else ifneq ($(wildcard $(srctree)/arch/$(SRCARCH)/configs/$(KBUILD_DEFCONFIG)),) +ifneq ($(wildcard $(srctree)/arch/$(SRCARCH)/configs/$(KBUILD_DEFCONFIG)),) @$(kecho) "*** Default configuration is based on '$(KBUILD_DEFCONFIG)'" $(Q)$< $(silent) --defconfig=arch/$(SRCARCH)/configs/$(KBUILD_DEFCONFIG) $(Kconfig) else -- cgit v1.2.3 From b6f7e9f7050b9f8e5fe60d86e05c0740295a54bf Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Mon, 27 May 2019 23:37:22 +0900 Subject: kconfig: require the argument of --defconfig Currently, the argument for --defconfig is optional. If the argument is not passed, the hard-coded default arch/$(ARCH)/defconfig is used. It no longer happens in Linux since the last users of the default are gone by the following commits: - Commit f3e20ad67b4c ("s390: move arch/s390/defconfig to arch/s390/configs/defconfig") - Commit 986a13769c4b ("alpha: move arch/alpha/defconfig to arch/alpha/configs/defconfig") I want to kill the Linux-specific directory path embedded in the Kconfig binary. The --savedefconfig (reverse operation of --defconfig) requires an argument, so it should not hurt to do likewise for --defconfig. Signed-off-by: Masahiro Yamada --- scripts/kconfig/conf.c | 4 +--- scripts/kconfig/confdata.c | 17 ----------------- scripts/kconfig/lkc.h | 1 - 3 files changed, 1 insertion(+), 21 deletions(-) (limited to 'scripts') diff --git a/scripts/kconfig/conf.c b/scripts/kconfig/conf.c index ef3678c24bab..0d4c4f3a8f29 100644 --- a/scripts/kconfig/conf.c +++ b/scripts/kconfig/conf.c @@ -451,7 +451,7 @@ static struct option long_opts[] = { {"oldaskconfig", no_argument, NULL, oldaskconfig}, {"oldconfig", no_argument, NULL, oldconfig}, {"syncconfig", no_argument, NULL, syncconfig}, - {"defconfig", optional_argument, NULL, defconfig}, + {"defconfig", required_argument, NULL, defconfig}, {"savedefconfig", required_argument, NULL, savedefconfig}, {"allnoconfig", no_argument, NULL, allnoconfig}, {"allyesconfig", no_argument, NULL, allyesconfig}, @@ -562,8 +562,6 @@ int main(int ac, char **av) switch (input_mode) { case defconfig: - if (!defconfig_file) - defconfig_file = conf_get_default_confname(); if (conf_read(defconfig_file)) { fprintf(stderr, "***\n" diff --git a/scripts/kconfig/confdata.c b/scripts/kconfig/confdata.c index 6006154d36bd..18e8051d89d7 100644 --- a/scripts/kconfig/confdata.c +++ b/scripts/kconfig/confdata.c @@ -177,8 +177,6 @@ static void conf_message(const char *fmt, ...) static const char *conf_filename; static int conf_lineno, conf_warnings; -const char conf_defname[] = "arch/$(ARCH)/defconfig"; - static void conf_warning(const char *fmt, ...) { va_list ap; @@ -233,21 +231,6 @@ static const char *conf_get_autoconfig_name(void) return name ? name : "include/config/auto.conf"; } -char *conf_get_default_confname(void) -{ - static char fullname[PATH_MAX+1]; - char *env, *name; - - name = expand_string(conf_defname); - env = getenv(SRCTREE); - if (env) { - snprintf(fullname, sizeof(fullname), "%s/%s", env, name); - if (is_present(fullname)) - return fullname; - } - return name; -} - static int conf_set_sym_val(struct symbol *sym, int def, int def_flags, char *p) { char *p2; diff --git a/scripts/kconfig/lkc.h b/scripts/kconfig/lkc.h index cbc7658ee27d..4fb16f316626 100644 --- a/scripts/kconfig/lkc.h +++ b/scripts/kconfig/lkc.h @@ -49,7 +49,6 @@ const char *zconf_curname(void); /* confdata.c */ const char *conf_get_configname(void); -char *conf_get_default_confname(void); void sym_set_change_count(int count); void sym_add_change_count(int count); bool conf_set_all_new_symbols(enum conf_def_mode mode); -- cgit v1.2.3 From 5533397d1ec83d749067794f54283890e38ff0c1 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Mon, 27 May 2019 23:37:23 +0900 Subject: kconfig: add static qualifier to expand_string() Now expand_string() is only used in preprocess.c Signed-off-by: Masahiro Yamada --- scripts/kconfig/lkc_proto.h | 1 - scripts/kconfig/preprocess.c | 3 ++- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/kconfig/lkc_proto.h b/scripts/kconfig/lkc_proto.h index 86c267540ccc..38a32b1c1a28 100644 --- a/scripts/kconfig/lkc_proto.h +++ b/scripts/kconfig/lkc_proto.h @@ -58,7 +58,6 @@ void env_write_dep(FILE *f, const char *auto_conf_name); void variable_add(const char *name, const char *value, enum variable_flavor flavor); void variable_all_del(void); -char *expand_string(const char *in); char *expand_dollar(const char **str); char *expand_one_token(const char **str); diff --git a/scripts/kconfig/preprocess.c b/scripts/kconfig/preprocess.c index 592dfbfa9fb3..0243086fb168 100644 --- a/scripts/kconfig/preprocess.c +++ b/scripts/kconfig/preprocess.c @@ -15,6 +15,7 @@ #define ARRAY_SIZE(arr) (sizeof(arr) / sizeof((arr)[0])) static char *expand_string_with_args(const char *in, int argc, char *argv[]); +static char *expand_string(const char *in); static void __attribute__((noreturn)) pperror(const char *format, ...) { @@ -550,7 +551,7 @@ static char *expand_string_with_args(const char *in, int argc, char *argv[]) return __expand_string(&in, is_end_of_str, argc, argv); } -char *expand_string(const char *in) +static char *expand_string(const char *in) { return expand_string_with_args(in, 0, NULL); } -- cgit v1.2.3 From bd305f259cd33f6cd550e479d0a0a856cd8b7941 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Mon, 27 May 2019 23:37:24 +0900 Subject: kconfig: make arch/*/configs/defconfig the default of KBUILD_DEFCONFIG Until recently, if KBUILD_DEFCONFIG was not set by the arch Makefile, the default path arch/*/defconfig was used. The last users of the default are gone by the following commits: - Commit f3e20ad67b4c ("s390: move arch/s390/defconfig to arch/s390/configs/defconfig") - Commit 986a13769c4b ("alpha: move arch/alpha/defconfig to arch/alpha/configs/defconfig") Let's set arch/*/configs/defconfig as a new default. This saves KBUILD_DEFCONFIG for some architectures. Signed-off-by: Masahiro Yamada Acked-by: Catalin Marinas --- arch/alpha/Makefile | 2 -- arch/arm64/Makefile | 2 -- arch/csky/Makefile | 1 - arch/nds32/Makefile | 2 -- arch/riscv/Makefile | 2 -- arch/s390/Makefile | 2 -- scripts/kconfig/Makefile | 4 ++++ 7 files changed, 4 insertions(+), 11 deletions(-) (limited to 'scripts') diff --git a/arch/alpha/Makefile b/arch/alpha/Makefile index b3314e0dcb6f..12dee59b011c 100644 --- a/arch/alpha/Makefile +++ b/arch/alpha/Makefile @@ -8,8 +8,6 @@ # Copyright (C) 1994 by Linus Torvalds # -KBUILD_DEFCONFIG := defconfig - NM := $(NM) -B LDFLAGS_vmlinux := -static -N #-relax diff --git a/arch/arm64/Makefile b/arch/arm64/Makefile index 8fbd583b18e1..7a45899db25b 100644 --- a/arch/arm64/Makefile +++ b/arch/arm64/Makefile @@ -30,8 +30,6 @@ LDFLAGS_vmlinux += --fix-cortex-a53-843419 endif endif -KBUILD_DEFCONFIG := defconfig - # Check for binutils support for specific extensions lseinstr := $(call as-instr,.arch_extension lse,-DCONFIG_AS_LSE=1) diff --git a/arch/csky/Makefile b/arch/csky/Makefile index f9aab9157c4a..fb1bbbd91954 100644 --- a/arch/csky/Makefile +++ b/arch/csky/Makefile @@ -1,7 +1,6 @@ # SPDX-License-Identifier: GPL-2.0-only OBJCOPYFLAGS :=-O binary GZFLAGS :=-9 -KBUILD_DEFCONFIG := defconfig ifdef CONFIG_CPU_HAS_FPU FPUEXT = f diff --git a/arch/nds32/Makefile b/arch/nds32/Makefile index 14dab5ad88ef..ccdca7142020 100644 --- a/arch/nds32/Makefile +++ b/arch/nds32/Makefile @@ -2,8 +2,6 @@ LDFLAGS_vmlinux := --no-undefined -X OBJCOPYFLAGS := -O binary -R .note -R .note.gnu.build-id -R .comment -S -KBUILD_DEFCONFIG := defconfig - ifdef CONFIG_FUNCTION_TRACER arch-y += -malways-save-lp -mno-relax endif diff --git a/arch/riscv/Makefile b/arch/riscv/Makefile index 6b0741c9f348..f8b3b07e4247 100644 --- a/arch/riscv/Makefile +++ b/arch/riscv/Makefile @@ -16,8 +16,6 @@ endif KBUILD_AFLAGS_MODULE += -fPIC KBUILD_CFLAGS_MODULE += -fPIC -KBUILD_DEFCONFIG = defconfig - export BITS ifeq ($(CONFIG_ARCH_RV64I),y) BITS := 64 diff --git a/arch/s390/Makefile b/arch/s390/Makefile index de8521fc9de5..df1d6a150f30 100644 --- a/arch/s390/Makefile +++ b/arch/s390/Makefile @@ -10,8 +10,6 @@ # Copyright (C) 1994 by Linus Torvalds # -KBUILD_DEFCONFIG := defconfig - LD_BFD := elf64-s390 KBUILD_LDFLAGS := -m elf64_s390 KBUILD_AFLAGS_MODULE += -fPIC diff --git a/scripts/kconfig/Makefile b/scripts/kconfig/Makefile index 059642bd6584..ab30fe724c43 100644 --- a/scripts/kconfig/Makefile +++ b/scripts/kconfig/Makefile @@ -12,6 +12,10 @@ else Kconfig := Kconfig endif +ifndef KBUILD_DEFCONFIG +KBUILD_DEFCONFIG := defconfig +endif + ifeq ($(quiet),silent_) silent := -s endif -- cgit v1.2.3 From 9bb9c6a110eaad53054e939f8800223ae6d9b66c Mon Sep 17 00:00:00 2001 From: Rob Herring Date: Wed, 12 Jun 2019 07:05:52 -0600 Subject: scripts/dtc: Update to upstream version v1.5.0-23-g87963ee20693 This adds the following commits from upstream: 87963ee20693 livetree: add missing type markers in generated overlay properties 825146d13dc0 Fix typos in various documentation and source files 25bb080c18d1 Update the GPL2 text to the latest revision 243176c4ce84 Fix bogus error on rebuild ce01b21098a4 libfdt: Add FDT_CREATE_FLAG_NO_NAME_DEDUP flag that trades size for speed fbb62754ce45 libfdt: Introduce fdt_create_with_flags() 228a44cce857 libfdt: Ensure fdt_add_property frees allocated name string on failure 8f695676227b Avoid assertion in check_interrupts_property() 5c3513f68921 Link tools and tests against libfdt shared library 00f9febf9c16 tests: Rename tests.sh to testutils.sh c5d45188f923 Clean up LDLIBS handling 6ef8fcd05b74 Rebuild libfdt shared object if versioning linker script changes 26ee65a16c38 Use Python3 by default cca6546244cb libfdt: Make fdt_get_max_phandle() an inline 730875016a6a libfdt: Add phandle generation helper 7dfb61ba96b1 libfdt: Use fdt_find_max_phandle() 2bc5b66d7f6c libfdt: Add new maximum phandle lookup function 7fcf8208b8a9 libfdt: add fdt_append_addrrange() ae795b2db7a4 checks: Do not omit nodes with labels if symbol generation is requested eac2ad495b29 Update version.lds again f67b47135523 Revert "libfdt: Add phandle generation helper" 54ea41c22415 libfdt: Add phandle generation helper 4762ad051ee0 checks: Fix spelling in check_graph_endpoint d37f6b20107e Bump version to v1.5.0 a4b1a307ff3a pylibfdt:tests: Extend the way how to find a Python module 625dd8aaf20f pylibfdt: Change how passing tests are recognized 364631626bb7 pylibfdt: Test fdt.setprop take bytes on Python 3, add error handling cb0f454f73cc pylibfdt: check_err accepts only integer as a first argument. 4b68c6b3605a pylibfdt: Proper handling of bytes/unicode strings and octal literals 78e113e81c9d Use PRIxPTR for printing uintptr_t values ea7a8f6dad67 libfdt: Fix FDT_ERR_NOTFOUND typos in documentation 5aafd7ca43e0 libfdt: Fix fdt_getprop_by_offset() parameter name in documentation 7cbc550f903b checks: Add unit address check if node is enabled Signed-off-by: Rob Herring --- scripts/dtc/checks.c | 55 +++++++++++-- scripts/dtc/dtc.h | 3 +- scripts/dtc/flattree.c | 2 +- scripts/dtc/libfdt/Makefile.libfdt | 2 + scripts/dtc/libfdt/fdt_addresses.c | 47 +++++++++++ scripts/dtc/libfdt/fdt_overlay.c | 10 ++- scripts/dtc/libfdt/fdt_ro.c | 50 ++++++++---- scripts/dtc/libfdt/fdt_rw.c | 22 +++++- scripts/dtc/libfdt/fdt_strerror.c | 1 + scripts/dtc/libfdt/fdt_sw.c | 78 +++++++++++++++--- scripts/dtc/libfdt/libfdt.h | 158 +++++++++++++++++++++++++++++++++++-- scripts/dtc/libfdt/libfdt_env.h | 1 + scripts/dtc/livetree.c | 20 +++-- scripts/dtc/util.h | 4 +- scripts/dtc/version_gen.h | 2 +- 15 files changed, 399 insertions(+), 56 deletions(-) (limited to 'scripts') diff --git a/scripts/dtc/checks.c b/scripts/dtc/checks.c index 4834e44b37b2..4719d658432b 100644 --- a/scripts/dtc/checks.c +++ b/scripts/dtc/checks.c @@ -660,6 +660,8 @@ ERROR(path_references, fixup_path_references, NULL, &duplicate_node_names); static void fixup_omit_unused_nodes(struct check *c, struct dt_info *dti, struct node *node) { + if (generate_symbols && node->labels) + return; if (node->omit_if_unused && !node->is_referenced) delete_node(node); } @@ -1212,8 +1214,24 @@ static void check_avoid_unnecessary_addr_size(struct check *c, struct dt_info *d } WARNING(avoid_unnecessary_addr_size, check_avoid_unnecessary_addr_size, NULL, &avoid_default_addr_size); -static void check_unique_unit_address(struct check *c, struct dt_info *dti, - struct node *node) +static bool node_is_disabled(struct node *node) +{ + struct property *prop; + + prop = get_property(node, "status"); + if (prop) { + char *str = prop->val.val; + if (streq("disabled", str)) + return true; + } + + return false; +} + +static void check_unique_unit_address_common(struct check *c, + struct dt_info *dti, + struct node *node, + bool disable_check) { struct node *childa; @@ -1230,18 +1248,38 @@ static void check_unique_unit_address(struct check *c, struct dt_info *dti, if (!strlen(addr_a)) continue; + if (disable_check && node_is_disabled(childa)) + continue; + for_each_child(node, childb) { const char *addr_b = get_unitname(childb); if (childa == childb) break; + if (disable_check && node_is_disabled(childb)) + continue; + if (streq(addr_a, addr_b)) FAIL(c, dti, childb, "duplicate unit-address (also used in node %s)", childa->fullpath); } } } + +static void check_unique_unit_address(struct check *c, struct dt_info *dti, + struct node *node) +{ + check_unique_unit_address_common(c, dti, node, false); +} WARNING(unique_unit_address, check_unique_unit_address, NULL, &avoid_default_addr_size); +static void check_unique_unit_address_if_enabled(struct check *c, struct dt_info *dti, + struct node *node) +{ + check_unique_unit_address_common(c, dti, node, true); +} +CHECK_ENTRY(unique_unit_address_if_enabled, check_unique_unit_address_if_enabled, + NULL, false, false, &avoid_default_addr_size); + static void check_obsolete_chosen_interrupt_controller(struct check *c, struct dt_info *dti, struct node *node) @@ -1542,10 +1580,14 @@ static void check_interrupts_property(struct check *c, prop = get_property(parent, "interrupt-parent"); if (prop) { phandle = propval_cell(prop); - /* Give up if this is an overlay with external references */ - if ((phandle == 0 || phandle == -1) && - (dti->dtsflags & DTSF_PLUGIN)) + if ((phandle == 0) || (phandle == -1)) { + /* Give up if this is an overlay with + * external references */ + if (dti->dtsflags & DTSF_PLUGIN) return; + FAIL_PROP(c, dti, parent, prop, "Invalid phandle"); + continue; + } irq_node = get_node_by_phandle(root, phandle); if (!irq_node) { @@ -1714,7 +1756,7 @@ static void check_graph_endpoint(struct check *c, struct dt_info *dti, return; if (!strprefixeq(node->name, node->basenamelen, "endpoint")) - FAIL(c, dti, node, "graph endpont node name should be 'endpoint'"); + FAIL(c, dti, node, "graph endpoint node name should be 'endpoint'"); check_graph_reg(c, dti, node); @@ -1769,6 +1811,7 @@ static struct check *check_table[] = { &avoid_default_addr_size, &avoid_unnecessary_addr_size, &unique_unit_address, + &unique_unit_address_if_enabled, &obsolete_chosen_interrupt_controller, &chosen_node_is_root, &chosen_node_bootargs, &chosen_node_stdout_path, diff --git a/scripts/dtc/dtc.h b/scripts/dtc/dtc.h index 789e0b1bc057..0d5fa215ac87 100644 --- a/scripts/dtc/dtc.h +++ b/scripts/dtc/dtc.h @@ -231,7 +231,8 @@ void add_child(struct node *parent, struct node *child); void delete_node_by_name(struct node *parent, char *name); void delete_node(struct node *node); void append_to_property(struct node *node, - char *name, const void *data, int len); + char *name, const void *data, int len, + enum markertype type); const char *get_unitname(struct node *node); struct property *get_property(struct node *node, const char *propname); diff --git a/scripts/dtc/flattree.c b/scripts/dtc/flattree.c index acf04c30669f..f7f70769d73f 100644 --- a/scripts/dtc/flattree.c +++ b/scripts/dtc/flattree.c @@ -525,7 +525,7 @@ void dt_to_asm(FILE *f, struct dt_info *dti, int version) fprintf(f, "/* Memory reserve map from source file */\n"); /* - * Use .long on high and low halfs of u64s to avoid .quad + * Use .long on high and low halves of u64s to avoid .quad * as it appears .quad isn't available in some assemblers. */ for (re = dti->reservelist; re; re = re->next) { diff --git a/scripts/dtc/libfdt/Makefile.libfdt b/scripts/dtc/libfdt/Makefile.libfdt index 3af3656df801..193da8c99d83 100644 --- a/scripts/dtc/libfdt/Makefile.libfdt +++ b/scripts/dtc/libfdt/Makefile.libfdt @@ -9,7 +9,9 @@ LIBFDT_VERSION = version.lds LIBFDT_SRCS = fdt.c fdt_ro.c fdt_wip.c fdt_sw.c fdt_rw.c fdt_strerror.c fdt_empty_tree.c \ fdt_addresses.c fdt_overlay.c LIBFDT_OBJS = $(LIBFDT_SRCS:%.c=%.o) +LIBFDT_LIB = libfdt-$(DTC_VERSION).$(SHAREDLIB_EXT) libfdt_clean: @$(VECHO) CLEAN "(libfdt)" rm -f $(STD_CLEANFILES:%=$(LIBFDT_dir)/%) + rm -f $(LIBFDT_dir)/$(LIBFDT_soname) diff --git a/scripts/dtc/libfdt/fdt_addresses.c b/scripts/dtc/libfdt/fdt_addresses.c index f13a87dfa068..2cc997ea5012 100644 --- a/scripts/dtc/libfdt/fdt_addresses.c +++ b/scripts/dtc/libfdt/fdt_addresses.c @@ -95,3 +95,50 @@ int fdt_size_cells(const void *fdt, int nodeoffset) return 1; return val; } + +/* This function assumes that [address|size]_cells is 1 or 2 */ +int fdt_appendprop_addrrange(void *fdt, int parent, int nodeoffset, + const char *name, uint64_t addr, uint64_t size) +{ + int addr_cells, size_cells, ret; + uint8_t data[sizeof(fdt64_t) * 2], *prop; + + ret = fdt_address_cells(fdt, parent); + if (ret < 0) + return ret; + addr_cells = ret; + + ret = fdt_size_cells(fdt, parent); + if (ret < 0) + return ret; + size_cells = ret; + + /* check validity of address */ + prop = data; + if (addr_cells == 1) { + if ((addr > UINT32_MAX) || ((UINT32_MAX + 1 - addr) < size)) + return -FDT_ERR_BADVALUE; + + fdt32_st(prop, (uint32_t)addr); + } else if (addr_cells == 2) { + fdt64_st(prop, addr); + } else { + return -FDT_ERR_BADNCELLS; + } + + /* check validity of size */ + prop += addr_cells * sizeof(fdt32_t); + if (size_cells == 1) { + if (size > UINT32_MAX) + return -FDT_ERR_BADVALUE; + + fdt32_st(prop, (uint32_t)size); + } else if (size_cells == 2) { + fdt64_st(prop, size); + } else { + return -FDT_ERR_BADNCELLS; + } + + return fdt_appendprop(fdt, nodeoffset, name, data, + (addr_cells + size_cells) * sizeof(fdt32_t)); +} diff --git a/scripts/dtc/libfdt/fdt_overlay.c b/scripts/dtc/libfdt/fdt_overlay.c index 5fdab6c6371d..d3e9ab2dbb7b 100644 --- a/scripts/dtc/libfdt/fdt_overlay.c +++ b/scripts/dtc/libfdt/fdt_overlay.c @@ -93,11 +93,11 @@ static uint32_t overlay_get_target_phandle(const void *fdto, int fragment) * @pathp: pointer which receives the path of the target (or NULL) * * overlay_get_target() retrieves the target offset in the base - * device tree of a fragment, no matter how the actual targetting is + * device tree of a fragment, no matter how the actual targeting is * done (through a phandle or a path) * * returns: - * the targetted node offset in the base device tree + * the targeted node offset in the base device tree * Negative error code on error */ static int overlay_get_target(const void *fdt, const void *fdto, @@ -863,12 +863,16 @@ static int overlay_symbol_update(void *fdt, void *fdto) int fdt_overlay_apply(void *fdt, void *fdto) { - uint32_t delta = fdt_get_max_phandle(fdt); + uint32_t delta; int ret; FDT_RO_PROBE(fdt); FDT_RO_PROBE(fdto); + ret = fdt_find_max_phandle(fdt, &delta); + if (ret) + goto err; + ret = overlay_adjust_local_phandles(fdto, delta); if (ret) goto err; diff --git a/scripts/dtc/libfdt/fdt_ro.c b/scripts/dtc/libfdt/fdt_ro.c index eafc14282892..2c393a100bfc 100644 --- a/scripts/dtc/libfdt/fdt_ro.c +++ b/scripts/dtc/libfdt/fdt_ro.c @@ -144,29 +144,49 @@ static int fdt_string_eq_(const void *fdt, int stroffset, return p && (slen == len) && (memcmp(p, s, len) == 0); } -uint32_t fdt_get_max_phandle(const void *fdt) +int fdt_find_max_phandle(const void *fdt, uint32_t *phandle) { - uint32_t max_phandle = 0; - int offset; + uint32_t max = 0; + int offset = -1; - for (offset = fdt_next_node(fdt, -1, NULL);; - offset = fdt_next_node(fdt, offset, NULL)) { - uint32_t phandle; + while (true) { + uint32_t value; - if (offset == -FDT_ERR_NOTFOUND) - return max_phandle; + offset = fdt_next_node(fdt, offset, NULL); + if (offset < 0) { + if (offset == -FDT_ERR_NOTFOUND) + break; - if (offset < 0) - return (uint32_t)-1; + return offset; + } - phandle = fdt_get_phandle(fdt, offset); - if (phandle == (uint32_t)-1) - continue; + value = fdt_get_phandle(fdt, offset); - if (phandle > max_phandle) - max_phandle = phandle; + if (value > max) + max = value; } + if (phandle) + *phandle = max; + + return 0; +} + +int fdt_generate_phandle(const void *fdt, uint32_t *phandle) +{ + uint32_t max; + int err; + + err = fdt_find_max_phandle(fdt, &max); + if (err < 0) + return err; + + if (max == FDT_MAX_PHANDLE) + return -FDT_ERR_NOPHANDLES; + + if (phandle) + *phandle = max + 1; + return 0; } diff --git a/scripts/dtc/libfdt/fdt_rw.c b/scripts/dtc/libfdt/fdt_rw.c index 2e49855d7cf8..9e7661509e9f 100644 --- a/scripts/dtc/libfdt/fdt_rw.c +++ b/scripts/dtc/libfdt/fdt_rw.c @@ -136,6 +136,14 @@ static int fdt_splice_struct_(void *fdt, void *p, return 0; } +/* Must only be used to roll back in case of error */ +static void fdt_del_last_string_(void *fdt, const char *s) +{ + int newlen = strlen(s) + 1; + + fdt_set_size_dt_strings(fdt, fdt_size_dt_strings(fdt) - newlen); +} + static int fdt_splice_string_(void *fdt, int newlen) { void *p = (char *)fdt @@ -149,7 +157,7 @@ static int fdt_splice_string_(void *fdt, int newlen) return 0; } -static int fdt_find_add_string_(void *fdt, const char *s) +static int fdt_find_add_string_(void *fdt, const char *s, int *allocated) { char *strtab = (char *)fdt + fdt_off_dt_strings(fdt); const char *p; @@ -157,6 +165,8 @@ static int fdt_find_add_string_(void *fdt, const char *s) int len = strlen(s) + 1; int err; + *allocated = 0; + p = fdt_find_string_(strtab, fdt_size_dt_strings(fdt), s); if (p) /* found it */ @@ -167,6 +177,8 @@ static int fdt_find_add_string_(void *fdt, const char *s) if (err) return err; + *allocated = 1; + memcpy(new, s, len); return (new - strtab); } @@ -225,11 +237,12 @@ static int fdt_add_property_(void *fdt, int nodeoffset, const char *name, int nextoffset; int namestroff; int err; + int allocated; if ((nextoffset = fdt_check_node_offset_(fdt, nodeoffset)) < 0) return nextoffset; - namestroff = fdt_find_add_string_(fdt, name); + namestroff = fdt_find_add_string_(fdt, name, &allocated); if (namestroff < 0) return namestroff; @@ -237,8 +250,11 @@ static int fdt_add_property_(void *fdt, int nodeoffset, const char *name, proplen = sizeof(**prop) + FDT_TAGALIGN(len); err = fdt_splice_struct_(fdt, *prop, 0, proplen); - if (err) + if (err) { + if (allocated) + fdt_del_last_string_(fdt, name); return err; + } (*prop)->tag = cpu_to_fdt32(FDT_PROP); (*prop)->nameoff = cpu_to_fdt32(namestroff); diff --git a/scripts/dtc/libfdt/fdt_strerror.c b/scripts/dtc/libfdt/fdt_strerror.c index 9677a1887e57..0e6b4fd5e7ce 100644 --- a/scripts/dtc/libfdt/fdt_strerror.c +++ b/scripts/dtc/libfdt/fdt_strerror.c @@ -82,6 +82,7 @@ static struct fdt_errtabent fdt_errtable[] = { FDT_ERRTABENT(FDT_ERR_BADVALUE), FDT_ERRTABENT(FDT_ERR_BADOVERLAY), FDT_ERRTABENT(FDT_ERR_NOPHANDLES), + FDT_ERRTABENT(FDT_ERR_BADFLAGS), }; #define FDT_ERRTABSIZE (sizeof(fdt_errtable) / sizeof(fdt_errtable[0])) diff --git a/scripts/dtc/libfdt/fdt_sw.c b/scripts/dtc/libfdt/fdt_sw.c index 9fa4a94d83c3..e773157d0fc4 100644 --- a/scripts/dtc/libfdt/fdt_sw.c +++ b/scripts/dtc/libfdt/fdt_sw.c @@ -121,6 +121,12 @@ static int fdt_sw_probe_struct_(void *fdt) return err; \ } +static inline uint32_t sw_flags(void *fdt) +{ + /* assert: (fdt_magic(fdt) == FDT_SW_MAGIC) */ + return fdt_last_comp_version(fdt); +} + /* 'complete' state: Enter this state after fdt_finish() * * Allowed functions: none @@ -141,7 +147,7 @@ static void *fdt_grab_space_(void *fdt, size_t len) return fdt_offset_ptr_w_(fdt, offset); } -int fdt_create(void *buf, int bufsize) +int fdt_create_with_flags(void *buf, int bufsize, uint32_t flags) { const size_t hdrsize = FDT_ALIGN(sizeof(struct fdt_header), sizeof(struct fdt_reserve_entry)); @@ -150,11 +156,22 @@ int fdt_create(void *buf, int bufsize) if (bufsize < hdrsize) return -FDT_ERR_NOSPACE; + if (flags & ~FDT_CREATE_FLAGS_ALL) + return -FDT_ERR_BADFLAGS; + memset(buf, 0, bufsize); + /* + * magic and last_comp_version keep intermediate state during the fdt + * creation process, which is replaced with the proper FDT format by + * fdt_finish(). + * + * flags should be accessed with sw_flags(). + */ fdt_set_magic(fdt, FDT_SW_MAGIC); fdt_set_version(fdt, FDT_LAST_SUPPORTED_VERSION); - fdt_set_last_comp_version(fdt, FDT_FIRST_SUPPORTED_VERSION); + fdt_set_last_comp_version(fdt, flags); + fdt_set_totalsize(fdt, bufsize); fdt_set_off_mem_rsvmap(fdt, hdrsize); @@ -164,6 +181,11 @@ int fdt_create(void *buf, int bufsize) return 0; } +int fdt_create(void *buf, int bufsize) +{ + return fdt_create_with_flags(buf, bufsize, 0); +} + int fdt_resize(void *fdt, void *buf, int bufsize) { size_t headsize, tailsize; @@ -262,19 +284,13 @@ int fdt_end_node(void *fdt) return 0; } -static int fdt_find_add_string_(void *fdt, const char *s) +static int fdt_add_string_(void *fdt, const char *s) { char *strtab = (char *)fdt + fdt_totalsize(fdt); - const char *p; int strtabsize = fdt_size_dt_strings(fdt); int len = strlen(s) + 1; int struct_top, offset; - p = fdt_find_string_(strtab - strtabsize, strtabsize, s); - if (p) - return p - strtab; - - /* Add it */ offset = -strtabsize - len; struct_top = fdt_off_dt_struct(fdt) + fdt_size_dt_struct(fdt); if (fdt_totalsize(fdt) + offset < struct_top) @@ -285,20 +301,56 @@ static int fdt_find_add_string_(void *fdt, const char *s) return offset; } +/* Must only be used to roll back in case of error */ +static void fdt_del_last_string_(void *fdt, const char *s) +{ + int strtabsize = fdt_size_dt_strings(fdt); + int len = strlen(s) + 1; + + fdt_set_size_dt_strings(fdt, strtabsize - len); +} + +static int fdt_find_add_string_(void *fdt, const char *s, int *allocated) +{ + char *strtab = (char *)fdt + fdt_totalsize(fdt); + int strtabsize = fdt_size_dt_strings(fdt); + const char *p; + + *allocated = 0; + + p = fdt_find_string_(strtab - strtabsize, strtabsize, s); + if (p) + return p - strtab; + + *allocated = 1; + + return fdt_add_string_(fdt, s); +} + int fdt_property_placeholder(void *fdt, const char *name, int len, void **valp) { struct fdt_property *prop; int nameoff; + int allocated; FDT_SW_PROBE_STRUCT(fdt); - nameoff = fdt_find_add_string_(fdt, name); + /* String de-duplication can be slow, _NO_NAME_DEDUP skips it */ + if (sw_flags(fdt) & FDT_CREATE_FLAG_NO_NAME_DEDUP) { + allocated = 1; + nameoff = fdt_add_string_(fdt, name); + } else { + nameoff = fdt_find_add_string_(fdt, name, &allocated); + } if (nameoff == 0) return -FDT_ERR_NOSPACE; prop = fdt_grab_space_(fdt, sizeof(*prop) + FDT_TAGALIGN(len)); - if (! prop) + if (! prop) { + if (allocated) + fdt_del_last_string_(fdt, name); return -FDT_ERR_NOSPACE; + } prop->tag = cpu_to_fdt32(FDT_PROP); prop->nameoff = cpu_to_fdt32(nameoff); @@ -360,6 +412,10 @@ int fdt_finish(void *fdt) /* Finally, adjust the header */ fdt_set_totalsize(fdt, newstroffset + fdt_size_dt_strings(fdt)); + + /* And fix up fields that were keeping intermediate state. */ + fdt_set_last_comp_version(fdt, FDT_FIRST_SUPPORTED_VERSION); fdt_set_magic(fdt, FDT_MAGIC); + return 0; } diff --git a/scripts/dtc/libfdt/libfdt.h b/scripts/dtc/libfdt/libfdt.h index 627da2e079c9..be14bf63e577 100644 --- a/scripts/dtc/libfdt/libfdt.h +++ b/scripts/dtc/libfdt/libfdt.h @@ -138,7 +138,15 @@ /* FDT_ERR_NOPHANDLES: The device tree doesn't have any * phandle available anymore without causing an overflow */ -#define FDT_ERR_MAX 17 +#define FDT_ERR_BADFLAGS 18 + /* FDT_ERR_BADFLAGS: The function was passed a flags field that + * contains invalid flags or an invalid combination of flags. */ + +#define FDT_ERR_MAX 18 + +/* constants */ +#define FDT_MAX_PHANDLE 0xfffffffe + /* Valid values for phandles range from 1 to 2^32-2. */ /**********************************************************************/ /* Low-level functions (you probably don't need these) */ @@ -171,6 +179,16 @@ static inline uint32_t fdt32_ld(const fdt32_t *p) | bp[3]; } +static inline void fdt32_st(void *property, uint32_t value) +{ + uint8_t *bp = property; + + bp[0] = value >> 24; + bp[1] = (value >> 16) & 0xff; + bp[2] = (value >> 8) & 0xff; + bp[3] = value & 0xff; +} + static inline uint64_t fdt64_ld(const fdt64_t *p) { const uint8_t *bp = (const uint8_t *)p; @@ -185,6 +203,20 @@ static inline uint64_t fdt64_ld(const fdt64_t *p) | bp[7]; } +static inline void fdt64_st(void *property, uint64_t value) +{ + uint8_t *bp = property; + + bp[0] = value >> 56; + bp[1] = (value >> 48) & 0xff; + bp[2] = (value >> 40) & 0xff; + bp[3] = (value >> 32) & 0xff; + bp[4] = (value >> 24) & 0xff; + bp[5] = (value >> 16) & 0xff; + bp[6] = (value >> 8) & 0xff; + bp[7] = value & 0xff; +} + /**********************************************************************/ /* Traversal functions */ /**********************************************************************/ @@ -227,7 +259,7 @@ int fdt_next_subnode(const void *fdt, int offset); * ... * } * - * if ((node < 0) && (node != -FDT_ERR_NOT_FOUND)) { + * if ((node < 0) && (node != -FDT_ERR_NOTFOUND)) { * Error handling * } * @@ -361,6 +393,20 @@ const char *fdt_get_string(const void *fdt, int stroffset, int *lenp); */ const char *fdt_string(const void *fdt, int stroffset); +/** + * fdt_find_max_phandle - find and return the highest phandle in a tree + * @fdt: pointer to the device tree blob + * @phandle: return location for the highest phandle value found in the tree + * + * fdt_find_max_phandle() finds the highest phandle value in the given device + * tree. The value returned in @phandle is only valid if the function returns + * success. + * + * returns: + * 0 on success or a negative error code on failure + */ +int fdt_find_max_phandle(const void *fdt, uint32_t *phandle); + /** * fdt_get_max_phandle - retrieves the highest phandle in a tree * @fdt: pointer to the device tree blob @@ -369,12 +415,39 @@ const char *fdt_string(const void *fdt, int stroffset); * device tree. This will ignore badly formatted phandles, or phandles * with a value of 0 or -1. * + * This function is deprecated in favour of fdt_find_max_phandle(). + * * returns: * the highest phandle on success * 0, if no phandle was found in the device tree * -1, if an error occurred */ -uint32_t fdt_get_max_phandle(const void *fdt); +static inline uint32_t fdt_get_max_phandle(const void *fdt) +{ + uint32_t phandle; + int err; + + err = fdt_find_max_phandle(fdt, &phandle); + if (err < 0) + return (uint32_t)-1; + + return phandle; +} + +/** + * fdt_generate_phandle - return a new, unused phandle for a device tree blob + * @fdt: pointer to the device tree blob + * @phandle: return location for the new phandle + * + * Walks the device tree blob and looks for the highest phandle value. On + * success, the new, unused phandle value (one higher than the previously + * highest phandle value in the device tree blob) will be returned in the + * @phandle parameter. + * + * Returns: + * 0 on success or a negative error-code on failure + */ +int fdt_generate_phandle(const void *fdt, uint32_t *phandle); /** * fdt_num_mem_rsv - retrieve the number of memory reserve map entries @@ -566,7 +639,7 @@ int fdt_next_property_offset(const void *fdt, int offset); * ... * } * - * if ((property < 0) && (property != -FDT_ERR_NOT_FOUND)) { + * if ((property < 0) && (property != -FDT_ERR_NOTFOUND)) { * Error handling * } * @@ -669,7 +742,7 @@ static inline struct fdt_property *fdt_get_property_w(void *fdt, int nodeoffset, /** * fdt_getprop_by_offset - retrieve the value of a property at a given offset * @fdt: pointer to the device tree blob - * @ffset: offset of the property to read + * @offset: offset of the property to read * @namep: pointer to a string variable (will be overwritten) or NULL * @lenp: pointer to an integer variable (will be overwritten) or NULL * @@ -1360,7 +1433,45 @@ int fdt_nop_node(void *fdt, int nodeoffset); /* Sequential write functions */ /**********************************************************************/ +/* fdt_create_with_flags flags */ +#define FDT_CREATE_FLAG_NO_NAME_DEDUP 0x1 + /* FDT_CREATE_FLAG_NO_NAME_DEDUP: Do not try to de-duplicate property + * names in the fdt. This can result in faster creation times, but + * a larger fdt. */ + +#define FDT_CREATE_FLAGS_ALL (FDT_CREATE_FLAG_NO_NAME_DEDUP) + +/** + * fdt_create_with_flags - begin creation of a new fdt + * @fdt: pointer to memory allocated where fdt will be created + * @bufsize: size of the memory space at fdt + * @flags: a valid combination of FDT_CREATE_FLAG_ flags, or 0. + * + * fdt_create_with_flags() begins the process of creating a new fdt with + * the sequential write interface. + * + * fdt creation process must end with fdt_finished() to produce a valid fdt. + * + * returns: + * 0, on success + * -FDT_ERR_NOSPACE, bufsize is insufficient for a minimal fdt + * -FDT_ERR_BADFLAGS, flags is not valid + */ +int fdt_create_with_flags(void *buf, int bufsize, uint32_t flags); + +/** + * fdt_create - begin creation of a new fdt + * @fdt: pointer to memory allocated where fdt will be created + * @bufsize: size of the memory space at fdt + * + * fdt_create() is equivalent to fdt_create_with_flags() with flags=0. + * + * returns: + * 0, on success + * -FDT_ERR_NOSPACE, bufsize is insufficient for a minimal fdt + */ int fdt_create(void *buf, int bufsize); + int fdt_resize(void *fdt, void *buf, int bufsize); int fdt_add_reservemap_entry(void *fdt, uint64_t addr, uint64_t size); int fdt_finish_reservemap(void *fdt); @@ -1831,6 +1942,43 @@ static inline int fdt_appendprop_cell(void *fdt, int nodeoffset, #define fdt_appendprop_string(fdt, nodeoffset, name, str) \ fdt_appendprop((fdt), (nodeoffset), (name), (str), strlen(str)+1) +/** + * fdt_appendprop_addrrange - append a address range property + * @fdt: pointer to the device tree blob + * @parent: offset of the parent node + * @nodeoffset: offset of the node to add a property at + * @name: name of property + * @addr: start address of a given range + * @size: size of a given range + * + * fdt_appendprop_addrrange() appends an address range value (start + * address and size) to the value of the named property in the given + * node, or creates a new property with that value if it does not + * already exist. + * If "name" is not specified, a default "reg" is used. + * Cell sizes are determined by parent's #address-cells and #size-cells. + * + * This function may insert data into the blob, and will therefore + * change the offsets of some existing nodes. + * + * returns: + * 0, on success + * -FDT_ERR_BADLAYOUT, + * -FDT_ERR_BADMAGIC, + * -FDT_ERR_BADNCELLS, if the node has a badly formatted or invalid + * #address-cells property + * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag + * -FDT_ERR_BADSTATE, + * -FDT_ERR_BADSTRUCTURE, + * -FDT_ERR_BADVERSION, + * -FDT_ERR_BADVALUE, addr or size doesn't fit to respective cells size + * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to + * contain a new property + * -FDT_ERR_TRUNCATED, standard meanings + */ +int fdt_appendprop_addrrange(void *fdt, int parent, int nodeoffset, + const char *name, uint64_t addr, uint64_t size); + /** * fdt_delprop - delete a property * @fdt: pointer to the device tree blob diff --git a/scripts/dtc/libfdt/libfdt_env.h b/scripts/dtc/libfdt/libfdt_env.h index eb2053845c9c..4d1cdfa58547 100644 --- a/scripts/dtc/libfdt/libfdt_env.h +++ b/scripts/dtc/libfdt/libfdt_env.h @@ -52,6 +52,7 @@ * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +#include #include #include #include diff --git a/scripts/dtc/livetree.c b/scripts/dtc/livetree.c index 7a2e6446a17b..21c274125c2c 100644 --- a/scripts/dtc/livetree.c +++ b/scripts/dtc/livetree.c @@ -249,6 +249,7 @@ struct node * add_orphan_node(struct node *dt, struct node *new_node, char *ref) char *name; if (ref[0] == '/') { + d = data_add_marker(d, TYPE_STRING, ref); d = data_append_data(d, ref, strlen(ref) + 1); p = build_property("target-path", d, NULL); @@ -350,17 +351,20 @@ void delete_node(struct node *node) } void append_to_property(struct node *node, - char *name, const void *data, int len) + char *name, const void *data, int len, + enum markertype type) { struct data d; struct property *p; p = get_property(node, name); if (p) { - d = data_append_data(p->val, data, len); + d = data_add_marker(p->val, type, name); + d = data_append_data(d, data, len); p->val = d; } else { - d = data_append_data(empty_data, data, len); + d = data_add_marker(empty_data, type, name); + d = data_append_data(d, data, len); p = build_property(name, d, NULL); add_property(node, p); } @@ -858,8 +862,8 @@ static void generate_label_tree_internal(struct dt_info *dti, /* insert it */ p = build_property(l->label, - data_copy_mem(node->fullpath, - strlen(node->fullpath) + 1), + data_copy_escape_string(node->fullpath, + strlen(node->fullpath)), NULL); add_property(an, p); } @@ -910,7 +914,7 @@ static void add_fixup_entry(struct dt_info *dti, struct node *fn, xasprintf(&entry, "%s:%s:%u", node->fullpath, prop->name, m->offset); - append_to_property(fn, m->ref, entry, strlen(entry) + 1); + append_to_property(fn, m->ref, entry, strlen(entry) + 1, TYPE_STRING); free(entry); } @@ -970,7 +974,7 @@ static void add_local_fixup_entry(struct dt_info *dti, char **compp; int i, depth; - /* walk back retreiving depth */ + /* walk back retrieving depth */ depth = 0; for (wn = node; wn; wn = wn->parent) depth++; @@ -993,7 +997,7 @@ static void add_local_fixup_entry(struct dt_info *dti, free(compp); value_32 = cpu_to_fdt32(m->offset); - append_to_property(wn, prop->name, &value_32, sizeof(value_32)); + append_to_property(wn, prop->name, &value_32, sizeof(value_32), TYPE_UINT32); } static void generate_local_fixups_tree_internal(struct dt_info *dti, diff --git a/scripts/dtc/util.h b/scripts/dtc/util.h index 7658781a6200..fc3c0d05ada3 100644 --- a/scripts/dtc/util.h +++ b/scripts/dtc/util.h @@ -122,7 +122,7 @@ int utilfdt_read_err(const char *filename, char **buffp, size_t *len); * stderr. * * @param filename The filename to write, or - for stdout - * @param blob Poiner to buffer containing fdt + * @param blob Pointer to buffer containing fdt * @return 0 if ok, -1 on error */ int utilfdt_write(const char *filename, const void *blob); @@ -133,7 +133,7 @@ int utilfdt_write(const char *filename, const void *blob); * an error message for the user. * * @param filename The filename to write, or - for stdout - * @param blob Poiner to buffer containing fdt + * @param blob Pointer to buffer containing fdt * @return 0 if ok, else an errno value representing the error */ int utilfdt_write_err(const char *filename, const void *blob); diff --git a/scripts/dtc/version_gen.h b/scripts/dtc/version_gen.h index 75f383c0b9d3..2111a6e351f9 100644 --- a/scripts/dtc/version_gen.h +++ b/scripts/dtc/version_gen.h @@ -1 +1 @@ -#define DTC_VERSION "DTC 1.4.7-gf267e674" +#define DTC_VERSION "DTC 1.5.0-g87963ee2" -- cgit v1.2.3 From cd238effefa28fac177e51dcf5e9d1a8b59c3c6b Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 12 Jun 2019 14:52:48 -0300 Subject: docs: kbuild: convert docs to ReST and rename to *.rst The kbuild documentation clearly shows that the documents there are written at different times: some use markdown, some use their own peculiar logic to split sections. Convert everything to ReST without affecting too much the author's style and avoiding adding uneeded markups. The conversion is actually: - add blank lines and identation in order to identify paragraphs; - fix tables markups; - add some lists markups; - mark literal blocks; - adjust title markups. At its new index.rst, let's add a :orphan: while this is not linked to the main index.rst file, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/README.rst | 2 +- Documentation/kbuild/headers_install.rst | 51 + Documentation/kbuild/headers_install.txt | 50 - Documentation/kbuild/index.rst | 27 + Documentation/kbuild/issues.rst | 11 + Documentation/kbuild/kbuild.rst | 265 ++++ Documentation/kbuild/kbuild.txt | 248 ---- Documentation/kbuild/kconfig-language.rst | 689 +++++++++ Documentation/kbuild/kconfig-language.txt | 669 --------- Documentation/kbuild/kconfig-macro-language.rst | 247 ++++ Documentation/kbuild/kconfig-macro-language.txt | 242 ---- Documentation/kbuild/kconfig.rst | 300 ++++ Documentation/kbuild/kconfig.txt | 272 ---- Documentation/kbuild/makefiles.rst | 1509 ++++++++++++++++++++ Documentation/kbuild/makefiles.txt | 1369 ------------------ Documentation/kbuild/modules.rst | 571 ++++++++ Documentation/kbuild/modules.txt | 541 ------- Documentation/kernel-hacking/hacking.rst | 4 +- Documentation/process/coding-style.rst | 2 +- Documentation/process/submit-checklist.rst | 2 +- .../translations/it_IT/kernel-hacking/hacking.rst | 4 +- .../translations/it_IT/process/coding-style.rst | 2 +- .../it_IT/process/submit-checklist.rst | 2 +- .../translations/zh_CN/process/coding-style.rst | 2 +- .../zh_CN/process/submit-checklist.rst | 2 +- Kconfig | 2 +- arch/arc/plat-eznps/Kconfig | 2 +- arch/c6x/Kconfig | 2 +- arch/microblaze/Kconfig.debug | 2 +- arch/microblaze/Kconfig.platform | 2 +- arch/nds32/Kconfig | 2 +- arch/openrisc/Kconfig | 2 +- arch/powerpc/sysdev/Kconfig | 2 +- arch/riscv/Kconfig | 2 +- drivers/auxdisplay/Kconfig | 2 +- drivers/firmware/Kconfig | 2 +- drivers/mtd/devices/Kconfig | 2 +- drivers/net/ethernet/smsc/Kconfig | 6 +- drivers/net/wireless/intel/iwlegacy/Kconfig | 4 +- drivers/net/wireless/intel/iwlwifi/Kconfig | 2 +- drivers/parport/Kconfig | 2 +- drivers/scsi/Kconfig | 4 +- drivers/staging/sm750fb/Kconfig | 2 +- drivers/usb/misc/Kconfig | 4 +- drivers/video/fbdev/Kconfig | 14 +- net/bridge/netfilter/Kconfig | 2 +- net/ipv4/netfilter/Kconfig | 2 +- net/ipv6/netfilter/Kconfig | 2 +- net/netfilter/Kconfig | 16 +- net/tipc/Kconfig | 2 +- scripts/Kbuild.include | 4 +- scripts/Makefile.host | 2 +- scripts/kconfig/symbol.c | 2 +- .../tests/err_recursive_dep/expected_stderr | 14 +- sound/oss/dmasound/Kconfig | 6 +- 55 files changed, 3738 insertions(+), 3459 deletions(-) create mode 100644 Documentation/kbuild/headers_install.rst delete mode 100644 Documentation/kbuild/headers_install.txt create mode 100644 Documentation/kbuild/index.rst create mode 100644 Documentation/kbuild/issues.rst create mode 100644 Documentation/kbuild/kbuild.rst delete mode 100644 Documentation/kbuild/kbuild.txt create mode 100644 Documentation/kbuild/kconfig-language.rst delete mode 100644 Documentation/kbuild/kconfig-language.txt create mode 100644 Documentation/kbuild/kconfig-macro-language.rst delete mode 100644 Documentation/kbuild/kconfig-macro-language.txt create mode 100644 Documentation/kbuild/kconfig.rst delete mode 100644 Documentation/kbuild/kconfig.txt create mode 100644 Documentation/kbuild/makefiles.rst delete mode 100644 Documentation/kbuild/makefiles.txt create mode 100644 Documentation/kbuild/modules.rst delete mode 100644 Documentation/kbuild/modules.txt (limited to 'scripts') diff --git a/Documentation/admin-guide/README.rst b/Documentation/admin-guide/README.rst index a582c780c3bd..cc6151fc0845 100644 --- a/Documentation/admin-guide/README.rst +++ b/Documentation/admin-guide/README.rst @@ -227,7 +227,7 @@ Configuring the kernel "make tinyconfig" Configure the tiniest possible kernel. You can find more information on using the Linux kernel config tools - in Documentation/kbuild/kconfig.txt. + in Documentation/kbuild/kconfig.rst. - NOTES on ``make config``: diff --git a/Documentation/kbuild/headers_install.rst b/Documentation/kbuild/headers_install.rst new file mode 100644 index 000000000000..1ab7294e41ac --- /dev/null +++ b/Documentation/kbuild/headers_install.rst @@ -0,0 +1,51 @@ +============================================= +Exporting kernel headers for use by userspace +============================================= + +The "make headers_install" command exports the kernel's header files in a +form suitable for use by userspace programs. + +The linux kernel's exported header files describe the API for user space +programs attempting to use kernel services. These kernel header files are +used by the system's C library (such as glibc or uClibc) to define available +system calls, as well as constants and structures to be used with these +system calls. The C library's header files include the kernel header files +from the "linux" subdirectory. The system's libc headers are usually +installed at the default location /usr/include and the kernel headers in +subdirectories under that (most notably /usr/include/linux and +/usr/include/asm). + +Kernel headers are backwards compatible, but not forwards compatible. This +means that a program built against a C library using older kernel headers +should run on a newer kernel (although it may not have access to new +features), but a program built against newer kernel headers may not work on an +older kernel. + +The "make headers_install" command can be run in the top level directory of the +kernel source code (or using a standard out-of-tree build). It takes two +optional arguments:: + + make headers_install ARCH=i386 INSTALL_HDR_PATH=/usr + +ARCH indicates which architecture to produce headers for, and defaults to the +current architecture. The linux/asm directory of the exported kernel headers +is platform-specific, to see a complete list of supported architectures use +the command:: + + ls -d include/asm-* | sed 's/.*-//' + +INSTALL_HDR_PATH indicates where to install the headers. It defaults to +"./usr". + +An 'include' directory is automatically created inside INSTALL_HDR_PATH and +headers are installed in 'INSTALL_HDR_PATH/include'. + +The command "make headers_install_all" exports headers for all architectures +simultaneously. (This is mostly of interest to distribution maintainers, +who create an architecture-independent tarball from the resulting include +directory.) You also can use HDR_ARCH_LIST to specify list of architectures. +Remember to provide the appropriate linux/asm directory via "mv" or "ln -s" +before building a C library with headers exported this way. + +The kernel header export infrastructure is maintained by David Woodhouse +. diff --git a/Documentation/kbuild/headers_install.txt b/Documentation/kbuild/headers_install.txt deleted file mode 100644 index f0153adb95e2..000000000000 --- a/Documentation/kbuild/headers_install.txt +++ /dev/null @@ -1,50 +0,0 @@ -Exporting kernel headers for use by userspace -============================================= - -The "make headers_install" command exports the kernel's header files in a -form suitable for use by userspace programs. - -The linux kernel's exported header files describe the API for user space -programs attempting to use kernel services. These kernel header files are -used by the system's C library (such as glibc or uClibc) to define available -system calls, as well as constants and structures to be used with these -system calls. The C library's header files include the kernel header files -from the "linux" subdirectory. The system's libc headers are usually -installed at the default location /usr/include and the kernel headers in -subdirectories under that (most notably /usr/include/linux and -/usr/include/asm). - -Kernel headers are backwards compatible, but not forwards compatible. This -means that a program built against a C library using older kernel headers -should run on a newer kernel (although it may not have access to new -features), but a program built against newer kernel headers may not work on an -older kernel. - -The "make headers_install" command can be run in the top level directory of the -kernel source code (or using a standard out-of-tree build). It takes two -optional arguments: - - make headers_install ARCH=i386 INSTALL_HDR_PATH=/usr - -ARCH indicates which architecture to produce headers for, and defaults to the -current architecture. The linux/asm directory of the exported kernel headers -is platform-specific, to see a complete list of supported architectures use -the command: - - ls -d include/asm-* | sed 's/.*-//' - -INSTALL_HDR_PATH indicates where to install the headers. It defaults to -"./usr". - -An 'include' directory is automatically created inside INSTALL_HDR_PATH and -headers are installed in 'INSTALL_HDR_PATH/include'. - -The command "make headers_install_all" exports headers for all architectures -simultaneously. (This is mostly of interest to distribution maintainers, -who create an architecture-independent tarball from the resulting include -directory.) You also can use HDR_ARCH_LIST to specify list of architectures. -Remember to provide the appropriate linux/asm directory via "mv" or "ln -s" -before building a C library with headers exported this way. - -The kernel header export infrastructure is maintained by David Woodhouse -. diff --git a/Documentation/kbuild/index.rst b/Documentation/kbuild/index.rst new file mode 100644 index 000000000000..42d4cbe4460c --- /dev/null +++ b/Documentation/kbuild/index.rst @@ -0,0 +1,27 @@ +:orphan: + +=================== +Kernel Build System +=================== + +.. toctree:: + :maxdepth: 1 + + kconfig-language + kconfig-macro-language + + kbuild + kconfig + makefiles + modules + + headers_install + + issues + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/kbuild/issues.rst b/Documentation/kbuild/issues.rst new file mode 100644 index 000000000000..9fdded4b681c --- /dev/null +++ b/Documentation/kbuild/issues.rst @@ -0,0 +1,11 @@ +Recursion issue #1 +------------------ + + .. include:: Kconfig.recursion-issue-01 + :literal: + +Recursion issue #2 +------------------ + + .. include:: Kconfig.recursion-issue-02 + :literal: diff --git a/Documentation/kbuild/kbuild.rst b/Documentation/kbuild/kbuild.rst new file mode 100644 index 000000000000..e774e760522d --- /dev/null +++ b/Documentation/kbuild/kbuild.rst @@ -0,0 +1,265 @@ +====== +Kbuild +====== + + +Output files +============ + +modules.order +------------- +This file records the order in which modules appear in Makefiles. This +is used by modprobe to deterministically resolve aliases that match +multiple modules. + +modules.builtin +--------------- +This file lists all modules that are built into the kernel. This is used +by modprobe to not fail when trying to load something builtin. + +modules.builtin.modinfo +-------------------------------------------------- +This file contains modinfo from all modules that are built into the kernel. +Unlike modinfo of a separate module, all fields are prefixed with module name. + + +Environment variables +===================== + +KCPPFLAGS +--------- +Additional options to pass when preprocessing. The preprocessing options +will be used in all cases where kbuild does preprocessing including +building C files and assembler files. + +KAFLAGS +------- +Additional options to the assembler (for built-in and modules). + +AFLAGS_MODULE +------------- +Additional module specific options to use for $(AS). + +AFLAGS_KERNEL +------------- +Additional options for $(AS) when used for assembler +code for code that is compiled as built-in. + +KCFLAGS +------- +Additional options to the C compiler (for built-in and modules). + +CFLAGS_KERNEL +------------- +Additional options for $(CC) when used to compile +code that is compiled as built-in. + +CFLAGS_MODULE +------------- +Additional module specific options to use for $(CC). + +LDFLAGS_MODULE +-------------- +Additional options used for $(LD) when linking modules. + +HOSTCFLAGS +---------- +Additional flags to be passed to $(HOSTCC) when building host programs. + +HOSTCXXFLAGS +------------ +Additional flags to be passed to $(HOSTCXX) when building host programs. + +HOSTLDFLAGS +----------- +Additional flags to be passed when linking host programs. + +HOSTLDLIBS +---------- +Additional libraries to link against when building host programs. + +KBUILD_KCONFIG +-------------- +Set the top-level Kconfig file to the value of this environment +variable. The default name is "Kconfig". + +KBUILD_VERBOSE +-------------- +Set the kbuild verbosity. Can be assigned same values as "V=...". + +See make help for the full list. + +Setting "V=..." takes precedence over KBUILD_VERBOSE. + +KBUILD_EXTMOD +------------- +Set the directory to look for the kernel source when building external +modules. + +Setting "M=..." takes precedence over KBUILD_EXTMOD. + +KBUILD_OUTPUT +------------- +Specify the output directory when building the kernel. + +The output directory can also be specified using "O=...". + +Setting "O=..." takes precedence over KBUILD_OUTPUT. + +KBUILD_DEBARCH +-------------- +For the deb-pkg target, allows overriding the normal heuristics deployed by +deb-pkg. Normally deb-pkg attempts to guess the right architecture based on +the UTS_MACHINE variable, and on some architectures also the kernel config. +The value of KBUILD_DEBARCH is assumed (not checked) to be a valid Debian +architecture. + +ARCH +---- +Set ARCH to the architecture to be built. + +In most cases the name of the architecture is the same as the +directory name found in the arch/ directory. + +But some architectures such as x86 and sparc have aliases. + +- x86: i386 for 32 bit, x86_64 for 64 bit +- sh: sh for 32 bit, sh64 for 64 bit +- sparc: sparc32 for 32 bit, sparc64 for 64 bit + +CROSS_COMPILE +------------- +Specify an optional fixed part of the binutils filename. +CROSS_COMPILE can be a part of the filename or the full path. + +CROSS_COMPILE is also used for ccache in some setups. + +CF +-- +Additional options for sparse. + +CF is often used on the command-line like this:: + + make CF=-Wbitwise C=2 + +INSTALL_PATH +------------ +INSTALL_PATH specifies where to place the updated kernel and system map +images. Default is /boot, but you can set it to other values. + +INSTALLKERNEL +------------- +Install script called when using "make install". +The default name is "installkernel". + +The script will be called with the following arguments: + - $1 - kernel version + - $2 - kernel image file + - $3 - kernel map file + - $4 - default install path (use root directory if blank) + +The implementation of "make install" is architecture specific +and it may differ from the above. + +INSTALLKERNEL is provided to enable the possibility to +specify a custom installer when cross compiling a kernel. + +MODLIB +------ +Specify where to install modules. +The default value is:: + + $(INSTALL_MOD_PATH)/lib/modules/$(KERNELRELEASE) + +The value can be overridden in which case the default value is ignored. + +INSTALL_MOD_PATH +---------------- +INSTALL_MOD_PATH specifies a prefix to MODLIB for module directory +relocations required by build roots. This is not defined in the +makefile but the argument can be passed to make if needed. + +INSTALL_MOD_STRIP +----------------- +INSTALL_MOD_STRIP, if defined, will cause modules to be +stripped after they are installed. If INSTALL_MOD_STRIP is '1', then +the default option --strip-debug will be used. Otherwise, +INSTALL_MOD_STRIP value will be used as the options to the strip command. + +INSTALL_HDR_PATH +---------------- +INSTALL_HDR_PATH specifies where to install user space headers when +executing "make headers_*". + +The default value is:: + + $(objtree)/usr + +$(objtree) is the directory where output files are saved. +The output directory is often set using "O=..." on the commandline. + +The value can be overridden in which case the default value is ignored. + +KBUILD_SIGN_PIN +--------------- +This variable allows a passphrase or PIN to be passed to the sign-file +utility when signing kernel modules, if the private key requires such. + +KBUILD_MODPOST_WARN +------------------- +KBUILD_MODPOST_WARN can be set to avoid errors in case of undefined +symbols in the final module linking stage. It changes such errors +into warnings. + +KBUILD_MODPOST_NOFINAL +---------------------- +KBUILD_MODPOST_NOFINAL can be set to skip the final link of modules. +This is solely useful to speed up test compiles. + +KBUILD_EXTRA_SYMBOLS +-------------------- +For modules that use symbols from other modules. +See more details in modules.txt. + +ALLSOURCE_ARCHS +--------------- +For tags/TAGS/cscope targets, you can specify more than one arch +to be included in the databases, separated by blank space. E.g.:: + + $ make ALLSOURCE_ARCHS="x86 mips arm" tags + +To get all available archs you can also specify all. E.g.:: + + $ make ALLSOURCE_ARCHS=all tags + +KBUILD_ENABLE_EXTRA_GCC_CHECKS +------------------------------ +If enabled over the make command line with "W=1", it turns on additional +gcc -W... options for more extensive build-time checking. + +KBUILD_BUILD_TIMESTAMP +---------------------- +Setting this to a date string overrides the timestamp used in the +UTS_VERSION definition (uname -v in the running kernel). The value has to +be a string that can be passed to date -d. The default value +is the output of the date command at one point during build. + +KBUILD_BUILD_USER, KBUILD_BUILD_HOST +------------------------------------ +These two variables allow to override the user@host string displayed during +boot and in /proc/version. The default value is the output of the commands +whoami and host, respectively. + +KBUILD_LDS +---------- +The linker script with full path. Assigned by the top-level Makefile. + +KBUILD_VMLINUX_OBJS +------------------- +All object files for vmlinux. They are linked to vmlinux in the same +order as listed in KBUILD_VMLINUX_OBJS. + +KBUILD_VMLINUX_LIBS +------------------- +All .a "lib" files for vmlinux. KBUILD_VMLINUX_OBJS and KBUILD_VMLINUX_LIBS +together specify all the object files used to link vmlinux. diff --git a/Documentation/kbuild/kbuild.txt b/Documentation/kbuild/kbuild.txt deleted file mode 100644 index 9c230ea71963..000000000000 --- a/Documentation/kbuild/kbuild.txt +++ /dev/null @@ -1,248 +0,0 @@ -Output files - -modules.order --------------------------------------------------- -This file records the order in which modules appear in Makefiles. This -is used by modprobe to deterministically resolve aliases that match -multiple modules. - -modules.builtin --------------------------------------------------- -This file lists all modules that are built into the kernel. This is used -by modprobe to not fail when trying to load something builtin. - -modules.builtin.modinfo --------------------------------------------------- -This file contains modinfo from all modules that are built into the kernel. -Unlike modinfo of a separate module, all fields are prefixed with module name. - - -Environment variables - -KCPPFLAGS --------------------------------------------------- -Additional options to pass when preprocessing. The preprocessing options -will be used in all cases where kbuild does preprocessing including -building C files and assembler files. - -KAFLAGS --------------------------------------------------- -Additional options to the assembler (for built-in and modules). - -AFLAGS_MODULE --------------------------------------------------- -Additional module specific options to use for $(AS). - -AFLAGS_KERNEL --------------------------------------------------- -Additional options for $(AS) when used for assembler -code for code that is compiled as built-in. - -KCFLAGS --------------------------------------------------- -Additional options to the C compiler (for built-in and modules). - -CFLAGS_KERNEL --------------------------------------------------- -Additional options for $(CC) when used to compile -code that is compiled as built-in. - -CFLAGS_MODULE --------------------------------------------------- -Additional module specific options to use for $(CC). - -LDFLAGS_MODULE --------------------------------------------------- -Additional options used for $(LD) when linking modules. - -HOSTCFLAGS --------------------------------------------------- -Additional flags to be passed to $(HOSTCC) when building host programs. - -HOSTCXXFLAGS --------------------------------------------------- -Additional flags to be passed to $(HOSTCXX) when building host programs. - -HOSTLDFLAGS --------------------------------------------------- -Additional flags to be passed when linking host programs. - -HOSTLDLIBS --------------------------------------------------- -Additional libraries to link against when building host programs. - -KBUILD_KCONFIG --------------------------------------------------- -Set the top-level Kconfig file to the value of this environment -variable. The default name is "Kconfig". - -KBUILD_VERBOSE --------------------------------------------------- -Set the kbuild verbosity. Can be assigned same values as "V=...". -See make help for the full list. -Setting "V=..." takes precedence over KBUILD_VERBOSE. - -KBUILD_EXTMOD --------------------------------------------------- -Set the directory to look for the kernel source when building external -modules. -Setting "M=..." takes precedence over KBUILD_EXTMOD. - -KBUILD_OUTPUT --------------------------------------------------- -Specify the output directory when building the kernel. -The output directory can also be specified using "O=...". -Setting "O=..." takes precedence over KBUILD_OUTPUT. - -KBUILD_DEBARCH --------------------------------------------------- -For the deb-pkg target, allows overriding the normal heuristics deployed by -deb-pkg. Normally deb-pkg attempts to guess the right architecture based on -the UTS_MACHINE variable, and on some architectures also the kernel config. -The value of KBUILD_DEBARCH is assumed (not checked) to be a valid Debian -architecture. - -ARCH --------------------------------------------------- -Set ARCH to the architecture to be built. -In most cases the name of the architecture is the same as the -directory name found in the arch/ directory. -But some architectures such as x86 and sparc have aliases. -x86: i386 for 32 bit, x86_64 for 64 bit -sh: sh for 32 bit, sh64 for 64 bit -sparc: sparc32 for 32 bit, sparc64 for 64 bit - -CROSS_COMPILE --------------------------------------------------- -Specify an optional fixed part of the binutils filename. -CROSS_COMPILE can be a part of the filename or the full path. - -CROSS_COMPILE is also used for ccache in some setups. - -CF --------------------------------------------------- -Additional options for sparse. -CF is often used on the command-line like this: - - make CF=-Wbitwise C=2 - -INSTALL_PATH --------------------------------------------------- -INSTALL_PATH specifies where to place the updated kernel and system map -images. Default is /boot, but you can set it to other values. - -INSTALLKERNEL --------------------------------------------------- -Install script called when using "make install". -The default name is "installkernel". - -The script will be called with the following arguments: - $1 - kernel version - $2 - kernel image file - $3 - kernel map file - $4 - default install path (use root directory if blank) - -The implementation of "make install" is architecture specific -and it may differ from the above. - -INSTALLKERNEL is provided to enable the possibility to -specify a custom installer when cross compiling a kernel. - -MODLIB --------------------------------------------------- -Specify where to install modules. -The default value is: - - $(INSTALL_MOD_PATH)/lib/modules/$(KERNELRELEASE) - -The value can be overridden in which case the default value is ignored. - -INSTALL_MOD_PATH --------------------------------------------------- -INSTALL_MOD_PATH specifies a prefix to MODLIB for module directory -relocations required by build roots. This is not defined in the -makefile but the argument can be passed to make if needed. - -INSTALL_MOD_STRIP --------------------------------------------------- -INSTALL_MOD_STRIP, if defined, will cause modules to be -stripped after they are installed. If INSTALL_MOD_STRIP is '1', then -the default option --strip-debug will be used. Otherwise, -INSTALL_MOD_STRIP value will be used as the options to the strip command. - -INSTALL_HDR_PATH --------------------------------------------------- -INSTALL_HDR_PATH specifies where to install user space headers when -executing "make headers_*". -The default value is: - - $(objtree)/usr - -$(objtree) is the directory where output files are saved. -The output directory is often set using "O=..." on the commandline. - -The value can be overridden in which case the default value is ignored. - -KBUILD_SIGN_PIN --------------------------------------------------- -This variable allows a passphrase or PIN to be passed to the sign-file -utility when signing kernel modules, if the private key requires such. - -KBUILD_MODPOST_WARN --------------------------------------------------- -KBUILD_MODPOST_WARN can be set to avoid errors in case of undefined -symbols in the final module linking stage. It changes such errors -into warnings. - -KBUILD_MODPOST_NOFINAL --------------------------------------------------- -KBUILD_MODPOST_NOFINAL can be set to skip the final link of modules. -This is solely useful to speed up test compiles. - -KBUILD_EXTRA_SYMBOLS --------------------------------------------------- -For modules that use symbols from other modules. -See more details in modules.txt. - -ALLSOURCE_ARCHS --------------------------------------------------- -For tags/TAGS/cscope targets, you can specify more than one arch -to be included in the databases, separated by blank space. E.g.: - - $ make ALLSOURCE_ARCHS="x86 mips arm" tags - -To get all available archs you can also specify all. E.g.: - - $ make ALLSOURCE_ARCHS=all tags - -KBUILD_ENABLE_EXTRA_GCC_CHECKS --------------------------------------------------- -If enabled over the make command line with "W=1", it turns on additional -gcc -W... options for more extensive build-time checking. - -KBUILD_BUILD_TIMESTAMP --------------------------------------------------- -Setting this to a date string overrides the timestamp used in the -UTS_VERSION definition (uname -v in the running kernel). The value has to -be a string that can be passed to date -d. The default value -is the output of the date command at one point during build. - -KBUILD_BUILD_USER, KBUILD_BUILD_HOST --------------------------------------------------- -These two variables allow to override the user@host string displayed during -boot and in /proc/version. The default value is the output of the commands -whoami and host, respectively. - -KBUILD_LDS --------------------------------------------------- -The linker script with full path. Assigned by the top-level Makefile. - -KBUILD_VMLINUX_OBJS --------------------------------------------------- -All object files for vmlinux. They are linked to vmlinux in the same -order as listed in KBUILD_VMLINUX_OBJS. - -KBUILD_VMLINUX_LIBS --------------------------------------------------- -All .a "lib" files for vmlinux. KBUILD_VMLINUX_OBJS and KBUILD_VMLINUX_LIBS -together specify all the object files used to link vmlinux. diff --git a/Documentation/kbuild/kconfig-language.rst b/Documentation/kbuild/kconfig-language.rst new file mode 100644 index 000000000000..2bc8a7803365 --- /dev/null +++ b/Documentation/kbuild/kconfig-language.rst @@ -0,0 +1,689 @@ +================ +Kconfig Language +================ + +Introduction +------------ + +The configuration database is a collection of configuration options +organized in a tree structure:: + + +- Code maturity level options + | +- Prompt for development and/or incomplete code/drivers + +- General setup + | +- Networking support + | +- System V IPC + | +- BSD Process Accounting + | +- Sysctl support + +- Loadable module support + | +- Enable loadable module support + | +- Set version information on all module symbols + | +- Kernel module loader + +- ... + +Every entry has its own dependencies. These dependencies are used +to determine the visibility of an entry. Any child entry is only +visible if its parent entry is also visible. + +Menu entries +------------ + +Most entries define a config option; all other entries help to organize +them. A single configuration option is defined like this:: + + config MODVERSIONS + bool "Set version information on all module symbols" + depends on MODULES + help + Usually, modules have to be recompiled whenever you switch to a new + kernel. ... + +Every line starts with a key word and can be followed by multiple +arguments. "config" starts a new config entry. The following lines +define attributes for this config option. Attributes can be the type of +the config option, input prompt, dependencies, help text and default +values. A config option can be defined multiple times with the same +name, but every definition can have only a single input prompt and the +type must not conflict. + +Menu attributes +--------------- + +A menu entry can have a number of attributes. Not all of them are +applicable everywhere (see syntax). + +- type definition: "bool"/"tristate"/"string"/"hex"/"int" + Every config option must have a type. There are only two basic types: + tristate and string; the other types are based on these two. The type + definition optionally accepts an input prompt, so these two examples + are equivalent:: + + bool "Networking support" + + and:: + + bool + prompt "Networking support" + +- input prompt: "prompt" ["if" ] + Every menu entry can have at most one prompt, which is used to display + to the user. Optionally dependencies only for this prompt can be added + with "if". + +- default value: "default" ["if" ] + A config option can have any number of default values. If multiple + default values are visible, only the first defined one is active. + Default values are not limited to the menu entry where they are + defined. This means the default can be defined somewhere else or be + overridden by an earlier definition. + The default value is only assigned to the config symbol if no other + value was set by the user (via the input prompt above). If an input + prompt is visible the default value is presented to the user and can + be overridden by him. + Optionally, dependencies only for this default value can be added with + "if". + + The default value deliberately defaults to 'n' in order to avoid bloating the + build. With few exceptions, new config options should not change this. The + intent is for "make oldconfig" to add as little as possible to the config from + release to release. + + Note: + Things that merit "default y/m" include: + + a) A new Kconfig option for something that used to always be built + should be "default y". + + b) A new gatekeeping Kconfig option that hides/shows other Kconfig + options (but does not generate any code of its own), should be + "default y" so people will see those other options. + + c) Sub-driver behavior or similar options for a driver that is + "default n". This allows you to provide sane defaults. + + d) Hardware or infrastructure that everybody expects, such as CONFIG_NET + or CONFIG_BLOCK. These are rare exceptions. + +- type definition + default value:: + + "def_bool"/"def_tristate" ["if" ] + + This is a shorthand notation for a type definition plus a value. + Optionally dependencies for this default value can be added with "if". + +- dependencies: "depends on" + This defines a dependency for this menu entry. If multiple + dependencies are defined, they are connected with '&&'. Dependencies + are applied to all other options within this menu entry (which also + accept an "if" expression), so these two examples are equivalent:: + + bool "foo" if BAR + default y if BAR + + and:: + + depends on BAR + bool "foo" + default y + +- reverse dependencies: "select" ["if" ] + While normal dependencies reduce the upper limit of a symbol (see + below), reverse dependencies can be used to force a lower limit of + another symbol. The value of the current menu symbol is used as the + minimal value can be set to. If is selected multiple + times, the limit is set to the largest selection. + Reverse dependencies can only be used with boolean or tristate + symbols. + + Note: + select should be used with care. select will force + a symbol to a value without visiting the dependencies. + By abusing select you are able to select a symbol FOO even + if FOO depends on BAR that is not set. + In general use select only for non-visible symbols + (no prompts anywhere) and for symbols with no dependencies. + That will limit the usefulness but on the other hand avoid + the illegal configurations all over. + +- weak reverse dependencies: "imply" ["if" ] + This is similar to "select" as it enforces a lower limit on another + symbol except that the "implied" symbol's value may still be set to n + from a direct dependency or with a visible prompt. + + Given the following example:: + + config FOO + tristate + imply BAZ + + config BAZ + tristate + depends on BAR + + The following values are possible: + + === === ============= ============== + FOO BAR BAZ's default choice for BAZ + === === ============= ============== + n y n N/m/y + m y m M/y/n + y y y Y/n + y n * N + === === ============= ============== + + This is useful e.g. with multiple drivers that want to indicate their + ability to hook into a secondary subsystem while allowing the user to + configure that subsystem out without also having to unset these drivers. + +- limiting menu display: "visible if" + This attribute is only applicable to menu blocks, if the condition is + false, the menu block is not displayed to the user (the symbols + contained there can still be selected by other symbols, though). It is + similar to a conditional "prompt" attribute for individual menu + entries. Default value of "visible" is true. + +- numerical ranges: "range" ["if" ] + This allows to limit the range of possible input values for int + and hex symbols. The user can only input a value which is larger than + or equal to the first symbol and smaller than or equal to the second + symbol. + +- help text: "help" or "---help---" + This defines a help text. The end of the help text is determined by + the indentation level, this means it ends at the first line which has + a smaller indentation than the first line of the help text. + "---help---" and "help" do not differ in behaviour, "---help---" is + used to help visually separate configuration logic from help within + the file as an aid to developers. + +- misc options: "option" [=] + Various less common options can be defined via this option syntax, + which can modify the behaviour of the menu entry and its config + symbol. These options are currently possible: + + - "defconfig_list" + This declares a list of default entries which can be used when + looking for the default configuration (which is used when the main + .config doesn't exists yet.) + + - "modules" + This declares the symbol to be used as the MODULES symbol, which + enables the third modular state for all config symbols. + At most one symbol may have the "modules" option set. + + - "allnoconfig_y" + This declares the symbol as one that should have the value y when + using "allnoconfig". Used for symbols that hide other symbols. + +Menu dependencies +----------------- + +Dependencies define the visibility of a menu entry and can also reduce +the input range of tristate symbols. The tristate logic used in the +expressions uses one more state than normal boolean logic to express the +module state. Dependency expressions have the following syntax:: + + ::= (1) + '=' (2) + '!=' (3) + '<' (4) + '>' (4) + '<=' (4) + '>=' (4) + '(' ')' (5) + '!' (6) + '&&' (7) + '||' (8) + +Expressions are listed in decreasing order of precedence. + +(1) Convert the symbol into an expression. Boolean and tristate symbols + are simply converted into the respective expression values. All + other symbol types result in 'n'. +(2) If the values of both symbols are equal, it returns 'y', + otherwise 'n'. +(3) If the values of both symbols are equal, it returns 'n', + otherwise 'y'. +(4) If value of is respectively lower, greater, lower-or-equal, + or greater-or-equal than value of , it returns 'y', + otherwise 'n'. +(5) Returns the value of the expression. Used to override precedence. +(6) Returns the result of (2-/expr/). +(7) Returns the result of min(/expr/, /expr/). +(8) Returns the result of max(/expr/, /expr/). + +An expression can have a value of 'n', 'm' or 'y' (or 0, 1, 2 +respectively for calculations). A menu entry becomes visible when its +expression evaluates to 'm' or 'y'. + +There are two types of symbols: constant and non-constant symbols. +Non-constant symbols are the most common ones and are defined with the +'config' statement. Non-constant symbols consist entirely of alphanumeric +characters or underscores. +Constant symbols are only part of expressions. Constant symbols are +always surrounded by single or double quotes. Within the quote, any +other character is allowed and the quotes can be escaped using '\'. + +Menu structure +-------------- + +The position of a menu entry in the tree is determined in two ways. First +it can be specified explicitly:: + + menu "Network device support" + depends on NET + + config NETDEVICES + ... + + endmenu + +All entries within the "menu" ... "endmenu" block become a submenu of +"Network device support". All subentries inherit the dependencies from +the menu entry, e.g. this means the dependency "NET" is added to the +dependency list of the config option NETDEVICES. + +The other way to generate the menu structure is done by analyzing the +dependencies. If a menu entry somehow depends on the previous entry, it +can be made a submenu of it. First, the previous (parent) symbol must +be part of the dependency list and then one of these two conditions +must be true: + +- the child entry must become invisible, if the parent is set to 'n' +- the child entry must only be visible, if the parent is visible:: + + config MODULES + bool "Enable loadable module support" + + config MODVERSIONS + bool "Set version information on all module symbols" + depends on MODULES + + comment "module support disabled" + depends on !MODULES + +MODVERSIONS directly depends on MODULES, this means it's only visible if +MODULES is different from 'n'. The comment on the other hand is only +visible when MODULES is set to 'n'. + + +Kconfig syntax +-------------- + +The configuration file describes a series of menu entries, where every +line starts with a keyword (except help texts). The following keywords +end a menu entry: + +- config +- menuconfig +- choice/endchoice +- comment +- menu/endmenu +- if/endif +- source + +The first five also start the definition of a menu entry. + +config:: + "config" + + +This defines a config symbol and accepts any of above +attributes as options. + +menuconfig:: + "menuconfig" + + +This is similar to the simple config entry above, but it also gives a +hint to front ends, that all suboptions should be displayed as a +separate list of options. To make sure all the suboptions will really +show up under the menuconfig entry and not outside of it, every item +from the list must depend on the menuconfig symbol. +In practice, this is achieved by using one of the next two constructs:: + + (1): + menuconfig M + if M + config C1 + config C2 + endif + + (2): + menuconfig M + config C1 + depends on M + config C2 + depends on M + +In the following examples (3) and (4), C1 and C2 still have the M +dependency, but will not appear under menuconfig M anymore, because +of C0, which doesn't depend on M:: + + (3): + menuconfig M + config C0 + if M + config C1 + config C2 + endif + + (4): + menuconfig M + config C0 + config C1 + depends on M + config C2 + depends on M + +choices:: + + "choice" [symbol] + + + "endchoice" + +This defines a choice group and accepts any of the above attributes as +options. A choice can only be of type bool or tristate. If no type is +specified for a choice, its type will be determined by the type of +the first choice element in the group or remain unknown if none of the +choice elements have a type specified, as well. + +While a boolean choice only allows a single config entry to be +selected, a tristate choice also allows any number of config entries +to be set to 'm'. This can be used if multiple drivers for a single +hardware exists and only a single driver can be compiled/loaded into +the kernel, but all drivers can be compiled as modules. + +A choice accepts another option "optional", which allows to set the +choice to 'n' and no entry needs to be selected. +If no [symbol] is associated with a choice, then you can not have multiple +definitions of that choice. If a [symbol] is associated to the choice, +then you may define the same choice (i.e. with the same entries) in another +place. + +comment:: + + "comment" + + +This defines a comment which is displayed to the user during the +configuration process and is also echoed to the output files. The only +possible options are dependencies. + +menu:: + + "menu" + + + "endmenu" + +This defines a menu block, see "Menu structure" above for more +information. The only possible options are dependencies and "visible" +attributes. + +if:: + + "if" + + "endif" + +This defines an if block. The dependency expression is appended +to all enclosed menu entries. + +source:: + + "source" + +This reads the specified configuration file. This file is always parsed. + +mainmenu:: + + "mainmenu" + +This sets the config program's title bar if the config program chooses +to use it. It should be placed at the top of the configuration, before any +other statement. + +'#' Kconfig source file comment: + +An unquoted '#' character anywhere in a source file line indicates +the beginning of a source file comment. The remainder of that line +is a comment. + + +Kconfig hints +------------- +This is a collection of Kconfig tips, most of which aren't obvious at +first glance and most of which have become idioms in several Kconfig +files. + +Adding common features and make the usage configurable +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +It is a common idiom to implement a feature/functionality that are +relevant for some architectures but not all. +The recommended way to do so is to use a config variable named HAVE_* +that is defined in a common Kconfig file and selected by the relevant +architectures. +An example is the generic IOMAP functionality. + +We would in lib/Kconfig see:: + + # Generic IOMAP is used to ... + config HAVE_GENERIC_IOMAP + + config GENERIC_IOMAP + depends on HAVE_GENERIC_IOMAP && FOO + +And in lib/Makefile we would see:: + + obj-$(CONFIG_GENERIC_IOMAP) += iomap.o + +For each architecture using the generic IOMAP functionality we would see:: + + config X86 + select ... + select HAVE_GENERIC_IOMAP + select ... + +Note: we use the existing config option and avoid creating a new +config variable to select HAVE_GENERIC_IOMAP. + +Note: the use of the internal config variable HAVE_GENERIC_IOMAP, it is +introduced to overcome the limitation of select which will force a +config option to 'y' no matter the dependencies. +The dependencies are moved to the symbol GENERIC_IOMAP and we avoid the +situation where select forces a symbol equals to 'y'. + +Adding features that need compiler support +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are several features that need compiler support. The recommended way +to describe the dependency on the compiler feature is to use "depends on" +followed by a test macro:: + + config STACKPROTECTOR + bool "Stack Protector buffer overflow detection" + depends on $(cc-option,-fstack-protector) + ... + +If you need to expose a compiler capability to makefiles and/or C source files, +`CC_HAS_` is the recommended prefix for the config option:: + + config CC_HAS_STACKPROTECTOR_NONE + def_bool $(cc-option,-fno-stack-protector) + +Build as module only +~~~~~~~~~~~~~~~~~~~~ +To restrict a component build to module-only, qualify its config symbol +with "depends on m". E.g.:: + + config FOO + depends on BAR && m + +limits FOO to module (=m) or disabled (=n). + +Kconfig recursive dependency limitations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you've hit the Kconfig error: "recursive dependency detected" you've run +into a recursive dependency issue with Kconfig, a recursive dependency can be +summarized as a circular dependency. The kconfig tools need to ensure that +Kconfig files comply with specified configuration requirements. In order to do +that kconfig must determine the values that are possible for all Kconfig +symbols, this is currently not possible if there is a circular relation +between two or more Kconfig symbols. For more details refer to the "Simple +Kconfig recursive issue" subsection below. Kconfig does not do recursive +dependency resolution; this has a few implications for Kconfig file writers. +We'll first explain why this issues exists and then provide an example +technical limitation which this brings upon Kconfig developers. Eager +developers wishing to try to address this limitation should read the next +subsections. + +Simple Kconfig recursive issue +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Read: Documentation/kbuild/Kconfig.recursion-issue-01 + +Test with:: + + make KBUILD_KCONFIG=Documentation/kbuild/Kconfig.recursion-issue-01 allnoconfig + +Cumulative Kconfig recursive issue +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Read: Documentation/kbuild/Kconfig.recursion-issue-02 + +Test with:: + + make KBUILD_KCONFIG=Documentation/kbuild/Kconfig.recursion-issue-02 allnoconfig + +Practical solutions to kconfig recursive issue +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Developers who run into the recursive Kconfig issue have two options +at their disposal. We document them below and also provide a list of +historical issues resolved through these different solutions. + + a) Remove any superfluous "select FOO" or "depends on FOO" + b) Match dependency semantics: + + b1) Swap all "select FOO" to "depends on FOO" or, + + b2) Swap all "depends on FOO" to "select FOO" + +The resolution to a) can be tested with the sample Kconfig file +Documentation/kbuild/Kconfig.recursion-issue-01 through the removal +of the "select CORE" from CORE_BELL_A_ADVANCED as that is implicit already +since CORE_BELL_A depends on CORE. At times it may not be possible to remove +some dependency criteria, for such cases you can work with solution b). + +The two different resolutions for b) can be tested in the sample Kconfig file +Documentation/kbuild/Kconfig.recursion-issue-02. + +Below is a list of examples of prior fixes for these types of recursive issues; +all errors appear to involve one or more select's and one or more "depends on". + +============ =================================== +commit fix +============ =================================== +06b718c01208 select A -> depends on A +c22eacfe82f9 depends on A -> depends on B +6a91e854442c select A -> depends on A +118c565a8f2e select A -> select B +f004e5594705 select A -> depends on A +c7861f37b4c6 depends on A -> (null) +80c69915e5fb select A -> (null) (1) +c2218e26c0d0 select A -> depends on A (1) +d6ae99d04e1c select A -> depends on A +95ca19cf8cbf select A -> depends on A +8f057d7bca54 depends on A -> (null) +8f057d7bca54 depends on A -> select A +a0701f04846e select A -> depends on A +0c8b92f7f259 depends on A -> (null) +e4e9e0540928 select A -> depends on A (2) +7453ea886e87 depends on A > (null) (1) +7b1fff7e4fdf select A -> depends on A +86c747d2a4f0 select A -> depends on A +d9f9ab51e55e select A -> depends on A +0c51a4d8abd6 depends on A -> select A (3) +e98062ed6dc4 select A -> depends on A (3) +91e5d284a7f1 select A -> (null) +============ =================================== + +(1) Partial (or no) quote of error. +(2) That seems to be the gist of that fix. +(3) Same error. + +Future kconfig work +~~~~~~~~~~~~~~~~~~~ + +Work on kconfig is welcomed on both areas of clarifying semantics and on +evaluating the use of a full SAT solver for it. A full SAT solver can be +desirable to enable more complex dependency mappings and / or queries, +for instance on possible use case for a SAT solver could be that of handling +the current known recursive dependency issues. It is not known if this would +address such issues but such evaluation is desirable. If support for a full SAT +solver proves too complex or that it cannot address recursive dependency issues +Kconfig should have at least clear and well defined semantics which also +addresses and documents limitations or requirements such as the ones dealing +with recursive dependencies. + +Further work on both of these areas is welcomed on Kconfig. We elaborate +on both of these in the next two subsections. + +Semantics of Kconfig +~~~~~~~~~~~~~~~~~~~~ + +The use of Kconfig is broad, Linux is now only one of Kconfig's users: +one study has completed a broad analysis of Kconfig use in 12 projects [0]_. +Despite its widespread use, and although this document does a reasonable job +in documenting basic Kconfig syntax a more precise definition of Kconfig +semantics is welcomed. One project deduced Kconfig semantics through +the use of the xconfig configurator [1]_. Work should be done to confirm if +the deduced semantics matches our intended Kconfig design goals. + +Having well defined semantics can be useful for tools for practical +evaluation of depenencies, for instance one such use known case was work to +express in boolean abstraction of the inferred semantics of Kconfig to +translate Kconfig logic into boolean formulas and run a SAT solver on this to +find dead code / features (always inactive), 114 dead features were found in +Linux using this methodology [1]_ (Section 8: Threats to validity). + +Confirming this could prove useful as Kconfig stands as one of the the leading +industrial variability modeling languages [1]_ [2]_. Its study would help +evaluate practical uses of such languages, their use was only theoretical +and real world requirements were not well understood. As it stands though +only reverse engineering techniques have been used to deduce semantics from +variability modeling languages such as Kconfig [3]_. + +.. [0] http://www.eng.uwaterloo.ca/~shshe/kconfig_semantics.pdf +.. [1] http://gsd.uwaterloo.ca/sites/default/files/vm-2013-berger.pdf +.. [2] http://gsd.uwaterloo.ca/sites/default/files/ase241-berger_0.pdf +.. [3] http://gsd.uwaterloo.ca/sites/default/files/icse2011.pdf + +Full SAT solver for Kconfig +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Although SAT solvers [4]_ haven't yet been used by Kconfig directly, as noted +in the previous subsection, work has been done however to express in boolean +abstraction the inferred semantics of Kconfig to translate Kconfig logic into +boolean formulas and run a SAT solver on it [5]_. Another known related project +is CADOS [6]_ (former VAMOS [7]_) and the tools, mainly undertaker [8]_, which +has been introduced first with [9]_. The basic concept of undertaker is to +exract variability models from Kconfig, and put them together with a +propositional formula extracted from CPP #ifdefs and build-rules into a SAT +solver in order to find dead code, dead files, and dead symbols. If using a SAT +solver is desirable on Kconfig one approach would be to evaluate repurposing +such efforts somehow on Kconfig. There is enough interest from mentors of +existing projects to not only help advise how to integrate this work upstream +but also help maintain it long term. Interested developers should visit: + +http://kernelnewbies.org/KernelProjects/kconfig-sat + +.. [4] http://www.cs.cornell.edu/~sabhar/chapters/SATSolvers-KR-Handbook.pdf +.. [5] http://gsd.uwaterloo.ca/sites/default/files/vm-2013-berger.pdf +.. [6] https://cados.cs.fau.de +.. [7] https://vamos.cs.fau.de +.. [8] https://undertaker.cs.fau.de +.. [9] https://www4.cs.fau.de/Publications/2011/tartler_11_eurosys.pdf diff --git a/Documentation/kbuild/kconfig-language.txt b/Documentation/kbuild/kconfig-language.txt deleted file mode 100644 index 864e740811da..000000000000 --- a/Documentation/kbuild/kconfig-language.txt +++ /dev/null @@ -1,669 +0,0 @@ -Introduction ------------- - -The configuration database is a collection of configuration options -organized in a tree structure: - - +- Code maturity level options - | +- Prompt for development and/or incomplete code/drivers - +- General setup - | +- Networking support - | +- System V IPC - | +- BSD Process Accounting - | +- Sysctl support - +- Loadable module support - | +- Enable loadable module support - | +- Set version information on all module symbols - | +- Kernel module loader - +- ... - -Every entry has its own dependencies. These dependencies are used -to determine the visibility of an entry. Any child entry is only -visible if its parent entry is also visible. - -Menu entries ------------- - -Most entries define a config option; all other entries help to organize -them. A single configuration option is defined like this: - -config MODVERSIONS - bool "Set version information on all module symbols" - depends on MODULES - help - Usually, modules have to be recompiled whenever you switch to a new - kernel. ... - -Every line starts with a key word and can be followed by multiple -arguments. "config" starts a new config entry. The following lines -define attributes for this config option. Attributes can be the type of -the config option, input prompt, dependencies, help text and default -values. A config option can be defined multiple times with the same -name, but every definition can have only a single input prompt and the -type must not conflict. - -Menu attributes ---------------- - -A menu entry can have a number of attributes. Not all of them are -applicable everywhere (see syntax). - -- type definition: "bool"/"tristate"/"string"/"hex"/"int" - Every config option must have a type. There are only two basic types: - tristate and string; the other types are based on these two. The type - definition optionally accepts an input prompt, so these two examples - are equivalent: - - bool "Networking support" - and - bool - prompt "Networking support" - -- input prompt: "prompt" ["if" ] - Every menu entry can have at most one prompt, which is used to display - to the user. Optionally dependencies only for this prompt can be added - with "if". - -- default value: "default" ["if" ] - A config option can have any number of default values. If multiple - default values are visible, only the first defined one is active. - Default values are not limited to the menu entry where they are - defined. This means the default can be defined somewhere else or be - overridden by an earlier definition. - The default value is only assigned to the config symbol if no other - value was set by the user (via the input prompt above). If an input - prompt is visible the default value is presented to the user and can - be overridden by him. - Optionally, dependencies only for this default value can be added with - "if". - - The default value deliberately defaults to 'n' in order to avoid bloating the - build. With few exceptions, new config options should not change this. The - intent is for "make oldconfig" to add as little as possible to the config from - release to release. - - Note: - Things that merit "default y/m" include: - - a) A new Kconfig option for something that used to always be built - should be "default y". - - b) A new gatekeeping Kconfig option that hides/shows other Kconfig - options (but does not generate any code of its own), should be - "default y" so people will see those other options. - - c) Sub-driver behavior or similar options for a driver that is - "default n". This allows you to provide sane defaults. - - d) Hardware or infrastructure that everybody expects, such as CONFIG_NET - or CONFIG_BLOCK. These are rare exceptions. - -- type definition + default value: - "def_bool"/"def_tristate" ["if" ] - This is a shorthand notation for a type definition plus a value. - Optionally dependencies for this default value can be added with "if". - -- dependencies: "depends on" - This defines a dependency for this menu entry. If multiple - dependencies are defined, they are connected with '&&'. Dependencies - are applied to all other options within this menu entry (which also - accept an "if" expression), so these two examples are equivalent: - - bool "foo" if BAR - default y if BAR - and - depends on BAR - bool "foo" - default y - -- reverse dependencies: "select" ["if" ] - While normal dependencies reduce the upper limit of a symbol (see - below), reverse dependencies can be used to force a lower limit of - another symbol. The value of the current menu symbol is used as the - minimal value can be set to. If is selected multiple - times, the limit is set to the largest selection. - Reverse dependencies can only be used with boolean or tristate - symbols. - Note: - select should be used with care. select will force - a symbol to a value without visiting the dependencies. - By abusing select you are able to select a symbol FOO even - if FOO depends on BAR that is not set. - In general use select only for non-visible symbols - (no prompts anywhere) and for symbols with no dependencies. - That will limit the usefulness but on the other hand avoid - the illegal configurations all over. - -- weak reverse dependencies: "imply" ["if" ] - This is similar to "select" as it enforces a lower limit on another - symbol except that the "implied" symbol's value may still be set to n - from a direct dependency or with a visible prompt. - - Given the following example: - - config FOO - tristate - imply BAZ - - config BAZ - tristate - depends on BAR - - The following values are possible: - - FOO BAR BAZ's default choice for BAZ - --- --- ------------- -------------- - n y n N/m/y - m y m M/y/n - y y y Y/n - y n * N - - This is useful e.g. with multiple drivers that want to indicate their - ability to hook into a secondary subsystem while allowing the user to - configure that subsystem out without also having to unset these drivers. - -- limiting menu display: "visible if" - This attribute is only applicable to menu blocks, if the condition is - false, the menu block is not displayed to the user (the symbols - contained there can still be selected by other symbols, though). It is - similar to a conditional "prompt" attribute for individual menu - entries. Default value of "visible" is true. - -- numerical ranges: "range" ["if" ] - This allows to limit the range of possible input values for int - and hex symbols. The user can only input a value which is larger than - or equal to the first symbol and smaller than or equal to the second - symbol. - -- help text: "help" or "---help---" - This defines a help text. The end of the help text is determined by - the indentation level, this means it ends at the first line which has - a smaller indentation than the first line of the help text. - "---help---" and "help" do not differ in behaviour, "---help---" is - used to help visually separate configuration logic from help within - the file as an aid to developers. - -- misc options: "option" [=] - Various less common options can be defined via this option syntax, - which can modify the behaviour of the menu entry and its config - symbol. These options are currently possible: - - - "defconfig_list" - This declares a list of default entries which can be used when - looking for the default configuration (which is used when the main - .config doesn't exists yet.) - - - "modules" - This declares the symbol to be used as the MODULES symbol, which - enables the third modular state for all config symbols. - At most one symbol may have the "modules" option set. - - - "allnoconfig_y" - This declares the symbol as one that should have the value y when - using "allnoconfig". Used for symbols that hide other symbols. - -Menu dependencies ------------------ - -Dependencies define the visibility of a menu entry and can also reduce -the input range of tristate symbols. The tristate logic used in the -expressions uses one more state than normal boolean logic to express the -module state. Dependency expressions have the following syntax: - - ::= (1) - '=' (2) - '!=' (3) - '<' (4) - '>' (4) - '<=' (4) - '>=' (4) - '(' ')' (5) - '!' (6) - '&&' (7) - '||' (8) - -Expressions are listed in decreasing order of precedence. - -(1) Convert the symbol into an expression. Boolean and tristate symbols - are simply converted into the respective expression values. All - other symbol types result in 'n'. -(2) If the values of both symbols are equal, it returns 'y', - otherwise 'n'. -(3) If the values of both symbols are equal, it returns 'n', - otherwise 'y'. -(4) If value of is respectively lower, greater, lower-or-equal, - or greater-or-equal than value of , it returns 'y', - otherwise 'n'. -(5) Returns the value of the expression. Used to override precedence. -(6) Returns the result of (2-/expr/). -(7) Returns the result of min(/expr/, /expr/). -(8) Returns the result of max(/expr/, /expr/). - -An expression can have a value of 'n', 'm' or 'y' (or 0, 1, 2 -respectively for calculations). A menu entry becomes visible when its -expression evaluates to 'm' or 'y'. - -There are two types of symbols: constant and non-constant symbols. -Non-constant symbols are the most common ones and are defined with the -'config' statement. Non-constant symbols consist entirely of alphanumeric -characters or underscores. -Constant symbols are only part of expressions. Constant symbols are -always surrounded by single or double quotes. Within the quote, any -other character is allowed and the quotes can be escaped using '\'. - -Menu structure --------------- - -The position of a menu entry in the tree is determined in two ways. First -it can be specified explicitly: - -menu "Network device support" - depends on NET - -config NETDEVICES - ... - -endmenu - -All entries within the "menu" ... "endmenu" block become a submenu of -"Network device support". All subentries inherit the dependencies from -the menu entry, e.g. this means the dependency "NET" is added to the -dependency list of the config option NETDEVICES. - -The other way to generate the menu structure is done by analyzing the -dependencies. If a menu entry somehow depends on the previous entry, it -can be made a submenu of it. First, the previous (parent) symbol must -be part of the dependency list and then one of these two conditions -must be true: -- the child entry must become invisible, if the parent is set to 'n' -- the child entry must only be visible, if the parent is visible - -config MODULES - bool "Enable loadable module support" - -config MODVERSIONS - bool "Set version information on all module symbols" - depends on MODULES - -comment "module support disabled" - depends on !MODULES - -MODVERSIONS directly depends on MODULES, this means it's only visible if -MODULES is different from 'n'. The comment on the other hand is only -visible when MODULES is set to 'n'. - - -Kconfig syntax --------------- - -The configuration file describes a series of menu entries, where every -line starts with a keyword (except help texts). The following keywords -end a menu entry: -- config -- menuconfig -- choice/endchoice -- comment -- menu/endmenu -- if/endif -- source -The first five also start the definition of a menu entry. - -config: - - "config" - - -This defines a config symbol and accepts any of above -attributes as options. - -menuconfig: - "menuconfig" - - -This is similar to the simple config entry above, but it also gives a -hint to front ends, that all suboptions should be displayed as a -separate list of options. To make sure all the suboptions will really -show up under the menuconfig entry and not outside of it, every item -from the list must depend on the menuconfig symbol. -In practice, this is achieved by using one of the next two constructs: - -(1): -menuconfig M -if M - config C1 - config C2 -endif - -(2): -menuconfig M -config C1 - depends on M -config C2 - depends on M - -In the following examples (3) and (4), C1 and C2 still have the M -dependency, but will not appear under menuconfig M anymore, because -of C0, which doesn't depend on M: - -(3): -menuconfig M - config C0 -if M - config C1 - config C2 -endif - -(4): -menuconfig M -config C0 -config C1 - depends on M -config C2 - depends on M - -choices: - - "choice" [symbol] - - - "endchoice" - -This defines a choice group and accepts any of the above attributes as -options. A choice can only be of type bool or tristate. If no type is -specified for a choice, its type will be determined by the type of -the first choice element in the group or remain unknown if none of the -choice elements have a type specified, as well. - -While a boolean choice only allows a single config entry to be -selected, a tristate choice also allows any number of config entries -to be set to 'm'. This can be used if multiple drivers for a single -hardware exists and only a single driver can be compiled/loaded into -the kernel, but all drivers can be compiled as modules. - -A choice accepts another option "optional", which allows to set the -choice to 'n' and no entry needs to be selected. -If no [symbol] is associated with a choice, then you can not have multiple -definitions of that choice. If a [symbol] is associated to the choice, -then you may define the same choice (i.e. with the same entries) in another -place. - -comment: - - "comment" - - -This defines a comment which is displayed to the user during the -configuration process and is also echoed to the output files. The only -possible options are dependencies. - -menu: - - "menu" - - - "endmenu" - -This defines a menu block, see "Menu structure" above for more -information. The only possible options are dependencies and "visible" -attributes. - -if: - - "if" - - "endif" - -This defines an if block. The dependency expression is appended -to all enclosed menu entries. - -source: - - "source" - -This reads the specified configuration file. This file is always parsed. - -mainmenu: - - "mainmenu" - -This sets the config program's title bar if the config program chooses -to use it. It should be placed at the top of the configuration, before any -other statement. - -'#' Kconfig source file comment: - -An unquoted '#' character anywhere in a source file line indicates -the beginning of a source file comment. The remainder of that line -is a comment. - - -Kconfig hints -------------- -This is a collection of Kconfig tips, most of which aren't obvious at -first glance and most of which have become idioms in several Kconfig -files. - -Adding common features and make the usage configurable -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -It is a common idiom to implement a feature/functionality that are -relevant for some architectures but not all. -The recommended way to do so is to use a config variable named HAVE_* -that is defined in a common Kconfig file and selected by the relevant -architectures. -An example is the generic IOMAP functionality. - -We would in lib/Kconfig see: - -# Generic IOMAP is used to ... -config HAVE_GENERIC_IOMAP - -config GENERIC_IOMAP - depends on HAVE_GENERIC_IOMAP && FOO - -And in lib/Makefile we would see: -obj-$(CONFIG_GENERIC_IOMAP) += iomap.o - -For each architecture using the generic IOMAP functionality we would see: - -config X86 - select ... - select HAVE_GENERIC_IOMAP - select ... - -Note: we use the existing config option and avoid creating a new -config variable to select HAVE_GENERIC_IOMAP. - -Note: the use of the internal config variable HAVE_GENERIC_IOMAP, it is -introduced to overcome the limitation of select which will force a -config option to 'y' no matter the dependencies. -The dependencies are moved to the symbol GENERIC_IOMAP and we avoid the -situation where select forces a symbol equals to 'y'. - -Adding features that need compiler support -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -There are several features that need compiler support. The recommended way -to describe the dependency on the compiler feature is to use "depends on" -followed by a test macro. - -config STACKPROTECTOR - bool "Stack Protector buffer overflow detection" - depends on $(cc-option,-fstack-protector) - ... - -If you need to expose a compiler capability to makefiles and/or C source files, -CC_HAS_ is the recommended prefix for the config option. - -config CC_HAS_STACKPROTECTOR_NONE - def_bool $(cc-option,-fno-stack-protector) - -Build as module only -~~~~~~~~~~~~~~~~~~~~ -To restrict a component build to module-only, qualify its config symbol -with "depends on m". E.g.: - -config FOO - depends on BAR && m - -limits FOO to module (=m) or disabled (=n). - -Kconfig recursive dependency limitations -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you've hit the Kconfig error: "recursive dependency detected" you've run -into a recursive dependency issue with Kconfig, a recursive dependency can be -summarized as a circular dependency. The kconfig tools need to ensure that -Kconfig files comply with specified configuration requirements. In order to do -that kconfig must determine the values that are possible for all Kconfig -symbols, this is currently not possible if there is a circular relation -between two or more Kconfig symbols. For more details refer to the "Simple -Kconfig recursive issue" subsection below. Kconfig does not do recursive -dependency resolution; this has a few implications for Kconfig file writers. -We'll first explain why this issues exists and then provide an example -technical limitation which this brings upon Kconfig developers. Eager -developers wishing to try to address this limitation should read the next -subsections. - -Simple Kconfig recursive issue -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Read: Documentation/kbuild/Kconfig.recursion-issue-01 - -Test with: - -make KBUILD_KCONFIG=Documentation/kbuild/Kconfig.recursion-issue-01 allnoconfig - -Cumulative Kconfig recursive issue -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Read: Documentation/kbuild/Kconfig.recursion-issue-02 - -Test with: - -make KBUILD_KCONFIG=Documentation/kbuild/Kconfig.recursion-issue-02 allnoconfig - -Practical solutions to kconfig recursive issue -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Developers who run into the recursive Kconfig issue have two options -at their disposal. We document them below and also provide a list of -historical issues resolved through these different solutions. - - a) Remove any superfluous "select FOO" or "depends on FOO" - b) Match dependency semantics: - b1) Swap all "select FOO" to "depends on FOO" or, - b2) Swap all "depends on FOO" to "select FOO" - -The resolution to a) can be tested with the sample Kconfig file -Documentation/kbuild/Kconfig.recursion-issue-01 through the removal -of the "select CORE" from CORE_BELL_A_ADVANCED as that is implicit already -since CORE_BELL_A depends on CORE. At times it may not be possible to remove -some dependency criteria, for such cases you can work with solution b). - -The two different resolutions for b) can be tested in the sample Kconfig file -Documentation/kbuild/Kconfig.recursion-issue-02. - -Below is a list of examples of prior fixes for these types of recursive issues; -all errors appear to involve one or more select's and one or more "depends on". - -commit fix -====== === -06b718c01208 select A -> depends on A -c22eacfe82f9 depends on A -> depends on B -6a91e854442c select A -> depends on A -118c565a8f2e select A -> select B -f004e5594705 select A -> depends on A -c7861f37b4c6 depends on A -> (null) -80c69915e5fb select A -> (null) (1) -c2218e26c0d0 select A -> depends on A (1) -d6ae99d04e1c select A -> depends on A -95ca19cf8cbf select A -> depends on A -8f057d7bca54 depends on A -> (null) -8f057d7bca54 depends on A -> select A -a0701f04846e select A -> depends on A -0c8b92f7f259 depends on A -> (null) -e4e9e0540928 select A -> depends on A (2) -7453ea886e87 depends on A > (null) (1) -7b1fff7e4fdf select A -> depends on A -86c747d2a4f0 select A -> depends on A -d9f9ab51e55e select A -> depends on A -0c51a4d8abd6 depends on A -> select A (3) -e98062ed6dc4 select A -> depends on A (3) -91e5d284a7f1 select A -> (null) - -(1) Partial (or no) quote of error. -(2) That seems to be the gist of that fix. -(3) Same error. - -Future kconfig work -~~~~~~~~~~~~~~~~~~~ - -Work on kconfig is welcomed on both areas of clarifying semantics and on -evaluating the use of a full SAT solver for it. A full SAT solver can be -desirable to enable more complex dependency mappings and / or queries, -for instance on possible use case for a SAT solver could be that of handling -the current known recursive dependency issues. It is not known if this would -address such issues but such evaluation is desirable. If support for a full SAT -solver proves too complex or that it cannot address recursive dependency issues -Kconfig should have at least clear and well defined semantics which also -addresses and documents limitations or requirements such as the ones dealing -with recursive dependencies. - -Further work on both of these areas is welcomed on Kconfig. We elaborate -on both of these in the next two subsections. - -Semantics of Kconfig -~~~~~~~~~~~~~~~~~~~~ - -The use of Kconfig is broad, Linux is now only one of Kconfig's users: -one study has completed a broad analysis of Kconfig use in 12 projects [0]. -Despite its widespread use, and although this document does a reasonable job -in documenting basic Kconfig syntax a more precise definition of Kconfig -semantics is welcomed. One project deduced Kconfig semantics through -the use of the xconfig configurator [1]. Work should be done to confirm if -the deduced semantics matches our intended Kconfig design goals. - -Having well defined semantics can be useful for tools for practical -evaluation of depenencies, for instance one such use known case was work to -express in boolean abstraction of the inferred semantics of Kconfig to -translate Kconfig logic into boolean formulas and run a SAT solver on this to -find dead code / features (always inactive), 114 dead features were found in -Linux using this methodology [1] (Section 8: Threats to validity). - -Confirming this could prove useful as Kconfig stands as one of the the leading -industrial variability modeling languages [1] [2]. Its study would help -evaluate practical uses of such languages, their use was only theoretical -and real world requirements were not well understood. As it stands though -only reverse engineering techniques have been used to deduce semantics from -variability modeling languages such as Kconfig [3]. - -[0] http://www.eng.uwaterloo.ca/~shshe/kconfig_semantics.pdf -[1] http://gsd.uwaterloo.ca/sites/default/files/vm-2013-berger.pdf -[2] http://gsd.uwaterloo.ca/sites/default/files/ase241-berger_0.pdf -[3] http://gsd.uwaterloo.ca/sites/default/files/icse2011.pdf - -Full SAT solver for Kconfig -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Although SAT solvers [0] haven't yet been used by Kconfig directly, as noted in -the previous subsection, work has been done however to express in boolean -abstraction the inferred semantics of Kconfig to translate Kconfig logic into -boolean formulas and run a SAT solver on it [1]. Another known related project -is CADOS [2] (former VAMOS [3]) and the tools, mainly undertaker [4], which has -been introduced first with [5]. The basic concept of undertaker is to exract -variability models from Kconfig, and put them together with a propositional -formula extracted from CPP #ifdefs and build-rules into a SAT solver in order -to find dead code, dead files, and dead symbols. If using a SAT solver is -desirable on Kconfig one approach would be to evaluate repurposing such efforts -somehow on Kconfig. There is enough interest from mentors of existing projects -to not only help advise how to integrate this work upstream but also help -maintain it long term. Interested developers should visit: - -http://kernelnewbies.org/KernelProjects/kconfig-sat - -[0] http://www.cs.cornell.edu/~sabhar/chapters/SATSolvers-KR-Handbook.pdf -[1] http://gsd.uwaterloo.ca/sites/default/files/vm-2013-berger.pdf -[2] https://cados.cs.fau.de -[3] https://vamos.cs.fau.de -[4] https://undertaker.cs.fau.de -[5] https://www4.cs.fau.de/Publications/2011/tartler_11_eurosys.pdf diff --git a/Documentation/kbuild/kconfig-macro-language.rst b/Documentation/kbuild/kconfig-macro-language.rst new file mode 100644 index 000000000000..35b3263b7e40 --- /dev/null +++ b/Documentation/kbuild/kconfig-macro-language.rst @@ -0,0 +1,247 @@ +====================== +Kconfig macro language +====================== + +Concept +------- + +The basic idea was inspired by Make. When we look at Make, we notice sort of +two languages in one. One language describes dependency graphs consisting of +targets and prerequisites. The other is a macro language for performing textual +substitution. + +There is clear distinction between the two language stages. For example, you +can write a makefile like follows:: + + APP := foo + SRC := foo.c + CC := gcc + + $(APP): $(SRC) + $(CC) -o $(APP) $(SRC) + +The macro language replaces the variable references with their expanded form, +and handles as if the source file were input like follows:: + + foo: foo.c + gcc -o foo foo.c + +Then, Make analyzes the dependency graph and determines the targets to be +updated. + +The idea is quite similar in Kconfig - it is possible to describe a Kconfig +file like this:: + + CC := gcc + + config CC_HAS_FOO + def_bool $(shell, $(srctree)/scripts/gcc-check-foo.sh $(CC)) + +The macro language in Kconfig processes the source file into the following +intermediate:: + + config CC_HAS_FOO + def_bool y + +Then, Kconfig moves onto the evaluation stage to resolve inter-symbol +dependency as explained in kconfig-language.txt. + + +Variables +--------- + +Like in Make, a variable in Kconfig works as a macro variable. A macro +variable is expanded "in place" to yield a text string that may then be +expanded further. To get the value of a variable, enclose the variable name in +$( ). The parentheses are required even for single-letter variable names; $X is +a syntax error. The curly brace form as in ${CC} is not supported either. + +There are two types of variables: simply expanded variables and recursively +expanded variables. + +A simply expanded variable is defined using the := assignment operator. Its +righthand side is expanded immediately upon reading the line from the Kconfig +file. + +A recursively expanded variable is defined using the = assignment operator. +Its righthand side is simply stored as the value of the variable without +expanding it in any way. Instead, the expansion is performed when the variable +is used. + +There is another type of assignment operator; += is used to append text to a +variable. The righthand side of += is expanded immediately if the lefthand +side was originally defined as a simple variable. Otherwise, its evaluation is +deferred. + +The variable reference can take parameters, in the following form:: + + $(name,arg1,arg2,arg3) + +You can consider the parameterized reference as a function. (more precisely, +"user-defined function" in contrast to "built-in function" listed below). + +Useful functions must be expanded when they are used since the same function is +expanded differently if different parameters are passed. Hence, a user-defined +function is defined using the = assignment operator. The parameters are +referenced within the body definition with $(1), $(2), etc. + +In fact, recursively expanded variables and user-defined functions are the same +internally. (In other words, "variable" is "function with zero argument".) +When we say "variable" in a broad sense, it includes "user-defined function". + + +Built-in functions +------------------ + +Like Make, Kconfig provides several built-in functions. Every function takes a +particular number of arguments. + +In Make, every built-in function takes at least one argument. Kconfig allows +zero argument for built-in functions, such as $(fileno), $(lineno). You could +consider those as "built-in variable", but it is just a matter of how we call +it after all. Let's say "built-in function" here to refer to natively supported +functionality. + +Kconfig currently supports the following built-in functions. + + - $(shell,command) + + The "shell" function accepts a single argument that is expanded and passed + to a subshell for execution. The standard output of the command is then read + and returned as the value of the function. Every newline in the output is + replaced with a space. Any trailing newlines are deleted. The standard error + is not returned, nor is any program exit status. + + - $(info,text) + + The "info" function takes a single argument and prints it to stdout. + It evaluates to an empty string. + + - $(warning-if,condition,text) + + The "warning-if" function takes two arguments. If the condition part is "y", + the text part is sent to stderr. The text is prefixed with the name of the + current Kconfig file and the current line number. + + - $(error-if,condition,text) + + The "error-if" function is similar to "warning-if", but it terminates the + parsing immediately if the condition part is "y". + + - $(filename) + + The 'filename' takes no argument, and $(filename) is expanded to the file + name being parsed. + + - $(lineno) + + The 'lineno' takes no argument, and $(lineno) is expanded to the line number + being parsed. + + +Make vs Kconfig +--------------- + +Kconfig adopts Make-like macro language, but the function call syntax is +slightly different. + +A function call in Make looks like this:: + + $(func-name arg1,arg2,arg3) + +The function name and the first argument are separated by at least one +whitespace. Then, leading whitespaces are trimmed from the first argument, +while whitespaces in the other arguments are kept. You need to use a kind of +trick to start the first parameter with spaces. For example, if you want +to make "info" function print " hello", you can write like follows:: + + empty := + space := $(empty) $(empty) + $(info $(space)$(space)hello) + +Kconfig uses only commas for delimiters, and keeps all whitespaces in the +function call. Some people prefer putting a space after each comma delimiter:: + + $(func-name, arg1, arg2, arg3) + +In this case, "func-name" will receive " arg1", " arg2", " arg3". The presence +of leading spaces may matter depending on the function. The same applies to +Make - for example, $(subst .c, .o, $(sources)) is a typical mistake; it +replaces ".c" with " .o". + +In Make, a user-defined function is referenced by using a built-in function, +'call', like this:: + + $(call my-func,arg1,arg2,arg3) + +Kconfig invokes user-defined functions and built-in functions in the same way. +The omission of 'call' makes the syntax shorter. + +In Make, some functions treat commas verbatim instead of argument separators. +For example, $(shell echo hello, world) runs the command "echo hello, world". +Likewise, $(info hello, world) prints "hello, world" to stdout. You could say +this is _useful_ inconsistency. + +In Kconfig, for simpler implementation and grammatical consistency, commas that +appear in the $( ) context are always delimiters. It means:: + + $(shell, echo hello, world) + +is an error because it is passing two parameters where the 'shell' function +accepts only one. To pass commas in arguments, you can use the following trick:: + + comma := , + $(shell, echo hello$(comma) world) + + +Caveats +------- + +A variable (or function) cannot be expanded across tokens. So, you cannot use +a variable as a shorthand for an expression that consists of multiple tokens. +The following works:: + + RANGE_MIN := 1 + RANGE_MAX := 3 + + config FOO + int "foo" + range $(RANGE_MIN) $(RANGE_MAX) + +But, the following does not work:: + + RANGES := 1 3 + + config FOO + int "foo" + range $(RANGES) + +A variable cannot be expanded to any keyword in Kconfig. The following does +not work:: + + MY_TYPE := tristate + + config FOO + $(MY_TYPE) "foo" + default y + +Obviously from the design, $(shell command) is expanded in the textual +substitution phase. You cannot pass symbols to the 'shell' function. + +The following does not work as expected:: + + config ENDIAN_FLAG + string + default "-mbig-endian" if CPU_BIG_ENDIAN + default "-mlittle-endian" if CPU_LITTLE_ENDIAN + + config CC_HAS_ENDIAN_FLAG + def_bool $(shell $(srctree)/scripts/gcc-check-flag ENDIAN_FLAG) + +Instead, you can do like follows so that any function call is statically +expanded:: + + config CC_HAS_ENDIAN_FLAG + bool + default $(shell $(srctree)/scripts/gcc-check-flag -mbig-endian) if CPU_BIG_ENDIAN + default $(shell $(srctree)/scripts/gcc-check-flag -mlittle-endian) if CPU_LITTLE_ENDIAN diff --git a/Documentation/kbuild/kconfig-macro-language.txt b/Documentation/kbuild/kconfig-macro-language.txt deleted file mode 100644 index 07da2ea68dce..000000000000 --- a/Documentation/kbuild/kconfig-macro-language.txt +++ /dev/null @@ -1,242 +0,0 @@ -Concept -------- - -The basic idea was inspired by Make. When we look at Make, we notice sort of -two languages in one. One language describes dependency graphs consisting of -targets and prerequisites. The other is a macro language for performing textual -substitution. - -There is clear distinction between the two language stages. For example, you -can write a makefile like follows: - - APP := foo - SRC := foo.c - CC := gcc - - $(APP): $(SRC) - $(CC) -o $(APP) $(SRC) - -The macro language replaces the variable references with their expanded form, -and handles as if the source file were input like follows: - - foo: foo.c - gcc -o foo foo.c - -Then, Make analyzes the dependency graph and determines the targets to be -updated. - -The idea is quite similar in Kconfig - it is possible to describe a Kconfig -file like this: - - CC := gcc - - config CC_HAS_FOO - def_bool $(shell, $(srctree)/scripts/gcc-check-foo.sh $(CC)) - -The macro language in Kconfig processes the source file into the following -intermediate: - - config CC_HAS_FOO - def_bool y - -Then, Kconfig moves onto the evaluation stage to resolve inter-symbol -dependency as explained in kconfig-language.txt. - - -Variables ---------- - -Like in Make, a variable in Kconfig works as a macro variable. A macro -variable is expanded "in place" to yield a text string that may then be -expanded further. To get the value of a variable, enclose the variable name in -$( ). The parentheses are required even for single-letter variable names; $X is -a syntax error. The curly brace form as in ${CC} is not supported either. - -There are two types of variables: simply expanded variables and recursively -expanded variables. - -A simply expanded variable is defined using the := assignment operator. Its -righthand side is expanded immediately upon reading the line from the Kconfig -file. - -A recursively expanded variable is defined using the = assignment operator. -Its righthand side is simply stored as the value of the variable without -expanding it in any way. Instead, the expansion is performed when the variable -is used. - -There is another type of assignment operator; += is used to append text to a -variable. The righthand side of += is expanded immediately if the lefthand -side was originally defined as a simple variable. Otherwise, its evaluation is -deferred. - -The variable reference can take parameters, in the following form: - - $(name,arg1,arg2,arg3) - -You can consider the parameterized reference as a function. (more precisely, -"user-defined function" in contrast to "built-in function" listed below). - -Useful functions must be expanded when they are used since the same function is -expanded differently if different parameters are passed. Hence, a user-defined -function is defined using the = assignment operator. The parameters are -referenced within the body definition with $(1), $(2), etc. - -In fact, recursively expanded variables and user-defined functions are the same -internally. (In other words, "variable" is "function with zero argument".) -When we say "variable" in a broad sense, it includes "user-defined function". - - -Built-in functions ------------------- - -Like Make, Kconfig provides several built-in functions. Every function takes a -particular number of arguments. - -In Make, every built-in function takes at least one argument. Kconfig allows -zero argument for built-in functions, such as $(fileno), $(lineno). You could -consider those as "built-in variable", but it is just a matter of how we call -it after all. Let's say "built-in function" here to refer to natively supported -functionality. - -Kconfig currently supports the following built-in functions. - - - $(shell,command) - - The "shell" function accepts a single argument that is expanded and passed - to a subshell for execution. The standard output of the command is then read - and returned as the value of the function. Every newline in the output is - replaced with a space. Any trailing newlines are deleted. The standard error - is not returned, nor is any program exit status. - - - $(info,text) - - The "info" function takes a single argument and prints it to stdout. - It evaluates to an empty string. - - - $(warning-if,condition,text) - - The "warning-if" function takes two arguments. If the condition part is "y", - the text part is sent to stderr. The text is prefixed with the name of the - current Kconfig file and the current line number. - - - $(error-if,condition,text) - - The "error-if" function is similar to "warning-if", but it terminates the - parsing immediately if the condition part is "y". - - - $(filename) - - The 'filename' takes no argument, and $(filename) is expanded to the file - name being parsed. - - - $(lineno) - - The 'lineno' takes no argument, and $(lineno) is expanded to the line number - being parsed. - - -Make vs Kconfig ---------------- - -Kconfig adopts Make-like macro language, but the function call syntax is -slightly different. - -A function call in Make looks like this: - - $(func-name arg1,arg2,arg3) - -The function name and the first argument are separated by at least one -whitespace. Then, leading whitespaces are trimmed from the first argument, -while whitespaces in the other arguments are kept. You need to use a kind of -trick to start the first parameter with spaces. For example, if you want -to make "info" function print " hello", you can write like follows: - - empty := - space := $(empty) $(empty) - $(info $(space)$(space)hello) - -Kconfig uses only commas for delimiters, and keeps all whitespaces in the -function call. Some people prefer putting a space after each comma delimiter: - - $(func-name, arg1, arg2, arg3) - -In this case, "func-name" will receive " arg1", " arg2", " arg3". The presence -of leading spaces may matter depending on the function. The same applies to -Make - for example, $(subst .c, .o, $(sources)) is a typical mistake; it -replaces ".c" with " .o". - -In Make, a user-defined function is referenced by using a built-in function, -'call', like this: - - $(call my-func,arg1,arg2,arg3) - -Kconfig invokes user-defined functions and built-in functions in the same way. -The omission of 'call' makes the syntax shorter. - -In Make, some functions treat commas verbatim instead of argument separators. -For example, $(shell echo hello, world) runs the command "echo hello, world". -Likewise, $(info hello, world) prints "hello, world" to stdout. You could say -this is _useful_ inconsistency. - -In Kconfig, for simpler implementation and grammatical consistency, commas that -appear in the $( ) context are always delimiters. It means - - $(shell, echo hello, world) - -is an error because it is passing two parameters where the 'shell' function -accepts only one. To pass commas in arguments, you can use the following trick: - - comma := , - $(shell, echo hello$(comma) world) - - -Caveats -------- - -A variable (or function) cannot be expanded across tokens. So, you cannot use -a variable as a shorthand for an expression that consists of multiple tokens. -The following works: - - RANGE_MIN := 1 - RANGE_MAX := 3 - - config FOO - int "foo" - range $(RANGE_MIN) $(RANGE_MAX) - -But, the following does not work: - - RANGES := 1 3 - - config FOO - int "foo" - range $(RANGES) - -A variable cannot be expanded to any keyword in Kconfig. The following does -not work: - - MY_TYPE := tristate - - config FOO - $(MY_TYPE) "foo" - default y - -Obviously from the design, $(shell command) is expanded in the textual -substitution phase. You cannot pass symbols to the 'shell' function. -The following does not work as expected. - - config ENDIAN_FLAG - string - default "-mbig-endian" if CPU_BIG_ENDIAN - default "-mlittle-endian" if CPU_LITTLE_ENDIAN - - config CC_HAS_ENDIAN_FLAG - def_bool $(shell $(srctree)/scripts/gcc-check-flag ENDIAN_FLAG) - -Instead, you can do like follows so that any function call is statically -expanded. - - config CC_HAS_ENDIAN_FLAG - bool - default $(shell $(srctree)/scripts/gcc-check-flag -mbig-endian) if CPU_BIG_ENDIAN - default $(shell $(srctree)/scripts/gcc-check-flag -mlittle-endian) if CPU_LITTLE_ENDIAN diff --git a/Documentation/kbuild/kconfig.rst b/Documentation/kbuild/kconfig.rst new file mode 100644 index 000000000000..88129af7e539 --- /dev/null +++ b/Documentation/kbuild/kconfig.rst @@ -0,0 +1,300 @@ +=================== +Kconfig make config +=================== + +This file contains some assistance for using `make *config`. + +Use "make help" to list all of the possible configuration targets. + +The xconfig ('qconf'), menuconfig ('mconf'), and nconfig ('nconf') +programs also have embedded help text. Be sure to check that for +navigation, search, and other general help text. + +General +------- + +New kernel releases often introduce new config symbols. Often more +important, new kernel releases may rename config symbols. When +this happens, using a previously working .config file and running +"make oldconfig" won't necessarily produce a working new kernel +for you, so you may find that you need to see what NEW kernel +symbols have been introduced. + +To see a list of new config symbols, use:: + + cp user/some/old.config .config + make listnewconfig + +and the config program will list any new symbols, one per line. + +Alternatively, you can use the brute force method:: + + make oldconfig + scripts/diffconfig .config.old .config | less + +---------------------------------------------------------------------- + +Environment variables for `*config` + +KCONFIG_CONFIG +-------------- +This environment variable can be used to specify a default kernel config +file name to override the default name of ".config". + +KCONFIG_OVERWRITECONFIG +----------------------- +If you set KCONFIG_OVERWRITECONFIG in the environment, Kconfig will not +break symlinks when .config is a symlink to somewhere else. + +`CONFIG_` +--------- +If you set `CONFIG_` in the environment, Kconfig will prefix all symbols +with its value when saving the configuration, instead of using the default, +`CONFIG_`. + +---------------------------------------------------------------------- + +Environment variables for '{allyes/allmod/allno/rand}config' + +KCONFIG_ALLCONFIG +----------------- +(partially based on lkml email from/by Rob Landley, re: miniconfig) + +-------------------------------------------------- + +The allyesconfig/allmodconfig/allnoconfig/randconfig variants can also +use the environment variable KCONFIG_ALLCONFIG as a flag or a filename +that contains config symbols that the user requires to be set to a +specific value. If KCONFIG_ALLCONFIG is used without a filename where +KCONFIG_ALLCONFIG == "" or KCONFIG_ALLCONFIG == "1", `make *config` +checks for a file named "all{yes/mod/no/def/random}.config" +(corresponding to the `*config` command that was used) for symbol values +that are to be forced. If this file is not found, it checks for a +file named "all.config" to contain forced values. + +This enables you to create "miniature" config (miniconfig) or custom +config files containing just the config symbols that you are interested +in. Then the kernel config system generates the full .config file, +including symbols of your miniconfig file. + +This 'KCONFIG_ALLCONFIG' file is a config file which contains +(usually a subset of all) preset config symbols. These variable +settings are still subject to normal dependency checks. + +Examples:: + + KCONFIG_ALLCONFIG=custom-notebook.config make allnoconfig + +or:: + + KCONFIG_ALLCONFIG=mini.config make allnoconfig + +or:: + + make KCONFIG_ALLCONFIG=mini.config allnoconfig + +These examples will disable most options (allnoconfig) but enable or +disable the options that are explicitly listed in the specified +mini-config files. + +---------------------------------------------------------------------- + +Environment variables for 'randconfig' + +KCONFIG_SEED +------------ +You can set this to the integer value used to seed the RNG, if you want +to somehow debug the behaviour of the kconfig parser/frontends. +If not set, the current time will be used. + +KCONFIG_PROBABILITY +------------------- +This variable can be used to skew the probabilities. This variable can +be unset or empty, or set to three different formats: + + ======================= ================== ===================== + KCONFIG_PROBABILITY y:n split y:m:n split + ======================= ================== ===================== + unset or empty 50 : 50 33 : 33 : 34 + N N : 100-N N/2 : N/2 : 100-N + [1] N:M N+M : 100-(N+M) N : M : 100-(N+M) + [2] N:M:L N : 100-N M : L : 100-(M+L) + ======================= ================== ===================== + +where N, M and L are integers (in base 10) in the range [0,100], and so +that: + + [1] N+M is in the range [0,100] + + [2] M+L is in the range [0,100] + +Examples:: + + KCONFIG_PROBABILITY=10 + 10% of booleans will be set to 'y', 90% to 'n' + 5% of tristates will be set to 'y', 5% to 'm', 90% to 'n' + KCONFIG_PROBABILITY=15:25 + 40% of booleans will be set to 'y', 60% to 'n' + 15% of tristates will be set to 'y', 25% to 'm', 60% to 'n' + KCONFIG_PROBABILITY=10:15:15 + 10% of booleans will be set to 'y', 90% to 'n' + 15% of tristates will be set to 'y', 15% to 'm', 70% to 'n' + +---------------------------------------------------------------------- + +Environment variables for 'syncconfig' + +KCONFIG_NOSILENTUPDATE +---------------------- +If this variable has a non-blank value, it prevents silent kernel +config updates (requires explicit updates). + +KCONFIG_AUTOCONFIG +------------------ +This environment variable can be set to specify the path & name of the +"auto.conf" file. Its default value is "include/config/auto.conf". + +KCONFIG_TRISTATE +---------------- +This environment variable can be set to specify the path & name of the +"tristate.conf" file. Its default value is "include/config/tristate.conf". + +KCONFIG_AUTOHEADER +------------------ +This environment variable can be set to specify the path & name of the +"autoconf.h" (header) file. +Its default value is "include/generated/autoconf.h". + + +---------------------------------------------------------------------- + +menuconfig +---------- + +SEARCHING for CONFIG symbols + +Searching in menuconfig: + + The Search function searches for kernel configuration symbol + names, so you have to know something close to what you are + looking for. + + Example:: + + /hotplug + This lists all config symbols that contain "hotplug", + e.g., HOTPLUG_CPU, MEMORY_HOTPLUG. + + For search help, enter / followed by TAB-TAB (to highlight + ) and Enter. This will tell you that you can also use + regular expressions (regexes) in the search string, so if you + are not interested in MEMORY_HOTPLUG, you could try:: + + /^hotplug + + When searching, symbols are sorted thus: + + - first, exact matches, sorted alphabetically (an exact match + is when the search matches the complete symbol name); + - then, other matches, sorted alphabetically. + + For example: ^ATH.K matches: + + ATH5K ATH9K ATH5K_AHB ATH5K_DEBUG [...] ATH6KL ATH6KL_DEBUG + [...] ATH9K_AHB ATH9K_BTCOEX_SUPPORT ATH9K_COMMON [...] + + of which only ATH5K and ATH9K match exactly and so are sorted + first (and in alphabetical order), then come all other symbols, + sorted in alphabetical order. + +---------------------------------------------------------------------- + +User interface options for 'menuconfig' + +MENUCONFIG_COLOR +---------------- +It is possible to select different color themes using the variable +MENUCONFIG_COLOR. To select a theme use:: + + make MENUCONFIG_COLOR= menuconfig + +Available themes are:: + + - mono => selects colors suitable for monochrome displays + - blackbg => selects a color scheme with black background + - classic => theme with blue background. The classic look + - bluetitle => a LCD friendly version of classic. (default) + +MENUCONFIG_MODE +--------------- +This mode shows all sub-menus in one large tree. + +Example:: + + make MENUCONFIG_MODE=single_menu menuconfig + +---------------------------------------------------------------------- + +nconfig +------- + +nconfig is an alternate text-based configurator. It lists function +keys across the bottom of the terminal (window) that execute commands. +You can also just use the corresponding numeric key to execute the +commands unless you are in a data entry window. E.g., instead of F6 +for Save, you can just press 6. + +Use F1 for Global help or F3 for the Short help menu. + +Searching in nconfig: + + You can search either in the menu entry "prompt" strings + or in the configuration symbols. + + Use / to begin a search through the menu entries. This does + not support regular expressions. Use or for + Next hit and Previous hit, respectively. Use to + terminate the search mode. + + F8 (SymSearch) searches the configuration symbols for the + given string or regular expression (regex). + +NCONFIG_MODE +------------ +This mode shows all sub-menus in one large tree. + +Example:: + make NCONFIG_MODE=single_menu nconfig + +---------------------------------------------------------------------- + +xconfig +------- + +Searching in xconfig: + + The Search function searches for kernel configuration symbol + names, so you have to know something close to what you are + looking for. + + Example: + Ctrl-F hotplug + or + Menu: File, Search, hotplug + + lists all config symbol entries that contain "hotplug" in + the symbol name. In this Search dialog, you may change the + config setting for any of the entries that are not grayed out. + You can also enter a different search string without having + to return to the main menu. + + +---------------------------------------------------------------------- + +gconfig +------- + +Searching in gconfig: + + There is no search command in gconfig. However, gconfig does + have several different viewing choices, modes, and options. diff --git a/Documentation/kbuild/kconfig.txt b/Documentation/kbuild/kconfig.txt deleted file mode 100644 index 68c82914c0f3..000000000000 --- a/Documentation/kbuild/kconfig.txt +++ /dev/null @@ -1,272 +0,0 @@ -This file contains some assistance for using "make *config". - -Use "make help" to list all of the possible configuration targets. - -The xconfig ('qconf'), menuconfig ('mconf'), and nconfig ('nconf') -programs also have embedded help text. Be sure to check that for -navigation, search, and other general help text. - -====================================================================== -General --------------------------------------------------- - -New kernel releases often introduce new config symbols. Often more -important, new kernel releases may rename config symbols. When -this happens, using a previously working .config file and running -"make oldconfig" won't necessarily produce a working new kernel -for you, so you may find that you need to see what NEW kernel -symbols have been introduced. - -To see a list of new config symbols, use - - cp user/some/old.config .config - make listnewconfig - -and the config program will list any new symbols, one per line. - -Alternatively, you can use the brute force method: - - make oldconfig - scripts/diffconfig .config.old .config | less - -______________________________________________________________________ -Environment variables for '*config' - -KCONFIG_CONFIG --------------------------------------------------- -This environment variable can be used to specify a default kernel config -file name to override the default name of ".config". - -KCONFIG_OVERWRITECONFIG --------------------------------------------------- -If you set KCONFIG_OVERWRITECONFIG in the environment, Kconfig will not -break symlinks when .config is a symlink to somewhere else. - -CONFIG_ --------------------------------------------------- -If you set CONFIG_ in the environment, Kconfig will prefix all symbols -with its value when saving the configuration, instead of using the default, -"CONFIG_". - -______________________________________________________________________ -Environment variables for '{allyes/allmod/allno/rand}config' - -KCONFIG_ALLCONFIG --------------------------------------------------- -(partially based on lkml email from/by Rob Landley, re: miniconfig) --------------------------------------------------- -The allyesconfig/allmodconfig/allnoconfig/randconfig variants can also -use the environment variable KCONFIG_ALLCONFIG as a flag or a filename -that contains config symbols that the user requires to be set to a -specific value. If KCONFIG_ALLCONFIG is used without a filename where -KCONFIG_ALLCONFIG == "" or KCONFIG_ALLCONFIG == "1", "make *config" -checks for a file named "all{yes/mod/no/def/random}.config" -(corresponding to the *config command that was used) for symbol values -that are to be forced. If this file is not found, it checks for a -file named "all.config" to contain forced values. - -This enables you to create "miniature" config (miniconfig) or custom -config files containing just the config symbols that you are interested -in. Then the kernel config system generates the full .config file, -including symbols of your miniconfig file. - -This 'KCONFIG_ALLCONFIG' file is a config file which contains -(usually a subset of all) preset config symbols. These variable -settings are still subject to normal dependency checks. - -Examples: - KCONFIG_ALLCONFIG=custom-notebook.config make allnoconfig -or - KCONFIG_ALLCONFIG=mini.config make allnoconfig -or - make KCONFIG_ALLCONFIG=mini.config allnoconfig - -These examples will disable most options (allnoconfig) but enable or -disable the options that are explicitly listed in the specified -mini-config files. - -______________________________________________________________________ -Environment variables for 'randconfig' - -KCONFIG_SEED --------------------------------------------------- -You can set this to the integer value used to seed the RNG, if you want -to somehow debug the behaviour of the kconfig parser/frontends. -If not set, the current time will be used. - -KCONFIG_PROBABILITY --------------------------------------------------- -This variable can be used to skew the probabilities. This variable can -be unset or empty, or set to three different formats: - KCONFIG_PROBABILITY y:n split y:m:n split - ----------------------------------------------------------------- - unset or empty 50 : 50 33 : 33 : 34 - N N : 100-N N/2 : N/2 : 100-N - [1] N:M N+M : 100-(N+M) N : M : 100-(N+M) - [2] N:M:L N : 100-N M : L : 100-(M+L) - -where N, M and L are integers (in base 10) in the range [0,100], and so -that: - [1] N+M is in the range [0,100] - [2] M+L is in the range [0,100] - -Examples: - KCONFIG_PROBABILITY=10 - 10% of booleans will be set to 'y', 90% to 'n' - 5% of tristates will be set to 'y', 5% to 'm', 90% to 'n' - KCONFIG_PROBABILITY=15:25 - 40% of booleans will be set to 'y', 60% to 'n' - 15% of tristates will be set to 'y', 25% to 'm', 60% to 'n' - KCONFIG_PROBABILITY=10:15:15 - 10% of booleans will be set to 'y', 90% to 'n' - 15% of tristates will be set to 'y', 15% to 'm', 70% to 'n' - -______________________________________________________________________ -Environment variables for 'syncconfig' - -KCONFIG_NOSILENTUPDATE --------------------------------------------------- -If this variable has a non-blank value, it prevents silent kernel -config updates (requires explicit updates). - -KCONFIG_AUTOCONFIG --------------------------------------------------- -This environment variable can be set to specify the path & name of the -"auto.conf" file. Its default value is "include/config/auto.conf". - -KCONFIG_TRISTATE --------------------------------------------------- -This environment variable can be set to specify the path & name of the -"tristate.conf" file. Its default value is "include/config/tristate.conf". - -KCONFIG_AUTOHEADER --------------------------------------------------- -This environment variable can be set to specify the path & name of the -"autoconf.h" (header) file. -Its default value is "include/generated/autoconf.h". - - -====================================================================== -menuconfig --------------------------------------------------- - -SEARCHING for CONFIG symbols - -Searching in menuconfig: - - The Search function searches for kernel configuration symbol - names, so you have to know something close to what you are - looking for. - - Example: - /hotplug - This lists all config symbols that contain "hotplug", - e.g., HOTPLUG_CPU, MEMORY_HOTPLUG. - - For search help, enter / followed by TAB-TAB (to highlight - ) and Enter. This will tell you that you can also use - regular expressions (regexes) in the search string, so if you - are not interested in MEMORY_HOTPLUG, you could try - - /^hotplug - - When searching, symbols are sorted thus: - - first, exact matches, sorted alphabetically (an exact match - is when the search matches the complete symbol name); - - then, other matches, sorted alphabetically. - For example: ^ATH.K matches: - ATH5K ATH9K ATH5K_AHB ATH5K_DEBUG [...] ATH6KL ATH6KL_DEBUG - [...] ATH9K_AHB ATH9K_BTCOEX_SUPPORT ATH9K_COMMON [...] - of which only ATH5K and ATH9K match exactly and so are sorted - first (and in alphabetical order), then come all other symbols, - sorted in alphabetical order. - -______________________________________________________________________ -User interface options for 'menuconfig' - -MENUCONFIG_COLOR --------------------------------------------------- -It is possible to select different color themes using the variable -MENUCONFIG_COLOR. To select a theme use: - - make MENUCONFIG_COLOR= menuconfig - -Available themes are: - mono => selects colors suitable for monochrome displays - blackbg => selects a color scheme with black background - classic => theme with blue background. The classic look - bluetitle => a LCD friendly version of classic. (default) - -MENUCONFIG_MODE --------------------------------------------------- -This mode shows all sub-menus in one large tree. - -Example: - make MENUCONFIG_MODE=single_menu menuconfig - - -====================================================================== -nconfig --------------------------------------------------- - -nconfig is an alternate text-based configurator. It lists function -keys across the bottom of the terminal (window) that execute commands. -You can also just use the corresponding numeric key to execute the -commands unless you are in a data entry window. E.g., instead of F6 -for Save, you can just press 6. - -Use F1 for Global help or F3 for the Short help menu. - -Searching in nconfig: - - You can search either in the menu entry "prompt" strings - or in the configuration symbols. - - Use / to begin a search through the menu entries. This does - not support regular expressions. Use or for - Next hit and Previous hit, respectively. Use to - terminate the search mode. - - F8 (SymSearch) searches the configuration symbols for the - given string or regular expression (regex). - -NCONFIG_MODE --------------------------------------------------- -This mode shows all sub-menus in one large tree. - -Example: - make NCONFIG_MODE=single_menu nconfig - - -====================================================================== -xconfig --------------------------------------------------- - -Searching in xconfig: - - The Search function searches for kernel configuration symbol - names, so you have to know something close to what you are - looking for. - - Example: - Ctrl-F hotplug - or - Menu: File, Search, hotplug - - lists all config symbol entries that contain "hotplug" in - the symbol name. In this Search dialog, you may change the - config setting for any of the entries that are not grayed out. - You can also enter a different search string without having - to return to the main menu. - - -====================================================================== -gconfig --------------------------------------------------- - -Searching in gconfig: - - There is no search command in gconfig. However, gconfig does - have several different viewing choices, modes, and options. - -### diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst new file mode 100644 index 000000000000..9274cdcc9bd2 --- /dev/null +++ b/Documentation/kbuild/makefiles.rst @@ -0,0 +1,1509 @@ +====================== +Linux Kernel Makefiles +====================== + +This document describes the Linux kernel Makefiles. + +.. Table of Contents + + === 1 Overview + === 2 Who does what + === 3 The kbuild files + --- 3.1 Goal definitions + --- 3.2 Built-in object goals - obj-y + --- 3.3 Loadable module goals - obj-m + --- 3.4 Objects which export symbols + --- 3.5 Library file goals - lib-y + --- 3.6 Descending down in directories + --- 3.7 Compilation flags + --- 3.8 Command line dependency + --- 3.9 Dependency tracking + --- 3.10 Special Rules + --- 3.11 $(CC) support functions + --- 3.12 $(LD) support functions + + === 4 Host Program support + --- 4.1 Simple Host Program + --- 4.2 Composite Host Programs + --- 4.3 Using C++ for host programs + --- 4.4 Controlling compiler options for host programs + --- 4.5 When host programs are actually built + --- 4.6 Using hostprogs-$(CONFIG_FOO) + + === 5 Kbuild clean infrastructure + + === 6 Architecture Makefiles + --- 6.1 Set variables to tweak the build to the architecture + --- 6.2 Add prerequisites to archheaders: + --- 6.3 Add prerequisites to archprepare: + --- 6.4 List directories to visit when descending + --- 6.5 Architecture-specific boot images + --- 6.6 Building non-kbuild targets + --- 6.7 Commands useful for building a boot image + --- 6.8 Custom kbuild commands + --- 6.9 Preprocessing linker scripts + --- 6.10 Generic header files + --- 6.11 Post-link pass + + === 7 Kbuild syntax for exported headers + --- 7.1 no-export-headers + --- 7.2 generic-y + --- 7.3 generated-y + --- 7.4 mandatory-y + + === 8 Kbuild Variables + === 9 Makefile language + === 10 Credits + === 11 TODO + +1 Overview +========== + +The Makefiles have five parts:: + + Makefile the top Makefile. + .config the kernel configuration file. + arch/$(ARCH)/Makefile the arch Makefile. + scripts/Makefile.* common rules etc. for all kbuild Makefiles. + kbuild Makefiles there are about 500 of these. + +The top Makefile reads the .config file, which comes from the kernel +configuration process. + +The top Makefile is responsible for building two major products: vmlinux +(the resident kernel image) and modules (any module files). +It builds these goals by recursively descending into the subdirectories of +the kernel source tree. +The list of subdirectories which are visited depends upon the kernel +configuration. The top Makefile textually includes an arch Makefile +with the name arch/$(ARCH)/Makefile. The arch Makefile supplies +architecture-specific information to the top Makefile. + +Each subdirectory has a kbuild Makefile which carries out the commands +passed down from above. The kbuild Makefile uses information from the +.config file to construct various file lists used by kbuild to build +any built-in or modular targets. + +scripts/Makefile.* contains all the definitions/rules etc. that +are used to build the kernel based on the kbuild makefiles. + + +2 Who does what +=============== + +People have four different relationships with the kernel Makefiles. + +*Users* are people who build kernels. These people type commands such as +"make menuconfig" or "make". They usually do not read or edit +any kernel Makefiles (or any other source files). + +*Normal developers* are people who work on features such as device +drivers, file systems, and network protocols. These people need to +maintain the kbuild Makefiles for the subsystem they are +working on. In order to do this effectively, they need some overall +knowledge about the kernel Makefiles, plus detailed knowledge about the +public interface for kbuild. + +*Arch developers* are people who work on an entire architecture, such +as sparc or ia64. Arch developers need to know about the arch Makefile +as well as kbuild Makefiles. + +*Kbuild developers* are people who work on the kernel build system itself. +These people need to know about all aspects of the kernel Makefiles. + +This document is aimed towards normal developers and arch developers. + + +3 The kbuild files +================== + +Most Makefiles within the kernel are kbuild Makefiles that use the +kbuild infrastructure. This chapter introduces the syntax used in the +kbuild makefiles. +The preferred name for the kbuild files are 'Makefile' but 'Kbuild' can +be used and if both a 'Makefile' and a 'Kbuild' file exists, then the 'Kbuild' +file will be used. + +Section 3.1 "Goal definitions" is a quick intro, further chapters provide +more details, with real examples. + +3.1 Goal definitions +-------------------- + + Goal definitions are the main part (heart) of the kbuild Makefile. + These lines define the files to be built, any special compilation + options, and any subdirectories to be entered recursively. + + The most simple kbuild makefile contains one line: + + Example:: + + obj-y += foo.o + + This tells kbuild that there is one object in that directory, named + foo.o. foo.o will be built from foo.c or foo.S. + + If foo.o shall be built as a module, the variable obj-m is used. + Therefore the following pattern is often used: + + Example:: + + obj-$(CONFIG_FOO) += foo.o + + $(CONFIG_FOO) evaluates to either y (for built-in) or m (for module). + If CONFIG_FOO is neither y nor m, then the file will not be compiled + nor linked. + +3.2 Built-in object goals - obj-y +--------------------------------- + + The kbuild Makefile specifies object files for vmlinux + in the $(obj-y) lists. These lists depend on the kernel + configuration. + + Kbuild compiles all the $(obj-y) files. It then calls + "$(AR) rcSTP" to merge these files into one built-in.a file. + This is a thin archive without a symbol table. It will be later + linked into vmlinux by scripts/link-vmlinux.sh + + The order of files in $(obj-y) is significant. Duplicates in + the lists are allowed: the first instance will be linked into + built-in.a and succeeding instances will be ignored. + + Link order is significant, because certain functions + (module_init() / __initcall) will be called during boot in the + order they appear. So keep in mind that changing the link + order may e.g. change the order in which your SCSI + controllers are detected, and thus your disks are renumbered. + + Example:: + + #drivers/isdn/i4l/Makefile + # Makefile for the kernel ISDN subsystem and device drivers. + # Each configuration option enables a list of files. + obj-$(CONFIG_ISDN_I4L) += isdn.o + obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o + +3.3 Loadable module goals - obj-m +--------------------------------- + + $(obj-m) specifies object files which are built as loadable + kernel modules. + + A module may be built from one source file or several source + files. In the case of one source file, the kbuild makefile + simply adds the file to $(obj-m). + + Example:: + + #drivers/isdn/i4l/Makefile + obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o + + Note: In this example $(CONFIG_ISDN_PPP_BSDCOMP) evaluates to 'm' + + If a kernel module is built from several source files, you specify + that you want to build a module in the same way as above; however, + kbuild needs to know which object files you want to build your + module from, so you have to tell it by setting a $(-y) + variable. + + Example:: + + #drivers/isdn/i4l/Makefile + obj-$(CONFIG_ISDN_I4L) += isdn.o + isdn-y := isdn_net_lib.o isdn_v110.o isdn_common.o + + In this example, the module name will be isdn.o. Kbuild will + compile the objects listed in $(isdn-y) and then run + "$(LD) -r" on the list of these files to generate isdn.o. + + Due to kbuild recognizing $(-y) for composite objects, + you can use the value of a `CONFIG_` symbol to optionally include an + object file as part of a composite object. + + Example:: + + #fs/ext2/Makefile + obj-$(CONFIG_EXT2_FS) += ext2.o + ext2-y := balloc.o dir.o file.o ialloc.o inode.o ioctl.o \ + namei.o super.o symlink.o + ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o xattr_user.o \ + xattr_trusted.o + + In this example, xattr.o, xattr_user.o and xattr_trusted.o are only + part of the composite object ext2.o if $(CONFIG_EXT2_FS_XATTR) + evaluates to 'y'. + + Note: Of course, when you are building objects into the kernel, + the syntax above will also work. So, if you have CONFIG_EXT2_FS=y, + kbuild will build an ext2.o file for you out of the individual + parts and then link this into built-in.a, as you would expect. + +3.4 Objects which export symbols +-------------------------------- + + No special notation is required in the makefiles for + modules exporting symbols. + +3.5 Library file goals - lib-y +------------------------------ + + Objects listed with obj-* are used for modules, or + combined in a built-in.a for that specific directory. + There is also the possibility to list objects that will + be included in a library, lib.a. + All objects listed with lib-y are combined in a single + library for that directory. + Objects that are listed in obj-y and additionally listed in + lib-y will not be included in the library, since they will + be accessible anyway. + For consistency, objects listed in lib-m will be included in lib.a. + + Note that the same kbuild makefile may list files to be built-in + and to be part of a library. Therefore the same directory + may contain both a built-in.a and a lib.a file. + + Example:: + + #arch/x86/lib/Makefile + lib-y := delay.o + + This will create a library lib.a based on delay.o. For kbuild to + actually recognize that there is a lib.a being built, the directory + shall be listed in libs-y. + + See also "6.4 List directories to visit when descending". + + Use of lib-y is normally restricted to `lib/` and `arch/*/lib`. + +3.6 Descending down in directories +---------------------------------- + + A Makefile is only responsible for building objects in its own + directory. Files in subdirectories should be taken care of by + Makefiles in these subdirs. The build system will automatically + invoke make recursively in subdirectories, provided you let it know of + them. + + To do so, obj-y and obj-m are used. + ext2 lives in a separate directory, and the Makefile present in fs/ + tells kbuild to descend down using the following assignment. + + Example:: + + #fs/Makefile + obj-$(CONFIG_EXT2_FS) += ext2/ + + If CONFIG_EXT2_FS is set to either 'y' (built-in) or 'm' (modular) + the corresponding obj- variable will be set, and kbuild will descend + down in the ext2 directory. + Kbuild only uses this information to decide that it needs to visit + the directory, it is the Makefile in the subdirectory that + specifies what is modular and what is built-in. + + It is good practice to use a `CONFIG_` variable when assigning directory + names. This allows kbuild to totally skip the directory if the + corresponding `CONFIG_` option is neither 'y' nor 'm'. + +3.7 Compilation flags +--------------------- + + ccflags-y, asflags-y and ldflags-y + These three flags apply only to the kbuild makefile in which they + are assigned. They are used for all the normal cc, as and ld + invocations happening during a recursive build. + Note: Flags with the same behaviour were previously named: + EXTRA_CFLAGS, EXTRA_AFLAGS and EXTRA_LDFLAGS. + They are still supported but their usage is deprecated. + + ccflags-y specifies options for compiling with $(CC). + + Example:: + + # drivers/acpi/acpica/Makefile + ccflags-y := -Os -D_LINUX -DBUILDING_ACPICA + ccflags-$(CONFIG_ACPI_DEBUG) += -DACPI_DEBUG_OUTPUT + + This variable is necessary because the top Makefile owns the + variable $(KBUILD_CFLAGS) and uses it for compilation flags for the + entire tree. + + asflags-y specifies options for assembling with $(AS). + + Example:: + + #arch/sparc/kernel/Makefile + asflags-y := -ansi + + ldflags-y specifies options for linking with $(LD). + + Example:: + + #arch/cris/boot/compressed/Makefile + ldflags-y += -T $(srctree)/$(src)/decompress_$(arch-y).lds + + subdir-ccflags-y, subdir-asflags-y + The two flags listed above are similar to ccflags-y and asflags-y. + The difference is that the subdir- variants have effect for the kbuild + file where they are present and all subdirectories. + Options specified using subdir-* are added to the commandline before + the options specified using the non-subdir variants. + + Example:: + + subdir-ccflags-y := -Werror + + CFLAGS_$@, AFLAGS_$@ + CFLAGS_$@ and AFLAGS_$@ only apply to commands in current + kbuild makefile. + + $(CFLAGS_$@) specifies per-file options for $(CC). The $@ + part has a literal value which specifies the file that it is for. + + Example:: + + # drivers/scsi/Makefile + CFLAGS_aha152x.o = -DAHA152X_STAT -DAUTOCONF + CFLAGS_gdth.o = # -DDEBUG_GDTH=2 -D__SERIAL__ -D__COM2__ \ + -DGDTH_STATISTICS + + These two lines specify compilation flags for aha152x.o and gdth.o. + + $(AFLAGS_$@) is a similar feature for source files in assembly + languages. + + Example:: + + # arch/arm/kernel/Makefile + AFLAGS_head.o := -DTEXT_OFFSET=$(TEXT_OFFSET) + AFLAGS_crunch-bits.o := -Wa,-mcpu=ep9312 + AFLAGS_iwmmxt.o := -Wa,-mcpu=iwmmxt + + +3.9 Dependency tracking +----------------------- + + Kbuild tracks dependencies on the following: + 1) All prerequisite files (both `*.c` and `*.h`) + 2) `CONFIG_` options used in all prerequisite files + 3) Command-line used to compile target + + Thus, if you change an option to $(CC) all affected files will + be re-compiled. + +3.10 Special Rules +------------------ + + Special rules are used when the kbuild infrastructure does + not provide the required support. A typical example is + header files generated during the build process. + Another example are the architecture-specific Makefiles which + need special rules to prepare boot images etc. + + Special rules are written as normal Make rules. + Kbuild is not executing in the directory where the Makefile is + located, so all special rules shall provide a relative + path to prerequisite files and target files. + + Two variables are used when defining special rules: + + $(src) + $(src) is a relative path which points to the directory + where the Makefile is located. Always use $(src) when + referring to files located in the src tree. + + $(obj) + $(obj) is a relative path which points to the directory + where the target is saved. Always use $(obj) when + referring to generated files. + + Example:: + + #drivers/scsi/Makefile + $(obj)/53c8xx_d.h: $(src)/53c7,8xx.scr $(src)/script_asm.pl + $(CPP) -DCHIP=810 - < $< | ... $(src)/script_asm.pl + + This is a special rule, following the normal syntax + required by make. + + The target file depends on two prerequisite files. References + to the target file are prefixed with $(obj), references + to prerequisites are referenced with $(src) (because they are not + generated files). + + $(kecho) + echoing information to user in a rule is often a good practice + but when execution "make -s" one does not expect to see any output + except for warnings/errors. + To support this kbuild defines $(kecho) which will echo out the + text following $(kecho) to stdout except if "make -s" is used. + + Example:: + + #arch/blackfin/boot/Makefile + $(obj)/vmImage: $(obj)/vmlinux.gz + $(call if_changed,uimage) + @$(kecho) 'Kernel: $@ is ready' + + +3.11 $(CC) support functions +---------------------------- + + The kernel may be built with several different versions of + $(CC), each supporting a unique set of features and options. + kbuild provides basic support to check for valid options for $(CC). + $(CC) is usually the gcc compiler, but other alternatives are + available. + + as-option + as-option is used to check if $(CC) -- when used to compile + assembler (`*.S`) files -- supports the given option. An optional + second option may be specified if the first option is not supported. + + Example:: + + #arch/sh/Makefile + cflags-y += $(call as-option,-Wa$(comma)-isa=$(isa-y),) + + In the above example, cflags-y will be assigned the option + -Wa$(comma)-isa=$(isa-y) if it is supported by $(CC). + The second argument is optional, and if supplied will be used + if first argument is not supported. + + cc-ldoption + cc-ldoption is used to check if $(CC) when used to link object files + supports the given option. An optional second option may be + specified if first option are not supported. + + Example:: + + #arch/x86/kernel/Makefile + vsyscall-flags += $(call cc-ldoption, -Wl$(comma)--hash-style=sysv) + + In the above example, vsyscall-flags will be assigned the option + -Wl$(comma)--hash-style=sysv if it is supported by $(CC). + The second argument is optional, and if supplied will be used + if first argument is not supported. + + as-instr + as-instr checks if the assembler reports a specific instruction + and then outputs either option1 or option2 + C escapes are supported in the test instruction + Note: as-instr-option uses KBUILD_AFLAGS for $(AS) options + + cc-option + cc-option is used to check if $(CC) supports a given option, and if + not supported to use an optional second option. + + Example:: + + #arch/x86/Makefile + cflags-y += $(call cc-option,-march=pentium-mmx,-march=i586) + + In the above example, cflags-y will be assigned the option + -march=pentium-mmx if supported by $(CC), otherwise -march=i586. + The second argument to cc-option is optional, and if omitted, + cflags-y will be assigned no value if first option is not supported. + Note: cc-option uses KBUILD_CFLAGS for $(CC) options + + cc-option-yn + cc-option-yn is used to check if gcc supports a given option + and return 'y' if supported, otherwise 'n'. + + Example:: + + #arch/ppc/Makefile + biarch := $(call cc-option-yn, -m32) + aflags-$(biarch) += -a32 + cflags-$(biarch) += -m32 + + In the above example, $(biarch) is set to y if $(CC) supports the -m32 + option. When $(biarch) equals 'y', the expanded variables $(aflags-y) + and $(cflags-y) will be assigned the values -a32 and -m32, + respectively. + Note: cc-option-yn uses KBUILD_CFLAGS for $(CC) options + + cc-disable-warning + cc-disable-warning checks if gcc supports a given warning and returns + the commandline switch to disable it. This special function is needed, + because gcc 4.4 and later accept any unknown -Wno-* option and only + warn about it if there is another warning in the source file. + + Example:: + + KBUILD_CFLAGS += $(call cc-disable-warning, unused-but-set-variable) + + In the above example, -Wno-unused-but-set-variable will be added to + KBUILD_CFLAGS only if gcc really accepts it. + + cc-ifversion + cc-ifversion tests the version of $(CC) and equals the fourth parameter + if version expression is true, or the fifth (if given) if the version + expression is false. + + Example:: + + #fs/reiserfs/Makefile + ccflags-y := $(call cc-ifversion, -lt, 0402, -O1) + + In this example, ccflags-y will be assigned the value -O1 if the + $(CC) version is less than 4.2. + cc-ifversion takes all the shell operators: + -eq, -ne, -lt, -le, -gt, and -ge + The third parameter may be a text as in this example, but it may also + be an expanded variable or a macro. + + cc-cross-prefix + cc-cross-prefix is used to check if there exists a $(CC) in path with + one of the listed prefixes. The first prefix where there exist a + prefix$(CC) in the PATH is returned - and if no prefix$(CC) is found + then nothing is returned. + Additional prefixes are separated by a single space in the + call of cc-cross-prefix. + This functionality is useful for architecture Makefiles that try + to set CROSS_COMPILE to well-known values but may have several + values to select between. + It is recommended only to try to set CROSS_COMPILE if it is a cross + build (host arch is different from target arch). And if CROSS_COMPILE + is already set then leave it with the old value. + + Example:: + + #arch/m68k/Makefile + ifneq ($(SUBARCH),$(ARCH)) + ifeq ($(CROSS_COMPILE),) + CROSS_COMPILE := $(call cc-cross-prefix, m68k-linux-gnu-) + endif + endif + +3.12 $(LD) support functions +---------------------------- + + ld-option + ld-option is used to check if $(LD) supports the supplied option. + ld-option takes two options as arguments. + The second argument is an optional option that can be used if the + first option is not supported by $(LD). + + Example:: + + #Makefile + LDFLAGS_vmlinux += $(call ld-option, -X) + + +4 Host Program support +====================== + +Kbuild supports building executables on the host for use during the +compilation stage. +Two steps are required in order to use a host executable. + +The first step is to tell kbuild that a host program exists. This is +done utilising the variable hostprogs-y. + +The second step is to add an explicit dependency to the executable. +This can be done in two ways. Either add the dependency in a rule, +or utilise the variable $(always). +Both possibilities are described in the following. + +4.1 Simple Host Program +----------------------- + + In some cases there is a need to compile and run a program on the + computer where the build is running. + The following line tells kbuild that the program bin2hex shall be + built on the build host. + + Example:: + + hostprogs-y := bin2hex + + Kbuild assumes in the above example that bin2hex is made from a single + c-source file named bin2hex.c located in the same directory as + the Makefile. + +4.2 Composite Host Programs +--------------------------- + + Host programs can be made up based on composite objects. + The syntax used to define composite objects for host programs is + similar to the syntax used for kernel objects. + $(-objs) lists all objects used to link the final + executable. + + Example:: + + #scripts/lxdialog/Makefile + hostprogs-y := lxdialog + lxdialog-objs := checklist.o lxdialog.o + + Objects with extension .o are compiled from the corresponding .c + files. In the above example, checklist.c is compiled to checklist.o + and lxdialog.c is compiled to lxdialog.o. + + Finally, the two .o files are linked to the executable, lxdialog. + Note: The syntax -y is not permitted for host-programs. + +4.3 Using C++ for host programs +------------------------------- + + kbuild offers support for host programs written in C++. This was + introduced solely to support kconfig, and is not recommended + for general use. + + Example:: + + #scripts/kconfig/Makefile + hostprogs-y := qconf + qconf-cxxobjs := qconf.o + + In the example above the executable is composed of the C++ file + qconf.cc - identified by $(qconf-cxxobjs). + + If qconf is composed of a mixture of .c and .cc files, then an + additional line can be used to identify this. + + Example:: + + #scripts/kconfig/Makefile + hostprogs-y := qconf + qconf-cxxobjs := qconf.o + qconf-objs := check.o + +4.4 Controlling compiler options for host programs +-------------------------------------------------- + + When compiling host programs, it is possible to set specific flags. + The programs will always be compiled utilising $(HOSTCC) passed + the options specified in $(KBUILD_HOSTCFLAGS). + To set flags that will take effect for all host programs created + in that Makefile, use the variable HOST_EXTRACFLAGS. + + Example:: + + #scripts/lxdialog/Makefile + HOST_EXTRACFLAGS += -I/usr/include/ncurses + + To set specific flags for a single file the following construction + is used: + + Example:: + + #arch/ppc64/boot/Makefile + HOSTCFLAGS_piggyback.o := -DKERNELBASE=$(KERNELBASE) + + It is also possible to specify additional options to the linker. + + Example:: + + #scripts/kconfig/Makefile + HOSTLDLIBS_qconf := -L$(QTDIR)/lib + + When linking qconf, it will be passed the extra option + "-L$(QTDIR)/lib". + +4.5 When host programs are actually built +----------------------------------------- + + Kbuild will only build host-programs when they are referenced + as a prerequisite. + This is possible in two ways: + + (1) List the prerequisite explicitly in a special rule. + + Example:: + + #drivers/pci/Makefile + hostprogs-y := gen-devlist + $(obj)/devlist.h: $(src)/pci.ids $(obj)/gen-devlist + ( cd $(obj); ./gen-devlist ) < $< + + The target $(obj)/devlist.h will not be built before + $(obj)/gen-devlist is updated. Note that references to + the host programs in special rules must be prefixed with $(obj). + + (2) Use $(always) + + When there is no suitable special rule, and the host program + shall be built when a makefile is entered, the $(always) + variable shall be used. + + Example:: + + #scripts/lxdialog/Makefile + hostprogs-y := lxdialog + always := $(hostprogs-y) + + This will tell kbuild to build lxdialog even if not referenced in + any rule. + +4.6 Using hostprogs-$(CONFIG_FOO) +--------------------------------- + + A typical pattern in a Kbuild file looks like this: + + Example:: + + #scripts/Makefile + hostprogs-$(CONFIG_KALLSYMS) += kallsyms + + Kbuild knows about both 'y' for built-in and 'm' for module. + So if a config symbol evaluates to 'm', kbuild will still build + the binary. In other words, Kbuild handles hostprogs-m exactly + like hostprogs-y. But only hostprogs-y is recommended to be used + when no CONFIG symbols are involved. + +5 Kbuild clean infrastructure +============================= + +"make clean" deletes most generated files in the obj tree where the kernel +is compiled. This includes generated files such as host programs. +Kbuild knows targets listed in $(hostprogs-y), $(hostprogs-m), $(always), +$(extra-y) and $(targets). They are all deleted during "make clean". +Files matching the patterns "*.[oas]", "*.ko", plus some additional files +generated by kbuild are deleted all over the kernel src tree when +"make clean" is executed. + +Additional files can be specified in kbuild makefiles by use of $(clean-files). + + Example:: + + #lib/Makefile + clean-files := crc32table.h + +When executing "make clean", the file "crc32table.h" will be deleted. +Kbuild will assume files to be in the same relative directory as the +Makefile, except if prefixed with $(objtree). + +To delete a directory hierarchy use: + + Example:: + + #scripts/package/Makefile + clean-dirs := $(objtree)/debian/ + +This will delete the directory debian in the toplevel directory, including all +subdirectories. + +To exclude certain files from make clean, use the $(no-clean-files) variable. +This is only a special case used in the top level Kbuild file: + + Example:: + + #Kbuild + no-clean-files := $(bounds-file) $(offsets-file) + +Usually kbuild descends down in subdirectories due to "obj-* := dir/", +but in the architecture makefiles where the kbuild infrastructure +is not sufficient this sometimes needs to be explicit. + + Example:: + + #arch/x86/boot/Makefile + subdir- := compressed/ + +The above assignment instructs kbuild to descend down in the +directory compressed/ when "make clean" is executed. + +To support the clean infrastructure in the Makefiles that build the +final bootimage there is an optional target named archclean: + + Example:: + + #arch/x86/Makefile + archclean: + $(Q)$(MAKE) $(clean)=arch/x86/boot + +When "make clean" is executed, make will descend down in arch/x86/boot, +and clean as usual. The Makefile located in arch/x86/boot/ may use +the subdir- trick to descend further down. + +Note 1: arch/$(ARCH)/Makefile cannot use "subdir-", because that file is +included in the top level makefile, and the kbuild infrastructure +is not operational at that point. + +Note 2: All directories listed in core-y, libs-y, drivers-y and net-y will +be visited during "make clean". + +6 Architecture Makefiles +======================== + +The top level Makefile sets up the environment and does the preparation, +before starting to descend down in the individual directories. +The top level makefile contains the generic part, whereas +arch/$(ARCH)/Makefile contains what is required to set up kbuild +for said architecture. +To do so, arch/$(ARCH)/Makefile sets up a number of variables and defines +a few targets. + +When kbuild executes, the following steps are followed (roughly): + +1) Configuration of the kernel => produce .config +2) Store kernel version in include/linux/version.h +3) Updating all other prerequisites to the target prepare: + - Additional prerequisites are specified in arch/$(ARCH)/Makefile +4) Recursively descend down in all directories listed in + init-* core* drivers-* net-* libs-* and build all targets. + - The values of the above variables are expanded in arch/$(ARCH)/Makefile. +5) All object files are then linked and the resulting file vmlinux is + located at the root of the obj tree. + The very first objects linked are listed in head-y, assigned by + arch/$(ARCH)/Makefile. +6) Finally, the architecture-specific part does any required post processing + and builds the final bootimage. + - This includes building boot records + - Preparing initrd images and the like + + +6.1 Set variables to tweak the build to the architecture +-------------------------------------------------------- + + LDFLAGS + Generic $(LD) options + + Flags used for all invocations of the linker. + Often specifying the emulation is sufficient. + + Example:: + + #arch/s390/Makefile + LDFLAGS := -m elf_s390 + + Note: ldflags-y can be used to further customise + the flags used. See chapter 3.7. + + LDFLAGS_vmlinux + Options for $(LD) when linking vmlinux + + LDFLAGS_vmlinux is used to specify additional flags to pass to + the linker when linking the final vmlinux image. + LDFLAGS_vmlinux uses the LDFLAGS_$@ support. + + Example:: + + #arch/x86/Makefile + LDFLAGS_vmlinux := -e stext + + OBJCOPYFLAGS + objcopy flags + + When $(call if_changed,objcopy) is used to translate a .o file, + the flags specified in OBJCOPYFLAGS will be used. + $(call if_changed,objcopy) is often used to generate raw binaries on + vmlinux. + + Example:: + + #arch/s390/Makefile + OBJCOPYFLAGS := -O binary + + #arch/s390/boot/Makefile + $(obj)/image: vmlinux FORCE + $(call if_changed,objcopy) + + In this example, the binary $(obj)/image is a binary version of + vmlinux. The usage of $(call if_changed,xxx) will be described later. + + KBUILD_AFLAGS + $(AS) assembler flags + + Default value - see top level Makefile + Append or modify as required per architecture. + + Example:: + + #arch/sparc64/Makefile + KBUILD_AFLAGS += -m64 -mcpu=ultrasparc + + KBUILD_CFLAGS + $(CC) compiler flags + + Default value - see top level Makefile + Append or modify as required per architecture. + + Often, the KBUILD_CFLAGS variable depends on the configuration. + + Example:: + + #arch/x86/boot/compressed/Makefile + cflags-$(CONFIG_X86_32) := -march=i386 + cflags-$(CONFIG_X86_64) := -mcmodel=small + KBUILD_CFLAGS += $(cflags-y) + + Many arch Makefiles dynamically run the target C compiler to + probe supported options:: + + #arch/x86/Makefile + + ... + cflags-$(CONFIG_MPENTIUMII) += $(call cc-option,\ + -march=pentium2,-march=i686) + ... + # Disable unit-at-a-time mode ... + KBUILD_CFLAGS += $(call cc-option,-fno-unit-at-a-time) + ... + + + The first example utilises the trick that a config option expands + to 'y' when selected. + + KBUILD_AFLAGS_KERNEL + $(AS) options specific for built-in + + $(KBUILD_AFLAGS_KERNEL) contains extra C compiler flags used to compile + resident kernel code. + + KBUILD_AFLAGS_MODULE + Options for $(AS) when building modules + + $(KBUILD_AFLAGS_MODULE) is used to add arch-specific options that + are used for $(AS). + + From commandline AFLAGS_MODULE shall be used (see kbuild.txt). + + KBUILD_CFLAGS_KERNEL + $(CC) options specific for built-in + + $(KBUILD_CFLAGS_KERNEL) contains extra C compiler flags used to compile + resident kernel code. + + KBUILD_CFLAGS_MODULE + Options for $(CC) when building modules + + $(KBUILD_CFLAGS_MODULE) is used to add arch-specific options that + are used for $(CC). + From commandline CFLAGS_MODULE shall be used (see kbuild.txt). + + KBUILD_LDFLAGS_MODULE + Options for $(LD) when linking modules + + $(KBUILD_LDFLAGS_MODULE) is used to add arch-specific options + used when linking modules. This is often a linker script. + + From commandline LDFLAGS_MODULE shall be used (see kbuild.txt). + + KBUILD_ARFLAGS Options for $(AR) when creating archives + + $(KBUILD_ARFLAGS) set by the top level Makefile to "D" (deterministic + mode) if this option is supported by $(AR). + + ARCH_CPPFLAGS, ARCH_AFLAGS, ARCH_CFLAGS Overrides the kbuild defaults + + These variables are appended to the KBUILD_CPPFLAGS, + KBUILD_AFLAGS, and KBUILD_CFLAGS, respectively, after the + top-level Makefile has set any other flags. This provides a + means for an architecture to override the defaults. + + +6.2 Add prerequisites to archheaders +------------------------------------ + + The archheaders: rule is used to generate header files that + may be installed into user space by "make header_install" or + "make headers_install_all". In order to support + "make headers_install_all", this target has to be able to run + on an unconfigured tree, or a tree configured for another + architecture. + + It is run before "make archprepare" when run on the + architecture itself. + + +6.3 Add prerequisites to archprepare +------------------------------------ + + The archprepare: rule is used to list prerequisites that need to be + built before starting to descend down in the subdirectories. + This is usually used for header files containing assembler constants. + + Example:: + + #arch/arm/Makefile + archprepare: maketools + + In this example, the file target maketools will be processed + before descending down in the subdirectories. + See also chapter XXX-TODO that describe how kbuild supports + generating offset header files. + + +6.4 List directories to visit when descending +--------------------------------------------- + + An arch Makefile cooperates with the top Makefile to define variables + which specify how to build the vmlinux file. Note that there is no + corresponding arch-specific section for modules; the module-building + machinery is all architecture-independent. + + + head-y, init-y, core-y, libs-y, drivers-y, net-y + $(head-y) lists objects to be linked first in vmlinux. + + $(libs-y) lists directories where a lib.a archive can be located. + + The rest list directories where a built-in.a object file can be + located. + + $(init-y) objects will be located after $(head-y). + + Then the rest follows in this order: + + $(core-y), $(libs-y), $(drivers-y) and $(net-y). + + The top level Makefile defines values for all generic directories, + and arch/$(ARCH)/Makefile only adds architecture-specific + directories. + + Example:: + + #arch/sparc64/Makefile + core-y += arch/sparc64/kernel/ + libs-y += arch/sparc64/prom/ arch/sparc64/lib/ + drivers-$(CONFIG_OPROFILE) += arch/sparc64/oprofile/ + + +6.5 Architecture-specific boot images +------------------------------------- + + An arch Makefile specifies goals that take the vmlinux file, compress + it, wrap it in bootstrapping code, and copy the resulting files + somewhere. This includes various kinds of installation commands. + The actual goals are not standardized across architectures. + + It is common to locate any additional processing in a boot/ + directory below arch/$(ARCH)/. + + Kbuild does not provide any smart way to support building a + target specified in boot/. Therefore arch/$(ARCH)/Makefile shall + call make manually to build a target in boot/. + + The recommended approach is to include shortcuts in + arch/$(ARCH)/Makefile, and use the full path when calling down + into the arch/$(ARCH)/boot/Makefile. + + Example:: + + #arch/x86/Makefile + boot := arch/x86/boot + bzImage: vmlinux + $(Q)$(MAKE) $(build)=$(boot) $(boot)/$@ + + "$(Q)$(MAKE) $(build)=" is the recommended way to invoke + make in a subdirectory. + + There are no rules for naming architecture-specific targets, + but executing "make help" will list all relevant targets. + To support this, $(archhelp) must be defined. + + Example:: + + #arch/x86/Makefile + define archhelp + echo '* bzImage - Image (arch/$(ARCH)/boot/bzImage)' + endif + + When make is executed without arguments, the first goal encountered + will be built. In the top level Makefile the first goal present + is all:. + An architecture shall always, per default, build a bootable image. + In "make help", the default goal is highlighted with a '*'. + Add a new prerequisite to all: to select a default goal different + from vmlinux. + + Example:: + + #arch/x86/Makefile + all: bzImage + + When "make" is executed without arguments, bzImage will be built. + +6.6 Building non-kbuild targets +------------------------------- + + extra-y + extra-y specifies additional targets created in the current + directory, in addition to any targets specified by `obj-*`. + + Listing all targets in extra-y is required for two purposes: + + 1) Enable kbuild to check changes in command lines + + - When $(call if_changed,xxx) is used + + 2) kbuild knows what files to delete during "make clean" + + Example:: + + #arch/x86/kernel/Makefile + extra-y := head.o init_task.o + + In this example, extra-y is used to list object files that + shall be built, but shall not be linked as part of built-in.a. + + +6.7 Commands useful for building a boot image +--------------------------------------------- + + Kbuild provides a few macros that are useful when building a + boot image. + + if_changed + if_changed is the infrastructure used for the following commands. + + Usage:: + + target: source(s) FORCE + $(call if_changed,ld/objcopy/gzip/...) + + When the rule is evaluated, it is checked to see if any files + need an update, or the command line has changed since the last + invocation. The latter will force a rebuild if any options + to the executable have changed. + Any target that utilises if_changed must be listed in $(targets), + otherwise the command line check will fail, and the target will + always be built. + Assignments to $(targets) are without $(obj)/ prefix. + if_changed may be used in conjunction with custom commands as + defined in 6.8 "Custom kbuild commands". + + Note: It is a typical mistake to forget the FORCE prerequisite. + Another common pitfall is that whitespace is sometimes + significant; for instance, the below will fail (note the extra space + after the comma):: + + target: source(s) FORCE + + **WRONG!** $(call if_changed, ld/objcopy/gzip/...) + + Note: + if_changed should not be used more than once per target. + It stores the executed command in a corresponding .cmd + + file and multiple calls would result in overwrites and + unwanted results when the target is up to date and only the + tests on changed commands trigger execution of commands. + + ld + Link target. Often, LDFLAGS_$@ is used to set specific options to ld. + + Example:: + + #arch/x86/boot/Makefile + LDFLAGS_bootsect := -Ttext 0x0 -s --oformat binary + LDFLAGS_setup := -Ttext 0x0 -s --oformat binary -e begtext + + targets += setup setup.o bootsect bootsect.o + $(obj)/setup $(obj)/bootsect: %: %.o FORCE + $(call if_changed,ld) + + In this example, there are two possible targets, requiring different + options to the linker. The linker options are specified using the + LDFLAGS_$@ syntax - one for each potential target. + $(targets) are assigned all potential targets, by which kbuild knows + the targets and will: + + 1) check for commandline changes + 2) delete target during make clean + + The ": %: %.o" part of the prerequisite is a shorthand that + frees us from listing the setup.o and bootsect.o files. + + Note: + It is a common mistake to forget the "targets :=" assignment, + resulting in the target file being recompiled for no + obvious reason. + + objcopy + Copy binary. Uses OBJCOPYFLAGS usually specified in + arch/$(ARCH)/Makefile. + OBJCOPYFLAGS_$@ may be used to set additional options. + + gzip + Compress target. Use maximum compression to compress target. + + Example:: + + #arch/x86/boot/compressed/Makefile + $(obj)/vmlinux.bin.gz: $(vmlinux.bin.all-y) FORCE + $(call if_changed,gzip) + + dtc + Create flattened device tree blob object suitable for linking + into vmlinux. Device tree blobs linked into vmlinux are placed + in an init section in the image. Platform code *must* copy the + blob to non-init memory prior to calling unflatten_device_tree(). + + To use this command, simply add `*.dtb` into obj-y or targets, or make + some other target depend on `%.dtb` + + A central rule exists to create `$(obj)/%.dtb` from `$(src)/%.dts`; + architecture Makefiles do no need to explicitly write out that rule. + + Example:: + + targets += $(dtb-y) + DTC_FLAGS ?= -p 1024 + +6.8 Custom kbuild commands +-------------------------- + + When kbuild is executing with KBUILD_VERBOSE=0, then only a shorthand + of a command is normally displayed. + To enable this behaviour for custom commands kbuild requires + two variables to be set:: + + quiet_cmd_ - what shall be echoed + cmd_ - the command to execute + + Example:: + + # + quiet_cmd_image = BUILD $@ + cmd_image = $(obj)/tools/build $(BUILDFLAGS) \ + $(obj)/vmlinux.bin > $@ + + targets += bzImage + $(obj)/bzImage: $(obj)/vmlinux.bin $(obj)/tools/build FORCE + $(call if_changed,image) + @echo 'Kernel: $@ is ready' + + When updating the $(obj)/bzImage target, the line: + + BUILD arch/x86/boot/bzImage + + will be displayed with "make KBUILD_VERBOSE=0". + + +--- 6.9 Preprocessing linker scripts + + When the vmlinux image is built, the linker script + arch/$(ARCH)/kernel/vmlinux.lds is used. + The script is a preprocessed variant of the file vmlinux.lds.S + located in the same directory. + kbuild knows .lds files and includes a rule `*lds.S` -> `*lds`. + + Example:: + + #arch/x86/kernel/Makefile + always := vmlinux.lds + + #Makefile + export CPPFLAGS_vmlinux.lds += -P -C -U$(ARCH) + + The assignment to $(always) is used to tell kbuild to build the + target vmlinux.lds. + The assignment to $(CPPFLAGS_vmlinux.lds) tells kbuild to use the + specified options when building the target vmlinux.lds. + + When building the `*.lds` target, kbuild uses the variables:: + + KBUILD_CPPFLAGS : Set in top-level Makefile + cppflags-y : May be set in the kbuild makefile + CPPFLAGS_$(@F) : Target-specific flags. + Note that the full filename is used in this + assignment. + + The kbuild infrastructure for `*lds` files is used in several + architecture-specific files. + +6.10 Generic header files +------------------------- + + The directory include/asm-generic contains the header files + that may be shared between individual architectures. + The recommended approach how to use a generic header file is + to list the file in the Kbuild file. + See "7.2 generic-y" for further info on syntax etc. + +6.11 Post-link pass +------------------- + + If the file arch/xxx/Makefile.postlink exists, this makefile + will be invoked for post-link objects (vmlinux and modules.ko) + for architectures to run post-link passes on. Must also handle + the clean target. + + This pass runs after kallsyms generation. If the architecture + needs to modify symbol locations, rather than manipulate the + kallsyms, it may be easier to add another postlink target for + .tmp_vmlinux? targets to be called from link-vmlinux.sh. + + For example, powerpc uses this to check relocation sanity of + the linked vmlinux file. + +7 Kbuild syntax for exported headers +------------------------------------ + +The kernel includes a set of headers that is exported to userspace. +Many headers can be exported as-is but other headers require a +minimal pre-processing before they are ready for user-space. +The pre-processing does: + +- drop kernel-specific annotations +- drop include of compiler.h +- drop all sections that are kernel internal (guarded by `ifdef __KERNEL__`) + +All headers under include/uapi/, include/generated/uapi/, +arch//include/uapi/ and arch//include/generated/uapi/ +are exported. + +A Kbuild file may be defined under arch//include/uapi/asm/ and +arch//include/asm/ to list asm files coming from asm-generic. +See subsequent chapter for the syntax of the Kbuild file. + +7.1 no-export-headers +--------------------- + + no-export-headers is essentially used by include/uapi/linux/Kbuild to + avoid exporting specific headers (e.g. kvm.h) on architectures that do + not support it. It should be avoided as much as possible. + +7.2 generic-y +------------- + + If an architecture uses a verbatim copy of a header from + include/asm-generic then this is listed in the file + arch/$(ARCH)/include/asm/Kbuild like this: + + Example:: + + #arch/x86/include/asm/Kbuild + generic-y += termios.h + generic-y += rtc.h + + During the prepare phase of the build a wrapper include + file is generated in the directory:: + + arch/$(ARCH)/include/generated/asm + + When a header is exported where the architecture uses + the generic header a similar wrapper is generated as part + of the set of exported headers in the directory:: + + usr/include/asm + + The generated wrapper will in both cases look like the following: + + Example: termios.h:: + + #include + +7.3 generated-y +--------------- + + If an architecture generates other header files alongside generic-y + wrappers, generated-y specifies them. + + This prevents them being treated as stale asm-generic wrappers and + removed. + + Example:: + + #arch/x86/include/asm/Kbuild + generated-y += syscalls_32.h + +7.4 mandatory-y +--------------- + + mandatory-y is essentially used by include/(uapi/)asm-generic/Kbuild + to define the minimum set of ASM headers that all architectures must have. + + This works like optional generic-y. If a mandatory header is missing + in arch/$(ARCH)/include/(uapi/)/asm, Kbuild will automatically generate + a wrapper of the asm-generic one. + + The convention is to list one subdir per line and + preferably in alphabetic order. + +8 Kbuild Variables +================== + +The top Makefile exports the following variables: + + VERSION, PATCHLEVEL, SUBLEVEL, EXTRAVERSION + These variables define the current kernel version. A few arch + Makefiles actually use these values directly; they should use + $(KERNELRELEASE) instead. + + $(VERSION), $(PATCHLEVEL), and $(SUBLEVEL) define the basic + three-part version number, such as "2", "4", and "0". These three + values are always numeric. + + $(EXTRAVERSION) defines an even tinier sublevel for pre-patches + or additional patches. It is usually some non-numeric string + such as "-pre4", and is often blank. + + KERNELRELEASE + $(KERNELRELEASE) is a single string such as "2.4.0-pre4", suitable + for constructing installation directory names or showing in + version strings. Some arch Makefiles use it for this purpose. + + ARCH + This variable defines the target architecture, such as "i386", + "arm", or "sparc". Some kbuild Makefiles test $(ARCH) to + determine which files to compile. + + By default, the top Makefile sets $(ARCH) to be the same as the + host system architecture. For a cross build, a user may + override the value of $(ARCH) on the command line:: + + make ARCH=m68k ... + + + INSTALL_PATH + This variable defines a place for the arch Makefiles to install + the resident kernel image and System.map file. + Use this for architecture-specific install targets. + + INSTALL_MOD_PATH, MODLIB + $(INSTALL_MOD_PATH) specifies a prefix to $(MODLIB) for module + installation. This variable is not defined in the Makefile but + may be passed in by the user if desired. + + $(MODLIB) specifies the directory for module installation. + The top Makefile defines $(MODLIB) to + $(INSTALL_MOD_PATH)/lib/modules/$(KERNELRELEASE). The user may + override this value on the command line if desired. + + INSTALL_MOD_STRIP + If this variable is specified, it will cause modules to be stripped + after they are installed. If INSTALL_MOD_STRIP is '1', then the + default option --strip-debug will be used. Otherwise, the + INSTALL_MOD_STRIP value will be used as the option(s) to the strip + command. + + +9 Makefile language +=================== + +The kernel Makefiles are designed to be run with GNU Make. The Makefiles +use only the documented features of GNU Make, but they do use many +GNU extensions. + +GNU Make supports elementary list-processing functions. The kernel +Makefiles use a novel style of list building and manipulation with few +"if" statements. + +GNU Make has two assignment operators, ":=" and "=". ":=" performs +immediate evaluation of the right-hand side and stores an actual string +into the left-hand side. "=" is like a formula definition; it stores the +right-hand side in an unevaluated form and then evaluates this form each +time the left-hand side is used. + +There are some cases where "=" is appropriate. Usually, though, ":=" +is the right choice. + +10 Credits +========== + +- Original version made by Michael Elizabeth Chastain, +- Updates by Kai Germaschewski +- Updates by Sam Ravnborg +- Language QA by Jan Engelhardt + +11 TODO +======= + +- Describe how kbuild supports shipped files with _shipped. +- Generating offset header files. +- Add more variables to section 7? diff --git a/Documentation/kbuild/makefiles.txt b/Documentation/kbuild/makefiles.txt deleted file mode 100644 index d65ad5746f94..000000000000 --- a/Documentation/kbuild/makefiles.txt +++ /dev/null @@ -1,1369 +0,0 @@ -Linux Kernel Makefiles - -This document describes the Linux kernel Makefiles. - -=== Table of Contents - - === 1 Overview - === 2 Who does what - === 3 The kbuild files - --- 3.1 Goal definitions - --- 3.2 Built-in object goals - obj-y - --- 3.3 Loadable module goals - obj-m - --- 3.4 Objects which export symbols - --- 3.5 Library file goals - lib-y - --- 3.6 Descending down in directories - --- 3.7 Compilation flags - --- 3.8 Command line dependency - --- 3.9 Dependency tracking - --- 3.10 Special Rules - --- 3.11 $(CC) support functions - --- 3.12 $(LD) support functions - - === 4 Host Program support - --- 4.1 Simple Host Program - --- 4.2 Composite Host Programs - --- 4.3 Using C++ for host programs - --- 4.4 Controlling compiler options for host programs - --- 4.5 When host programs are actually built - --- 4.6 Using hostprogs-$(CONFIG_FOO) - - === 5 Kbuild clean infrastructure - - === 6 Architecture Makefiles - --- 6.1 Set variables to tweak the build to the architecture - --- 6.2 Add prerequisites to archheaders: - --- 6.3 Add prerequisites to archprepare: - --- 6.4 List directories to visit when descending - --- 6.5 Architecture-specific boot images - --- 6.6 Building non-kbuild targets - --- 6.7 Commands useful for building a boot image - --- 6.8 Custom kbuild commands - --- 6.9 Preprocessing linker scripts - --- 6.10 Generic header files - --- 6.11 Post-link pass - - === 7 Kbuild syntax for exported headers - --- 7.1 no-export-headers - --- 7.2 generic-y - --- 7.3 generated-y - --- 7.4 mandatory-y - - === 8 Kbuild Variables - === 9 Makefile language - === 10 Credits - === 11 TODO - -=== 1 Overview - -The Makefiles have five parts: - - Makefile the top Makefile. - .config the kernel configuration file. - arch/$(ARCH)/Makefile the arch Makefile. - scripts/Makefile.* common rules etc. for all kbuild Makefiles. - kbuild Makefiles there are about 500 of these. - -The top Makefile reads the .config file, which comes from the kernel -configuration process. - -The top Makefile is responsible for building two major products: vmlinux -(the resident kernel image) and modules (any module files). -It builds these goals by recursively descending into the subdirectories of -the kernel source tree. -The list of subdirectories which are visited depends upon the kernel -configuration. The top Makefile textually includes an arch Makefile -with the name arch/$(ARCH)/Makefile. The arch Makefile supplies -architecture-specific information to the top Makefile. - -Each subdirectory has a kbuild Makefile which carries out the commands -passed down from above. The kbuild Makefile uses information from the -.config file to construct various file lists used by kbuild to build -any built-in or modular targets. - -scripts/Makefile.* contains all the definitions/rules etc. that -are used to build the kernel based on the kbuild makefiles. - - -=== 2 Who does what - -People have four different relationships with the kernel Makefiles. - -*Users* are people who build kernels. These people type commands such as -"make menuconfig" or "make". They usually do not read or edit -any kernel Makefiles (or any other source files). - -*Normal developers* are people who work on features such as device -drivers, file systems, and network protocols. These people need to -maintain the kbuild Makefiles for the subsystem they are -working on. In order to do this effectively, they need some overall -knowledge about the kernel Makefiles, plus detailed knowledge about the -public interface for kbuild. - -*Arch developers* are people who work on an entire architecture, such -as sparc or ia64. Arch developers need to know about the arch Makefile -as well as kbuild Makefiles. - -*Kbuild developers* are people who work on the kernel build system itself. -These people need to know about all aspects of the kernel Makefiles. - -This document is aimed towards normal developers and arch developers. - - -=== 3 The kbuild files - -Most Makefiles within the kernel are kbuild Makefiles that use the -kbuild infrastructure. This chapter introduces the syntax used in the -kbuild makefiles. -The preferred name for the kbuild files are 'Makefile' but 'Kbuild' can -be used and if both a 'Makefile' and a 'Kbuild' file exists, then the 'Kbuild' -file will be used. - -Section 3.1 "Goal definitions" is a quick intro, further chapters provide -more details, with real examples. - ---- 3.1 Goal definitions - - Goal definitions are the main part (heart) of the kbuild Makefile. - These lines define the files to be built, any special compilation - options, and any subdirectories to be entered recursively. - - The most simple kbuild makefile contains one line: - - Example: - obj-y += foo.o - - This tells kbuild that there is one object in that directory, named - foo.o. foo.o will be built from foo.c or foo.S. - - If foo.o shall be built as a module, the variable obj-m is used. - Therefore the following pattern is often used: - - Example: - obj-$(CONFIG_FOO) += foo.o - - $(CONFIG_FOO) evaluates to either y (for built-in) or m (for module). - If CONFIG_FOO is neither y nor m, then the file will not be compiled - nor linked. - ---- 3.2 Built-in object goals - obj-y - - The kbuild Makefile specifies object files for vmlinux - in the $(obj-y) lists. These lists depend on the kernel - configuration. - - Kbuild compiles all the $(obj-y) files. It then calls - "$(AR) rcSTP" to merge these files into one built-in.a file. - This is a thin archive without a symbol table. It will be later - linked into vmlinux by scripts/link-vmlinux.sh - - The order of files in $(obj-y) is significant. Duplicates in - the lists are allowed: the first instance will be linked into - built-in.a and succeeding instances will be ignored. - - Link order is significant, because certain functions - (module_init() / __initcall) will be called during boot in the - order they appear. So keep in mind that changing the link - order may e.g. change the order in which your SCSI - controllers are detected, and thus your disks are renumbered. - - Example: - #drivers/isdn/i4l/Makefile - # Makefile for the kernel ISDN subsystem and device drivers. - # Each configuration option enables a list of files. - obj-$(CONFIG_ISDN_I4L) += isdn.o - obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o - ---- 3.3 Loadable module goals - obj-m - - $(obj-m) specifies object files which are built as loadable - kernel modules. - - A module may be built from one source file or several source - files. In the case of one source file, the kbuild makefile - simply adds the file to $(obj-m). - - Example: - #drivers/isdn/i4l/Makefile - obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o - - Note: In this example $(CONFIG_ISDN_PPP_BSDCOMP) evaluates to 'm' - - If a kernel module is built from several source files, you specify - that you want to build a module in the same way as above; however, - kbuild needs to know which object files you want to build your - module from, so you have to tell it by setting a $(-y) - variable. - - Example: - #drivers/isdn/i4l/Makefile - obj-$(CONFIG_ISDN_I4L) += isdn.o - isdn-y := isdn_net_lib.o isdn_v110.o isdn_common.o - - In this example, the module name will be isdn.o. Kbuild will - compile the objects listed in $(isdn-y) and then run - "$(LD) -r" on the list of these files to generate isdn.o. - - Due to kbuild recognizing $(-y) for composite objects, - you can use the value of a CONFIG_ symbol to optionally include an - object file as part of a composite object. - - Example: - #fs/ext2/Makefile - obj-$(CONFIG_EXT2_FS) += ext2.o - ext2-y := balloc.o dir.o file.o ialloc.o inode.o ioctl.o \ - namei.o super.o symlink.o - ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o xattr_user.o \ - xattr_trusted.o - - In this example, xattr.o, xattr_user.o and xattr_trusted.o are only - part of the composite object ext2.o if $(CONFIG_EXT2_FS_XATTR) - evaluates to 'y'. - - Note: Of course, when you are building objects into the kernel, - the syntax above will also work. So, if you have CONFIG_EXT2_FS=y, - kbuild will build an ext2.o file for you out of the individual - parts and then link this into built-in.a, as you would expect. - ---- 3.4 Objects which export symbols - - No special notation is required in the makefiles for - modules exporting symbols. - ---- 3.5 Library file goals - lib-y - - Objects listed with obj-* are used for modules, or - combined in a built-in.a for that specific directory. - There is also the possibility to list objects that will - be included in a library, lib.a. - All objects listed with lib-y are combined in a single - library for that directory. - Objects that are listed in obj-y and additionally listed in - lib-y will not be included in the library, since they will - be accessible anyway. - For consistency, objects listed in lib-m will be included in lib.a. - - Note that the same kbuild makefile may list files to be built-in - and to be part of a library. Therefore the same directory - may contain both a built-in.a and a lib.a file. - - Example: - #arch/x86/lib/Makefile - lib-y := delay.o - - This will create a library lib.a based on delay.o. For kbuild to - actually recognize that there is a lib.a being built, the directory - shall be listed in libs-y. - See also "6.4 List directories to visit when descending". - - Use of lib-y is normally restricted to lib/ and arch/*/lib. - ---- 3.6 Descending down in directories - - A Makefile is only responsible for building objects in its own - directory. Files in subdirectories should be taken care of by - Makefiles in these subdirs. The build system will automatically - invoke make recursively in subdirectories, provided you let it know of - them. - - To do so, obj-y and obj-m are used. - ext2 lives in a separate directory, and the Makefile present in fs/ - tells kbuild to descend down using the following assignment. - - Example: - #fs/Makefile - obj-$(CONFIG_EXT2_FS) += ext2/ - - If CONFIG_EXT2_FS is set to either 'y' (built-in) or 'm' (modular) - the corresponding obj- variable will be set, and kbuild will descend - down in the ext2 directory. - Kbuild only uses this information to decide that it needs to visit - the directory, it is the Makefile in the subdirectory that - specifies what is modular and what is built-in. - - It is good practice to use a CONFIG_ variable when assigning directory - names. This allows kbuild to totally skip the directory if the - corresponding CONFIG_ option is neither 'y' nor 'm'. - ---- 3.7 Compilation flags - - ccflags-y, asflags-y and ldflags-y - These three flags apply only to the kbuild makefile in which they - are assigned. They are used for all the normal cc, as and ld - invocations happening during a recursive build. - Note: Flags with the same behaviour were previously named: - EXTRA_CFLAGS, EXTRA_AFLAGS and EXTRA_LDFLAGS. - They are still supported but their usage is deprecated. - - ccflags-y specifies options for compiling with $(CC). - - Example: - # drivers/acpi/acpica/Makefile - ccflags-y := -Os -D_LINUX -DBUILDING_ACPICA - ccflags-$(CONFIG_ACPI_DEBUG) += -DACPI_DEBUG_OUTPUT - - This variable is necessary because the top Makefile owns the - variable $(KBUILD_CFLAGS) and uses it for compilation flags for the - entire tree. - - asflags-y specifies options for assembling with $(AS). - - Example: - #arch/sparc/kernel/Makefile - asflags-y := -ansi - - ldflags-y specifies options for linking with $(LD). - - Example: - #arch/cris/boot/compressed/Makefile - ldflags-y += -T $(srctree)/$(src)/decompress_$(arch-y).lds - - subdir-ccflags-y, subdir-asflags-y - The two flags listed above are similar to ccflags-y and asflags-y. - The difference is that the subdir- variants have effect for the kbuild - file where they are present and all subdirectories. - Options specified using subdir-* are added to the commandline before - the options specified using the non-subdir variants. - - Example: - subdir-ccflags-y := -Werror - - CFLAGS_$@, AFLAGS_$@ - - CFLAGS_$@ and AFLAGS_$@ only apply to commands in current - kbuild makefile. - - $(CFLAGS_$@) specifies per-file options for $(CC). The $@ - part has a literal value which specifies the file that it is for. - - Example: - # drivers/scsi/Makefile - CFLAGS_aha152x.o = -DAHA152X_STAT -DAUTOCONF - CFLAGS_gdth.o = # -DDEBUG_GDTH=2 -D__SERIAL__ -D__COM2__ \ - -DGDTH_STATISTICS - - These two lines specify compilation flags for aha152x.o and gdth.o. - - $(AFLAGS_$@) is a similar feature for source files in assembly - languages. - - Example: - # arch/arm/kernel/Makefile - AFLAGS_head.o := -DTEXT_OFFSET=$(TEXT_OFFSET) - AFLAGS_crunch-bits.o := -Wa,-mcpu=ep9312 - AFLAGS_iwmmxt.o := -Wa,-mcpu=iwmmxt - - ---- 3.9 Dependency tracking - - Kbuild tracks dependencies on the following: - 1) All prerequisite files (both *.c and *.h) - 2) CONFIG_ options used in all prerequisite files - 3) Command-line used to compile target - - Thus, if you change an option to $(CC) all affected files will - be re-compiled. - ---- 3.10 Special Rules - - Special rules are used when the kbuild infrastructure does - not provide the required support. A typical example is - header files generated during the build process. - Another example are the architecture-specific Makefiles which - need special rules to prepare boot images etc. - - Special rules are written as normal Make rules. - Kbuild is not executing in the directory where the Makefile is - located, so all special rules shall provide a relative - path to prerequisite files and target files. - - Two variables are used when defining special rules: - - $(src) - $(src) is a relative path which points to the directory - where the Makefile is located. Always use $(src) when - referring to files located in the src tree. - - $(obj) - $(obj) is a relative path which points to the directory - where the target is saved. Always use $(obj) when - referring to generated files. - - Example: - #drivers/scsi/Makefile - $(obj)/53c8xx_d.h: $(src)/53c7,8xx.scr $(src)/script_asm.pl - $(CPP) -DCHIP=810 - < $< | ... $(src)/script_asm.pl - - This is a special rule, following the normal syntax - required by make. - The target file depends on two prerequisite files. References - to the target file are prefixed with $(obj), references - to prerequisites are referenced with $(src) (because they are not - generated files). - - $(kecho) - echoing information to user in a rule is often a good practice - but when execution "make -s" one does not expect to see any output - except for warnings/errors. - To support this kbuild defines $(kecho) which will echo out the - text following $(kecho) to stdout except if "make -s" is used. - - Example: - #arch/blackfin/boot/Makefile - $(obj)/vmImage: $(obj)/vmlinux.gz - $(call if_changed,uimage) - @$(kecho) 'Kernel: $@ is ready' - - ---- 3.11 $(CC) support functions - - The kernel may be built with several different versions of - $(CC), each supporting a unique set of features and options. - kbuild provides basic support to check for valid options for $(CC). - $(CC) is usually the gcc compiler, but other alternatives are - available. - - as-option - as-option is used to check if $(CC) -- when used to compile - assembler (*.S) files -- supports the given option. An optional - second option may be specified if the first option is not supported. - - Example: - #arch/sh/Makefile - cflags-y += $(call as-option,-Wa$(comma)-isa=$(isa-y),) - - In the above example, cflags-y will be assigned the option - -Wa$(comma)-isa=$(isa-y) if it is supported by $(CC). - The second argument is optional, and if supplied will be used - if first argument is not supported. - - as-instr - as-instr checks if the assembler reports a specific instruction - and then outputs either option1 or option2 - C escapes are supported in the test instruction - Note: as-instr-option uses KBUILD_AFLAGS for $(AS) options - - cc-option - cc-option is used to check if $(CC) supports a given option, and if - not supported to use an optional second option. - - Example: - #arch/x86/Makefile - cflags-y += $(call cc-option,-march=pentium-mmx,-march=i586) - - In the above example, cflags-y will be assigned the option - -march=pentium-mmx if supported by $(CC), otherwise -march=i586. - The second argument to cc-option is optional, and if omitted, - cflags-y will be assigned no value if first option is not supported. - Note: cc-option uses KBUILD_CFLAGS for $(CC) options - - cc-option-yn - cc-option-yn is used to check if gcc supports a given option - and return 'y' if supported, otherwise 'n'. - - Example: - #arch/ppc/Makefile - biarch := $(call cc-option-yn, -m32) - aflags-$(biarch) += -a32 - cflags-$(biarch) += -m32 - - In the above example, $(biarch) is set to y if $(CC) supports the -m32 - option. When $(biarch) equals 'y', the expanded variables $(aflags-y) - and $(cflags-y) will be assigned the values -a32 and -m32, - respectively. - Note: cc-option-yn uses KBUILD_CFLAGS for $(CC) options - - cc-disable-warning - cc-disable-warning checks if gcc supports a given warning and returns - the commandline switch to disable it. This special function is needed, - because gcc 4.4 and later accept any unknown -Wno-* option and only - warn about it if there is another warning in the source file. - - Example: - KBUILD_CFLAGS += $(call cc-disable-warning, unused-but-set-variable) - - In the above example, -Wno-unused-but-set-variable will be added to - KBUILD_CFLAGS only if gcc really accepts it. - - cc-ifversion - cc-ifversion tests the version of $(CC) and equals the fourth parameter - if version expression is true, or the fifth (if given) if the version - expression is false. - - Example: - #fs/reiserfs/Makefile - ccflags-y := $(call cc-ifversion, -lt, 0402, -O1) - - In this example, ccflags-y will be assigned the value -O1 if the - $(CC) version is less than 4.2. - cc-ifversion takes all the shell operators: - -eq, -ne, -lt, -le, -gt, and -ge - The third parameter may be a text as in this example, but it may also - be an expanded variable or a macro. - - cc-cross-prefix - cc-cross-prefix is used to check if there exists a $(CC) in path with - one of the listed prefixes. The first prefix where there exist a - prefix$(CC) in the PATH is returned - and if no prefix$(CC) is found - then nothing is returned. - Additional prefixes are separated by a single space in the - call of cc-cross-prefix. - This functionality is useful for architecture Makefiles that try - to set CROSS_COMPILE to well-known values but may have several - values to select between. - It is recommended only to try to set CROSS_COMPILE if it is a cross - build (host arch is different from target arch). And if CROSS_COMPILE - is already set then leave it with the old value. - - Example: - #arch/m68k/Makefile - ifneq ($(SUBARCH),$(ARCH)) - ifeq ($(CROSS_COMPILE),) - CROSS_COMPILE := $(call cc-cross-prefix, m68k-linux-gnu-) - endif - endif - ---- 3.12 $(LD) support functions - - ld-option - ld-option is used to check if $(LD) supports the supplied option. - ld-option takes two options as arguments. - The second argument is an optional option that can be used if the - first option is not supported by $(LD). - - Example: - #Makefile - LDFLAGS_vmlinux += $(call ld-option, -X) - - -=== 4 Host Program support - -Kbuild supports building executables on the host for use during the -compilation stage. -Two steps are required in order to use a host executable. - -The first step is to tell kbuild that a host program exists. This is -done utilising the variable hostprogs-y. - -The second step is to add an explicit dependency to the executable. -This can be done in two ways. Either add the dependency in a rule, -or utilise the variable $(always). -Both possibilities are described in the following. - ---- 4.1 Simple Host Program - - In some cases there is a need to compile and run a program on the - computer where the build is running. - The following line tells kbuild that the program bin2hex shall be - built on the build host. - - Example: - hostprogs-y := bin2hex - - Kbuild assumes in the above example that bin2hex is made from a single - c-source file named bin2hex.c located in the same directory as - the Makefile. - ---- 4.2 Composite Host Programs - - Host programs can be made up based on composite objects. - The syntax used to define composite objects for host programs is - similar to the syntax used for kernel objects. - $(-objs) lists all objects used to link the final - executable. - - Example: - #scripts/lxdialog/Makefile - hostprogs-y := lxdialog - lxdialog-objs := checklist.o lxdialog.o - - Objects with extension .o are compiled from the corresponding .c - files. In the above example, checklist.c is compiled to checklist.o - and lxdialog.c is compiled to lxdialog.o. - Finally, the two .o files are linked to the executable, lxdialog. - Note: The syntax -y is not permitted for host-programs. - ---- 4.3 Using C++ for host programs - - kbuild offers support for host programs written in C++. This was - introduced solely to support kconfig, and is not recommended - for general use. - - Example: - #scripts/kconfig/Makefile - hostprogs-y := qconf - qconf-cxxobjs := qconf.o - - In the example above the executable is composed of the C++ file - qconf.cc - identified by $(qconf-cxxobjs). - - If qconf is composed of a mixture of .c and .cc files, then an - additional line can be used to identify this. - - Example: - #scripts/kconfig/Makefile - hostprogs-y := qconf - qconf-cxxobjs := qconf.o - qconf-objs := check.o - ---- 4.4 Controlling compiler options for host programs - - When compiling host programs, it is possible to set specific flags. - The programs will always be compiled utilising $(HOSTCC) passed - the options specified in $(KBUILD_HOSTCFLAGS). - To set flags that will take effect for all host programs created - in that Makefile, use the variable HOST_EXTRACFLAGS. - - Example: - #scripts/lxdialog/Makefile - HOST_EXTRACFLAGS += -I/usr/include/ncurses - - To set specific flags for a single file the following construction - is used: - - Example: - #arch/ppc64/boot/Makefile - HOSTCFLAGS_piggyback.o := -DKERNELBASE=$(KERNELBASE) - - It is also possible to specify additional options to the linker. - - Example: - #scripts/kconfig/Makefile - HOSTLDLIBS_qconf := -L$(QTDIR)/lib - - When linking qconf, it will be passed the extra option - "-L$(QTDIR)/lib". - ---- 4.5 When host programs are actually built - - Kbuild will only build host-programs when they are referenced - as a prerequisite. - This is possible in two ways: - - (1) List the prerequisite explicitly in a special rule. - - Example: - #drivers/pci/Makefile - hostprogs-y := gen-devlist - $(obj)/devlist.h: $(src)/pci.ids $(obj)/gen-devlist - ( cd $(obj); ./gen-devlist ) < $< - - The target $(obj)/devlist.h will not be built before - $(obj)/gen-devlist is updated. Note that references to - the host programs in special rules must be prefixed with $(obj). - - (2) Use $(always) - When there is no suitable special rule, and the host program - shall be built when a makefile is entered, the $(always) - variable shall be used. - - Example: - #scripts/lxdialog/Makefile - hostprogs-y := lxdialog - always := $(hostprogs-y) - - This will tell kbuild to build lxdialog even if not referenced in - any rule. - ---- 4.6 Using hostprogs-$(CONFIG_FOO) - - A typical pattern in a Kbuild file looks like this: - - Example: - #scripts/Makefile - hostprogs-$(CONFIG_KALLSYMS) += kallsyms - - Kbuild knows about both 'y' for built-in and 'm' for module. - So if a config symbol evaluates to 'm', kbuild will still build - the binary. In other words, Kbuild handles hostprogs-m exactly - like hostprogs-y. But only hostprogs-y is recommended to be used - when no CONFIG symbols are involved. - -=== 5 Kbuild clean infrastructure - -"make clean" deletes most generated files in the obj tree where the kernel -is compiled. This includes generated files such as host programs. -Kbuild knows targets listed in $(hostprogs-y), $(hostprogs-m), $(always), -$(extra-y) and $(targets). They are all deleted during "make clean". -Files matching the patterns "*.[oas]", "*.ko", plus some additional files -generated by kbuild are deleted all over the kernel src tree when -"make clean" is executed. - -Additional files can be specified in kbuild makefiles by use of $(clean-files). - - Example: - #lib/Makefile - clean-files := crc32table.h - -When executing "make clean", the file "crc32table.h" will be deleted. -Kbuild will assume files to be in the same relative directory as the -Makefile, except if prefixed with $(objtree). - -To delete a directory hierarchy use: - - Example: - #scripts/package/Makefile - clean-dirs := $(objtree)/debian/ - -This will delete the directory debian in the toplevel directory, including all -subdirectories. - -To exclude certain files from make clean, use the $(no-clean-files) variable. -This is only a special case used in the top level Kbuild file: - - Example: - #Kbuild - no-clean-files := $(bounds-file) $(offsets-file) - -Usually kbuild descends down in subdirectories due to "obj-* := dir/", -but in the architecture makefiles where the kbuild infrastructure -is not sufficient this sometimes needs to be explicit. - - Example: - #arch/x86/boot/Makefile - subdir- := compressed/ - -The above assignment instructs kbuild to descend down in the -directory compressed/ when "make clean" is executed. - -To support the clean infrastructure in the Makefiles that build the -final bootimage there is an optional target named archclean: - - Example: - #arch/x86/Makefile - archclean: - $(Q)$(MAKE) $(clean)=arch/x86/boot - -When "make clean" is executed, make will descend down in arch/x86/boot, -and clean as usual. The Makefile located in arch/x86/boot/ may use -the subdir- trick to descend further down. - -Note 1: arch/$(ARCH)/Makefile cannot use "subdir-", because that file is -included in the top level makefile, and the kbuild infrastructure -is not operational at that point. - -Note 2: All directories listed in core-y, libs-y, drivers-y and net-y will -be visited during "make clean". - -=== 6 Architecture Makefiles - -The top level Makefile sets up the environment and does the preparation, -before starting to descend down in the individual directories. -The top level makefile contains the generic part, whereas -arch/$(ARCH)/Makefile contains what is required to set up kbuild -for said architecture. -To do so, arch/$(ARCH)/Makefile sets up a number of variables and defines -a few targets. - -When kbuild executes, the following steps are followed (roughly): -1) Configuration of the kernel => produce .config -2) Store kernel version in include/linux/version.h -3) Updating all other prerequisites to the target prepare: - - Additional prerequisites are specified in arch/$(ARCH)/Makefile -4) Recursively descend down in all directories listed in - init-* core* drivers-* net-* libs-* and build all targets. - - The values of the above variables are expanded in arch/$(ARCH)/Makefile. -5) All object files are then linked and the resulting file vmlinux is - located at the root of the obj tree. - The very first objects linked are listed in head-y, assigned by - arch/$(ARCH)/Makefile. -6) Finally, the architecture-specific part does any required post processing - and builds the final bootimage. - - This includes building boot records - - Preparing initrd images and the like - - ---- 6.1 Set variables to tweak the build to the architecture - - LDFLAGS Generic $(LD) options - - Flags used for all invocations of the linker. - Often specifying the emulation is sufficient. - - Example: - #arch/s390/Makefile - LDFLAGS := -m elf_s390 - Note: ldflags-y can be used to further customise - the flags used. See chapter 3.7. - - LDFLAGS_vmlinux Options for $(LD) when linking vmlinux - - LDFLAGS_vmlinux is used to specify additional flags to pass to - the linker when linking the final vmlinux image. - LDFLAGS_vmlinux uses the LDFLAGS_$@ support. - - Example: - #arch/x86/Makefile - LDFLAGS_vmlinux := -e stext - - OBJCOPYFLAGS objcopy flags - - When $(call if_changed,objcopy) is used to translate a .o file, - the flags specified in OBJCOPYFLAGS will be used. - $(call if_changed,objcopy) is often used to generate raw binaries on - vmlinux. - - Example: - #arch/s390/Makefile - OBJCOPYFLAGS := -O binary - - #arch/s390/boot/Makefile - $(obj)/image: vmlinux FORCE - $(call if_changed,objcopy) - - In this example, the binary $(obj)/image is a binary version of - vmlinux. The usage of $(call if_changed,xxx) will be described later. - - KBUILD_AFLAGS $(AS) assembler flags - - Default value - see top level Makefile - Append or modify as required per architecture. - - Example: - #arch/sparc64/Makefile - KBUILD_AFLAGS += -m64 -mcpu=ultrasparc - - KBUILD_CFLAGS $(CC) compiler flags - - Default value - see top level Makefile - Append or modify as required per architecture. - - Often, the KBUILD_CFLAGS variable depends on the configuration. - - Example: - #arch/x86/boot/compressed/Makefile - cflags-$(CONFIG_X86_32) := -march=i386 - cflags-$(CONFIG_X86_64) := -mcmodel=small - KBUILD_CFLAGS += $(cflags-y) - - Many arch Makefiles dynamically run the target C compiler to - probe supported options: - - #arch/x86/Makefile - - ... - cflags-$(CONFIG_MPENTIUMII) += $(call cc-option,\ - -march=pentium2,-march=i686) - ... - # Disable unit-at-a-time mode ... - KBUILD_CFLAGS += $(call cc-option,-fno-unit-at-a-time) - ... - - - The first example utilises the trick that a config option expands - to 'y' when selected. - - KBUILD_AFLAGS_KERNEL $(AS) options specific for built-in - - $(KBUILD_AFLAGS_KERNEL) contains extra C compiler flags used to compile - resident kernel code. - - KBUILD_AFLAGS_MODULE Options for $(AS) when building modules - - $(KBUILD_AFLAGS_MODULE) is used to add arch-specific options that - are used for $(AS). - From commandline AFLAGS_MODULE shall be used (see kbuild.txt). - - KBUILD_CFLAGS_KERNEL $(CC) options specific for built-in - - $(KBUILD_CFLAGS_KERNEL) contains extra C compiler flags used to compile - resident kernel code. - - KBUILD_CFLAGS_MODULE Options for $(CC) when building modules - - $(KBUILD_CFLAGS_MODULE) is used to add arch-specific options that - are used for $(CC). - From commandline CFLAGS_MODULE shall be used (see kbuild.txt). - - KBUILD_LDFLAGS_MODULE Options for $(LD) when linking modules - - $(KBUILD_LDFLAGS_MODULE) is used to add arch-specific options - used when linking modules. This is often a linker script. - From commandline LDFLAGS_MODULE shall be used (see kbuild.txt). - - KBUILD_ARFLAGS Options for $(AR) when creating archives - - $(KBUILD_ARFLAGS) set by the top level Makefile to "D" (deterministic - mode) if this option is supported by $(AR). - - ARCH_CPPFLAGS, ARCH_AFLAGS, ARCH_CFLAGS Overrides the kbuild defaults - - These variables are appended to the KBUILD_CPPFLAGS, - KBUILD_AFLAGS, and KBUILD_CFLAGS, respectively, after the - top-level Makefile has set any other flags. This provides a - means for an architecture to override the defaults. - - ---- 6.2 Add prerequisites to archheaders: - - The archheaders: rule is used to generate header files that - may be installed into user space by "make header_install" or - "make headers_install_all". In order to support - "make headers_install_all", this target has to be able to run - on an unconfigured tree, or a tree configured for another - architecture. - - It is run before "make archprepare" when run on the - architecture itself. - - ---- 6.3 Add prerequisites to archprepare: - - The archprepare: rule is used to list prerequisites that need to be - built before starting to descend down in the subdirectories. - This is usually used for header files containing assembler constants. - - Example: - #arch/arm/Makefile - archprepare: maketools - - In this example, the file target maketools will be processed - before descending down in the subdirectories. - See also chapter XXX-TODO that describe how kbuild supports - generating offset header files. - - ---- 6.4 List directories to visit when descending - - An arch Makefile cooperates with the top Makefile to define variables - which specify how to build the vmlinux file. Note that there is no - corresponding arch-specific section for modules; the module-building - machinery is all architecture-independent. - - - head-y, init-y, core-y, libs-y, drivers-y, net-y - - $(head-y) lists objects to be linked first in vmlinux. - $(libs-y) lists directories where a lib.a archive can be located. - The rest list directories where a built-in.a object file can be - located. - - $(init-y) objects will be located after $(head-y). - Then the rest follows in this order: - $(core-y), $(libs-y), $(drivers-y) and $(net-y). - - The top level Makefile defines values for all generic directories, - and arch/$(ARCH)/Makefile only adds architecture-specific directories. - - Example: - #arch/sparc64/Makefile - core-y += arch/sparc64/kernel/ - libs-y += arch/sparc64/prom/ arch/sparc64/lib/ - drivers-$(CONFIG_OPROFILE) += arch/sparc64/oprofile/ - - ---- 6.5 Architecture-specific boot images - - An arch Makefile specifies goals that take the vmlinux file, compress - it, wrap it in bootstrapping code, and copy the resulting files - somewhere. This includes various kinds of installation commands. - The actual goals are not standardized across architectures. - - It is common to locate any additional processing in a boot/ - directory below arch/$(ARCH)/. - - Kbuild does not provide any smart way to support building a - target specified in boot/. Therefore arch/$(ARCH)/Makefile shall - call make manually to build a target in boot/. - - The recommended approach is to include shortcuts in - arch/$(ARCH)/Makefile, and use the full path when calling down - into the arch/$(ARCH)/boot/Makefile. - - Example: - #arch/x86/Makefile - boot := arch/x86/boot - bzImage: vmlinux - $(Q)$(MAKE) $(build)=$(boot) $(boot)/$@ - - "$(Q)$(MAKE) $(build)=" is the recommended way to invoke - make in a subdirectory. - - There are no rules for naming architecture-specific targets, - but executing "make help" will list all relevant targets. - To support this, $(archhelp) must be defined. - - Example: - #arch/x86/Makefile - define archhelp - echo '* bzImage - Image (arch/$(ARCH)/boot/bzImage)' - endif - - When make is executed without arguments, the first goal encountered - will be built. In the top level Makefile the first goal present - is all:. - An architecture shall always, per default, build a bootable image. - In "make help", the default goal is highlighted with a '*'. - Add a new prerequisite to all: to select a default goal different - from vmlinux. - - Example: - #arch/x86/Makefile - all: bzImage - - When "make" is executed without arguments, bzImage will be built. - ---- 6.6 Building non-kbuild targets - - extra-y - - extra-y specifies additional targets created in the current - directory, in addition to any targets specified by obj-*. - - Listing all targets in extra-y is required for two purposes: - 1) Enable kbuild to check changes in command lines - - When $(call if_changed,xxx) is used - 2) kbuild knows what files to delete during "make clean" - - Example: - #arch/x86/kernel/Makefile - extra-y := head.o init_task.o - - In this example, extra-y is used to list object files that - shall be built, but shall not be linked as part of built-in.a. - - ---- 6.7 Commands useful for building a boot image - - Kbuild provides a few macros that are useful when building a - boot image. - - if_changed - - if_changed is the infrastructure used for the following commands. - - Usage: - target: source(s) FORCE - $(call if_changed,ld/objcopy/gzip/...) - - When the rule is evaluated, it is checked to see if any files - need an update, or the command line has changed since the last - invocation. The latter will force a rebuild if any options - to the executable have changed. - Any target that utilises if_changed must be listed in $(targets), - otherwise the command line check will fail, and the target will - always be built. - Assignments to $(targets) are without $(obj)/ prefix. - if_changed may be used in conjunction with custom commands as - defined in 6.8 "Custom kbuild commands". - - Note: It is a typical mistake to forget the FORCE prerequisite. - Another common pitfall is that whitespace is sometimes - significant; for instance, the below will fail (note the extra space - after the comma): - target: source(s) FORCE - #WRONG!# $(call if_changed, ld/objcopy/gzip/...) - - Note: if_changed should not be used more than once per target. - It stores the executed command in a corresponding .cmd - file and multiple calls would result in overwrites and - unwanted results when the target is up to date and only the - tests on changed commands trigger execution of commands. - - ld - Link target. Often, LDFLAGS_$@ is used to set specific options to ld. - - Example: - #arch/x86/boot/Makefile - LDFLAGS_bootsect := -Ttext 0x0 -s --oformat binary - LDFLAGS_setup := -Ttext 0x0 -s --oformat binary -e begtext - - targets += setup setup.o bootsect bootsect.o - $(obj)/setup $(obj)/bootsect: %: %.o FORCE - $(call if_changed,ld) - - In this example, there are two possible targets, requiring different - options to the linker. The linker options are specified using the - LDFLAGS_$@ syntax - one for each potential target. - $(targets) are assigned all potential targets, by which kbuild knows - the targets and will: - 1) check for commandline changes - 2) delete target during make clean - - The ": %: %.o" part of the prerequisite is a shorthand that - frees us from listing the setup.o and bootsect.o files. - Note: It is a common mistake to forget the "targets :=" assignment, - resulting in the target file being recompiled for no - obvious reason. - - objcopy - Copy binary. Uses OBJCOPYFLAGS usually specified in - arch/$(ARCH)/Makefile. - OBJCOPYFLAGS_$@ may be used to set additional options. - - gzip - Compress target. Use maximum compression to compress target. - - Example: - #arch/x86/boot/compressed/Makefile - $(obj)/vmlinux.bin.gz: $(vmlinux.bin.all-y) FORCE - $(call if_changed,gzip) - - dtc - Create flattened device tree blob object suitable for linking - into vmlinux. Device tree blobs linked into vmlinux are placed - in an init section in the image. Platform code *must* copy the - blob to non-init memory prior to calling unflatten_device_tree(). - - To use this command, simply add *.dtb into obj-y or targets, or make - some other target depend on %.dtb - - A central rule exists to create $(obj)/%.dtb from $(src)/%.dts; - architecture Makefiles do no need to explicitly write out that rule. - - Example: - targets += $(dtb-y) - DTC_FLAGS ?= -p 1024 - ---- 6.8 Custom kbuild commands - - When kbuild is executing with KBUILD_VERBOSE=0, then only a shorthand - of a command is normally displayed. - To enable this behaviour for custom commands kbuild requires - two variables to be set: - quiet_cmd_ - what shall be echoed - cmd_ - the command to execute - - Example: - # - quiet_cmd_image = BUILD $@ - cmd_image = $(obj)/tools/build $(BUILDFLAGS) \ - $(obj)/vmlinux.bin > $@ - - targets += bzImage - $(obj)/bzImage: $(obj)/vmlinux.bin $(obj)/tools/build FORCE - $(call if_changed,image) - @echo 'Kernel: $@ is ready' - - When updating the $(obj)/bzImage target, the line - - BUILD arch/x86/boot/bzImage - - will be displayed with "make KBUILD_VERBOSE=0". - - ---- 6.9 Preprocessing linker scripts - - When the vmlinux image is built, the linker script - arch/$(ARCH)/kernel/vmlinux.lds is used. - The script is a preprocessed variant of the file vmlinux.lds.S - located in the same directory. - kbuild knows .lds files and includes a rule *lds.S -> *lds. - - Example: - #arch/x86/kernel/Makefile - always := vmlinux.lds - - #Makefile - export CPPFLAGS_vmlinux.lds += -P -C -U$(ARCH) - - The assignment to $(always) is used to tell kbuild to build the - target vmlinux.lds. - The assignment to $(CPPFLAGS_vmlinux.lds) tells kbuild to use the - specified options when building the target vmlinux.lds. - - When building the *.lds target, kbuild uses the variables: - KBUILD_CPPFLAGS : Set in top-level Makefile - cppflags-y : May be set in the kbuild makefile - CPPFLAGS_$(@F) : Target-specific flags. - Note that the full filename is used in this - assignment. - - The kbuild infrastructure for *lds files is used in several - architecture-specific files. - ---- 6.10 Generic header files - - The directory include/asm-generic contains the header files - that may be shared between individual architectures. - The recommended approach how to use a generic header file is - to list the file in the Kbuild file. - See "7.2 generic-y" for further info on syntax etc. - ---- 6.11 Post-link pass - - If the file arch/xxx/Makefile.postlink exists, this makefile - will be invoked for post-link objects (vmlinux and modules.ko) - for architectures to run post-link passes on. Must also handle - the clean target. - - This pass runs after kallsyms generation. If the architecture - needs to modify symbol locations, rather than manipulate the - kallsyms, it may be easier to add another postlink target for - .tmp_vmlinux? targets to be called from link-vmlinux.sh. - - For example, powerpc uses this to check relocation sanity of - the linked vmlinux file. - -=== 7 Kbuild syntax for exported headers - -The kernel includes a set of headers that is exported to userspace. -Many headers can be exported as-is but other headers require a -minimal pre-processing before they are ready for user-space. -The pre-processing does: -- drop kernel-specific annotations -- drop include of compiler.h -- drop all sections that are kernel internal (guarded by ifdef __KERNEL__) - -All headers under include/uapi/, include/generated/uapi/, -arch//include/uapi/ and arch//include/generated/uapi/ -are exported. - -A Kbuild file may be defined under arch//include/uapi/asm/ and -arch//include/asm/ to list asm files coming from asm-generic. -See subsequent chapter for the syntax of the Kbuild file. - ---- 7.1 no-export-headers - - no-export-headers is essentially used by include/uapi/linux/Kbuild to - avoid exporting specific headers (e.g. kvm.h) on architectures that do - not support it. It should be avoided as much as possible. - ---- 7.2 generic-y - - If an architecture uses a verbatim copy of a header from - include/asm-generic then this is listed in the file - arch/$(ARCH)/include/asm/Kbuild like this: - - Example: - #arch/x86/include/asm/Kbuild - generic-y += termios.h - generic-y += rtc.h - - During the prepare phase of the build a wrapper include - file is generated in the directory: - - arch/$(ARCH)/include/generated/asm - - When a header is exported where the architecture uses - the generic header a similar wrapper is generated as part - of the set of exported headers in the directory: - - usr/include/asm - - The generated wrapper will in both cases look like the following: - - Example: termios.h - #include - ---- 7.3 generated-y - - If an architecture generates other header files alongside generic-y - wrappers, generated-y specifies them. - - This prevents them being treated as stale asm-generic wrappers and - removed. - - Example: - #arch/x86/include/asm/Kbuild - generated-y += syscalls_32.h - ---- 7.4 mandatory-y - - mandatory-y is essentially used by include/(uapi/)asm-generic/Kbuild - to define the minimum set of ASM headers that all architectures must have. - - This works like optional generic-y. If a mandatory header is missing - in arch/$(ARCH)/include/(uapi/)/asm, Kbuild will automatically generate - a wrapper of the asm-generic one. - - The convention is to list one subdir per line and - preferably in alphabetic order. - -=== 8 Kbuild Variables - -The top Makefile exports the following variables: - - VERSION, PATCHLEVEL, SUBLEVEL, EXTRAVERSION - - These variables define the current kernel version. A few arch - Makefiles actually use these values directly; they should use - $(KERNELRELEASE) instead. - - $(VERSION), $(PATCHLEVEL), and $(SUBLEVEL) define the basic - three-part version number, such as "2", "4", and "0". These three - values are always numeric. - - $(EXTRAVERSION) defines an even tinier sublevel for pre-patches - or additional patches. It is usually some non-numeric string - such as "-pre4", and is often blank. - - KERNELRELEASE - - $(KERNELRELEASE) is a single string such as "2.4.0-pre4", suitable - for constructing installation directory names or showing in - version strings. Some arch Makefiles use it for this purpose. - - ARCH - - This variable defines the target architecture, such as "i386", - "arm", or "sparc". Some kbuild Makefiles test $(ARCH) to - determine which files to compile. - - By default, the top Makefile sets $(ARCH) to be the same as the - host system architecture. For a cross build, a user may - override the value of $(ARCH) on the command line: - - make ARCH=m68k ... - - - INSTALL_PATH - - This variable defines a place for the arch Makefiles to install - the resident kernel image and System.map file. - Use this for architecture-specific install targets. - - INSTALL_MOD_PATH, MODLIB - - $(INSTALL_MOD_PATH) specifies a prefix to $(MODLIB) for module - installation. This variable is not defined in the Makefile but - may be passed in by the user if desired. - - $(MODLIB) specifies the directory for module installation. - The top Makefile defines $(MODLIB) to - $(INSTALL_MOD_PATH)/lib/modules/$(KERNELRELEASE). The user may - override this value on the command line if desired. - - INSTALL_MOD_STRIP - - If this variable is specified, it will cause modules to be stripped - after they are installed. If INSTALL_MOD_STRIP is '1', then the - default option --strip-debug will be used. Otherwise, the - INSTALL_MOD_STRIP value will be used as the option(s) to the strip - command. - - -=== 9 Makefile language - -The kernel Makefiles are designed to be run with GNU Make. The Makefiles -use only the documented features of GNU Make, but they do use many -GNU extensions. - -GNU Make supports elementary list-processing functions. The kernel -Makefiles use a novel style of list building and manipulation with few -"if" statements. - -GNU Make has two assignment operators, ":=" and "=". ":=" performs -immediate evaluation of the right-hand side and stores an actual string -into the left-hand side. "=" is like a formula definition; it stores the -right-hand side in an unevaluated form and then evaluates this form each -time the left-hand side is used. - -There are some cases where "=" is appropriate. Usually, though, ":=" -is the right choice. - -=== 10 Credits - -Original version made by Michael Elizabeth Chastain, -Updates by Kai Germaschewski -Updates by Sam Ravnborg -Language QA by Jan Engelhardt - -=== 11 TODO - -- Describe how kbuild supports shipped files with _shipped. -- Generating offset header files. -- Add more variables to section 7? - - - diff --git a/Documentation/kbuild/modules.rst b/Documentation/kbuild/modules.rst new file mode 100644 index 000000000000..24e763482650 --- /dev/null +++ b/Documentation/kbuild/modules.rst @@ -0,0 +1,571 @@ +========================= +Building External Modules +========================= + +This document describes how to build an out-of-tree kernel module. + +.. Table of Contents + + === 1 Introduction + === 2 How to Build External Modules + --- 2.1 Command Syntax + --- 2.2 Options + --- 2.3 Targets + --- 2.4 Building Separate Files + === 3. Creating a Kbuild File for an External Module + --- 3.1 Shared Makefile + --- 3.2 Separate Kbuild file and Makefile + --- 3.3 Binary Blobs + --- 3.4 Building Multiple Modules + === 4. Include Files + --- 4.1 Kernel Includes + --- 4.2 Single Subdirectory + --- 4.3 Several Subdirectories + === 5. Module Installation + --- 5.1 INSTALL_MOD_PATH + --- 5.2 INSTALL_MOD_DIR + === 6. Module Versioning + --- 6.1 Symbols From the Kernel (vmlinux + modules) + --- 6.2 Symbols and External Modules + --- 6.3 Symbols From Another External Module + === 7. Tips & Tricks + --- 7.1 Testing for CONFIG_FOO_BAR + + + +1. Introduction +=============== + +"kbuild" is the build system used by the Linux kernel. Modules must use +kbuild to stay compatible with changes in the build infrastructure and +to pick up the right flags to "gcc." Functionality for building modules +both in-tree and out-of-tree is provided. The method for building +either is similar, and all modules are initially developed and built +out-of-tree. + +Covered in this document is information aimed at developers interested +in building out-of-tree (or "external") modules. The author of an +external module should supply a makefile that hides most of the +complexity, so one only has to type "make" to build the module. This is +easily accomplished, and a complete example will be presented in +section 3. + + +2. How to Build External Modules +================================ + +To build external modules, you must have a prebuilt kernel available +that contains the configuration and header files used in the build. +Also, the kernel must have been built with modules enabled. If you are +using a distribution kernel, there will be a package for the kernel you +are running provided by your distribution. + +An alternative is to use the "make" target "modules_prepare." This will +make sure the kernel contains the information required. The target +exists solely as a simple way to prepare a kernel source tree for +building external modules. + +NOTE: "modules_prepare" will not build Module.symvers even if +CONFIG_MODVERSIONS is set; therefore, a full kernel build needs to be +executed to make module versioning work. + +2.1 Command Syntax +================== + + The command to build an external module is:: + + $ make -C M=$PWD + + The kbuild system knows that an external module is being built + due to the "M=" option given in the command. + + To build against the running kernel use:: + + $ make -C /lib/modules/`uname -r`/build M=$PWD + + Then to install the module(s) just built, add the target + "modules_install" to the command:: + + $ make -C /lib/modules/`uname -r`/build M=$PWD modules_install + +2.2 Options +=========== + + ($KDIR refers to the path of the kernel source directory.) + + make -C $KDIR M=$PWD + + -C $KDIR + The directory where the kernel source is located. + "make" will actually change to the specified directory + when executing and will change back when finished. + + M=$PWD + Informs kbuild that an external module is being built. + The value given to "M" is the absolute path of the + directory where the external module (kbuild file) is + located. + +2.3 Targets +=========== + + When building an external module, only a subset of the "make" + targets are available. + + make -C $KDIR M=$PWD [target] + + The default will build the module(s) located in the current + directory, so a target does not need to be specified. All + output files will also be generated in this directory. No + attempts are made to update the kernel source, and it is a + precondition that a successful "make" has been executed for the + kernel. + + modules + The default target for external modules. It has the + same functionality as if no target was specified. See + description above. + + modules_install + Install the external module(s). The default location is + /lib/modules//extra/, but a prefix may + be added with INSTALL_MOD_PATH (discussed in section 5). + + clean + Remove all generated files in the module directory only. + + help + List the available targets for external modules. + +2.4 Building Separate Files +=========================== + + It is possible to build single files that are part of a module. + This works equally well for the kernel, a module, and even for + external modules. + + Example (The module foo.ko, consist of bar.o and baz.o):: + + make -C $KDIR M=$PWD bar.lst + make -C $KDIR M=$PWD baz.o + make -C $KDIR M=$PWD foo.ko + make -C $KDIR M=$PWD ./ + + +3. Creating a Kbuild File for an External Module +================================================ + +In the last section we saw the command to build a module for the +running kernel. The module is not actually built, however, because a +build file is required. Contained in this file will be the name of +the module(s) being built, along with the list of requisite source +files. The file may be as simple as a single line:: + + obj-m := .o + +The kbuild system will build .o from .c, +and, after linking, will result in the kernel module .ko. +The above line can be put in either a "Kbuild" file or a "Makefile." +When the module is built from multiple sources, an additional line is +needed listing the files:: + + -y := .o .o ... + +NOTE: Further documentation describing the syntax used by kbuild is +located in Documentation/kbuild/makefiles.rst. + +The examples below demonstrate how to create a build file for the +module 8123.ko, which is built from the following files:: + + 8123_if.c + 8123_if.h + 8123_pci.c + 8123_bin.o_shipped <= Binary blob + +--- 3.1 Shared Makefile + + An external module always includes a wrapper makefile that + supports building the module using "make" with no arguments. + This target is not used by kbuild; it is only for convenience. + Additional functionality, such as test targets, can be included + but should be filtered out from kbuild due to possible name + clashes. + + Example 1:: + + --> filename: Makefile + ifneq ($(KERNELRELEASE),) + # kbuild part of makefile + obj-m := 8123.o + 8123-y := 8123_if.o 8123_pci.o 8123_bin.o + + else + # normal makefile + KDIR ?= /lib/modules/`uname -r`/build + + default: + $(MAKE) -C $(KDIR) M=$$PWD + + # Module specific targets + genbin: + echo "X" > 8123_bin.o_shipped + + endif + + The check for KERNELRELEASE is used to separate the two parts + of the makefile. In the example, kbuild will only see the two + assignments, whereas "make" will see everything except these + two assignments. This is due to two passes made on the file: + the first pass is by the "make" instance run on the command + line; the second pass is by the kbuild system, which is + initiated by the parameterized "make" in the default target. + +3.2 Separate Kbuild File and Makefile +------------------------------------- + + In newer versions of the kernel, kbuild will first look for a + file named "Kbuild," and only if that is not found, will it + then look for a makefile. Utilizing a "Kbuild" file allows us + to split up the makefile from example 1 into two files: + + Example 2:: + + --> filename: Kbuild + obj-m := 8123.o + 8123-y := 8123_if.o 8123_pci.o 8123_bin.o + + --> filename: Makefile + KDIR ?= /lib/modules/`uname -r`/build + + default: + $(MAKE) -C $(KDIR) M=$$PWD + + # Module specific targets + genbin: + echo "X" > 8123_bin.o_shipped + + The split in example 2 is questionable due to the simplicity of + each file; however, some external modules use makefiles + consisting of several hundred lines, and here it really pays + off to separate the kbuild part from the rest. + + The next example shows a backward compatible version. + + Example 3:: + + --> filename: Kbuild + obj-m := 8123.o + 8123-y := 8123_if.o 8123_pci.o 8123_bin.o + + --> filename: Makefile + ifneq ($(KERNELRELEASE),) + # kbuild part of makefile + include Kbuild + + else + # normal makefile + KDIR ?= /lib/modules/`uname -r`/build + + default: + $(MAKE) -C $(KDIR) M=$$PWD + + # Module specific targets + genbin: + echo "X" > 8123_bin.o_shipped + + endif + + Here the "Kbuild" file is included from the makefile. This + allows an older version of kbuild, which only knows of + makefiles, to be used when the "make" and kbuild parts are + split into separate files. + +3.3 Binary Blobs +---------------- + + Some external modules need to include an object file as a blob. + kbuild has support for this, but requires the blob file to be + named _shipped. When the kbuild rules kick in, a copy + of _shipped is created with _shipped stripped off, + giving us . This shortened filename can be used in + the assignment to the module. + + Throughout this section, 8123_bin.o_shipped has been used to + build the kernel module 8123.ko; it has been included as + 8123_bin.o:: + + 8123-y := 8123_if.o 8123_pci.o 8123_bin.o + + Although there is no distinction between the ordinary source + files and the binary file, kbuild will pick up different rules + when creating the object file for the module. + +3.4 Building Multiple Modules +============================= + + kbuild supports building multiple modules with a single build + file. For example, if you wanted to build two modules, foo.ko + and bar.ko, the kbuild lines would be:: + + obj-m := foo.o bar.o + foo-y := + bar-y := + + It is that simple! + + +4. Include Files +================ + +Within the kernel, header files are kept in standard locations +according to the following rule: + + * If the header file only describes the internal interface of a + module, then the file is placed in the same directory as the + source files. + * If the header file describes an interface used by other parts + of the kernel that are located in different directories, then + the file is placed in include/linux/. + + NOTE: + There are two notable exceptions to this rule: larger + subsystems have their own directory under include/, such as + include/scsi; and architecture specific headers are located + under arch/$(ARCH)/include/. + +4.1 Kernel Includes +------------------- + + To include a header file located under include/linux/, simply + use:: + + #include + + kbuild will add options to "gcc" so the relevant directories + are searched. + +4.2 Single Subdirectory +----------------------- + + External modules tend to place header files in a separate + include/ directory where their source is located, although this + is not the usual kernel style. To inform kbuild of the + directory, use either ccflags-y or CFLAGS_.o. + + Using the example from section 3, if we moved 8123_if.h to a + subdirectory named include, the resulting kbuild file would + look like:: + + --> filename: Kbuild + obj-m := 8123.o + + ccflags-y := -Iinclude + 8123-y := 8123_if.o 8123_pci.o 8123_bin.o + + Note that in the assignment there is no space between -I and + the path. This is a limitation of kbuild: there must be no + space present. + +4.3 Several Subdirectories +-------------------------- + + kbuild can handle files that are spread over several directories. + Consider the following example:: + + . + |__ src + | |__ complex_main.c + | |__ hal + | |__ hardwareif.c + | |__ include + | |__ hardwareif.h + |__ include + |__ complex.h + + To build the module complex.ko, we then need the following + kbuild file:: + + --> filename: Kbuild + obj-m := complex.o + complex-y := src/complex_main.o + complex-y += src/hal/hardwareif.o + + ccflags-y := -I$(src)/include + ccflags-y += -I$(src)/src/hal/include + + As you can see, kbuild knows how to handle object files located + in other directories. The trick is to specify the directory + relative to the kbuild file's location. That being said, this + is NOT recommended practice. + + For the header files, kbuild must be explicitly told where to + look. When kbuild executes, the current directory is always the + root of the kernel tree (the argument to "-C") and therefore an + absolute path is needed. $(src) provides the absolute path by + pointing to the directory where the currently executing kbuild + file is located. + + +5. Module Installation +====================== + +Modules which are included in the kernel are installed in the +directory: + + /lib/modules/$(KERNELRELEASE)/kernel/ + +And external modules are installed in: + + /lib/modules/$(KERNELRELEASE)/extra/ + +5.1 INSTALL_MOD_PATH +-------------------- + + Above are the default directories but as always some level of + customization is possible. A prefix can be added to the + installation path using the variable INSTALL_MOD_PATH:: + + $ make INSTALL_MOD_PATH=/frodo modules_install + => Install dir: /frodo/lib/modules/$(KERNELRELEASE)/kernel/ + + INSTALL_MOD_PATH may be set as an ordinary shell variable or, + as shown above, can be specified on the command line when + calling "make." This has effect when installing both in-tree + and out-of-tree modules. + +5.2 INSTALL_MOD_DIR +------------------- + + External modules are by default installed to a directory under + /lib/modules/$(KERNELRELEASE)/extra/, but you may wish to + locate modules for a specific functionality in a separate + directory. For this purpose, use INSTALL_MOD_DIR to specify an + alternative name to "extra.":: + + $ make INSTALL_MOD_DIR=gandalf -C $KDIR \ + M=$PWD modules_install + => Install dir: /lib/modules/$(KERNELRELEASE)/gandalf/ + + +6. Module Versioning +==================== + +Module versioning is enabled by the CONFIG_MODVERSIONS tag, and is used +as a simple ABI consistency check. A CRC value of the full prototype +for an exported symbol is created. When a module is loaded/used, the +CRC values contained in the kernel are compared with similar values in +the module; if they are not equal, the kernel refuses to load the +module. + +Module.symvers contains a list of all exported symbols from a kernel +build. + +6.1 Symbols From the Kernel (vmlinux + modules) +----------------------------------------------- + + During a kernel build, a file named Module.symvers will be + generated. Module.symvers contains all exported symbols from + the kernel and compiled modules. For each symbol, the + corresponding CRC value is also stored. + + The syntax of the Module.symvers file is:: + + + + 0x2d036834 scsi_remove_host drivers/scsi/scsi_mod + + For a kernel build without CONFIG_MODVERSIONS enabled, the CRC + would read 0x00000000. + + Module.symvers serves two purposes: + + 1) It lists all exported symbols from vmlinux and all modules. + 2) It lists the CRC if CONFIG_MODVERSIONS is enabled. + +6.2 Symbols and External Modules +-------------------------------- + + When building an external module, the build system needs access + to the symbols from the kernel to check if all external symbols + are defined. This is done in the MODPOST step. modpost obtains + the symbols by reading Module.symvers from the kernel source + tree. If a Module.symvers file is present in the directory + where the external module is being built, this file will be + read too. During the MODPOST step, a new Module.symvers file + will be written containing all exported symbols that were not + defined in the kernel. + +--- 6.3 Symbols From Another External Module + + Sometimes, an external module uses exported symbols from + another external module. kbuild needs to have full knowledge of + all symbols to avoid spitting out warnings about undefined + symbols. Three solutions exist for this situation. + + NOTE: The method with a top-level kbuild file is recommended + but may be impractical in certain situations. + + Use a top-level kbuild file + If you have two modules, foo.ko and bar.ko, where + foo.ko needs symbols from bar.ko, you can use a + common top-level kbuild file so both modules are + compiled in the same build. Consider the following + directory layout:: + + ./foo/ <= contains foo.ko + ./bar/ <= contains bar.ko + + The top-level kbuild file would then look like:: + + #./Kbuild (or ./Makefile): + obj-y := foo/ bar/ + + And executing:: + + $ make -C $KDIR M=$PWD + + will then do the expected and compile both modules with + full knowledge of symbols from either module. + + Use an extra Module.symvers file + When an external module is built, a Module.symvers file + is generated containing all exported symbols which are + not defined in the kernel. To get access to symbols + from bar.ko, copy the Module.symvers file from the + compilation of bar.ko to the directory where foo.ko is + built. During the module build, kbuild will read the + Module.symvers file in the directory of the external + module, and when the build is finished, a new + Module.symvers file is created containing the sum of + all symbols defined and not part of the kernel. + + Use "make" variable KBUILD_EXTRA_SYMBOLS + If it is impractical to copy Module.symvers from + another module, you can assign a space separated list + of files to KBUILD_EXTRA_SYMBOLS in your build file. + These files will be loaded by modpost during the + initialization of its symbol tables. + + +7. Tips & Tricks +================ + +7.1 Testing for CONFIG_FOO_BAR +------------------------------ + + Modules often need to check for certain `CONFIG_` options to + decide if a specific feature is included in the module. In + kbuild this is done by referencing the `CONFIG_` variable + directly:: + + #fs/ext2/Makefile + obj-$(CONFIG_EXT2_FS) += ext2.o + + ext2-y := balloc.o bitmap.o dir.o + ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o + + External modules have traditionally used "grep" to check for + specific `CONFIG_` settings directly in .config. This usage is + broken. As introduced before, external modules should use + kbuild for building and can therefore use the same methods as + in-tree modules when testing for `CONFIG_` definitions. diff --git a/Documentation/kbuild/modules.txt b/Documentation/kbuild/modules.txt deleted file mode 100644 index 80295c613e37..000000000000 --- a/Documentation/kbuild/modules.txt +++ /dev/null @@ -1,541 +0,0 @@ -Building External Modules - -This document describes how to build an out-of-tree kernel module. - -=== Table of Contents - - === 1 Introduction - === 2 How to Build External Modules - --- 2.1 Command Syntax - --- 2.2 Options - --- 2.3 Targets - --- 2.4 Building Separate Files - === 3. Creating a Kbuild File for an External Module - --- 3.1 Shared Makefile - --- 3.2 Separate Kbuild file and Makefile - --- 3.3 Binary Blobs - --- 3.4 Building Multiple Modules - === 4. Include Files - --- 4.1 Kernel Includes - --- 4.2 Single Subdirectory - --- 4.3 Several Subdirectories - === 5. Module Installation - --- 5.1 INSTALL_MOD_PATH - --- 5.2 INSTALL_MOD_DIR - === 6. Module Versioning - --- 6.1 Symbols From the Kernel (vmlinux + modules) - --- 6.2 Symbols and External Modules - --- 6.3 Symbols From Another External Module - === 7. Tips & Tricks - --- 7.1 Testing for CONFIG_FOO_BAR - - - -=== 1. Introduction - -"kbuild" is the build system used by the Linux kernel. Modules must use -kbuild to stay compatible with changes in the build infrastructure and -to pick up the right flags to "gcc." Functionality for building modules -both in-tree and out-of-tree is provided. The method for building -either is similar, and all modules are initially developed and built -out-of-tree. - -Covered in this document is information aimed at developers interested -in building out-of-tree (or "external") modules. The author of an -external module should supply a makefile that hides most of the -complexity, so one only has to type "make" to build the module. This is -easily accomplished, and a complete example will be presented in -section 3. - - -=== 2. How to Build External Modules - -To build external modules, you must have a prebuilt kernel available -that contains the configuration and header files used in the build. -Also, the kernel must have been built with modules enabled. If you are -using a distribution kernel, there will be a package for the kernel you -are running provided by your distribution. - -An alternative is to use the "make" target "modules_prepare." This will -make sure the kernel contains the information required. The target -exists solely as a simple way to prepare a kernel source tree for -building external modules. - -NOTE: "modules_prepare" will not build Module.symvers even if -CONFIG_MODVERSIONS is set; therefore, a full kernel build needs to be -executed to make module versioning work. - ---- 2.1 Command Syntax - - The command to build an external module is: - - $ make -C M=$PWD - - The kbuild system knows that an external module is being built - due to the "M=" option given in the command. - - To build against the running kernel use: - - $ make -C /lib/modules/`uname -r`/build M=$PWD - - Then to install the module(s) just built, add the target - "modules_install" to the command: - - $ make -C /lib/modules/`uname -r`/build M=$PWD modules_install - ---- 2.2 Options - - ($KDIR refers to the path of the kernel source directory.) - - make -C $KDIR M=$PWD - - -C $KDIR - The directory where the kernel source is located. - "make" will actually change to the specified directory - when executing and will change back when finished. - - M=$PWD - Informs kbuild that an external module is being built. - The value given to "M" is the absolute path of the - directory where the external module (kbuild file) is - located. - ---- 2.3 Targets - - When building an external module, only a subset of the "make" - targets are available. - - make -C $KDIR M=$PWD [target] - - The default will build the module(s) located in the current - directory, so a target does not need to be specified. All - output files will also be generated in this directory. No - attempts are made to update the kernel source, and it is a - precondition that a successful "make" has been executed for the - kernel. - - modules - The default target for external modules. It has the - same functionality as if no target was specified. See - description above. - - modules_install - Install the external module(s). The default location is - /lib/modules//extra/, but a prefix may - be added with INSTALL_MOD_PATH (discussed in section 5). - - clean - Remove all generated files in the module directory only. - - help - List the available targets for external modules. - ---- 2.4 Building Separate Files - - It is possible to build single files that are part of a module. - This works equally well for the kernel, a module, and even for - external modules. - - Example (The module foo.ko, consist of bar.o and baz.o): - make -C $KDIR M=$PWD bar.lst - make -C $KDIR M=$PWD baz.o - make -C $KDIR M=$PWD foo.ko - make -C $KDIR M=$PWD ./ - - -=== 3. Creating a Kbuild File for an External Module - -In the last section we saw the command to build a module for the -running kernel. The module is not actually built, however, because a -build file is required. Contained in this file will be the name of -the module(s) being built, along with the list of requisite source -files. The file may be as simple as a single line: - - obj-m := .o - -The kbuild system will build .o from .c, -and, after linking, will result in the kernel module .ko. -The above line can be put in either a "Kbuild" file or a "Makefile." -When the module is built from multiple sources, an additional line is -needed listing the files: - - -y := .o .o ... - -NOTE: Further documentation describing the syntax used by kbuild is -located in Documentation/kbuild/makefiles.txt. - -The examples below demonstrate how to create a build file for the -module 8123.ko, which is built from the following files: - - 8123_if.c - 8123_if.h - 8123_pci.c - 8123_bin.o_shipped <= Binary blob - ---- 3.1 Shared Makefile - - An external module always includes a wrapper makefile that - supports building the module using "make" with no arguments. - This target is not used by kbuild; it is only for convenience. - Additional functionality, such as test targets, can be included - but should be filtered out from kbuild due to possible name - clashes. - - Example 1: - --> filename: Makefile - ifneq ($(KERNELRELEASE),) - # kbuild part of makefile - obj-m := 8123.o - 8123-y := 8123_if.o 8123_pci.o 8123_bin.o - - else - # normal makefile - KDIR ?= /lib/modules/`uname -r`/build - - default: - $(MAKE) -C $(KDIR) M=$$PWD - - # Module specific targets - genbin: - echo "X" > 8123_bin.o_shipped - - endif - - The check for KERNELRELEASE is used to separate the two parts - of the makefile. In the example, kbuild will only see the two - assignments, whereas "make" will see everything except these - two assignments. This is due to two passes made on the file: - the first pass is by the "make" instance run on the command - line; the second pass is by the kbuild system, which is - initiated by the parameterized "make" in the default target. - ---- 3.2 Separate Kbuild File and Makefile - - In newer versions of the kernel, kbuild will first look for a - file named "Kbuild," and only if that is not found, will it - then look for a makefile. Utilizing a "Kbuild" file allows us - to split up the makefile from example 1 into two files: - - Example 2: - --> filename: Kbuild - obj-m := 8123.o - 8123-y := 8123_if.o 8123_pci.o 8123_bin.o - - --> filename: Makefile - KDIR ?= /lib/modules/`uname -r`/build - - default: - $(MAKE) -C $(KDIR) M=$$PWD - - # Module specific targets - genbin: - echo "X" > 8123_bin.o_shipped - - The split in example 2 is questionable due to the simplicity of - each file; however, some external modules use makefiles - consisting of several hundred lines, and here it really pays - off to separate the kbuild part from the rest. - - The next example shows a backward compatible version. - - Example 3: - --> filename: Kbuild - obj-m := 8123.o - 8123-y := 8123_if.o 8123_pci.o 8123_bin.o - - --> filename: Makefile - ifneq ($(KERNELRELEASE),) - # kbuild part of makefile - include Kbuild - - else - # normal makefile - KDIR ?= /lib/modules/`uname -r`/build - - default: - $(MAKE) -C $(KDIR) M=$$PWD - - # Module specific targets - genbin: - echo "X" > 8123_bin.o_shipped - - endif - - Here the "Kbuild" file is included from the makefile. This - allows an older version of kbuild, which only knows of - makefiles, to be used when the "make" and kbuild parts are - split into separate files. - ---- 3.3 Binary Blobs - - Some external modules need to include an object file as a blob. - kbuild has support for this, but requires the blob file to be - named _shipped. When the kbuild rules kick in, a copy - of _shipped is created with _shipped stripped off, - giving us . This shortened filename can be used in - the assignment to the module. - - Throughout this section, 8123_bin.o_shipped has been used to - build the kernel module 8123.ko; it has been included as - 8123_bin.o. - - 8123-y := 8123_if.o 8123_pci.o 8123_bin.o - - Although there is no distinction between the ordinary source - files and the binary file, kbuild will pick up different rules - when creating the object file for the module. - ---- 3.4 Building Multiple Modules - - kbuild supports building multiple modules with a single build - file. For example, if you wanted to build two modules, foo.ko - and bar.ko, the kbuild lines would be: - - obj-m := foo.o bar.o - foo-y := - bar-y := - - It is that simple! - - -=== 4. Include Files - -Within the kernel, header files are kept in standard locations -according to the following rule: - - * If the header file only describes the internal interface of a - module, then the file is placed in the same directory as the - source files. - * If the header file describes an interface used by other parts - of the kernel that are located in different directories, then - the file is placed in include/linux/. - - NOTE: There are two notable exceptions to this rule: larger - subsystems have their own directory under include/, such as - include/scsi; and architecture specific headers are located - under arch/$(ARCH)/include/. - ---- 4.1 Kernel Includes - - To include a header file located under include/linux/, simply - use: - - #include - - kbuild will add options to "gcc" so the relevant directories - are searched. - ---- 4.2 Single Subdirectory - - External modules tend to place header files in a separate - include/ directory where their source is located, although this - is not the usual kernel style. To inform kbuild of the - directory, use either ccflags-y or CFLAGS_.o. - - Using the example from section 3, if we moved 8123_if.h to a - subdirectory named include, the resulting kbuild file would - look like: - - --> filename: Kbuild - obj-m := 8123.o - - ccflags-y := -Iinclude - 8123-y := 8123_if.o 8123_pci.o 8123_bin.o - - Note that in the assignment there is no space between -I and - the path. This is a limitation of kbuild: there must be no - space present. - ---- 4.3 Several Subdirectories - - kbuild can handle files that are spread over several directories. - Consider the following example: - - . - |__ src - | |__ complex_main.c - | |__ hal - | |__ hardwareif.c - | |__ include - | |__ hardwareif.h - |__ include - |__ complex.h - - To build the module complex.ko, we then need the following - kbuild file: - - --> filename: Kbuild - obj-m := complex.o - complex-y := src/complex_main.o - complex-y += src/hal/hardwareif.o - - ccflags-y := -I$(src)/include - ccflags-y += -I$(src)/src/hal/include - - As you can see, kbuild knows how to handle object files located - in other directories. The trick is to specify the directory - relative to the kbuild file's location. That being said, this - is NOT recommended practice. - - For the header files, kbuild must be explicitly told where to - look. When kbuild executes, the current directory is always the - root of the kernel tree (the argument to "-C") and therefore an - absolute path is needed. $(src) provides the absolute path by - pointing to the directory where the currently executing kbuild - file is located. - - -=== 5. Module Installation - -Modules which are included in the kernel are installed in the -directory: - - /lib/modules/$(KERNELRELEASE)/kernel/ - -And external modules are installed in: - - /lib/modules/$(KERNELRELEASE)/extra/ - ---- 5.1 INSTALL_MOD_PATH - - Above are the default directories but as always some level of - customization is possible. A prefix can be added to the - installation path using the variable INSTALL_MOD_PATH: - - $ make INSTALL_MOD_PATH=/frodo modules_install - => Install dir: /frodo/lib/modules/$(KERNELRELEASE)/kernel/ - - INSTALL_MOD_PATH may be set as an ordinary shell variable or, - as shown above, can be specified on the command line when - calling "make." This has effect when installing both in-tree - and out-of-tree modules. - ---- 5.2 INSTALL_MOD_DIR - - External modules are by default installed to a directory under - /lib/modules/$(KERNELRELEASE)/extra/, but you may wish to - locate modules for a specific functionality in a separate - directory. For this purpose, use INSTALL_MOD_DIR to specify an - alternative name to "extra." - - $ make INSTALL_MOD_DIR=gandalf -C $KDIR \ - M=$PWD modules_install - => Install dir: /lib/modules/$(KERNELRELEASE)/gandalf/ - - -=== 6. Module Versioning - -Module versioning is enabled by the CONFIG_MODVERSIONS tag, and is used -as a simple ABI consistency check. A CRC value of the full prototype -for an exported symbol is created. When a module is loaded/used, the -CRC values contained in the kernel are compared with similar values in -the module; if they are not equal, the kernel refuses to load the -module. - -Module.symvers contains a list of all exported symbols from a kernel -build. - ---- 6.1 Symbols From the Kernel (vmlinux + modules) - - During a kernel build, a file named Module.symvers will be - generated. Module.symvers contains all exported symbols from - the kernel and compiled modules. For each symbol, the - corresponding CRC value is also stored. - - The syntax of the Module.symvers file is: - - - 0x2d036834 scsi_remove_host drivers/scsi/scsi_mod - - For a kernel build without CONFIG_MODVERSIONS enabled, the CRC - would read 0x00000000. - - Module.symvers serves two purposes: - 1) It lists all exported symbols from vmlinux and all modules. - 2) It lists the CRC if CONFIG_MODVERSIONS is enabled. - ---- 6.2 Symbols and External Modules - - When building an external module, the build system needs access - to the symbols from the kernel to check if all external symbols - are defined. This is done in the MODPOST step. modpost obtains - the symbols by reading Module.symvers from the kernel source - tree. If a Module.symvers file is present in the directory - where the external module is being built, this file will be - read too. During the MODPOST step, a new Module.symvers file - will be written containing all exported symbols that were not - defined in the kernel. - ---- 6.3 Symbols From Another External Module - - Sometimes, an external module uses exported symbols from - another external module. kbuild needs to have full knowledge of - all symbols to avoid spitting out warnings about undefined - symbols. Three solutions exist for this situation. - - NOTE: The method with a top-level kbuild file is recommended - but may be impractical in certain situations. - - Use a top-level kbuild file - If you have two modules, foo.ko and bar.ko, where - foo.ko needs symbols from bar.ko, you can use a - common top-level kbuild file so both modules are - compiled in the same build. Consider the following - directory layout: - - ./foo/ <= contains foo.ko - ./bar/ <= contains bar.ko - - The top-level kbuild file would then look like: - - #./Kbuild (or ./Makefile): - obj-y := foo/ bar/ - - And executing - - $ make -C $KDIR M=$PWD - - will then do the expected and compile both modules with - full knowledge of symbols from either module. - - Use an extra Module.symvers file - When an external module is built, a Module.symvers file - is generated containing all exported symbols which are - not defined in the kernel. To get access to symbols - from bar.ko, copy the Module.symvers file from the - compilation of bar.ko to the directory where foo.ko is - built. During the module build, kbuild will read the - Module.symvers file in the directory of the external - module, and when the build is finished, a new - Module.symvers file is created containing the sum of - all symbols defined and not part of the kernel. - - Use "make" variable KBUILD_EXTRA_SYMBOLS - If it is impractical to copy Module.symvers from - another module, you can assign a space separated list - of files to KBUILD_EXTRA_SYMBOLS in your build file. - These files will be loaded by modpost during the - initialization of its symbol tables. - - -=== 7. Tips & Tricks - ---- 7.1 Testing for CONFIG_FOO_BAR - - Modules often need to check for certain CONFIG_ options to - decide if a specific feature is included in the module. In - kbuild this is done by referencing the CONFIG_ variable - directly. - - #fs/ext2/Makefile - obj-$(CONFIG_EXT2_FS) += ext2.o - - ext2-y := balloc.o bitmap.o dir.o - ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o - - External modules have traditionally used "grep" to check for - specific CONFIG_ settings directly in .config. This usage is - broken. As introduced before, external modules should use - kbuild for building and can therefore use the same methods as - in-tree modules when testing for CONFIG_ definitions. - diff --git a/Documentation/kernel-hacking/hacking.rst b/Documentation/kernel-hacking/hacking.rst index d824e4feaff3..5891a701a159 100644 --- a/Documentation/kernel-hacking/hacking.rst +++ b/Documentation/kernel-hacking/hacking.rst @@ -718,7 +718,7 @@ make a neat patch, there's administrative work to be done: - Usually you want a configuration option for your kernel hack. Edit ``Kconfig`` in the appropriate directory. The Config language is simple to use by cut and paste, and there's complete documentation in - ``Documentation/kbuild/kconfig-language.txt``. + ``Documentation/kbuild/kconfig-language.rst``. In your description of the option, make sure you address both the expert user and the user who knows nothing about your feature. @@ -728,7 +728,7 @@ make a neat patch, there's administrative work to be done: - Edit the ``Makefile``: the CONFIG variables are exported here so you can usually just add a "obj-$(CONFIG_xxx) += xxx.o" line. The syntax - is documented in ``Documentation/kbuild/makefiles.txt``. + is documented in ``Documentation/kbuild/makefiles.rst``. - Put yourself in ``CREDITS`` if you've done something noteworthy, usually beyond a single file (your name should be at the top of the diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index fa864a51e6ea..f4a2198187f9 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -686,7 +686,7 @@ filesystems) should advertise this prominently in their prompt string:: ... For full documentation on the configuration files, see the file -Documentation/kbuild/kconfig-language.txt. +Documentation/kbuild/kconfig-language.rst. 11) Data structures diff --git a/Documentation/process/submit-checklist.rst b/Documentation/process/submit-checklist.rst index c88867b173d9..365efc9e4aa8 100644 --- a/Documentation/process/submit-checklist.rst +++ b/Documentation/process/submit-checklist.rst @@ -39,7 +39,7 @@ and elsewhere regarding submitting Linux kernel patches. 6) Any new or modified ``CONFIG`` options do not muck up the config menu and default to off unless they meet the exception criteria documented in - ``Documentation/kbuild/kconfig-language.txt`` Menu attributes: default value. + ``Documentation/kbuild/kconfig-language.rst`` Menu attributes: default value. 7) All new ``Kconfig`` options have help text. diff --git a/Documentation/translations/it_IT/kernel-hacking/hacking.rst b/Documentation/translations/it_IT/kernel-hacking/hacking.rst index 7178e517af0a..24c592852bf1 100644 --- a/Documentation/translations/it_IT/kernel-hacking/hacking.rst +++ b/Documentation/translations/it_IT/kernel-hacking/hacking.rst @@ -755,7 +755,7 @@ anche per avere patch pulite, c'è del lavoro amministrativo da fare: - Solitamente vorrete un'opzione di configurazione per la vostra modifica al kernel. Modificate ``Kconfig`` nella cartella giusta. Il linguaggio Config è facile con copia ed incolla, e c'è una completa documentazione - nel file ``Documentation/kbuild/kconfig-language.txt``. + nel file ``Documentation/kbuild/kconfig-language.rst``. Nella descrizione della vostra opzione, assicuratevi di parlare sia agli utenti esperti sia agli utente che non sanno nulla del vostro lavoro. @@ -767,7 +767,7 @@ anche per avere patch pulite, c'è del lavoro amministrativo da fare: - Modificate il file ``Makefile``: le variabili CONFIG sono esportate qui, quindi potete solitamente aggiungere una riga come la seguete "obj-$(CONFIG_xxx) += xxx.o". La sintassi è documentata nel file - ``Documentation/kbuild/makefiles.txt``. + ``Documentation/kbuild/makefiles.rst``. - Aggiungete voi stessi in ``CREDITS`` se avete fatto qualcosa di notevole, solitamente qualcosa che supera il singolo file (comunque il vostro nome diff --git a/Documentation/translations/it_IT/process/coding-style.rst b/Documentation/translations/it_IT/process/coding-style.rst index a6559d25a23d..8995d2d19f20 100644 --- a/Documentation/translations/it_IT/process/coding-style.rst +++ b/Documentation/translations/it_IT/process/coding-style.rst @@ -696,7 +696,7 @@ nella stringa di titolo:: ... Per la documentazione completa sui file di configurazione, consultate -il documento Documentation/kbuild/kconfig-language.txt +il documento Documentation/kbuild/kconfig-language.rst 11) Strutture dati diff --git a/Documentation/translations/it_IT/process/submit-checklist.rst b/Documentation/translations/it_IT/process/submit-checklist.rst index 70e65a7b3620..ea74cae958d7 100644 --- a/Documentation/translations/it_IT/process/submit-checklist.rst +++ b/Documentation/translations/it_IT/process/submit-checklist.rst @@ -43,7 +43,7 @@ sottomissione delle patch, in particolare 6) Le opzioni ``CONFIG``, nuove o modificate, non scombussolano il menu di configurazione e sono preimpostate come disabilitate a meno che non - soddisfino i criteri descritti in ``Documentation/kbuild/kconfig-language.txt`` + soddisfino i criteri descritti in ``Documentation/kbuild/kconfig-language.rst`` alla punto "Voci di menu: valori predefiniti". 7) Tutte le nuove opzioni ``Kconfig`` hanno un messaggio di aiuto. diff --git a/Documentation/translations/zh_CN/process/coding-style.rst b/Documentation/translations/zh_CN/process/coding-style.rst index 5479c591c2f7..4f6237392e65 100644 --- a/Documentation/translations/zh_CN/process/coding-style.rst +++ b/Documentation/translations/zh_CN/process/coding-style.rst @@ -599,7 +599,7 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以获得详细信息。 depends on ADFS_FS ... -要查看配置文件的完整文档，请看 Documentation/kbuild/kconfig-language.txt。 +要查看配置文件的完整文档，请看 Documentation/kbuild/kconfig-language.rst。 11) 数据结构 diff --git a/Documentation/translations/zh_CN/process/submit-checklist.rst b/Documentation/translations/zh_CN/process/submit-checklist.rst index 89061aa8fdbe..f4785d2b0491 100644 --- a/Documentation/translations/zh_CN/process/submit-checklist.rst +++ b/Documentation/translations/zh_CN/process/submit-checklist.rst @@ -38,7 +38,7 @@ Linux内核补丁提交清单 违规行为。 6) 任何新的或修改过的 ``CONFIG`` 选项都不会弄脏配置菜单，并默认为关闭，除非 - 它们符合 ``Documentation/kbuild/kconfig-language.txt`` 中记录的异常条件, + 它们符合 ``Documentation/kbuild/kconfig-language.rst`` 中记录的异常条件, 菜单属性：默认值. 7) 所有新的 ``kconfig`` 选项都有帮助文本。 diff --git a/Kconfig b/Kconfig index 990b0c390dfc..e10b3ee084d4 100644 --- a/Kconfig +++ b/Kconfig @@ -1,7 +1,7 @@ # SPDX-License-Identifier: GPL-2.0 # # For a description of the syntax of this configuration file, -# see Documentation/kbuild/kconfig-language.txt. +# see Documentation/kbuild/kconfig-language.rst. # mainmenu "Linux/$(ARCH) $(KERNELVERSION) Kernel Configuration" diff --git a/arch/arc/plat-eznps/Kconfig b/arch/arc/plat-eznps/Kconfig index 2eaecfb063a7..a376a50d3fea 100644 --- a/arch/arc/plat-eznps/Kconfig +++ b/arch/arc/plat-eznps/Kconfig @@ -1,7 +1,7 @@ # SPDX-License-Identifier: GPL-2.0 # # For a description of the syntax of this configuration file, -# see Documentation/kbuild/kconfig-language.txt. +# see Documentation/kbuild/kconfig-language.rst. # menuconfig ARC_PLAT_EZNPS diff --git a/arch/c6x/Kconfig b/arch/c6x/Kconfig index eeb0471268a0..c5e6b70e1510 100644 --- a/arch/c6x/Kconfig +++ b/arch/c6x/Kconfig @@ -1,7 +1,7 @@ # SPDX-License-Identifier: GPL-2.0 # # For a description of the syntax of this configuration file, -# see Documentation/kbuild/kconfig-language.txt. +# see Documentation/kbuild/kconfig-language.rst. # config C6X diff --git a/arch/microblaze/Kconfig.debug b/arch/microblaze/Kconfig.debug index 3a343188d86c..865527ac332a 100644 --- a/arch/microblaze/Kconfig.debug +++ b/arch/microblaze/Kconfig.debug @@ -1,6 +1,6 @@ # SPDX-License-Identifier: GPL-2.0-only # For a description of the syntax of this configuration file, -# see Documentation/kbuild/kconfig-language.txt. +# see Documentation/kbuild/kconfig-language.rst. config TRACE_IRQFLAGS_SUPPORT def_bool y diff --git a/arch/microblaze/Kconfig.platform b/arch/microblaze/Kconfig.platform index 5bf54c1d4f60..7795f90dad86 100644 --- a/arch/microblaze/Kconfig.platform +++ b/arch/microblaze/Kconfig.platform @@ -1,6 +1,6 @@ # SPDX-License-Identifier: GPL-2.0-only # For a description of the syntax of this configuration file, -# see Documentation/kbuild/kconfig-language.txt. +# see Documentation/kbuild/kconfig-language.rst. # # Platform selection Kconfig menu for MicroBlaze targets # diff --git a/arch/nds32/Kconfig b/arch/nds32/Kconfig index 3299e287a477..fd0d0639454f 100644 --- a/arch/nds32/Kconfig +++ b/arch/nds32/Kconfig @@ -1,7 +1,7 @@ # SPDX-License-Identifier: GPL-2.0-only # # For a description of the syntax of this configuration file, -# see Documentation/kbuild/kconfig-language.txt. +# see Documentation/kbuild/kconfig-language.rst. # config NDS32 diff --git a/arch/openrisc/Kconfig b/arch/openrisc/Kconfig index 7cfb20555b10..bf326f0edd2f 100644 --- a/arch/openrisc/Kconfig +++ b/arch/openrisc/Kconfig @@ -1,7 +1,7 @@ # SPDX-License-Identifier: GPL-2.0 # # For a description of the syntax of this configuration file, -# see Documentation/kbuild/kconfig-language.txt. +# see Documentation/kbuild/kconfig-language.rst. # config OPENRISC diff --git a/arch/powerpc/sysdev/Kconfig b/arch/powerpc/sysdev/Kconfig index e0dbec780fe9..d23288c4abf6 100644 --- a/arch/powerpc/sysdev/Kconfig +++ b/arch/powerpc/sysdev/Kconfig @@ -1,6 +1,6 @@ # SPDX-License-Identifier: GPL-2.0 # For a description of the syntax of this configuration file, -# see Documentation/kbuild/kconfig-language.txt. +# see Documentation/kbuild/kconfig-language.rst. # config PPC4xx_PCI_EXPRESS diff --git a/arch/riscv/Kconfig b/arch/riscv/Kconfig index 0c4b12205632..be713da93946 100644 --- a/arch/riscv/Kconfig +++ b/arch/riscv/Kconfig @@ -1,7 +1,7 @@ # SPDX-License-Identifier: GPL-2.0-only # # For a description of the syntax of this configuration file, -# see Documentation/kbuild/kconfig-language.txt. +# see Documentation/kbuild/kconfig-language.rst. # config 64BIT diff --git a/drivers/auxdisplay/Kconfig b/drivers/auxdisplay/Kconfig index c52c738e554a..dd61fdd400f0 100644 --- a/drivers/auxdisplay/Kconfig +++ b/drivers/auxdisplay/Kconfig @@ -1,7 +1,7 @@ # SPDX-License-Identifier: GPL-2.0 # # For a description of the syntax of this configuration file, -# see Documentation/kbuild/kconfig-language.txt. +# see Documentation/kbuild/kconfig-language.rst. # # Auxiliary display drivers configuration. # diff --git a/drivers/firmware/Kconfig b/drivers/firmware/Kconfig index 9026df923542..35078c6f334a 100644 --- a/drivers/firmware/Kconfig +++ b/drivers/firmware/Kconfig @@ -1,7 +1,7 @@ # SPDX-License-Identifier: GPL-2.0-only # # For a description of the syntax of this configuration file, -# see Documentation/kbuild/kconfig-language.txt. +# see Documentation/kbuild/kconfig-language.rst. # menu "Firmware Drivers" diff --git a/drivers/mtd/devices/Kconfig b/drivers/mtd/devices/Kconfig index ef0e476b2525..49abbc52457d 100644 --- a/drivers/mtd/devices/Kconfig +++ b/drivers/mtd/devices/Kconfig @@ -48,7 +48,7 @@ config MTD_MS02NV If you want to compile this driver as a module ( = code which can be inserted in and removed from the running kernel whenever you want), - say M here and read . + say M here and read . The module will be called ms02-nv. config MTD_DATAFLASH diff --git a/drivers/net/ethernet/smsc/Kconfig b/drivers/net/ethernet/smsc/Kconfig index d1b6a78557ec..9e1c3752b200 100644 --- a/drivers/net/ethernet/smsc/Kconfig +++ b/drivers/net/ethernet/smsc/Kconfig @@ -49,7 +49,7 @@ config SMC91X This driver is also available as a module ( = code which can be inserted in and removed from the running kernel whenever you want). The module will be called smc91x. If you want to compile it as a - module, say M here and read . + module, say M here and read . config PCMCIA_SMC91C92 tristate "SMC 91Cxx PCMCIA support" @@ -86,7 +86,7 @@ config SMC911X This driver is also available as a module. The module will be called smc911x. If you want to compile it as a module, say M - here and read + here and read config SMSC911X tristate "SMSC LAN911x/LAN921x families embedded ethernet support" @@ -121,6 +121,6 @@ config SMSC9420 This driver is also available as a module. The module will be called smsc9420. If you want to compile it as a module, say M - here and read + here and read endif # NET_VENDOR_SMSC diff --git a/drivers/net/wireless/intel/iwlegacy/Kconfig b/drivers/net/wireless/intel/iwlegacy/Kconfig index aa01c83e0060..e329fd7b09c0 100644 --- a/drivers/net/wireless/intel/iwlegacy/Kconfig +++ b/drivers/net/wireless/intel/iwlegacy/Kconfig @@ -32,7 +32,7 @@ config IWL4965 If you want to compile the driver as a module ( = code which can be inserted in and removed from the running kernel whenever you want), - say M here and read . The + say M here and read . The module will be called iwl4965. config IWL3945 @@ -58,7 +58,7 @@ config IWL3945 If you want to compile the driver as a module ( = code which can be inserted in and removed from the running kernel whenever you want), - say M here and read . The + say M here and read . The module will be called iwl3945. menu "iwl3945 / iwl4965 Debugging Options" diff --git a/drivers/net/wireless/intel/iwlwifi/Kconfig b/drivers/net/wireless/intel/iwlwifi/Kconfig index e5528189163f..235349a33a3c 100644 --- a/drivers/net/wireless/intel/iwlwifi/Kconfig +++ b/drivers/net/wireless/intel/iwlwifi/Kconfig @@ -40,7 +40,7 @@ config IWLWIFI If you want to compile the driver as a module ( = code which can be inserted in and removed from the running kernel whenever you want), - say M here and read . The + say M here and read . The module will be called iwlwifi. if IWLWIFI diff --git a/drivers/parport/Kconfig b/drivers/parport/Kconfig index 24189c3399e0..1791830e7a71 100644 --- a/drivers/parport/Kconfig +++ b/drivers/parport/Kconfig @@ -1,7 +1,7 @@ # SPDX-License-Identifier: GPL-2.0-only # # For a description of the syntax of this configuration file, -# see Documentation/kbuild/kconfig-language.txt. +# see Documentation/kbuild/kconfig-language.rst. # # Parport configuration. # diff --git a/drivers/scsi/Kconfig b/drivers/scsi/Kconfig index 61da513fc0ed..f31b6b780eaf 100644 --- a/drivers/scsi/Kconfig +++ b/drivers/scsi/Kconfig @@ -183,7 +183,7 @@ config CHR_DEV_SCH If you want to compile this as a module ( = code which can be inserted in and removed from the running kernel whenever you want), - say M here and read and + say M here and read and . The module will be called ch.o. If unsure, say N. @@ -1474,7 +1474,7 @@ config ZFCP This driver is also available as a module. This module will be called zfcp. If you want to compile it as a module, say M here - and read . + and read . config SCSI_PMCRAID tristate "PMC SIERRA Linux MaxRAID adapter support" diff --git a/drivers/staging/sm750fb/Kconfig b/drivers/staging/sm750fb/Kconfig index fb5a086bf9b1..8c0d8a873d5b 100644 --- a/drivers/staging/sm750fb/Kconfig +++ b/drivers/staging/sm750fb/Kconfig @@ -12,4 +12,4 @@ config FB_SM750 This driver is also available as a module. The module will be called sm750fb. If you want to compile it as a module, say M - here and read . + here and read . diff --git a/drivers/usb/misc/Kconfig b/drivers/usb/misc/Kconfig index c97f270338bf..4a88e1ca25c0 100644 --- a/drivers/usb/misc/Kconfig +++ b/drivers/usb/misc/Kconfig @@ -16,7 +16,7 @@ config USB_EMI62 This code is also available as a module ( = code which can be inserted in and removed from the running kernel whenever you want). The module will be called audio. If you want to compile it as a - module, say M here and read . + module, say M here and read . config USB_EMI26 tristate "EMI 2|6 USB Audio interface support" @@ -67,7 +67,7 @@ config USB_LEGOTOWER inserted in and removed from the running kernel whenever you want). The module will be called legousbtower. If you want to compile it as a module, say M here and read - . + . config USB_LCD tristate "USB LCD driver support" diff --git a/drivers/video/fbdev/Kconfig b/drivers/video/fbdev/Kconfig index 737b86328c9e..31ba91cb916a 100644 --- a/drivers/video/fbdev/Kconfig +++ b/drivers/video/fbdev/Kconfig @@ -289,7 +289,7 @@ config FB_ARMCLCD If you want to compile this as a module (=code which can be inserted into and removed from the running kernel), say M - here and read . The module + here and read . The module will be called amba-clcd. config FB_ACORN @@ -1752,7 +1752,7 @@ config FB_PXA This driver is also available as a module ( = code which can be inserted and removed from the running kernel whenever you want). The module will be called pxafb. If you want to compile it as a module, - say M here and read . + say M here and read . If unsure, say N. @@ -1833,7 +1833,7 @@ config FB_W100 This driver is also available as a module ( = code which can be inserted and removed from the running kernel whenever you want). The module will be called w100fb. If you want to compile it as a module, - say M here and read . + say M here and read . If unsure, say N. @@ -1862,7 +1862,7 @@ config FB_TMIO This driver is also available as a module ( = code which can be inserted and removed from the running kernel whenever you want). The module will be called tmiofb. If you want to compile it as a module, - say M here and read . + say M here and read . If unsure, say N. @@ -1908,7 +1908,7 @@ config FB_S3C2410 This driver is also available as a module ( = code which can be inserted and removed from the running kernel whenever you want). The module will be called s3c2410fb. If you want to compile it as a module, - say M here and read . + say M here and read . If unsure, say N. config FB_S3C2410_DEBUG @@ -1945,7 +1945,7 @@ config FB_SM501 This driver is also available as a module ( = code which can be inserted and removed from the running kernel whenever you want). The module will be called sm501fb. If you want to compile it as a module, - say M here and read . + say M here and read . If unsure, say N. @@ -2288,7 +2288,7 @@ config FB_SM712 This driver is also available as a module. The module will be called sm712fb. If you want to compile it as a module, say M - here and read . + here and read . source "drivers/video/fbdev/omap/Kconfig" source "drivers/video/fbdev/omap2/Kconfig" diff --git a/net/bridge/netfilter/Kconfig b/net/bridge/netfilter/Kconfig index c3ad90c43801..36a98d36d339 100644 --- a/net/bridge/netfilter/Kconfig +++ b/net/bridge/netfilter/Kconfig @@ -114,7 +114,7 @@ config BRIDGE_EBT_LIMIT equivalent of the iptables limit match. If you want to compile it as a module, say M here and read - . If unsure, say `N'. + . If unsure, say `N'. config BRIDGE_EBT_MARK tristate "ebt: mark filter support" diff --git a/net/ipv4/netfilter/Kconfig b/net/ipv4/netfilter/Kconfig index 3e6494269501..69e76d677f9e 100644 --- a/net/ipv4/netfilter/Kconfig +++ b/net/ipv4/netfilter/Kconfig @@ -308,7 +308,7 @@ config IP_NF_RAW and OUTPUT chains. If you want to compile it as a module, say M here and read - . If unsure, say `N'. + . If unsure, say `N'. # security table for MAC policy config IP_NF_SECURITY diff --git a/net/ipv6/netfilter/Kconfig b/net/ipv6/netfilter/Kconfig index f7c6f5be9f76..6120a7800975 100644 --- a/net/ipv6/netfilter/Kconfig +++ b/net/ipv6/netfilter/Kconfig @@ -241,7 +241,7 @@ config IP6_NF_RAW and OUTPUT chains. If you want to compile it as a module, say M here and read - . If unsure, say `N'. + . If unsure, say `N'. # security table for MAC policy config IP6_NF_SECURITY diff --git a/net/netfilter/Kconfig b/net/netfilter/Kconfig index 21025c2c605b..dd2af7be3eea 100644 --- a/net/netfilter/Kconfig +++ b/net/netfilter/Kconfig @@ -1056,7 +1056,7 @@ config NETFILTER_XT_TARGET_TRACE the tables, chains, rules. If you want to compile it as a module, say M here and read - . If unsure, say `N'. + . If unsure, say `N'. config NETFILTER_XT_TARGET_SECMARK tristate '"SECMARK" target support' @@ -1115,7 +1115,7 @@ config NETFILTER_XT_MATCH_ADDRTYPE eg. UNICAST, LOCAL, BROADCAST, ... If you want to compile it as a module, say M here and read - . If unsure, say `N'. + . If unsure, say `N'. config NETFILTER_XT_MATCH_BPF tristate '"bpf" match support' @@ -1160,7 +1160,7 @@ config NETFILTER_XT_MATCH_COMMENT comments in your iptables ruleset. If you want to compile it as a module, say M here and read - . If unsure, say `N'. + . If unsure, say `N'. config NETFILTER_XT_MATCH_CONNBYTES tristate '"connbytes" per-connection counter match support' @@ -1171,7 +1171,7 @@ config NETFILTER_XT_MATCH_CONNBYTES number of bytes and/or packets for each direction within a connection. If you want to compile it as a module, say M here and read - . If unsure, say `N'. + . If unsure, say `N'. config NETFILTER_XT_MATCH_CONNLABEL tristate '"connlabel" match support' @@ -1237,7 +1237,7 @@ config NETFILTER_XT_MATCH_DCCP and DCCP flags. If you want to compile it as a module, say M here and read - . If unsure, say `N'. + . If unsure, say `N'. config NETFILTER_XT_MATCH_DEVGROUP tristate '"devgroup" match support' @@ -1473,7 +1473,7 @@ config NETFILTER_XT_MATCH_QUOTA byte counter. If you want to compile it as a module, say M here and read - . If unsure, say `N'. + . If unsure, say `N'. config NETFILTER_XT_MATCH_RATEEST tristate '"rateest" match support' @@ -1497,7 +1497,7 @@ config NETFILTER_XT_MATCH_REALM in tc world. If you want to compile it as a module, say M here and read - . If unsure, say `N'. + . If unsure, say `N'. config NETFILTER_XT_MATCH_RECENT tristate '"recent" match support' @@ -1519,7 +1519,7 @@ config NETFILTER_XT_MATCH_SCTP and SCTP chunk types. If you want to compile it as a module, say M here and read - . If unsure, say `N'. + . If unsure, say `N'. config NETFILTER_XT_MATCH_SOCKET tristate '"socket" match support' diff --git a/net/tipc/Kconfig b/net/tipc/Kconfig index b93bb7bdb04a..b83e16ade4d2 100644 --- a/net/tipc/Kconfig +++ b/net/tipc/Kconfig @@ -17,7 +17,7 @@ menuconfig TIPC This protocol support is also available as a module ( = code which can be inserted in and removed from the running kernel whenever you want). The module will be called tipc. If you want to compile it - as a module, say M here and read . + as a module, say M here and read . If in doubt, say N. diff --git a/scripts/Kbuild.include b/scripts/Kbuild.include index f641bb0aa63f..ee58cde8ee3b 100644 --- a/scripts/Kbuild.include +++ b/scripts/Kbuild.include @@ -68,7 +68,7 @@ endef ###### # gcc support functions -# See documentation in Documentation/kbuild/makefiles.txt +# See documentation in Documentation/kbuild/makefiles.rst # cc-cross-prefix # Usage: CROSS_COMPILE := $(call cc-cross-prefix, m68k-linux-gnu- m68k-linux-) @@ -210,7 +210,7 @@ objectify = $(foreach o,$(1),$(if $(filter /%,$(o)),$(o),$(obj)/$(o))) # if_changed_dep - as if_changed, but uses fixdep to reveal dependencies # including used config symbols # if_changed_rule - as if_changed but execute rule instead -# See Documentation/kbuild/makefiles.txt for more info +# See Documentation/kbuild/makefiles.rst for more info ifneq ($(KBUILD_NOCMDDEP),1) # Check if both arguments are the same including their order. Result is empty diff --git a/scripts/Makefile.host b/scripts/Makefile.host index b6a54bdf0965..a316d368b697 100644 --- a/scripts/Makefile.host +++ b/scripts/Makefile.host @@ -6,7 +6,7 @@ # # Both C and C++ are supported, but preferred language is C for such utilities. # -# Sample syntax (see Documentation/kbuild/makefiles.txt for reference) +# Sample syntax (see Documentation/kbuild/makefiles.rst for reference) # hostprogs-y := bin2hex # Will compile bin2hex.c and create an executable named bin2hex # diff --git a/scripts/kconfig/symbol.c b/scripts/kconfig/symbol.c index 1f9266dadedf..09fd6fa18e1a 100644 --- a/scripts/kconfig/symbol.c +++ b/scripts/kconfig/symbol.c @@ -1114,7 +1114,7 @@ static void sym_check_print_recursive(struct symbol *last_sym) } fprintf(stderr, - "For a resolution refer to Documentation/kbuild/kconfig-language.txt\n" + "For a resolution refer to Documentation/kbuild/kconfig-language.rst\n" "subsection \"Kconfig recursive dependency limitations\"\n" "\n"); diff --git a/scripts/kconfig/tests/err_recursive_dep/expected_stderr b/scripts/kconfig/tests/err_recursive_dep/expected_stderr index 84679b104655..c9f4abf9a791 100644 --- a/scripts/kconfig/tests/err_recursive_dep/expected_stderr +++ b/scripts/kconfig/tests/err_recursive_dep/expected_stderr @@ -1,38 +1,38 @@ Kconfig:11:error: recursive dependency detected! Kconfig:11: symbol B is selected by B -For a resolution refer to Documentation/kbuild/kconfig-language.txt +For a resolution refer to Documentation/kbuild/kconfig-language.rst subsection "Kconfig recursive dependency limitations" Kconfig:5:error: recursive dependency detected! Kconfig:5: symbol A depends on A -For a resolution refer to Documentation/kbuild/kconfig-language.txt +For a resolution refer to Documentation/kbuild/kconfig-language.rst subsection "Kconfig recursive dependency limitations" Kconfig:17:error: recursive dependency detected! Kconfig:17: symbol C1 depends on C2 Kconfig:21: symbol C2 depends on C1 -For a resolution refer to Documentation/kbuild/kconfig-language.txt +For a resolution refer to Documentation/kbuild/kconfig-language.rst subsection "Kconfig recursive dependency limitations" Kconfig:32:error: recursive dependency detected! Kconfig:32: symbol D2 is selected by D1 Kconfig:27: symbol D1 depends on D2 -For a resolution refer to Documentation/kbuild/kconfig-language.txt +For a resolution refer to Documentation/kbuild/kconfig-language.rst subsection "Kconfig recursive dependency limitations" Kconfig:37:error: recursive dependency detected! Kconfig:37: symbol E1 depends on E2 Kconfig:42: symbol E2 is implied by E1 -For a resolution refer to Documentation/kbuild/kconfig-language.txt +For a resolution refer to Documentation/kbuild/kconfig-language.rst subsection "Kconfig recursive dependency limitations" Kconfig:60:error: recursive dependency detected! Kconfig:60: symbol G depends on G -For a resolution refer to Documentation/kbuild/kconfig-language.txt +For a resolution refer to Documentation/kbuild/kconfig-language.rst subsection "Kconfig recursive dependency limitations" Kconfig:51:error: recursive dependency detected! Kconfig:51: symbol F2 depends on F1 Kconfig:49: symbol F1 default value contains F2 -For a resolution refer to Documentation/kbuild/kconfig-language.txt +For a resolution refer to Documentation/kbuild/kconfig-language.rst subsection "Kconfig recursive dependency limitations" diff --git a/sound/oss/dmasound/Kconfig b/sound/oss/dmasound/Kconfig index 12e42165b4a5..1a3339859840 100644 --- a/sound/oss/dmasound/Kconfig +++ b/sound/oss/dmasound/Kconfig @@ -11,7 +11,7 @@ config DMASOUND_ATARI This driver is also available as a module ( = code which can be inserted in and removed from the running kernel whenever you want). If you want to compile it as a module, say M here and read - . + . config DMASOUND_PAULA tristate "Amiga DMA sound support" @@ -25,7 +25,7 @@ config DMASOUND_PAULA This driver is also available as a module ( = code which can be inserted in and removed from the running kernel whenever you want). If you want to compile it as a module, say M here and read - . + . config DMASOUND_Q40 tristate "Q40 sound support" @@ -39,7 +39,7 @@ config DMASOUND_Q40 This driver is also available as a module ( = code which can be inserted in and removed from the running kernel whenever you want). If you want to compile it as a module, say M here and read - . + . config DMASOUND tristate -- cgit v1.2.3 From 4ca9bc225e46eb7bc040dd948be7cb68975d80d3 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 12 Jun 2019 14:52:59 -0300 Subject: docs: target: convert docs to ReST and rename to *.rst Convert the TCM docs to ReST format and add them to the bookset. This has a mix of userspace-faced and Kernelspace faced docs. Still, it sounds a better candidate to be added at the kernel API set of docs. The conversion is actually: - add blank lines and identation in order to identify paragraphs; - fix tables markups; - add some lists markups; - mark literal blocks; - adjust title markups. At its new index.rst, let's add a :orphan: while this is not linked to the main index.rst file, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/target/index.rst | 19 ++ Documentation/target/scripts.rst | 11 + Documentation/target/tcm_mod_builder.rst | 149 ++++++++++++ Documentation/target/tcm_mod_builder.txt | 145 ----------- Documentation/target/tcmu-design.rst | 405 +++++++++++++++++++++++++++++++ Documentation/target/tcmu-design.txt | 381 ----------------------------- scripts/documentation-file-ref-check | 2 +- 7 files changed, 585 insertions(+), 527 deletions(-) create mode 100644 Documentation/target/index.rst create mode 100644 Documentation/target/scripts.rst create mode 100644 Documentation/target/tcm_mod_builder.rst delete mode 100644 Documentation/target/tcm_mod_builder.txt create mode 100644 Documentation/target/tcmu-design.rst delete mode 100644 Documentation/target/tcmu-design.txt (limited to 'scripts') diff --git a/Documentation/target/index.rst b/Documentation/target/index.rst new file mode 100644 index 000000000000..b68f48982392 --- /dev/null +++ b/Documentation/target/index.rst @@ -0,0 +1,19 @@ +:orphan: + +================== +TCM Virtual Device +================== + +.. toctree:: + :maxdepth: 1 + + tcmu-design + tcm_mod_builder + scripts + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/target/scripts.rst b/Documentation/target/scripts.rst new file mode 100644 index 000000000000..172d42b522e4 --- /dev/null +++ b/Documentation/target/scripts.rst @@ -0,0 +1,11 @@ +TCM mod builder script +---------------------- + +.. literalinclude:: tcm_mod_builder.py + :language: perl + +Target export device script +--------------------------- + +.. literalinclude:: target-export-device + :language: shell diff --git a/Documentation/target/tcm_mod_builder.rst b/Documentation/target/tcm_mod_builder.rst new file mode 100644 index 000000000000..9bfc9822e2bd --- /dev/null +++ b/Documentation/target/tcm_mod_builder.rst @@ -0,0 +1,149 @@ +========================================= +The TCM v4 fabric module script generator +========================================= + +Greetings all, + +This document is intended to be a mini-HOWTO for using the tcm_mod_builder.py +script to generate a brand new functional TCM v4 fabric .ko module of your very own, +that once built can be immediately be loaded to start access the new TCM/ConfigFS +fabric skeleton, by simply using:: + + modprobe $TCM_NEW_MOD + mkdir -p /sys/kernel/config/target/$TCM_NEW_MOD + +This script will create a new drivers/target/$TCM_NEW_MOD/, and will do the following + + 1) Generate new API callers for drivers/target/target_core_fabric_configs.c logic + ->make_tpg(), ->drop_tpg(), ->make_wwn(), ->drop_wwn(). These are created + into $TCM_NEW_MOD/$TCM_NEW_MOD_configfs.c + 2) Generate basic infrastructure for loading/unloading LKMs and TCM/ConfigFS fabric module + using a skeleton struct target_core_fabric_ops API template. + 3) Based on user defined T10 Proto_Ident for the new fabric module being built, + the TransportID / Initiator and Target WWPN related handlers for + SPC-3 persistent reservation are automatically generated in $TCM_NEW_MOD/$TCM_NEW_MOD_fabric.c + using drivers/target/target_core_fabric_lib.c logic. + 4) NOP API calls for all other Data I/O path and fabric dependent attribute logic + in $TCM_NEW_MOD/$TCM_NEW_MOD_fabric.c + +tcm_mod_builder.py depends upon the mandatory '-p $PROTO_IDENT' and '-m +$FABRIC_MOD_name' parameters, and actually running the script looks like:: + + target:/mnt/sdb/lio-core-2.6.git/Documentation/target# python tcm_mod_builder.py -p iSCSI -m tcm_nab5000 + tcm_dir: /mnt/sdb/lio-core-2.6.git/Documentation/target/../../ + Set fabric_mod_name: tcm_nab5000 + Set fabric_mod_dir: + /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000 + Using proto_ident: iSCSI + Creating fabric_mod_dir: + /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000 + Writing file: + /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_base.h + Using tcm_mod_scan_fabric_ops: + /mnt/sdb/lio-core-2.6.git/Documentation/target/../../include/target/target_core_fabric_ops.h + Writing file: + /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.c + Writing file: + /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.h + Writing file: + /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_configfs.c + Writing file: + /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kbuild + Writing file: + /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kconfig + Would you like to add tcm_nab5000to drivers/target/Kbuild..? [yes,no]: yes + Would you like to add tcm_nab5000to drivers/target/Kconfig..? [yes,no]: yes + +At the end of tcm_mod_builder.py. the script will ask to add the following +line to drivers/target/Kbuild:: + + obj-$(CONFIG_TCM_NAB5000) += tcm_nab5000/ + +and the same for drivers/target/Kconfig:: + + source "drivers/target/tcm_nab5000/Kconfig" + +#) Run 'make menuconfig' and select the new CONFIG_TCM_NAB5000 item:: + + TCM_NAB5000 fabric module + +#) Build using 'make modules', once completed you will have:: + + target:/mnt/sdb/lio-core-2.6.git# ls -la drivers/target/tcm_nab5000/ + total 1348 + drwxr-xr-x 2 root root 4096 2010-10-05 03:23 . + drwxr-xr-x 9 root root 4096 2010-10-05 03:22 .. + -rw-r--r-- 1 root root 282 2010-10-05 03:22 Kbuild + -rw-r--r-- 1 root root 171 2010-10-05 03:22 Kconfig + -rw-r--r-- 1 root root 49 2010-10-05 03:23 modules.order + -rw-r--r-- 1 root root 738 2010-10-05 03:22 tcm_nab5000_base.h + -rw-r--r-- 1 root root 9096 2010-10-05 03:22 tcm_nab5000_configfs.c + -rw-r--r-- 1 root root 191200 2010-10-05 03:23 tcm_nab5000_configfs.o + -rw-r--r-- 1 root root 40504 2010-10-05 03:23 .tcm_nab5000_configfs.o.cmd + -rw-r--r-- 1 root root 5414 2010-10-05 03:22 tcm_nab5000_fabric.c + -rw-r--r-- 1 root root 2016 2010-10-05 03:22 tcm_nab5000_fabric.h + -rw-r--r-- 1 root root 190932 2010-10-05 03:23 tcm_nab5000_fabric.o + -rw-r--r-- 1 root root 40713 2010-10-05 03:23 .tcm_nab5000_fabric.o.cmd + -rw-r--r-- 1 root root 401861 2010-10-05 03:23 tcm_nab5000.ko + -rw-r--r-- 1 root root 265 2010-10-05 03:23 .tcm_nab5000.ko.cmd + -rw-r--r-- 1 root root 459 2010-10-05 03:23 tcm_nab5000.mod.c + -rw-r--r-- 1 root root 23896 2010-10-05 03:23 tcm_nab5000.mod.o + -rw-r--r-- 1 root root 22655 2010-10-05 03:23 .tcm_nab5000.mod.o.cmd + -rw-r--r-- 1 root root 379022 2010-10-05 03:23 tcm_nab5000.o + -rw-r--r-- 1 root root 211 2010-10-05 03:23 .tcm_nab5000.o.cmd + +#) Load the new module, create a lun_0 configfs group, and add new TCM Core + IBLOCK backstore symlink to port:: + + target:/mnt/sdb/lio-core-2.6.git# insmod drivers/target/tcm_nab5000.ko + target:/mnt/sdb/lio-core-2.6.git# mkdir -p /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0 + target:/mnt/sdb/lio-core-2.6.git# cd /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0/ + target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# ln -s /sys/kernel/config/target/core/iblock_0/lvm_test0 nab5000_port + + target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# cd - + target:/mnt/sdb/lio-core-2.6.git# tree /sys/kernel/config/target/nab5000/ + /sys/kernel/config/target/nab5000/ + |-- discovery_auth + |-- iqn.foo + | `-- tpgt_1 + | |-- acls + | |-- attrib + | |-- lun + | | `-- lun_0 + | | |-- alua_tg_pt_gp + | | |-- alua_tg_pt_offline + | | |-- alua_tg_pt_status + | | |-- alua_tg_pt_write_md + | | `-- nab5000_port -> ../../../../../../target/core/iblock_0/lvm_test0 + | |-- np + | `-- param + `-- version + + target:/mnt/sdb/lio-core-2.6.git# lsmod + Module Size Used by + tcm_nab5000 3935 4 + iscsi_target_mod 193211 0 + target_core_stgt 8090 0 + target_core_pscsi 11122 1 + target_core_file 9172 2 + target_core_iblock 9280 1 + target_core_mod 228575 31 + tcm_nab5000,iscsi_target_mod,target_core_stgt,target_core_pscsi,target_core_file,target_core_iblock + libfc 73681 0 + scsi_debug 56265 0 + scsi_tgt 8666 1 target_core_stgt + configfs 20644 2 target_core_mod + +---------------------------------------------------------------------- + +Future TODO items +================= + + 1) Add more T10 proto_idents + 2) Make tcm_mod_dump_fabric_ops() smarter and generate function pointer + defs directly from include/target/target_core_fabric_ops.h:struct target_core_fabric_ops + structure members. + +October 5th, 2010 + +Nicholas A. Bellinger diff --git a/Documentation/target/tcm_mod_builder.txt b/Documentation/target/tcm_mod_builder.txt deleted file mode 100644 index ae22f7005540..000000000000 --- a/Documentation/target/tcm_mod_builder.txt +++ /dev/null @@ -1,145 +0,0 @@ ->>>>>>>>>> The TCM v4 fabric module script generator <<<<<<<<<< - -Greetings all, - -This document is intended to be a mini-HOWTO for using the tcm_mod_builder.py -script to generate a brand new functional TCM v4 fabric .ko module of your very own, -that once built can be immediately be loaded to start access the new TCM/ConfigFS -fabric skeleton, by simply using: - - modprobe $TCM_NEW_MOD - mkdir -p /sys/kernel/config/target/$TCM_NEW_MOD - -This script will create a new drivers/target/$TCM_NEW_MOD/, and will do the following - - *) Generate new API callers for drivers/target/target_core_fabric_configs.c logic - ->make_tpg(), ->drop_tpg(), ->make_wwn(), ->drop_wwn(). These are created - into $TCM_NEW_MOD/$TCM_NEW_MOD_configfs.c - *) Generate basic infrastructure for loading/unloading LKMs and TCM/ConfigFS fabric module - using a skeleton struct target_core_fabric_ops API template. - *) Based on user defined T10 Proto_Ident for the new fabric module being built, - the TransportID / Initiator and Target WWPN related handlers for - SPC-3 persistent reservation are automatically generated in $TCM_NEW_MOD/$TCM_NEW_MOD_fabric.c - using drivers/target/target_core_fabric_lib.c logic. - *) NOP API calls for all other Data I/O path and fabric dependent attribute logic - in $TCM_NEW_MOD/$TCM_NEW_MOD_fabric.c - -tcm_mod_builder.py depends upon the mandatory '-p $PROTO_IDENT' and '-m -$FABRIC_MOD_name' parameters, and actually running the script looks like: - -target:/mnt/sdb/lio-core-2.6.git/Documentation/target# python tcm_mod_builder.py -p iSCSI -m tcm_nab5000 -tcm_dir: /mnt/sdb/lio-core-2.6.git/Documentation/target/../../ -Set fabric_mod_name: tcm_nab5000 -Set fabric_mod_dir: -/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000 -Using proto_ident: iSCSI -Creating fabric_mod_dir: -/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000 -Writing file: -/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_base.h -Using tcm_mod_scan_fabric_ops: -/mnt/sdb/lio-core-2.6.git/Documentation/target/../../include/target/target_core_fabric_ops.h -Writing file: -/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.c -Writing file: -/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.h -Writing file: -/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_configfs.c -Writing file: -/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kbuild -Writing file: -/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kconfig -Would you like to add tcm_nab5000to drivers/target/Kbuild..? [yes,no]: yes -Would you like to add tcm_nab5000to drivers/target/Kconfig..? [yes,no]: yes - -At the end of tcm_mod_builder.py. the script will ask to add the following -line to drivers/target/Kbuild: - - obj-$(CONFIG_TCM_NAB5000) += tcm_nab5000/ - -and the same for drivers/target/Kconfig: - - source "drivers/target/tcm_nab5000/Kconfig" - -*) Run 'make menuconfig' and select the new CONFIG_TCM_NAB5000 item: - - TCM_NAB5000 fabric module - -*) Build using 'make modules', once completed you will have: - -target:/mnt/sdb/lio-core-2.6.git# ls -la drivers/target/tcm_nab5000/ -total 1348 -drwxr-xr-x 2 root root 4096 2010-10-05 03:23 . -drwxr-xr-x 9 root root 4096 2010-10-05 03:22 .. --rw-r--r-- 1 root root 282 2010-10-05 03:22 Kbuild --rw-r--r-- 1 root root 171 2010-10-05 03:22 Kconfig --rw-r--r-- 1 root root 49 2010-10-05 03:23 modules.order --rw-r--r-- 1 root root 738 2010-10-05 03:22 tcm_nab5000_base.h --rw-r--r-- 1 root root 9096 2010-10-05 03:22 tcm_nab5000_configfs.c --rw-r--r-- 1 root root 191200 2010-10-05 03:23 tcm_nab5000_configfs.o --rw-r--r-- 1 root root 40504 2010-10-05 03:23 .tcm_nab5000_configfs.o.cmd --rw-r--r-- 1 root root 5414 2010-10-05 03:22 tcm_nab5000_fabric.c --rw-r--r-- 1 root root 2016 2010-10-05 03:22 tcm_nab5000_fabric.h --rw-r--r-- 1 root root 190932 2010-10-05 03:23 tcm_nab5000_fabric.o --rw-r--r-- 1 root root 40713 2010-10-05 03:23 .tcm_nab5000_fabric.o.cmd --rw-r--r-- 1 root root 401861 2010-10-05 03:23 tcm_nab5000.ko --rw-r--r-- 1 root root 265 2010-10-05 03:23 .tcm_nab5000.ko.cmd --rw-r--r-- 1 root root 459 2010-10-05 03:23 tcm_nab5000.mod.c --rw-r--r-- 1 root root 23896 2010-10-05 03:23 tcm_nab5000.mod.o --rw-r--r-- 1 root root 22655 2010-10-05 03:23 .tcm_nab5000.mod.o.cmd --rw-r--r-- 1 root root 379022 2010-10-05 03:23 tcm_nab5000.o --rw-r--r-- 1 root root 211 2010-10-05 03:23 .tcm_nab5000.o.cmd - -*) Load the new module, create a lun_0 configfs group, and add new TCM Core - IBLOCK backstore symlink to port: - -target:/mnt/sdb/lio-core-2.6.git# insmod drivers/target/tcm_nab5000.ko -target:/mnt/sdb/lio-core-2.6.git# mkdir -p /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0 -target:/mnt/sdb/lio-core-2.6.git# cd /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0/ -target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# ln -s /sys/kernel/config/target/core/iblock_0/lvm_test0 nab5000_port - -target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# cd - -target:/mnt/sdb/lio-core-2.6.git# tree /sys/kernel/config/target/nab5000/ -/sys/kernel/config/target/nab5000/ -|-- discovery_auth -|-- iqn.foo -| `-- tpgt_1 -| |-- acls -| |-- attrib -| |-- lun -| | `-- lun_0 -| | |-- alua_tg_pt_gp -| | |-- alua_tg_pt_offline -| | |-- alua_tg_pt_status -| | |-- alua_tg_pt_write_md -| | `-- nab5000_port -> ../../../../../../target/core/iblock_0/lvm_test0 -| |-- np -| `-- param -`-- version - -target:/mnt/sdb/lio-core-2.6.git# lsmod -Module Size Used by -tcm_nab5000 3935 4 -iscsi_target_mod 193211 0 -target_core_stgt 8090 0 -target_core_pscsi 11122 1 -target_core_file 9172 2 -target_core_iblock 9280 1 -target_core_mod 228575 31 -tcm_nab5000,iscsi_target_mod,target_core_stgt,target_core_pscsi,target_core_file,target_core_iblock -libfc 73681 0 -scsi_debug 56265 0 -scsi_tgt 8666 1 target_core_stgt -configfs 20644 2 target_core_mod - ----------------------------------------------------------------------- - -Future TODO items: - - *) Add more T10 proto_idents - *) Make tcm_mod_dump_fabric_ops() smarter and generate function pointer - defs directly from include/target/target_core_fabric_ops.h:struct target_core_fabric_ops - structure members. - -October 5th, 2010 -Nicholas A. Bellinger diff --git a/Documentation/target/tcmu-design.rst b/Documentation/target/tcmu-design.rst new file mode 100644 index 000000000000..a7b426707bf6 --- /dev/null +++ b/Documentation/target/tcmu-design.rst @@ -0,0 +1,405 @@ +==================== +TCM Userspace Design +==================== + + +.. Contents: + + 1) TCM Userspace Design + a) Background + b) Benefits + c) Design constraints + d) Implementation overview + i. Mailbox + ii. Command ring + iii. Data Area + e) Device discovery + f) Device events + g) Other contingencies + 2) Writing a user pass-through handler + a) Discovering and configuring TCMU uio devices + b) Waiting for events on the device(s) + c) Managing the command ring + 3) A final note + + +TCM Userspace Design +==================== + +TCM is another name for LIO, an in-kernel iSCSI target (server). +Existing TCM targets run in the kernel. TCMU (TCM in Userspace) +allows userspace programs to be written which act as iSCSI targets. +This document describes the design. + +The existing kernel provides modules for different SCSI transport +protocols. TCM also modularizes the data storage. There are existing +modules for file, block device, RAM or using another SCSI device as +storage. These are called "backstores" or "storage engines". These +built-in modules are implemented entirely as kernel code. + +Background +---------- + +In addition to modularizing the transport protocol used for carrying +SCSI commands ("fabrics"), the Linux kernel target, LIO, also modularizes +the actual data storage as well. These are referred to as "backstores" +or "storage engines". The target comes with backstores that allow a +file, a block device, RAM, or another SCSI device to be used for the +local storage needed for the exported SCSI LUN. Like the rest of LIO, +these are implemented entirely as kernel code. + +These backstores cover the most common use cases, but not all. One new +use case that other non-kernel target solutions, such as tgt, are able +to support is using Gluster's GLFS or Ceph's RBD as a backstore. The +target then serves as a translator, allowing initiators to store data +in these non-traditional networked storage systems, while still only +using standard protocols themselves. + +If the target is a userspace process, supporting these is easy. tgt, +for example, needs only a small adapter module for each, because the +modules just use the available userspace libraries for RBD and GLFS. + +Adding support for these backstores in LIO is considerably more +difficult, because LIO is entirely kernel code. Instead of undertaking +the significant work to port the GLFS or RBD APIs and protocols to the +kernel, another approach is to create a userspace pass-through +backstore for LIO, "TCMU". + + +Benefits +-------- + +In addition to allowing relatively easy support for RBD and GLFS, TCMU +will also allow easier development of new backstores. TCMU combines +with the LIO loopback fabric to become something similar to FUSE +(Filesystem in Userspace), but at the SCSI layer instead of the +filesystem layer. A SUSE, if you will. + +The disadvantage is there are more distinct components to configure, and +potentially to malfunction. This is unavoidable, but hopefully not +fatal if we're careful to keep things as simple as possible. + +Design constraints +------------------ + +- Good performance: high throughput, low latency +- Cleanly handle if userspace: + + 1) never attaches + 2) hangs + 3) dies + 4) misbehaves + +- Allow future flexibility in user & kernel implementations +- Be reasonably memory-efficient +- Simple to configure & run +- Simple to write a userspace backend + + +Implementation overview +----------------------- + +The core of the TCMU interface is a memory region that is shared +between kernel and userspace. Within this region is: a control area +(mailbox); a lockless producer/consumer circular buffer for commands +to be passed up, and status returned; and an in/out data buffer area. + +TCMU uses the pre-existing UIO subsystem. UIO allows device driver +development in userspace, and this is conceptually very close to the +TCMU use case, except instead of a physical device, TCMU implements a +memory-mapped layout designed for SCSI commands. Using UIO also +benefits TCMU by handling device introspection (e.g. a way for +userspace to determine how large the shared region is) and signaling +mechanisms in both directions. + +There are no embedded pointers in the memory region. Everything is +expressed as an offset from the region's starting address. This allows +the ring to still work if the user process dies and is restarted with +the region mapped at a different virtual address. + +See target_core_user.h for the struct definitions. + +The Mailbox +----------- + +The mailbox is always at the start of the shared memory region, and +contains a version, details about the starting offset and size of the +command ring, and head and tail pointers to be used by the kernel and +userspace (respectively) to put commands on the ring, and indicate +when the commands are completed. + +version - 1 (userspace should abort if otherwise) + +flags: + - TCMU_MAILBOX_FLAG_CAP_OOOC: + indicates out-of-order completion is supported. + See "The Command Ring" for details. + +cmdr_off + The offset of the start of the command ring from the start + of the memory region, to account for the mailbox size. +cmdr_size + The size of the command ring. This does *not* need to be a + power of two. +cmd_head + Modified by the kernel to indicate when a command has been + placed on the ring. +cmd_tail + Modified by userspace to indicate when it has completed + processing of a command. + +The Command Ring +---------------- + +Commands are placed on the ring by the kernel incrementing +mailbox.cmd_head by the size of the command, modulo cmdr_size, and +then signaling userspace via uio_event_notify(). Once the command is +completed, userspace updates mailbox.cmd_tail in the same way and +signals the kernel via a 4-byte write(). When cmd_head equals +cmd_tail, the ring is empty -- no commands are currently waiting to be +processed by userspace. + +TCMU commands are 8-byte aligned. They start with a common header +containing "len_op", a 32-bit value that stores the length, as well as +the opcode in the lowest unused bits. It also contains cmd_id and +flags fields for setting by the kernel (kflags) and userspace +(uflags). + +Currently only two opcodes are defined, TCMU_OP_CMD and TCMU_OP_PAD. + +When the opcode is CMD, the entry in the command ring is a struct +tcmu_cmd_entry. Userspace finds the SCSI CDB (Command Data Block) via +tcmu_cmd_entry.req.cdb_off. This is an offset from the start of the +overall shared memory region, not the entry. The data in/out buffers +are accessible via tht req.iov[] array. iov_cnt contains the number of +entries in iov[] needed to describe either the Data-In or Data-Out +buffers. For bidirectional commands, iov_cnt specifies how many iovec +entries cover the Data-Out area, and iov_bidi_cnt specifies how many +iovec entries immediately after that in iov[] cover the Data-In +area. Just like other fields, iov.iov_base is an offset from the start +of the region. + +When completing a command, userspace sets rsp.scsi_status, and +rsp.sense_buffer if necessary. Userspace then increments +mailbox.cmd_tail by entry.hdr.length (mod cmdr_size) and signals the +kernel via the UIO method, a 4-byte write to the file descriptor. + +If TCMU_MAILBOX_FLAG_CAP_OOOC is set for mailbox->flags, kernel is +capable of handling out-of-order completions. In this case, userspace can +handle command in different order other than original. Since kernel would +still process the commands in the same order it appeared in the command +ring, userspace need to update the cmd->id when completing the +command(a.k.a steal the original command's entry). + +When the opcode is PAD, userspace only updates cmd_tail as above -- +it's a no-op. (The kernel inserts PAD entries to ensure each CMD entry +is contiguous within the command ring.) + +More opcodes may be added in the future. If userspace encounters an +opcode it does not handle, it must set UNKNOWN_OP bit (bit 0) in +hdr.uflags, update cmd_tail, and proceed with processing additional +commands, if any. + +The Data Area +------------- + +This is shared-memory space after the command ring. The organization +of this area is not defined in the TCMU interface, and userspace +should access only the parts referenced by pending iovs. + + +Device Discovery +---------------- + +Other devices may be using UIO besides TCMU. Unrelated user processes +may also be handling different sets of TCMU devices. TCMU userspace +processes must find their devices by scanning sysfs +class/uio/uio*/name. For TCMU devices, these names will be of the +format:: + + tcm-user//// + +where "tcm-user" is common for all TCMU-backed UIO devices. +and allow userspace to find the device's path in the +kernel target's configfs tree. Assuming the usual mount point, it is +found at:: + + /sys/kernel/config/target/core/user_/ + +This location contains attributes such as "hw_block_size", that +userspace needs to know for correct operation. + + will be a userspace-process-unique string to identify the +TCMU device as expecting to be backed by a certain handler, and +will be an additional handler-specific string for the user process to +configure the device, if needed. The name cannot contain ':', due to +LIO limitations. + +For all devices so discovered, the user handler opens /dev/uioX and +calls mmap():: + + mmap(NULL, size, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0) + +where size must be equal to the value read from +/sys/class/uio/uioX/maps/map0/size. + + +Device Events +------------- + +If a new device is added or removed, a notification will be broadcast +over netlink, using a generic netlink family name of "TCM-USER" and a +multicast group named "config". This will include the UIO name as +described in the previous section, as well as the UIO minor +number. This should allow userspace to identify both the UIO device and +the LIO device, so that after determining the device is supported +(based on subtype) it can take the appropriate action. + + +Other contingencies +------------------- + +Userspace handler process never attaches: + +- TCMU will post commands, and then abort them after a timeout period + (30 seconds.) + +Userspace handler process is killed: + +- It is still possible to restart and re-connect to TCMU + devices. Command ring is preserved. However, after the timeout period, + the kernel will abort pending tasks. + +Userspace handler process hangs: + +- The kernel will abort pending tasks after a timeout period. + +Userspace handler process is malicious: + +- The process can trivially break the handling of devices it controls, + but should not be able to access kernel memory outside its shared + memory areas. + + +Writing a user pass-through handler (with example code) +======================================================= + +A user process handing a TCMU device must support the following: + +a) Discovering and configuring TCMU uio devices +b) Waiting for events on the device(s) +c) Managing the command ring: Parsing operations and commands, + performing work as needed, setting response fields (scsi_status and + possibly sense_buffer), updating cmd_tail, and notifying the kernel + that work has been finished + +First, consider instead writing a plugin for tcmu-runner. tcmu-runner +implements all of this, and provides a higher-level API for plugin +authors. + +TCMU is designed so that multiple unrelated processes can manage TCMU +devices separately. All handlers should make sure to only open their +devices, based opon a known subtype string. + +a) Discovering and configuring TCMU UIO devices:: + + /* error checking omitted for brevity */ + + int fd, dev_fd; + char buf[256]; + unsigned long long map_len; + void *map; + + fd = open("/sys/class/uio/uio0/name", O_RDONLY); + ret = read(fd, buf, sizeof(buf)); + close(fd); + buf[ret-1] = '\0'; /* null-terminate and chop off the \n */ + + /* we only want uio devices whose name is a format we expect */ + if (strncmp(buf, "tcm-user", 8)) + exit(-1); + + /* Further checking for subtype also needed here */ + + fd = open(/sys/class/uio/%s/maps/map0/size, O_RDONLY); + ret = read(fd, buf, sizeof(buf)); + close(fd); + str_buf[ret-1] = '\0'; /* null-terminate and chop off the \n */ + + map_len = strtoull(buf, NULL, 0); + + dev_fd = open("/dev/uio0", O_RDWR); + map = mmap(NULL, map_len, PROT_READ|PROT_WRITE, MAP_SHARED, dev_fd, 0); + + + b) Waiting for events on the device(s) + + while (1) { + char buf[4]; + + int ret = read(dev_fd, buf, 4); /* will block */ + + handle_device_events(dev_fd, map); + } + + +c) Managing the command ring:: + + #include + + int handle_device_events(int fd, void *map) + { + struct tcmu_mailbox *mb = map; + struct tcmu_cmd_entry *ent = (void *) mb + mb->cmdr_off + mb->cmd_tail; + int did_some_work = 0; + + /* Process events from cmd ring until we catch up with cmd_head */ + while (ent != (void *)mb + mb->cmdr_off + mb->cmd_head) { + + if (tcmu_hdr_get_op(ent->hdr.len_op) == TCMU_OP_CMD) { + uint8_t *cdb = (void *)mb + ent->req.cdb_off; + bool success = true; + + /* Handle command here. */ + printf("SCSI opcode: 0x%x\n", cdb[0]); + + /* Set response fields */ + if (success) + ent->rsp.scsi_status = SCSI_NO_SENSE; + else { + /* Also fill in rsp->sense_buffer here */ + ent->rsp.scsi_status = SCSI_CHECK_CONDITION; + } + } + else if (tcmu_hdr_get_op(ent->hdr.len_op) != TCMU_OP_PAD) { + /* Tell the kernel we didn't handle unknown opcodes */ + ent->hdr.uflags |= TCMU_UFLAG_UNKNOWN_OP; + } + else { + /* Do nothing for PAD entries except update cmd_tail */ + } + + /* update cmd_tail */ + mb->cmd_tail = (mb->cmd_tail + tcmu_hdr_get_len(&ent->hdr)) % mb->cmdr_size; + ent = (void *) mb + mb->cmdr_off + mb->cmd_tail; + did_some_work = 1; + } + + /* Notify the kernel that work has been finished */ + if (did_some_work) { + uint32_t buf = 0; + + write(fd, &buf, 4); + } + + return 0; + } + + +A final note +============ + +Please be careful to return codes as defined by the SCSI +specifications. These are different than some values defined in the +scsi/scsi.h include file. For example, CHECK CONDITION's status code +is 2, not 1. diff --git a/Documentation/target/tcmu-design.txt b/Documentation/target/tcmu-design.txt deleted file mode 100644 index 4cebc1ebf99a..000000000000 --- a/Documentation/target/tcmu-design.txt +++ /dev/null @@ -1,381 +0,0 @@ -Contents: - -1) TCM Userspace Design - a) Background - b) Benefits - c) Design constraints - d) Implementation overview - i. Mailbox - ii. Command ring - iii. Data Area - e) Device discovery - f) Device events - g) Other contingencies -2) Writing a user pass-through handler - a) Discovering and configuring TCMU uio devices - b) Waiting for events on the device(s) - c) Managing the command ring -3) A final note - - -TCM Userspace Design --------------------- - -TCM is another name for LIO, an in-kernel iSCSI target (server). -Existing TCM targets run in the kernel. TCMU (TCM in Userspace) -allows userspace programs to be written which act as iSCSI targets. -This document describes the design. - -The existing kernel provides modules for different SCSI transport -protocols. TCM also modularizes the data storage. There are existing -modules for file, block device, RAM or using another SCSI device as -storage. These are called "backstores" or "storage engines". These -built-in modules are implemented entirely as kernel code. - -Background: - -In addition to modularizing the transport protocol used for carrying -SCSI commands ("fabrics"), the Linux kernel target, LIO, also modularizes -the actual data storage as well. These are referred to as "backstores" -or "storage engines". The target comes with backstores that allow a -file, a block device, RAM, or another SCSI device to be used for the -local storage needed for the exported SCSI LUN. Like the rest of LIO, -these are implemented entirely as kernel code. - -These backstores cover the most common use cases, but not all. One new -use case that other non-kernel target solutions, such as tgt, are able -to support is using Gluster's GLFS or Ceph's RBD as a backstore. The -target then serves as a translator, allowing initiators to store data -in these non-traditional networked storage systems, while still only -using standard protocols themselves. - -If the target is a userspace process, supporting these is easy. tgt, -for example, needs only a small adapter module for each, because the -modules just use the available userspace libraries for RBD and GLFS. - -Adding support for these backstores in LIO is considerably more -difficult, because LIO is entirely kernel code. Instead of undertaking -the significant work to port the GLFS or RBD APIs and protocols to the -kernel, another approach is to create a userspace pass-through -backstore for LIO, "TCMU". - - -Benefits: - -In addition to allowing relatively easy support for RBD and GLFS, TCMU -will also allow easier development of new backstores. TCMU combines -with the LIO loopback fabric to become something similar to FUSE -(Filesystem in Userspace), but at the SCSI layer instead of the -filesystem layer. A SUSE, if you will. - -The disadvantage is there are more distinct components to configure, and -potentially to malfunction. This is unavoidable, but hopefully not -fatal if we're careful to keep things as simple as possible. - -Design constraints: - -- Good performance: high throughput, low latency -- Cleanly handle if userspace: - 1) never attaches - 2) hangs - 3) dies - 4) misbehaves -- Allow future flexibility in user & kernel implementations -- Be reasonably memory-efficient -- Simple to configure & run -- Simple to write a userspace backend - - -Implementation overview: - -The core of the TCMU interface is a memory region that is shared -between kernel and userspace. Within this region is: a control area -(mailbox); a lockless producer/consumer circular buffer for commands -to be passed up, and status returned; and an in/out data buffer area. - -TCMU uses the pre-existing UIO subsystem. UIO allows device driver -development in userspace, and this is conceptually very close to the -TCMU use case, except instead of a physical device, TCMU implements a -memory-mapped layout designed for SCSI commands. Using UIO also -benefits TCMU by handling device introspection (e.g. a way for -userspace to determine how large the shared region is) and signaling -mechanisms in both directions. - -There are no embedded pointers in the memory region. Everything is -expressed as an offset from the region's starting address. This allows -the ring to still work if the user process dies and is restarted with -the region mapped at a different virtual address. - -See target_core_user.h for the struct definitions. - -The Mailbox: - -The mailbox is always at the start of the shared memory region, and -contains a version, details about the starting offset and size of the -command ring, and head and tail pointers to be used by the kernel and -userspace (respectively) to put commands on the ring, and indicate -when the commands are completed. - -version - 1 (userspace should abort if otherwise) -flags: -- TCMU_MAILBOX_FLAG_CAP_OOOC: indicates out-of-order completion is - supported. See "The Command Ring" for details. -cmdr_off - The offset of the start of the command ring from the start -of the memory region, to account for the mailbox size. -cmdr_size - The size of the command ring. This does *not* need to be a -power of two. -cmd_head - Modified by the kernel to indicate when a command has been -placed on the ring. -cmd_tail - Modified by userspace to indicate when it has completed -processing of a command. - -The Command Ring: - -Commands are placed on the ring by the kernel incrementing -mailbox.cmd_head by the size of the command, modulo cmdr_size, and -then signaling userspace via uio_event_notify(). Once the command is -completed, userspace updates mailbox.cmd_tail in the same way and -signals the kernel via a 4-byte write(). When cmd_head equals -cmd_tail, the ring is empty -- no commands are currently waiting to be -processed by userspace. - -TCMU commands are 8-byte aligned. They start with a common header -containing "len_op", a 32-bit value that stores the length, as well as -the opcode in the lowest unused bits. It also contains cmd_id and -flags fields for setting by the kernel (kflags) and userspace -(uflags). - -Currently only two opcodes are defined, TCMU_OP_CMD and TCMU_OP_PAD. - -When the opcode is CMD, the entry in the command ring is a struct -tcmu_cmd_entry. Userspace finds the SCSI CDB (Command Data Block) via -tcmu_cmd_entry.req.cdb_off. This is an offset from the start of the -overall shared memory region, not the entry. The data in/out buffers -are accessible via tht req.iov[] array. iov_cnt contains the number of -entries in iov[] needed to describe either the Data-In or Data-Out -buffers. For bidirectional commands, iov_cnt specifies how many iovec -entries cover the Data-Out area, and iov_bidi_cnt specifies how many -iovec entries immediately after that in iov[] cover the Data-In -area. Just like other fields, iov.iov_base is an offset from the start -of the region. - -When completing a command, userspace sets rsp.scsi_status, and -rsp.sense_buffer if necessary. Userspace then increments -mailbox.cmd_tail by entry.hdr.length (mod cmdr_size) and signals the -kernel via the UIO method, a 4-byte write to the file descriptor. - -If TCMU_MAILBOX_FLAG_CAP_OOOC is set for mailbox->flags, kernel is -capable of handling out-of-order completions. In this case, userspace can -handle command in different order other than original. Since kernel would -still process the commands in the same order it appeared in the command -ring, userspace need to update the cmd->id when completing the -command(a.k.a steal the original command's entry). - -When the opcode is PAD, userspace only updates cmd_tail as above -- -it's a no-op. (The kernel inserts PAD entries to ensure each CMD entry -is contiguous within the command ring.) - -More opcodes may be added in the future. If userspace encounters an -opcode it does not handle, it must set UNKNOWN_OP bit (bit 0) in -hdr.uflags, update cmd_tail, and proceed with processing additional -commands, if any. - -The Data Area: - -This is shared-memory space after the command ring. The organization -of this area is not defined in the TCMU interface, and userspace -should access only the parts referenced by pending iovs. - - -Device Discovery: - -Other devices may be using UIO besides TCMU. Unrelated user processes -may also be handling different sets of TCMU devices. TCMU userspace -processes must find their devices by scanning sysfs -class/uio/uio*/name. For TCMU devices, these names will be of the -format: - -tcm-user//// - -where "tcm-user" is common for all TCMU-backed UIO devices. -and allow userspace to find the device's path in the -kernel target's configfs tree. Assuming the usual mount point, it is -found at: - -/sys/kernel/config/target/core/user_/ - -This location contains attributes such as "hw_block_size", that -userspace needs to know for correct operation. - - will be a userspace-process-unique string to identify the -TCMU device as expecting to be backed by a certain handler, and -will be an additional handler-specific string for the user process to -configure the device, if needed. The name cannot contain ':', due to -LIO limitations. - -For all devices so discovered, the user handler opens /dev/uioX and -calls mmap(): - -mmap(NULL, size, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0) - -where size must be equal to the value read from -/sys/class/uio/uioX/maps/map0/size. - - -Device Events: - -If a new device is added or removed, a notification will be broadcast -over netlink, using a generic netlink family name of "TCM-USER" and a -multicast group named "config". This will include the UIO name as -described in the previous section, as well as the UIO minor -number. This should allow userspace to identify both the UIO device and -the LIO device, so that after determining the device is supported -(based on subtype) it can take the appropriate action. - - -Other contingencies: - -Userspace handler process never attaches: - -- TCMU will post commands, and then abort them after a timeout period - (30 seconds.) - -Userspace handler process is killed: - -- It is still possible to restart and re-connect to TCMU - devices. Command ring is preserved. However, after the timeout period, - the kernel will abort pending tasks. - -Userspace handler process hangs: - -- The kernel will abort pending tasks after a timeout period. - -Userspace handler process is malicious: - -- The process can trivially break the handling of devices it controls, - but should not be able to access kernel memory outside its shared - memory areas. - - -Writing a user pass-through handler (with example code) -------------------------------------------------------- - -A user process handing a TCMU device must support the following: - -a) Discovering and configuring TCMU uio devices -b) Waiting for events on the device(s) -c) Managing the command ring: Parsing operations and commands, - performing work as needed, setting response fields (scsi_status and - possibly sense_buffer), updating cmd_tail, and notifying the kernel - that work has been finished - -First, consider instead writing a plugin for tcmu-runner. tcmu-runner -implements all of this, and provides a higher-level API for plugin -authors. - -TCMU is designed so that multiple unrelated processes can manage TCMU -devices separately. All handlers should make sure to only open their -devices, based opon a known subtype string. - -a) Discovering and configuring TCMU UIO devices: - -(error checking omitted for brevity) - -int fd, dev_fd; -char buf[256]; -unsigned long long map_len; -void *map; - -fd = open("/sys/class/uio/uio0/name", O_RDONLY); -ret = read(fd, buf, sizeof(buf)); -close(fd); -buf[ret-1] = '\0'; /* null-terminate and chop off the \n */ - -/* we only want uio devices whose name is a format we expect */ -if (strncmp(buf, "tcm-user", 8)) - exit(-1); - -/* Further checking for subtype also needed here */ - -fd = open(/sys/class/uio/%s/maps/map0/size, O_RDONLY); -ret = read(fd, buf, sizeof(buf)); -close(fd); -str_buf[ret-1] = '\0'; /* null-terminate and chop off the \n */ - -map_len = strtoull(buf, NULL, 0); - -dev_fd = open("/dev/uio0", O_RDWR); -map = mmap(NULL, map_len, PROT_READ|PROT_WRITE, MAP_SHARED, dev_fd, 0); - - -b) Waiting for events on the device(s) - -while (1) { - char buf[4]; - - int ret = read(dev_fd, buf, 4); /* will block */ - - handle_device_events(dev_fd, map); -} - - -c) Managing the command ring - -#include - -int handle_device_events(int fd, void *map) -{ - struct tcmu_mailbox *mb = map; - struct tcmu_cmd_entry *ent = (void *) mb + mb->cmdr_off + mb->cmd_tail; - int did_some_work = 0; - - /* Process events from cmd ring until we catch up with cmd_head */ - while (ent != (void *)mb + mb->cmdr_off + mb->cmd_head) { - - if (tcmu_hdr_get_op(ent->hdr.len_op) == TCMU_OP_CMD) { - uint8_t *cdb = (void *)mb + ent->req.cdb_off; - bool success = true; - - /* Handle command here. */ - printf("SCSI opcode: 0x%x\n", cdb[0]); - - /* Set response fields */ - if (success) - ent->rsp.scsi_status = SCSI_NO_SENSE; - else { - /* Also fill in rsp->sense_buffer here */ - ent->rsp.scsi_status = SCSI_CHECK_CONDITION; - } - } - else if (tcmu_hdr_get_op(ent->hdr.len_op) != TCMU_OP_PAD) { - /* Tell the kernel we didn't handle unknown opcodes */ - ent->hdr.uflags |= TCMU_UFLAG_UNKNOWN_OP; - } - else { - /* Do nothing for PAD entries except update cmd_tail */ - } - - /* update cmd_tail */ - mb->cmd_tail = (mb->cmd_tail + tcmu_hdr_get_len(&ent->hdr)) % mb->cmdr_size; - ent = (void *) mb + mb->cmdr_off + mb->cmd_tail; - did_some_work = 1; - } - - /* Notify the kernel that work has been finished */ - if (did_some_work) { - uint32_t buf = 0; - - write(fd, &buf, 4); - } - - return 0; -} - - -A final note ------------- - -Please be careful to return codes as defined by the SCSI -specifications. These are different than some values defined in the -scsi/scsi.h include file. For example, CHECK CONDITION's status code -is 2, not 1. diff --git a/scripts/documentation-file-ref-check b/scripts/documentation-file-ref-check index 440227bb55a9..a4139a576726 100755 --- a/scripts/documentation-file-ref-check +++ b/scripts/documentation-file-ref-check @@ -124,7 +124,7 @@ while () { # Remove sched-pelt false-positive next if ($fulref =~ m,^Documentation/scheduler/sched-pelt$,); - # Discard some build examples from Documentation/target/tcm_mod_builder.txt + # Discard some build examples from Documentation/target/tcm_mod_builder.rst next if ($fulref =~ m,mnt/sdb/lio-core-2.6.git/Documentation/target,); # Check if exists, evaluating wildcards -- cgit v1.2.3 From 458f69ef36656dc74679667380422dd8063eabfb Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 12 Jun 2019 14:53:00 -0300 Subject: docs: timers: convert docs to ReST and rename to *.rst The conversion here is really trivial: just a bunch of title markups and very few puntual changes is enough to make it to be parsed by Sphinx and generate a nice html. The conversion is actually: - add blank lines and identation in order to identify paragraphs; - fix tables markups; - add some lists markups; - mark literal blocks; - adjust title markups. At its new index.rst, let's add a :orphan: while this is not linked to the main index.rst file, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab Acked-by: Mark Brown Signed-off-by: Jonathan Corbet --- Documentation/timers/NO_HZ.txt | 318 --------------------------------- Documentation/timers/highres.rst | 250 ++++++++++++++++++++++++++ Documentation/timers/highres.txt | 249 -------------------------- Documentation/timers/hpet.rst | 30 ++++ Documentation/timers/hpet.txt | 28 --- Documentation/timers/hrtimers.rst | 178 +++++++++++++++++++ Documentation/timers/hrtimers.txt | 178 ------------------- Documentation/timers/index.rst | 22 +++ Documentation/timers/no_hz.rst | 326 ++++++++++++++++++++++++++++++++++ Documentation/timers/timekeeping.rst | 180 +++++++++++++++++++ Documentation/timers/timekeeping.txt | 179 ------------------- Documentation/timers/timers-howto.rst | 112 ++++++++++++ Documentation/timers/timers-howto.txt | 105 ----------- MAINTAINERS | 2 +- drivers/media/usb/dvb-usb-v2/anysee.c | 2 +- drivers/regulator/core.c | 2 +- include/linux/iopoll.h | 4 +- include/linux/regmap.h | 4 +- scripts/checkpatch.pl | 8 +- sound/soc/sof/ops.h | 2 +- 20 files changed, 1110 insertions(+), 1069 deletions(-) delete mode 100644 Documentation/timers/NO_HZ.txt create mode 100644 Documentation/timers/highres.rst delete mode 100644 Documentation/timers/highres.txt create mode 100644 Documentation/timers/hpet.rst delete mode 100644 Documentation/timers/hpet.txt create mode 100644 Documentation/timers/hrtimers.rst delete mode 100644 Documentation/timers/hrtimers.txt create mode 100644 Documentation/timers/index.rst create mode 100644 Documentation/timers/no_hz.rst create mode 100644 Documentation/timers/timekeeping.rst delete mode 100644 Documentation/timers/timekeeping.txt create mode 100644 Documentation/timers/timers-howto.rst delete mode 100644 Documentation/timers/timers-howto.txt (limited to 'scripts') diff --git a/Documentation/timers/NO_HZ.txt b/Documentation/timers/NO_HZ.txt deleted file mode 100644 index 9591092da5e0..000000000000 --- a/Documentation/timers/NO_HZ.txt +++ /dev/null @@ -1,318 +0,0 @@ - NO_HZ: Reducing Scheduling-Clock Ticks - - -This document describes Kconfig options and boot parameters that can -reduce the number of scheduling-clock interrupts, thereby improving energy -efficiency and reducing OS jitter. Reducing OS jitter is important for -some types of computationally intensive high-performance computing (HPC) -applications and for real-time applications. - -There are three main ways of managing scheduling-clock interrupts -(also known as "scheduling-clock ticks" or simply "ticks"): - -1. Never omit scheduling-clock ticks (CONFIG_HZ_PERIODIC=y or - CONFIG_NO_HZ=n for older kernels). You normally will -not- - want to choose this option. - -2. Omit scheduling-clock ticks on idle CPUs (CONFIG_NO_HZ_IDLE=y or - CONFIG_NO_HZ=y for older kernels). This is the most common - approach, and should be the default. - -3. Omit scheduling-clock ticks on CPUs that are either idle or that - have only one runnable task (CONFIG_NO_HZ_FULL=y). Unless you - are running realtime applications or certain types of HPC - workloads, you will normally -not- want this option. - -These three cases are described in the following three sections, followed -by a third section on RCU-specific considerations, a fourth section -discussing testing, and a fifth and final section listing known issues. - - -NEVER OMIT SCHEDULING-CLOCK TICKS - -Very old versions of Linux from the 1990s and the very early 2000s -are incapable of omitting scheduling-clock ticks. It turns out that -there are some situations where this old-school approach is still the -right approach, for example, in heavy workloads with lots of tasks -that use short bursts of CPU, where there are very frequent idle -periods, but where these idle periods are also quite short (tens or -hundreds of microseconds). For these types of workloads, scheduling -clock interrupts will normally be delivered any way because there -will frequently be multiple runnable tasks per CPU. In these cases, -attempting to turn off the scheduling clock interrupt will have no effect -other than increasing the overhead of switching to and from idle and -transitioning between user and kernel execution. - -This mode of operation can be selected using CONFIG_HZ_PERIODIC=y (or -CONFIG_NO_HZ=n for older kernels). - -However, if you are instead running a light workload with long idle -periods, failing to omit scheduling-clock interrupts will result in -excessive power consumption. This is especially bad on battery-powered -devices, where it results in extremely short battery lifetimes. If you -are running light workloads, you should therefore read the following -section. - -In addition, if you are running either a real-time workload or an HPC -workload with short iterations, the scheduling-clock interrupts can -degrade your applications performance. If this describes your workload, -you should read the following two sections. - - -OMIT SCHEDULING-CLOCK TICKS FOR IDLE CPUs - -If a CPU is idle, there is little point in sending it a scheduling-clock -interrupt. After all, the primary purpose of a scheduling-clock interrupt -is to force a busy CPU to shift its attention among multiple duties, -and an idle CPU has no duties to shift its attention among. - -The CONFIG_NO_HZ_IDLE=y Kconfig option causes the kernel to avoid sending -scheduling-clock interrupts to idle CPUs, which is critically important -both to battery-powered devices and to highly virtualized mainframes. -A battery-powered device running a CONFIG_HZ_PERIODIC=y kernel would -drain its battery very quickly, easily 2-3 times as fast as would the -same device running a CONFIG_NO_HZ_IDLE=y kernel. A mainframe running -1,500 OS instances might find that half of its CPU time was consumed by -unnecessary scheduling-clock interrupts. In these situations, there -is strong motivation to avoid sending scheduling-clock interrupts to -idle CPUs. That said, dyntick-idle mode is not free: - -1. It increases the number of instructions executed on the path - to and from the idle loop. - -2. On many architectures, dyntick-idle mode also increases the - number of expensive clock-reprogramming operations. - -Therefore, systems with aggressive real-time response constraints often -run CONFIG_HZ_PERIODIC=y kernels (or CONFIG_NO_HZ=n for older kernels) -in order to avoid degrading from-idle transition latencies. - -An idle CPU that is not receiving scheduling-clock interrupts is said to -be "dyntick-idle", "in dyntick-idle mode", "in nohz mode", or "running -tickless". The remainder of this document will use "dyntick-idle mode". - -There is also a boot parameter "nohz=" that can be used to disable -dyntick-idle mode in CONFIG_NO_HZ_IDLE=y kernels by specifying "nohz=off". -By default, CONFIG_NO_HZ_IDLE=y kernels boot with "nohz=on", enabling -dyntick-idle mode. - - -OMIT SCHEDULING-CLOCK TICKS FOR CPUs WITH ONLY ONE RUNNABLE TASK - -If a CPU has only one runnable task, there is little point in sending it -a scheduling-clock interrupt because there is no other task to switch to. -Note that omitting scheduling-clock ticks for CPUs with only one runnable -task implies also omitting them for idle CPUs. - -The CONFIG_NO_HZ_FULL=y Kconfig option causes the kernel to avoid -sending scheduling-clock interrupts to CPUs with a single runnable task, -and such CPUs are said to be "adaptive-ticks CPUs". This is important -for applications with aggressive real-time response constraints because -it allows them to improve their worst-case response times by the maximum -duration of a scheduling-clock interrupt. It is also important for -computationally intensive short-iteration workloads: If any CPU is -delayed during a given iteration, all the other CPUs will be forced to -wait idle while the delayed CPU finishes. Thus, the delay is multiplied -by one less than the number of CPUs. In these situations, there is -again strong motivation to avoid sending scheduling-clock interrupts. - -By default, no CPU will be an adaptive-ticks CPU. The "nohz_full=" -boot parameter specifies the adaptive-ticks CPUs. For example, -"nohz_full=1,6-8" says that CPUs 1, 6, 7, and 8 are to be adaptive-ticks -CPUs. Note that you are prohibited from marking all of the CPUs as -adaptive-tick CPUs: At least one non-adaptive-tick CPU must remain -online to handle timekeeping tasks in order to ensure that system -calls like gettimeofday() returns accurate values on adaptive-tick CPUs. -(This is not an issue for CONFIG_NO_HZ_IDLE=y because there are no running -user processes to observe slight drifts in clock rate.) Therefore, the -boot CPU is prohibited from entering adaptive-ticks mode. Specifying a -"nohz_full=" mask that includes the boot CPU will result in a boot-time -error message, and the boot CPU will be removed from the mask. Note that -this means that your system must have at least two CPUs in order for -CONFIG_NO_HZ_FULL=y to do anything for you. - -Finally, adaptive-ticks CPUs must have their RCU callbacks offloaded. -This is covered in the "RCU IMPLICATIONS" section below. - -Normally, a CPU remains in adaptive-ticks mode as long as possible. -In particular, transitioning to kernel mode does not automatically change -the mode. Instead, the CPU will exit adaptive-ticks mode only if needed, -for example, if that CPU enqueues an RCU callback. - -Just as with dyntick-idle mode, the benefits of adaptive-tick mode do -not come for free: - -1. CONFIG_NO_HZ_FULL selects CONFIG_NO_HZ_COMMON, so you cannot run - adaptive ticks without also running dyntick idle. This dependency - extends down into the implementation, so that all of the costs - of CONFIG_NO_HZ_IDLE are also incurred by CONFIG_NO_HZ_FULL. - -2. The user/kernel transitions are slightly more expensive due - to the need to inform kernel subsystems (such as RCU) about - the change in mode. - -3. POSIX CPU timers prevent CPUs from entering adaptive-tick mode. - Real-time applications needing to take actions based on CPU time - consumption need to use other means of doing so. - -4. If there are more perf events pending than the hardware can - accommodate, they are normally round-robined so as to collect - all of them over time. Adaptive-tick mode may prevent this - round-robining from happening. This will likely be fixed by - preventing CPUs with large numbers of perf events pending from - entering adaptive-tick mode. - -5. Scheduler statistics for adaptive-tick CPUs may be computed - slightly differently than those for non-adaptive-tick CPUs. - This might in turn perturb load-balancing of real-time tasks. - -6. The LB_BIAS scheduler feature is disabled by adaptive ticks. - -Although improvements are expected over time, adaptive ticks is quite -useful for many types of real-time and compute-intensive applications. -However, the drawbacks listed above mean that adaptive ticks should not -(yet) be enabled by default. - - -RCU IMPLICATIONS - -There are situations in which idle CPUs cannot be permitted to -enter either dyntick-idle mode or adaptive-tick mode, the most -common being when that CPU has RCU callbacks pending. - -The CONFIG_RCU_FAST_NO_HZ=y Kconfig option may be used to cause such CPUs -to enter dyntick-idle mode or adaptive-tick mode anyway. In this case, -a timer will awaken these CPUs every four jiffies in order to ensure -that the RCU callbacks are processed in a timely fashion. - -Another approach is to offload RCU callback processing to "rcuo" kthreads -using the CONFIG_RCU_NOCB_CPU=y Kconfig option. The specific CPUs to -offload may be selected using The "rcu_nocbs=" kernel boot parameter, -which takes a comma-separated list of CPUs and CPU ranges, for example, -"1,3-5" selects CPUs 1, 3, 4, and 5. - -The offloaded CPUs will never queue RCU callbacks, and therefore RCU -never prevents offloaded CPUs from entering either dyntick-idle mode -or adaptive-tick mode. That said, note that it is up to userspace to -pin the "rcuo" kthreads to specific CPUs if desired. Otherwise, the -scheduler will decide where to run them, which might or might not be -where you want them to run. - - -TESTING - -So you enable all the OS-jitter features described in this document, -but do not see any change in your workload's behavior. Is this because -your workload isn't affected that much by OS jitter, or is it because -something else is in the way? This section helps answer this question -by providing a simple OS-jitter test suite, which is available on branch -master of the following git archive: - -git://git.kernel.org/pub/scm/linux/kernel/git/frederic/dynticks-testing.git - -Clone this archive and follow the instructions in the README file. -This test procedure will produce a trace that will allow you to evaluate -whether or not you have succeeded in removing OS jitter from your system. -If this trace shows that you have removed OS jitter as much as is -possible, then you can conclude that your workload is not all that -sensitive to OS jitter. - -Note: this test requires that your system have at least two CPUs. -We do not currently have a good way to remove OS jitter from single-CPU -systems. - - -KNOWN ISSUES - -o Dyntick-idle slows transitions to and from idle slightly. - In practice, this has not been a problem except for the most - aggressive real-time workloads, which have the option of disabling - dyntick-idle mode, an option that most of them take. However, - some workloads will no doubt want to use adaptive ticks to - eliminate scheduling-clock interrupt latencies. Here are some - options for these workloads: - - a. Use PMQOS from userspace to inform the kernel of your - latency requirements (preferred). - - b. On x86 systems, use the "idle=mwait" boot parameter. - - c. On x86 systems, use the "intel_idle.max_cstate=" to limit - ` the maximum C-state depth. - - d. On x86 systems, use the "idle=poll" boot parameter. - However, please note that use of this parameter can cause - your CPU to overheat, which may cause thermal throttling - to degrade your latencies -- and that this degradation can - be even worse than that of dyntick-idle. Furthermore, - this parameter effectively disables Turbo Mode on Intel - CPUs, which can significantly reduce maximum performance. - -o Adaptive-ticks slows user/kernel transitions slightly. - This is not expected to be a problem for computationally intensive - workloads, which have few such transitions. Careful benchmarking - will be required to determine whether or not other workloads - are significantly affected by this effect. - -o Adaptive-ticks does not do anything unless there is only one - runnable task for a given CPU, even though there are a number - of other situations where the scheduling-clock tick is not - needed. To give but one example, consider a CPU that has one - runnable high-priority SCHED_FIFO task and an arbitrary number - of low-priority SCHED_OTHER tasks. In this case, the CPU is - required to run the SCHED_FIFO task until it either blocks or - some other higher-priority task awakens on (or is assigned to) - this CPU, so there is no point in sending a scheduling-clock - interrupt to this CPU. However, the current implementation - nevertheless sends scheduling-clock interrupts to CPUs having a - single runnable SCHED_FIFO task and multiple runnable SCHED_OTHER - tasks, even though these interrupts are unnecessary. - - And even when there are multiple runnable tasks on a given CPU, - there is little point in interrupting that CPU until the current - running task's timeslice expires, which is almost always way - longer than the time of the next scheduling-clock interrupt. - - Better handling of these sorts of situations is future work. - -o A reboot is required to reconfigure both adaptive idle and RCU - callback offloading. Runtime reconfiguration could be provided - if needed, however, due to the complexity of reconfiguring RCU at - runtime, there would need to be an earthshakingly good reason. - Especially given that you have the straightforward option of - simply offloading RCU callbacks from all CPUs and pinning them - where you want them whenever you want them pinned. - -o Additional configuration is required to deal with other sources - of OS jitter, including interrupts and system-utility tasks - and processes. This configuration normally involves binding - interrupts and tasks to particular CPUs. - -o Some sources of OS jitter can currently be eliminated only by - constraining the workload. For example, the only way to eliminate - OS jitter due to global TLB shootdowns is to avoid the unmapping - operations (such as kernel module unload operations) that - result in these shootdowns. For another example, page faults - and TLB misses can be reduced (and in some cases eliminated) by - using huge pages and by constraining the amount of memory used - by the application. Pre-faulting the working set can also be - helpful, especially when combined with the mlock() and mlockall() - system calls. - -o Unless all CPUs are idle, at least one CPU must keep the - scheduling-clock interrupt going in order to support accurate - timekeeping. - -o If there might potentially be some adaptive-ticks CPUs, there - will be at least one CPU keeping the scheduling-clock interrupt - going, even if all CPUs are otherwise idle. - - Better handling of this situation is ongoing work. - -o Some process-handling operations still require the occasional - scheduling-clock tick. These operations include calculating CPU - load, maintaining sched average, computing CFS entity vruntime, - computing avenrun, and carrying out load balancing. They are - currently accommodated by scheduling-clock tick every second - or so. On-going work will eliminate the need even for these - infrequent scheduling-clock ticks. diff --git a/Documentation/timers/highres.rst b/Documentation/timers/highres.rst new file mode 100644 index 000000000000..bde5eb7e5c9e --- /dev/null +++ b/Documentation/timers/highres.rst @@ -0,0 +1,250 @@ +===================================================== +High resolution timers and dynamic ticks design notes +===================================================== + +Further information can be found in the paper of the OLS 2006 talk "hrtimers +and beyond". The paper is part of the OLS 2006 Proceedings Volume 1, which can +be found on the OLS website: +https://www.kernel.org/doc/ols/2006/ols2006v1-pages-333-346.pdf + +The slides to this talk are available from: +http://www.cs.columbia.edu/~nahum/w6998/papers/ols2006-hrtimers-slides.pdf + +The slides contain five figures (pages 2, 15, 18, 20, 22), which illustrate the +changes in the time(r) related Linux subsystems. Figure #1 (p. 2) shows the +design of the Linux time(r) system before hrtimers and other building blocks +got merged into mainline. + +Note: the paper and the slides are talking about "clock event source", while we +switched to the name "clock event devices" in meantime. + +The design contains the following basic building blocks: + +- hrtimer base infrastructure +- timeofday and clock source management +- clock event management +- high resolution timer functionality +- dynamic ticks + + +hrtimer base infrastructure +--------------------------- + +The hrtimer base infrastructure was merged into the 2.6.16 kernel. Details of +the base implementation are covered in Documentation/timers/hrtimers.rst. See +also figure #2 (OLS slides p. 15) + +The main differences to the timer wheel, which holds the armed timer_list type +timers are: + + - time ordered enqueueing into a rb-tree + - independent of ticks (the processing is based on nanoseconds) + + +timeofday and clock source management +------------------------------------- + +John Stultz's Generic Time Of Day (GTOD) framework moves a large portion of +code out of the architecture-specific areas into a generic management +framework, as illustrated in figure #3 (OLS slides p. 18). The architecture +specific portion is reduced to the low level hardware details of the clock +sources, which are registered in the framework and selected on a quality based +decision. The low level code provides hardware setup and readout routines and +initializes data structures, which are used by the generic time keeping code to +convert the clock ticks to nanosecond based time values. All other time keeping +related functionality is moved into the generic code. The GTOD base patch got +merged into the 2.6.18 kernel. + +Further information about the Generic Time Of Day framework is available in the +OLS 2005 Proceedings Volume 1: + + http://www.linuxsymposium.org/2005/linuxsymposium_procv1.pdf + +The paper "We Are Not Getting Any Younger: A New Approach to Time and +Timers" was written by J. Stultz, D.V. Hart, & N. Aravamudan. + +Figure #3 (OLS slides p.18) illustrates the transformation. + + +clock event management +---------------------- + +While clock sources provide read access to the monotonically increasing time +value, clock event devices are used to schedule the next event +interrupt(s). The next event is currently defined to be periodic, with its +period defined at compile time. The setup and selection of the event device +for various event driven functionalities is hardwired into the architecture +dependent code. This results in duplicated code across all architectures and +makes it extremely difficult to change the configuration of the system to use +event interrupt devices other than those already built into the +architecture. Another implication of the current design is that it is necessary +to touch all the architecture-specific implementations in order to provide new +functionality like high resolution timers or dynamic ticks. + +The clock events subsystem tries to address this problem by providing a generic +solution to manage clock event devices and their usage for the various clock +event driven kernel functionalities. The goal of the clock event subsystem is +to minimize the clock event related architecture dependent code to the pure +hardware related handling and to allow easy addition and utilization of new +clock event devices. It also minimizes the duplicated code across the +architectures as it provides generic functionality down to the interrupt +service handler, which is almost inherently hardware dependent. + +Clock event devices are registered either by the architecture dependent boot +code or at module insertion time. Each clock event device fills a data +structure with clock-specific property parameters and callback functions. The +clock event management decides, by using the specified property parameters, the +set of system functions a clock event device will be used to support. This +includes the distinction of per-CPU and per-system global event devices. + +System-level global event devices are used for the Linux periodic tick. Per-CPU +event devices are used to provide local CPU functionality such as process +accounting, profiling, and high resolution timers. + +The management layer assigns one or more of the following functions to a clock +event device: + + - system global periodic tick (jiffies update) + - cpu local update_process_times + - cpu local profiling + - cpu local next event interrupt (non periodic mode) + +The clock event device delegates the selection of those timer interrupt related +functions completely to the management layer. The clock management layer stores +a function pointer in the device description structure, which has to be called +from the hardware level handler. This removes a lot of duplicated code from the +architecture specific timer interrupt handlers and hands the control over the +clock event devices and the assignment of timer interrupt related functionality +to the core code. + +The clock event layer API is rather small. Aside from the clock event device +registration interface it provides functions to schedule the next event +interrupt, clock event device notification service and support for suspend and +resume. + +The framework adds about 700 lines of code which results in a 2KB increase of +the kernel binary size. The conversion of i386 removes about 100 lines of +code. The binary size decrease is in the range of 400 byte. We believe that the +increase of flexibility and the avoidance of duplicated code across +architectures justifies the slight increase of the binary size. + +The conversion of an architecture has no functional impact, but allows to +utilize the high resolution and dynamic tick functionalities without any change +to the clock event device and timer interrupt code. After the conversion the +enabling of high resolution timers and dynamic ticks is simply provided by +adding the kernel/time/Kconfig file to the architecture specific Kconfig and +adding the dynamic tick specific calls to the idle routine (a total of 3 lines +added to the idle function and the Kconfig file) + +Figure #4 (OLS slides p.20) illustrates the transformation. + + +high resolution timer functionality +----------------------------------- + +During system boot it is not possible to use the high resolution timer +functionality, while making it possible would be difficult and would serve no +useful function. The initialization of the clock event device framework, the +clock source framework (GTOD) and hrtimers itself has to be done and +appropriate clock sources and clock event devices have to be registered before +the high resolution functionality can work. Up to the point where hrtimers are +initialized, the system works in the usual low resolution periodic mode. The +clock source and the clock event device layers provide notification functions +which inform hrtimers about availability of new hardware. hrtimers validates +the usability of the registered clock sources and clock event devices before +switching to high resolution mode. This ensures also that a kernel which is +configured for high resolution timers can run on a system which lacks the +necessary hardware support. + +The high resolution timer code does not support SMP machines which have only +global clock event devices. The support of such hardware would involve IPI +calls when an interrupt happens. The overhead would be much larger than the +benefit. This is the reason why we currently disable high resolution and +dynamic ticks on i386 SMP systems which stop the local APIC in C3 power +state. A workaround is available as an idea, but the problem has not been +tackled yet. + +The time ordered insertion of timers provides all the infrastructure to decide +whether the event device has to be reprogrammed when a timer is added. The +decision is made per timer base and synchronized across per-cpu timer bases in +a support function. The design allows the system to utilize separate per-CPU +clock event devices for the per-CPU timer bases, but currently only one +reprogrammable clock event device per-CPU is utilized. + +When the timer interrupt happens, the next event interrupt handler is called +from the clock event distribution code and moves expired timers from the +red-black tree to a separate double linked list and invokes the softirq +handler. An additional mode field in the hrtimer structure allows the system to +execute callback functions directly from the next event interrupt handler. This +is restricted to code which can safely be executed in the hard interrupt +context. This applies, for example, to the common case of a wakeup function as +used by nanosleep. The advantage of executing the handler in the interrupt +context is the avoidance of up to two context switches - from the interrupted +context to the softirq and to the task which is woken up by the expired +timer. + +Once a system has switched to high resolution mode, the periodic tick is +switched off. This disables the per system global periodic clock event device - +e.g. the PIT on i386 SMP systems. + +The periodic tick functionality is provided by an per-cpu hrtimer. The callback +function is executed in the next event interrupt context and updates jiffies +and calls update_process_times and profiling. The implementation of the hrtimer +based periodic tick is designed to be extended with dynamic tick functionality. +This allows to use a single clock event device to schedule high resolution +timer and periodic events (jiffies tick, profiling, process accounting) on UP +systems. This has been proved to work with the PIT on i386 and the Incrementer +on PPC. + +The softirq for running the hrtimer queues and executing the callbacks has been +separated from the tick bound timer softirq to allow accurate delivery of high +resolution timer signals which are used by itimer and POSIX interval +timers. The execution of this softirq can still be delayed by other softirqs, +but the overall latencies have been significantly improved by this separation. + +Figure #5 (OLS slides p.22) illustrates the transformation. + + +dynamic ticks +------------- + +Dynamic ticks are the logical consequence of the hrtimer based periodic tick +replacement (sched_tick). The functionality of the sched_tick hrtimer is +extended by three functions: + +- hrtimer_stop_sched_tick +- hrtimer_restart_sched_tick +- hrtimer_update_jiffies + +hrtimer_stop_sched_tick() is called when a CPU goes into idle state. The code +evaluates the next scheduled timer event (from both hrtimers and the timer +wheel) and in case that the next event is further away than the next tick it +reprograms the sched_tick to this future event, to allow longer idle sleeps +without worthless interruption by the periodic tick. The function is also +called when an interrupt happens during the idle period, which does not cause a +reschedule. The call is necessary as the interrupt handler might have armed a +new timer whose expiry time is before the time which was identified as the +nearest event in the previous call to hrtimer_stop_sched_tick. + +hrtimer_restart_sched_tick() is called when the CPU leaves the idle state before +it calls schedule(). hrtimer_restart_sched_tick() resumes the periodic tick, +which is kept active until the next call to hrtimer_stop_sched_tick(). + +hrtimer_update_jiffies() is called from irq_enter() when an interrupt happens +in the idle period to make sure that jiffies are up to date and the interrupt +handler has not to deal with an eventually stale jiffy value. + +The dynamic tick feature provides statistical values which are exported to +userspace via /proc/stat and can be made available for enhanced power +management control. + +The implementation leaves room for further development like full tickless +systems, where the time slice is controlled by the scheduler, variable +frequency profiling, and a complete removal of jiffies in the future. + + +Aside the current initial submission of i386 support, the patchset has been +extended to x86_64 and ARM already. Initial (work in progress) support is also +available for MIPS and PowerPC. + + Thomas, Ingo diff --git a/Documentation/timers/highres.txt b/Documentation/timers/highres.txt deleted file mode 100644 index 8f9741592123..000000000000 --- a/Documentation/timers/highres.txt +++ /dev/null @@ -1,249 +0,0 @@ -High resolution timers and dynamic ticks design notes ------------------------------------------------------ - -Further information can be found in the paper of the OLS 2006 talk "hrtimers -and beyond". The paper is part of the OLS 2006 Proceedings Volume 1, which can -be found on the OLS website: -https://www.kernel.org/doc/ols/2006/ols2006v1-pages-333-346.pdf - -The slides to this talk are available from: -http://www.cs.columbia.edu/~nahum/w6998/papers/ols2006-hrtimers-slides.pdf - -The slides contain five figures (pages 2, 15, 18, 20, 22), which illustrate the -changes in the time(r) related Linux subsystems. Figure #1 (p. 2) shows the -design of the Linux time(r) system before hrtimers and other building blocks -got merged into mainline. - -Note: the paper and the slides are talking about "clock event source", while we -switched to the name "clock event devices" in meantime. - -The design contains the following basic building blocks: - -- hrtimer base infrastructure -- timeofday and clock source management -- clock event management -- high resolution timer functionality -- dynamic ticks - - -hrtimer base infrastructure ---------------------------- - -The hrtimer base infrastructure was merged into the 2.6.16 kernel. Details of -the base implementation are covered in Documentation/timers/hrtimers.txt. See -also figure #2 (OLS slides p. 15) - -The main differences to the timer wheel, which holds the armed timer_list type -timers are: - - time ordered enqueueing into a rb-tree - - independent of ticks (the processing is based on nanoseconds) - - -timeofday and clock source management -------------------------------------- - -John Stultz's Generic Time Of Day (GTOD) framework moves a large portion of -code out of the architecture-specific areas into a generic management -framework, as illustrated in figure #3 (OLS slides p. 18). The architecture -specific portion is reduced to the low level hardware details of the clock -sources, which are registered in the framework and selected on a quality based -decision. The low level code provides hardware setup and readout routines and -initializes data structures, which are used by the generic time keeping code to -convert the clock ticks to nanosecond based time values. All other time keeping -related functionality is moved into the generic code. The GTOD base patch got -merged into the 2.6.18 kernel. - -Further information about the Generic Time Of Day framework is available in the -OLS 2005 Proceedings Volume 1: -http://www.linuxsymposium.org/2005/linuxsymposium_procv1.pdf - -The paper "We Are Not Getting Any Younger: A New Approach to Time and -Timers" was written by J. Stultz, D.V. Hart, & N. Aravamudan. - -Figure #3 (OLS slides p.18) illustrates the transformation. - - -clock event management ----------------------- - -While clock sources provide read access to the monotonically increasing time -value, clock event devices are used to schedule the next event -interrupt(s). The next event is currently defined to be periodic, with its -period defined at compile time. The setup and selection of the event device -for various event driven functionalities is hardwired into the architecture -dependent code. This results in duplicated code across all architectures and -makes it extremely difficult to change the configuration of the system to use -event interrupt devices other than those already built into the -architecture. Another implication of the current design is that it is necessary -to touch all the architecture-specific implementations in order to provide new -functionality like high resolution timers or dynamic ticks. - -The clock events subsystem tries to address this problem by providing a generic -solution to manage clock event devices and their usage for the various clock -event driven kernel functionalities. The goal of the clock event subsystem is -to minimize the clock event related architecture dependent code to the pure -hardware related handling and to allow easy addition and utilization of new -clock event devices. It also minimizes the duplicated code across the -architectures as it provides generic functionality down to the interrupt -service handler, which is almost inherently hardware dependent. - -Clock event devices are registered either by the architecture dependent boot -code or at module insertion time. Each clock event device fills a data -structure with clock-specific property parameters and callback functions. The -clock event management decides, by using the specified property parameters, the -set of system functions a clock event device will be used to support. This -includes the distinction of per-CPU and per-system global event devices. - -System-level global event devices are used for the Linux periodic tick. Per-CPU -event devices are used to provide local CPU functionality such as process -accounting, profiling, and high resolution timers. - -The management layer assigns one or more of the following functions to a clock -event device: - - system global periodic tick (jiffies update) - - cpu local update_process_times - - cpu local profiling - - cpu local next event interrupt (non periodic mode) - -The clock event device delegates the selection of those timer interrupt related -functions completely to the management layer. The clock management layer stores -a function pointer in the device description structure, which has to be called -from the hardware level handler. This removes a lot of duplicated code from the -architecture specific timer interrupt handlers and hands the control over the -clock event devices and the assignment of timer interrupt related functionality -to the core code. - -The clock event layer API is rather small. Aside from the clock event device -registration interface it provides functions to schedule the next event -interrupt, clock event device notification service and support for suspend and -resume. - -The framework adds about 700 lines of code which results in a 2KB increase of -the kernel binary size. The conversion of i386 removes about 100 lines of -code. The binary size decrease is in the range of 400 byte. We believe that the -increase of flexibility and the avoidance of duplicated code across -architectures justifies the slight increase of the binary size. - -The conversion of an architecture has no functional impact, but allows to -utilize the high resolution and dynamic tick functionalities without any change -to the clock event device and timer interrupt code. After the conversion the -enabling of high resolution timers and dynamic ticks is simply provided by -adding the kernel/time/Kconfig file to the architecture specific Kconfig and -adding the dynamic tick specific calls to the idle routine (a total of 3 lines -added to the idle function and the Kconfig file) - -Figure #4 (OLS slides p.20) illustrates the transformation. - - -high resolution timer functionality ------------------------------------ - -During system boot it is not possible to use the high resolution timer -functionality, while making it possible would be difficult and would serve no -useful function. The initialization of the clock event device framework, the -clock source framework (GTOD) and hrtimers itself has to be done and -appropriate clock sources and clock event devices have to be registered before -the high resolution functionality can work. Up to the point where hrtimers are -initialized, the system works in the usual low resolution periodic mode. The -clock source and the clock event device layers provide notification functions -which inform hrtimers about availability of new hardware. hrtimers validates -the usability of the registered clock sources and clock event devices before -switching to high resolution mode. This ensures also that a kernel which is -configured for high resolution timers can run on a system which lacks the -necessary hardware support. - -The high resolution timer code does not support SMP machines which have only -global clock event devices. The support of such hardware would involve IPI -calls when an interrupt happens. The overhead would be much larger than the -benefit. This is the reason why we currently disable high resolution and -dynamic ticks on i386 SMP systems which stop the local APIC in C3 power -state. A workaround is available as an idea, but the problem has not been -tackled yet. - -The time ordered insertion of timers provides all the infrastructure to decide -whether the event device has to be reprogrammed when a timer is added. The -decision is made per timer base and synchronized across per-cpu timer bases in -a support function. The design allows the system to utilize separate per-CPU -clock event devices for the per-CPU timer bases, but currently only one -reprogrammable clock event device per-CPU is utilized. - -When the timer interrupt happens, the next event interrupt handler is called -from the clock event distribution code and moves expired timers from the -red-black tree to a separate double linked list and invokes the softirq -handler. An additional mode field in the hrtimer structure allows the system to -execute callback functions directly from the next event interrupt handler. This -is restricted to code which can safely be executed in the hard interrupt -context. This applies, for example, to the common case of a wakeup function as -used by nanosleep. The advantage of executing the handler in the interrupt -context is the avoidance of up to two context switches - from the interrupted -context to the softirq and to the task which is woken up by the expired -timer. - -Once a system has switched to high resolution mode, the periodic tick is -switched off. This disables the per system global periodic clock event device - -e.g. the PIT on i386 SMP systems. - -The periodic tick functionality is provided by an per-cpu hrtimer. The callback -function is executed in the next event interrupt context and updates jiffies -and calls update_process_times and profiling. The implementation of the hrtimer -based periodic tick is designed to be extended with dynamic tick functionality. -This allows to use a single clock event device to schedule high resolution -timer and periodic events (jiffies tick, profiling, process accounting) on UP -systems. This has been proved to work with the PIT on i386 and the Incrementer -on PPC. - -The softirq for running the hrtimer queues and executing the callbacks has been -separated from the tick bound timer softirq to allow accurate delivery of high -resolution timer signals which are used by itimer and POSIX interval -timers. The execution of this softirq can still be delayed by other softirqs, -but the overall latencies have been significantly improved by this separation. - -Figure #5 (OLS slides p.22) illustrates the transformation. - - -dynamic ticks -------------- - -Dynamic ticks are the logical consequence of the hrtimer based periodic tick -replacement (sched_tick). The functionality of the sched_tick hrtimer is -extended by three functions: - -- hrtimer_stop_sched_tick -- hrtimer_restart_sched_tick -- hrtimer_update_jiffies - -hrtimer_stop_sched_tick() is called when a CPU goes into idle state. The code -evaluates the next scheduled timer event (from both hrtimers and the timer -wheel) and in case that the next event is further away than the next tick it -reprograms the sched_tick to this future event, to allow longer idle sleeps -without worthless interruption by the periodic tick. The function is also -called when an interrupt happens during the idle period, which does not cause a -reschedule. The call is necessary as the interrupt handler might have armed a -new timer whose expiry time is before the time which was identified as the -nearest event in the previous call to hrtimer_stop_sched_tick. - -hrtimer_restart_sched_tick() is called when the CPU leaves the idle state before -it calls schedule(). hrtimer_restart_sched_tick() resumes the periodic tick, -which is kept active until the next call to hrtimer_stop_sched_tick(). - -hrtimer_update_jiffies() is called from irq_enter() when an interrupt happens -in the idle period to make sure that jiffies are up to date and the interrupt -handler has not to deal with an eventually stale jiffy value. - -The dynamic tick feature provides statistical values which are exported to -userspace via /proc/stat and can be made available for enhanced power -management control. - -The implementation leaves room for further development like full tickless -systems, where the time slice is controlled by the scheduler, variable -frequency profiling, and a complete removal of jiffies in the future. - - -Aside the current initial submission of i386 support, the patchset has been -extended to x86_64 and ARM already. Initial (work in progress) support is also -available for MIPS and PowerPC. - - Thomas, Ingo - - - diff --git a/Documentation/timers/hpet.rst b/Documentation/timers/hpet.rst new file mode 100644 index 000000000000..c9d05d3caaca --- /dev/null +++ b/Documentation/timers/hpet.rst @@ -0,0 +1,30 @@ +=========================================== +High Precision Event Timer Driver for Linux +=========================================== + +The High Precision Event Timer (HPET) hardware follows a specification +by Intel and Microsoft, revision 1. + +Each HPET has one fixed-rate counter (at 10+ MHz, hence "High Precision") +and up to 32 comparators. Normally three or more comparators are provided, +each of which can generate oneshot interrupts and at least one of which has +additional hardware to support periodic interrupts. The comparators are +also called "timers", which can be misleading since usually timers are +independent of each other ... these share a counter, complicating resets. + +HPET devices can support two interrupt routing modes. In one mode, the +comparators are additional interrupt sources with no particular system +role. Many x86 BIOS writers don't route HPET interrupts at all, which +prevents use of that mode. They support the other "legacy replacement" +mode where the first two comparators block interrupts from 8254 timers +and from the RTC. + +The driver supports detection of HPET driver allocation and initialization +of the HPET before the driver module_init routine is called. This enables +platform code which uses timer 0 or 1 as the main timer to intercept HPET +initialization. An example of this initialization can be found in +arch/x86/kernel/hpet.c. + +The driver provides a userspace API which resembles the API found in the +RTC driver framework. An example user space program is provided in +file:samples/timers/hpet_example.c diff --git a/Documentation/timers/hpet.txt b/Documentation/timers/hpet.txt deleted file mode 100644 index 895345ec513b..000000000000 --- a/Documentation/timers/hpet.txt +++ /dev/null @@ -1,28 +0,0 @@ - High Precision Event Timer Driver for Linux - -The High Precision Event Timer (HPET) hardware follows a specification -by Intel and Microsoft, revision 1. - -Each HPET has one fixed-rate counter (at 10+ MHz, hence "High Precision") -and up to 32 comparators. Normally three or more comparators are provided, -each of which can generate oneshot interrupts and at least one of which has -additional hardware to support periodic interrupts. The comparators are -also called "timers", which can be misleading since usually timers are -independent of each other ... these share a counter, complicating resets. - -HPET devices can support two interrupt routing modes. In one mode, the -comparators are additional interrupt sources with no particular system -role. Many x86 BIOS writers don't route HPET interrupts at all, which -prevents use of that mode. They support the other "legacy replacement" -mode where the first two comparators block interrupts from 8254 timers -and from the RTC. - -The driver supports detection of HPET driver allocation and initialization -of the HPET before the driver module_init routine is called. This enables -platform code which uses timer 0 or 1 as the main timer to intercept HPET -initialization. An example of this initialization can be found in -arch/x86/kernel/hpet.c. - -The driver provides a userspace API which resembles the API found in the -RTC driver framework. An example user space program is provided in -file:samples/timers/hpet_example.c diff --git a/Documentation/timers/hrtimers.rst b/Documentation/timers/hrtimers.rst new file mode 100644 index 000000000000..c1c20a693e8f --- /dev/null +++ b/Documentation/timers/hrtimers.rst @@ -0,0 +1,178 @@ +====================================================== +hrtimers - subsystem for high-resolution kernel timers +====================================================== + +This patch introduces a new subsystem for high-resolution kernel timers. + +One might ask the question: we already have a timer subsystem +(kernel/timers.c), why do we need two timer subsystems? After a lot of +back and forth trying to integrate high-resolution and high-precision +features into the existing timer framework, and after testing various +such high-resolution timer implementations in practice, we came to the +conclusion that the timer wheel code is fundamentally not suitable for +such an approach. We initially didn't believe this ('there must be a way +to solve this'), and spent a considerable effort trying to integrate +things into the timer wheel, but we failed. In hindsight, there are +several reasons why such integration is hard/impossible: + +- the forced handling of low-resolution and high-resolution timers in + the same way leads to a lot of compromises, macro magic and #ifdef + mess. The timers.c code is very "tightly coded" around jiffies and + 32-bitness assumptions, and has been honed and micro-optimized for a + relatively narrow use case (jiffies in a relatively narrow HZ range) + for many years - and thus even small extensions to it easily break + the wheel concept, leading to even worse compromises. The timer wheel + code is very good and tight code, there's zero problems with it in its + current usage - but it is simply not suitable to be extended for + high-res timers. + +- the unpredictable [O(N)] overhead of cascading leads to delays which + necessitate a more complex handling of high resolution timers, which + in turn decreases robustness. Such a design still leads to rather large + timing inaccuracies. Cascading is a fundamental property of the timer + wheel concept, it cannot be 'designed out' without inevitably + degrading other portions of the timers.c code in an unacceptable way. + +- the implementation of the current posix-timer subsystem on top of + the timer wheel has already introduced a quite complex handling of + the required readjusting of absolute CLOCK_REALTIME timers at + settimeofday or NTP time - further underlying our experience by + example: that the timer wheel data structure is too rigid for high-res + timers. + +- the timer wheel code is most optimal for use cases which can be + identified as "timeouts". Such timeouts are usually set up to cover + error conditions in various I/O paths, such as networking and block + I/O. The vast majority of those timers never expire and are rarely + recascaded because the expected correct event arrives in time so they + can be removed from the timer wheel before any further processing of + them becomes necessary. Thus the users of these timeouts can accept + the granularity and precision tradeoffs of the timer wheel, and + largely expect the timer subsystem to have near-zero overhead. + Accurate timing for them is not a core purpose - in fact most of the + timeout values used are ad-hoc. For them it is at most a necessary + evil to guarantee the processing of actual timeout completions + (because most of the timeouts are deleted before completion), which + should thus be as cheap and unintrusive as possible. + +The primary users of precision timers are user-space applications that +utilize nanosleep, posix-timers and itimer interfaces. Also, in-kernel +users like drivers and subsystems which require precise timed events +(e.g. multimedia) can benefit from the availability of a separate +high-resolution timer subsystem as well. + +While this subsystem does not offer high-resolution clock sources just +yet, the hrtimer subsystem can be easily extended with high-resolution +clock capabilities, and patches for that exist and are maturing quickly. +The increasing demand for realtime and multimedia applications along +with other potential users for precise timers gives another reason to +separate the "timeout" and "precise timer" subsystems. + +Another potential benefit is that such a separation allows even more +special-purpose optimization of the existing timer wheel for the low +resolution and low precision use cases - once the precision-sensitive +APIs are separated from the timer wheel and are migrated over to +hrtimers. E.g. we could decrease the frequency of the timeout subsystem +from 250 Hz to 100 HZ (or even smaller). + +hrtimer subsystem implementation details +---------------------------------------- + +the basic design considerations were: + +- simplicity + +- data structure not bound to jiffies or any other granularity. All the + kernel logic works at 64-bit nanoseconds resolution - no compromises. + +- simplification of existing, timing related kernel code + +another basic requirement was the immediate enqueueing and ordering of +timers at activation time. After looking at several possible solutions +such as radix trees and hashes, we chose the red black tree as the basic +data structure. Rbtrees are available as a library in the kernel and are +used in various performance-critical areas of e.g. memory management and +file systems. The rbtree is solely used for time sorted ordering, while +a separate list is used to give the expiry code fast access to the +queued timers, without having to walk the rbtree. + +(This separate list is also useful for later when we'll introduce +high-resolution clocks, where we need separate pending and expired +queues while keeping the time-order intact.) + +Time-ordered enqueueing is not purely for the purposes of +high-resolution clocks though, it also simplifies the handling of +absolute timers based on a low-resolution CLOCK_REALTIME. The existing +implementation needed to keep an extra list of all armed absolute +CLOCK_REALTIME timers along with complex locking. In case of +settimeofday and NTP, all the timers (!) had to be dequeued, the +time-changing code had to fix them up one by one, and all of them had to +be enqueued again. The time-ordered enqueueing and the storage of the +expiry time in absolute time units removes all this complex and poorly +scaling code from the posix-timer implementation - the clock can simply +be set without having to touch the rbtree. This also makes the handling +of posix-timers simpler in general. + +The locking and per-CPU behavior of hrtimers was mostly taken from the +existing timer wheel code, as it is mature and well suited. Sharing code +was not really a win, due to the different data structures. Also, the +hrtimer functions now have clearer behavior and clearer names - such as +hrtimer_try_to_cancel() and hrtimer_cancel() [which are roughly +equivalent to del_timer() and del_timer_sync()] - so there's no direct +1:1 mapping between them on the algorithmic level, and thus no real +potential for code sharing either. + +Basic data types: every time value, absolute or relative, is in a +special nanosecond-resolution type: ktime_t. The kernel-internal +representation of ktime_t values and operations is implemented via +macros and inline functions, and can be switched between a "hybrid +union" type and a plain "scalar" 64bit nanoseconds representation (at +compile time). The hybrid union type optimizes time conversions on 32bit +CPUs. This build-time-selectable ktime_t storage format was implemented +to avoid the performance impact of 64-bit multiplications and divisions +on 32bit CPUs. Such operations are frequently necessary to convert +between the storage formats provided by kernel and userspace interfaces +and the internal time format. (See include/linux/ktime.h for further +details.) + +hrtimers - rounding of timer values +----------------------------------- + +the hrtimer code will round timer events to lower-resolution clocks +because it has to. Otherwise it will do no artificial rounding at all. + +one question is, what resolution value should be returned to the user by +the clock_getres() interface. This will return whatever real resolution +a given clock has - be it low-res, high-res, or artificially-low-res. + +hrtimers - testing and verification +----------------------------------- + +We used the high-resolution clock subsystem ontop of hrtimers to verify +the hrtimer implementation details in praxis, and we also ran the posix +timer tests in order to ensure specification compliance. We also ran +tests on low-resolution clocks. + +The hrtimer patch converts the following kernel functionality to use +hrtimers: + + - nanosleep + - itimers + - posix-timers + +The conversion of nanosleep and posix-timers enabled the unification of +nanosleep and clock_nanosleep. + +The code was successfully compiled for the following platforms: + + i386, x86_64, ARM, PPC, PPC64, IA64 + +The code was run-tested on the following platforms: + + i386(UP/SMP), x86_64(UP/SMP), ARM, PPC + +hrtimers were also integrated into the -rt tree, along with a +hrtimers-based high-resolution clock implementation, so the hrtimers +code got a healthy amount of testing and use in practice. + + Thomas Gleixner, Ingo Molnar diff --git a/Documentation/timers/hrtimers.txt b/Documentation/timers/hrtimers.txt deleted file mode 100644 index 588d85724f10..000000000000 --- a/Documentation/timers/hrtimers.txt +++ /dev/null @@ -1,178 +0,0 @@ - -hrtimers - subsystem for high-resolution kernel timers ----------------------------------------------------- - -This patch introduces a new subsystem for high-resolution kernel timers. - -One might ask the question: we already have a timer subsystem -(kernel/timers.c), why do we need two timer subsystems? After a lot of -back and forth trying to integrate high-resolution and high-precision -features into the existing timer framework, and after testing various -such high-resolution timer implementations in practice, we came to the -conclusion that the timer wheel code is fundamentally not suitable for -such an approach. We initially didn't believe this ('there must be a way -to solve this'), and spent a considerable effort trying to integrate -things into the timer wheel, but we failed. In hindsight, there are -several reasons why such integration is hard/impossible: - -- the forced handling of low-resolution and high-resolution timers in - the same way leads to a lot of compromises, macro magic and #ifdef - mess. The timers.c code is very "tightly coded" around jiffies and - 32-bitness assumptions, and has been honed and micro-optimized for a - relatively narrow use case (jiffies in a relatively narrow HZ range) - for many years - and thus even small extensions to it easily break - the wheel concept, leading to even worse compromises. The timer wheel - code is very good and tight code, there's zero problems with it in its - current usage - but it is simply not suitable to be extended for - high-res timers. - -- the unpredictable [O(N)] overhead of cascading leads to delays which - necessitate a more complex handling of high resolution timers, which - in turn decreases robustness. Such a design still leads to rather large - timing inaccuracies. Cascading is a fundamental property of the timer - wheel concept, it cannot be 'designed out' without inevitably - degrading other portions of the timers.c code in an unacceptable way. - -- the implementation of the current posix-timer subsystem on top of - the timer wheel has already introduced a quite complex handling of - the required readjusting of absolute CLOCK_REALTIME timers at - settimeofday or NTP time - further underlying our experience by - example: that the timer wheel data structure is too rigid for high-res - timers. - -- the timer wheel code is most optimal for use cases which can be - identified as "timeouts". Such timeouts are usually set up to cover - error conditions in various I/O paths, such as networking and block - I/O. The vast majority of those timers never expire and are rarely - recascaded because the expected correct event arrives in time so they - can be removed from the timer wheel before any further processing of - them becomes necessary. Thus the users of these timeouts can accept - the granularity and precision tradeoffs of the timer wheel, and - largely expect the timer subsystem to have near-zero overhead. - Accurate timing for them is not a core purpose - in fact most of the - timeout values used are ad-hoc. For them it is at most a necessary - evil to guarantee the processing of actual timeout completions - (because most of the timeouts are deleted before completion), which - should thus be as cheap and unintrusive as possible. - -The primary users of precision timers are user-space applications that -utilize nanosleep, posix-timers and itimer interfaces. Also, in-kernel -users like drivers and subsystems which require precise timed events -(e.g. multimedia) can benefit from the availability of a separate -high-resolution timer subsystem as well. - -While this subsystem does not offer high-resolution clock sources just -yet, the hrtimer subsystem can be easily extended with high-resolution -clock capabilities, and patches for that exist and are maturing quickly. -The increasing demand for realtime and multimedia applications along -with other potential users for precise timers gives another reason to -separate the "timeout" and "precise timer" subsystems. - -Another potential benefit is that such a separation allows even more -special-purpose optimization of the existing timer wheel for the low -resolution and low precision use cases - once the precision-sensitive -APIs are separated from the timer wheel and are migrated over to -hrtimers. E.g. we could decrease the frequency of the timeout subsystem -from 250 Hz to 100 HZ (or even smaller). - -hrtimer subsystem implementation details ----------------------------------------- - -the basic design considerations were: - -- simplicity - -- data structure not bound to jiffies or any other granularity. All the - kernel logic works at 64-bit nanoseconds resolution - no compromises. - -- simplification of existing, timing related kernel code - -another basic requirement was the immediate enqueueing and ordering of -timers at activation time. After looking at several possible solutions -such as radix trees and hashes, we chose the red black tree as the basic -data structure. Rbtrees are available as a library in the kernel and are -used in various performance-critical areas of e.g. memory management and -file systems. The rbtree is solely used for time sorted ordering, while -a separate list is used to give the expiry code fast access to the -queued timers, without having to walk the rbtree. - -(This separate list is also useful for later when we'll introduce -high-resolution clocks, where we need separate pending and expired -queues while keeping the time-order intact.) - -Time-ordered enqueueing is not purely for the purposes of -high-resolution clocks though, it also simplifies the handling of -absolute timers based on a low-resolution CLOCK_REALTIME. The existing -implementation needed to keep an extra list of all armed absolute -CLOCK_REALTIME timers along with complex locking. In case of -settimeofday and NTP, all the timers (!) had to be dequeued, the -time-changing code had to fix them up one by one, and all of them had to -be enqueued again. The time-ordered enqueueing and the storage of the -expiry time in absolute time units removes all this complex and poorly -scaling code from the posix-timer implementation - the clock can simply -be set without having to touch the rbtree. This also makes the handling -of posix-timers simpler in general. - -The locking and per-CPU behavior of hrtimers was mostly taken from the -existing timer wheel code, as it is mature and well suited. Sharing code -was not really a win, due to the different data structures. Also, the -hrtimer functions now have clearer behavior and clearer names - such as -hrtimer_try_to_cancel() and hrtimer_cancel() [which are roughly -equivalent to del_timer() and del_timer_sync()] - so there's no direct -1:1 mapping between them on the algorithmic level, and thus no real -potential for code sharing either. - -Basic data types: every time value, absolute or relative, is in a -special nanosecond-resolution type: ktime_t. The kernel-internal -representation of ktime_t values and operations is implemented via -macros and inline functions, and can be switched between a "hybrid -union" type and a plain "scalar" 64bit nanoseconds representation (at -compile time). The hybrid union type optimizes time conversions on 32bit -CPUs. This build-time-selectable ktime_t storage format was implemented -to avoid the performance impact of 64-bit multiplications and divisions -on 32bit CPUs. Such operations are frequently necessary to convert -between the storage formats provided by kernel and userspace interfaces -and the internal time format. (See include/linux/ktime.h for further -details.) - -hrtimers - rounding of timer values ------------------------------------ - -the hrtimer code will round timer events to lower-resolution clocks -because it has to. Otherwise it will do no artificial rounding at all. - -one question is, what resolution value should be returned to the user by -the clock_getres() interface. This will return whatever real resolution -a given clock has - be it low-res, high-res, or artificially-low-res. - -hrtimers - testing and verification ----------------------------------- - -We used the high-resolution clock subsystem ontop of hrtimers to verify -the hrtimer implementation details in praxis, and we also ran the posix -timer tests in order to ensure specification compliance. We also ran -tests on low-resolution clocks. - -The hrtimer patch converts the following kernel functionality to use -hrtimers: - - - nanosleep - - itimers - - posix-timers - -The conversion of nanosleep and posix-timers enabled the unification of -nanosleep and clock_nanosleep. - -The code was successfully compiled for the following platforms: - - i386, x86_64, ARM, PPC, PPC64, IA64 - -The code was run-tested on the following platforms: - - i386(UP/SMP), x86_64(UP/SMP), ARM, PPC - -hrtimers were also integrated into the -rt tree, along with a -hrtimers-based high-resolution clock implementation, so the hrtimers -code got a healthy amount of testing and use in practice. - - Thomas Gleixner, Ingo Molnar diff --git a/Documentation/timers/index.rst b/Documentation/timers/index.rst new file mode 100644 index 000000000000..91f6f8263c48 --- /dev/null +++ b/Documentation/timers/index.rst @@ -0,0 +1,22 @@ +:orphan: + +====== +timers +====== + +.. toctree:: + :maxdepth: 1 + + highres + hpet + hrtimers + no_hz + timekeeping + timers-howto + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/timers/no_hz.rst b/Documentation/timers/no_hz.rst new file mode 100644 index 000000000000..065db217cb04 --- /dev/null +++ b/Documentation/timers/no_hz.rst @@ -0,0 +1,326 @@ +====================================== +NO_HZ: Reducing Scheduling-Clock Ticks +====================================== + + +This document describes Kconfig options and boot parameters that can +reduce the number of scheduling-clock interrupts, thereby improving energy +efficiency and reducing OS jitter. Reducing OS jitter is important for +some types of computationally intensive high-performance computing (HPC) +applications and for real-time applications. + +There are three main ways of managing scheduling-clock interrupts +(also known as "scheduling-clock ticks" or simply "ticks"): + +1. Never omit scheduling-clock ticks (CONFIG_HZ_PERIODIC=y or + CONFIG_NO_HZ=n for older kernels). You normally will -not- + want to choose this option. + +2. Omit scheduling-clock ticks on idle CPUs (CONFIG_NO_HZ_IDLE=y or + CONFIG_NO_HZ=y for older kernels). This is the most common + approach, and should be the default. + +3. Omit scheduling-clock ticks on CPUs that are either idle or that + have only one runnable task (CONFIG_NO_HZ_FULL=y). Unless you + are running realtime applications or certain types of HPC + workloads, you will normally -not- want this option. + +These three cases are described in the following three sections, followed +by a third section on RCU-specific considerations, a fourth section +discussing testing, and a fifth and final section listing known issues. + + +Never Omit Scheduling-Clock Ticks +================================= + +Very old versions of Linux from the 1990s and the very early 2000s +are incapable of omitting scheduling-clock ticks. It turns out that +there are some situations where this old-school approach is still the +right approach, for example, in heavy workloads with lots of tasks +that use short bursts of CPU, where there are very frequent idle +periods, but where these idle periods are also quite short (tens or +hundreds of microseconds). For these types of workloads, scheduling +clock interrupts will normally be delivered any way because there +will frequently be multiple runnable tasks per CPU. In these cases, +attempting to turn off the scheduling clock interrupt will have no effect +other than increasing the overhead of switching to and from idle and +transitioning between user and kernel execution. + +This mode of operation can be selected using CONFIG_HZ_PERIODIC=y (or +CONFIG_NO_HZ=n for older kernels). + +However, if you are instead running a light workload with long idle +periods, failing to omit scheduling-clock interrupts will result in +excessive power consumption. This is especially bad on battery-powered +devices, where it results in extremely short battery lifetimes. If you +are running light workloads, you should therefore read the following +section. + +In addition, if you are running either a real-time workload or an HPC +workload with short iterations, the scheduling-clock interrupts can +degrade your applications performance. If this describes your workload, +you should read the following two sections. + + +Omit Scheduling-Clock Ticks For Idle CPUs +========================================= + +If a CPU is idle, there is little point in sending it a scheduling-clock +interrupt. After all, the primary purpose of a scheduling-clock interrupt +is to force a busy CPU to shift its attention among multiple duties, +and an idle CPU has no duties to shift its attention among. + +The CONFIG_NO_HZ_IDLE=y Kconfig option causes the kernel to avoid sending +scheduling-clock interrupts to idle CPUs, which is critically important +both to battery-powered devices and to highly virtualized mainframes. +A battery-powered device running a CONFIG_HZ_PERIODIC=y kernel would +drain its battery very quickly, easily 2-3 times as fast as would the +same device running a CONFIG_NO_HZ_IDLE=y kernel. A mainframe running +1,500 OS instances might find that half of its CPU time was consumed by +unnecessary scheduling-clock interrupts. In these situations, there +is strong motivation to avoid sending scheduling-clock interrupts to +idle CPUs. That said, dyntick-idle mode is not free: + +1. It increases the number of instructions executed on the path + to and from the idle loop. + +2. On many architectures, dyntick-idle mode also increases the + number of expensive clock-reprogramming operations. + +Therefore, systems with aggressive real-time response constraints often +run CONFIG_HZ_PERIODIC=y kernels (or CONFIG_NO_HZ=n for older kernels) +in order to avoid degrading from-idle transition latencies. + +An idle CPU that is not receiving scheduling-clock interrupts is said to +be "dyntick-idle", "in dyntick-idle mode", "in nohz mode", or "running +tickless". The remainder of this document will use "dyntick-idle mode". + +There is also a boot parameter "nohz=" that can be used to disable +dyntick-idle mode in CONFIG_NO_HZ_IDLE=y kernels by specifying "nohz=off". +By default, CONFIG_NO_HZ_IDLE=y kernels boot with "nohz=on", enabling +dyntick-idle mode. + + +Omit Scheduling-Clock Ticks For CPUs With Only One Runnable Task +================================================================ + +If a CPU has only one runnable task, there is little point in sending it +a scheduling-clock interrupt because there is no other task to switch to. +Note that omitting scheduling-clock ticks for CPUs with only one runnable +task implies also omitting them for idle CPUs. + +The CONFIG_NO_HZ_FULL=y Kconfig option causes the kernel to avoid +sending scheduling-clock interrupts to CPUs with a single runnable task, +and such CPUs are said to be "adaptive-ticks CPUs". This is important +for applications with aggressive real-time response constraints because +it allows them to improve their worst-case response times by the maximum +duration of a scheduling-clock interrupt. It is also important for +computationally intensive short-iteration workloads: If any CPU is +delayed during a given iteration, all the other CPUs will be forced to +wait idle while the delayed CPU finishes. Thus, the delay is multiplied +by one less than the number of CPUs. In these situations, there is +again strong motivation to avoid sending scheduling-clock interrupts. + +By default, no CPU will be an adaptive-ticks CPU. The "nohz_full=" +boot parameter specifies the adaptive-ticks CPUs. For example, +"nohz_full=1,6-8" says that CPUs 1, 6, 7, and 8 are to be adaptive-ticks +CPUs. Note that you are prohibited from marking all of the CPUs as +adaptive-tick CPUs: At least one non-adaptive-tick CPU must remain +online to handle timekeeping tasks in order to ensure that system +calls like gettimeofday() returns accurate values on adaptive-tick CPUs. +(This is not an issue for CONFIG_NO_HZ_IDLE=y because there are no running +user processes to observe slight drifts in clock rate.) Therefore, the +boot CPU is prohibited from entering adaptive-ticks mode. Specifying a +"nohz_full=" mask that includes the boot CPU will result in a boot-time +error message, and the boot CPU will be removed from the mask. Note that +this means that your system must have at least two CPUs in order for +CONFIG_NO_HZ_FULL=y to do anything for you. + +Finally, adaptive-ticks CPUs must have their RCU callbacks offloaded. +This is covered in the "RCU IMPLICATIONS" section below. + +Normally, a CPU remains in adaptive-ticks mode as long as possible. +In particular, transitioning to kernel mode does not automatically change +the mode. Instead, the CPU will exit adaptive-ticks mode only if needed, +for example, if that CPU enqueues an RCU callback. + +Just as with dyntick-idle mode, the benefits of adaptive-tick mode do +not come for free: + +1. CONFIG_NO_HZ_FULL selects CONFIG_NO_HZ_COMMON, so you cannot run + adaptive ticks without also running dyntick idle. This dependency + extends down into the implementation, so that all of the costs + of CONFIG_NO_HZ_IDLE are also incurred by CONFIG_NO_HZ_FULL. + +2. The user/kernel transitions are slightly more expensive due + to the need to inform kernel subsystems (such as RCU) about + the change in mode. + +3. POSIX CPU timers prevent CPUs from entering adaptive-tick mode. + Real-time applications needing to take actions based on CPU time + consumption need to use other means of doing so. + +4. If there are more perf events pending than the hardware can + accommodate, they are normally round-robined so as to collect + all of them over time. Adaptive-tick mode may prevent this + round-robining from happening. This will likely be fixed by + preventing CPUs with large numbers of perf events pending from + entering adaptive-tick mode. + +5. Scheduler statistics for adaptive-tick CPUs may be computed + slightly differently than those for non-adaptive-tick CPUs. + This might in turn perturb load-balancing of real-time tasks. + +6. The LB_BIAS scheduler feature is disabled by adaptive ticks. + +Although improvements are expected over time, adaptive ticks is quite +useful for many types of real-time and compute-intensive applications. +However, the drawbacks listed above mean that adaptive ticks should not +(yet) be enabled by default. + + +RCU Implications +================ + +There are situations in which idle CPUs cannot be permitted to +enter either dyntick-idle mode or adaptive-tick mode, the most +common being when that CPU has RCU callbacks pending. + +The CONFIG_RCU_FAST_NO_HZ=y Kconfig option may be used to cause such CPUs +to enter dyntick-idle mode or adaptive-tick mode anyway. In this case, +a timer will awaken these CPUs every four jiffies in order to ensure +that the RCU callbacks are processed in a timely fashion. + +Another approach is to offload RCU callback processing to "rcuo" kthreads +using the CONFIG_RCU_NOCB_CPU=y Kconfig option. The specific CPUs to +offload may be selected using The "rcu_nocbs=" kernel boot parameter, +which takes a comma-separated list of CPUs and CPU ranges, for example, +"1,3-5" selects CPUs 1, 3, 4, and 5. + +The offloaded CPUs will never queue RCU callbacks, and therefore RCU +never prevents offloaded CPUs from entering either dyntick-idle mode +or adaptive-tick mode. That said, note that it is up to userspace to +pin the "rcuo" kthreads to specific CPUs if desired. Otherwise, the +scheduler will decide where to run them, which might or might not be +where you want them to run. + + +Testing +======= + +So you enable all the OS-jitter features described in this document, +but do not see any change in your workload's behavior. Is this because +your workload isn't affected that much by OS jitter, or is it because +something else is in the way? This section helps answer this question +by providing a simple OS-jitter test suite, which is available on branch +master of the following git archive: + +git://git.kernel.org/pub/scm/linux/kernel/git/frederic/dynticks-testing.git + +Clone this archive and follow the instructions in the README file. +This test procedure will produce a trace that will allow you to evaluate +whether or not you have succeeded in removing OS jitter from your system. +If this trace shows that you have removed OS jitter as much as is +possible, then you can conclude that your workload is not all that +sensitive to OS jitter. + +Note: this test requires that your system have at least two CPUs. +We do not currently have a good way to remove OS jitter from single-CPU +systems. + + +Known Issues +============ + +* Dyntick-idle slows transitions to and from idle slightly. + In practice, this has not been a problem except for the most + aggressive real-time workloads, which have the option of disabling + dyntick-idle mode, an option that most of them take. However, + some workloads will no doubt want to use adaptive ticks to + eliminate scheduling-clock interrupt latencies. Here are some + options for these workloads: + + a. Use PMQOS from userspace to inform the kernel of your + latency requirements (preferred). + + b. On x86 systems, use the "idle=mwait" boot parameter. + + c. On x86 systems, use the "intel_idle.max_cstate=" to limit + ` the maximum C-state depth. + + d. On x86 systems, use the "idle=poll" boot parameter. + However, please note that use of this parameter can cause + your CPU to overheat, which may cause thermal throttling + to degrade your latencies -- and that this degradation can + be even worse than that of dyntick-idle. Furthermore, + this parameter effectively disables Turbo Mode on Intel + CPUs, which can significantly reduce maximum performance. + +* Adaptive-ticks slows user/kernel transitions slightly. + This is not expected to be a problem for computationally intensive + workloads, which have few such transitions. Careful benchmarking + will be required to determine whether or not other workloads + are significantly affected by this effect. + +* Adaptive-ticks does not do anything unless there is only one + runnable task for a given CPU, even though there are a number + of other situations where the scheduling-clock tick is not + needed. To give but one example, consider a CPU that has one + runnable high-priority SCHED_FIFO task and an arbitrary number + of low-priority SCHED_OTHER tasks. In this case, the CPU is + required to run the SCHED_FIFO task until it either blocks or + some other higher-priority task awakens on (or is assigned to) + this CPU, so there is no point in sending a scheduling-clock + interrupt to this CPU. However, the current implementation + nevertheless sends scheduling-clock interrupts to CPUs having a + single runnable SCHED_FIFO task and multiple runnable SCHED_OTHER + tasks, even though these interrupts are unnecessary. + + And even when there are multiple runnable tasks on a given CPU, + there is little point in interrupting that CPU until the current + running task's timeslice expires, which is almost always way + longer than the time of the next scheduling-clock interrupt. + + Better handling of these sorts of situations is future work. + +* A reboot is required to reconfigure both adaptive idle and RCU + callback offloading. Runtime reconfiguration could be provided + if needed, however, due to the complexity of reconfiguring RCU at + runtime, there would need to be an earthshakingly good reason. + Especially given that you have the straightforward option of + simply offloading RCU callbacks from all CPUs and pinning them + where you want them whenever you want them pinned. + +* Additional configuration is required to deal with other sources + of OS jitter, including interrupts and system-utility tasks + and processes. This configuration normally involves binding + interrupts and tasks to particular CPUs. + +* Some sources of OS jitter can currently be eliminated only by + constraining the workload. For example, the only way to eliminate + OS jitter due to global TLB shootdowns is to avoid the unmapping + operations (such as kernel module unload operations) that + result in these shootdowns. For another example, page faults + and TLB misses can be reduced (and in some cases eliminated) by + using huge pages and by constraining the amount of memory used + by the application. Pre-faulting the working set can also be + helpful, especially when combined with the mlock() and mlockall() + system calls. + +* Unless all CPUs are idle, at least one CPU must keep the + scheduling-clock interrupt going in order to support accurate + timekeeping. + +* If there might potentially be some adaptive-ticks CPUs, there + will be at least one CPU keeping the scheduling-clock interrupt + going, even if all CPUs are otherwise idle. + + Better handling of this situation is ongoing work. + +* Some process-handling operations still require the occasional + scheduling-clock tick. These operations include calculating CPU + load, maintaining sched average, computing CFS entity vruntime, + computing avenrun, and carrying out load balancing. They are + currently accommodated by scheduling-clock tick every second + or so. On-going work will eliminate the need even for these + infrequent scheduling-clock ticks. diff --git a/Documentation/timers/timekeeping.rst b/Documentation/timers/timekeeping.rst new file mode 100644 index 000000000000..f83e98852e2c --- /dev/null +++ b/Documentation/timers/timekeeping.rst @@ -0,0 +1,180 @@ +=========================================================== +Clock sources, Clock events, sched_clock() and delay timers +=========================================================== + +This document tries to briefly explain some basic kernel timekeeping +abstractions. It partly pertains to the drivers usually found in +drivers/clocksource in the kernel tree, but the code may be spread out +across the kernel. + +If you grep through the kernel source you will find a number of architecture- +specific implementations of clock sources, clockevents and several likewise +architecture-specific overrides of the sched_clock() function and some +delay timers. + +To provide timekeeping for your platform, the clock source provides +the basic timeline, whereas clock events shoot interrupts on certain points +on this timeline, providing facilities such as high-resolution timers. +sched_clock() is used for scheduling and timestamping, and delay timers +provide an accurate delay source using hardware counters. + + +Clock sources +------------- + +The purpose of the clock source is to provide a timeline for the system that +tells you where you are in time. For example issuing the command 'date' on +a Linux system will eventually read the clock source to determine exactly +what time it is. + +Typically the clock source is a monotonic, atomic counter which will provide +n bits which count from 0 to (2^n)-1 and then wraps around to 0 and start over. +It will ideally NEVER stop ticking as long as the system is running. It +may stop during system suspend. + +The clock source shall have as high resolution as possible, and the frequency +shall be as stable and correct as possible as compared to a real-world wall +clock. It should not move unpredictably back and forth in time or miss a few +cycles here and there. + +It must be immune to the kind of effects that occur in hardware where e.g. +the counter register is read in two phases on the bus lowest 16 bits first +and the higher 16 bits in a second bus cycle with the counter bits +potentially being updated in between leading to the risk of very strange +values from the counter. + +When the wall-clock accuracy of the clock source isn't satisfactory, there +are various quirks and layers in the timekeeping code for e.g. synchronizing +the user-visible time to RTC clocks in the system or against networked time +servers using NTP, but all they do basically is update an offset against +the clock source, which provides the fundamental timeline for the system. +These measures does not affect the clock source per se, they only adapt the +system to the shortcomings of it. + +The clock source struct shall provide means to translate the provided counter +into a nanosecond value as an unsigned long long (unsigned 64 bit) number. +Since this operation may be invoked very often, doing this in a strict +mathematical sense is not desirable: instead the number is taken as close as +possible to a nanosecond value using only the arithmetic operations +multiply and shift, so in clocksource_cyc2ns() you find: + + ns ~= (clocksource * mult) >> shift + +You will find a number of helper functions in the clock source code intended +to aid in providing these mult and shift values, such as +clocksource_khz2mult(), clocksource_hz2mult() that help determine the +mult factor from a fixed shift, and clocksource_register_hz() and +clocksource_register_khz() which will help out assigning both shift and mult +factors using the frequency of the clock source as the only input. + +For real simple clock sources accessed from a single I/O memory location +there is nowadays even clocksource_mmio_init() which will take a memory +location, bit width, a parameter telling whether the counter in the +register counts up or down, and the timer clock rate, and then conjure all +necessary parameters. + +Since a 32-bit counter at say 100 MHz will wrap around to zero after some 43 +seconds, the code handling the clock source will have to compensate for this. +That is the reason why the clock source struct also contains a 'mask' +member telling how many bits of the source are valid. This way the timekeeping +code knows when the counter will wrap around and can insert the necessary +compensation code on both sides of the wrap point so that the system timeline +remains monotonic. + + +Clock events +------------ + +Clock events are the conceptual reverse of clock sources: they take a +desired time specification value and calculate the values to poke into +hardware timer registers. + +Clock events are orthogonal to clock sources. The same hardware +and register range may be used for the clock event, but it is essentially +a different thing. The hardware driving clock events has to be able to +fire interrupts, so as to trigger events on the system timeline. On an SMP +system, it is ideal (and customary) to have one such event driving timer per +CPU core, so that each core can trigger events independently of any other +core. + +You will notice that the clock event device code is based on the same basic +idea about translating counters to nanoseconds using mult and shift +arithmetic, and you find the same family of helper functions again for +assigning these values. The clock event driver does not need a 'mask' +attribute however: the system will not try to plan events beyond the time +horizon of the clock event. + + +sched_clock() +------------- + +In addition to the clock sources and clock events there is a special weak +function in the kernel called sched_clock(). This function shall return the +number of nanoseconds since the system was started. An architecture may or +may not provide an implementation of sched_clock() on its own. If a local +implementation is not provided, the system jiffy counter will be used as +sched_clock(). + +As the name suggests, sched_clock() is used for scheduling the system, +determining the absolute timeslice for a certain process in the CFS scheduler +for example. It is also used for printk timestamps when you have selected to +include time information in printk for things like bootcharts. + +Compared to clock sources, sched_clock() has to be very fast: it is called +much more often, especially by the scheduler. If you have to do trade-offs +between accuracy compared to the clock source, you may sacrifice accuracy +for speed in sched_clock(). It however requires some of the same basic +characteristics as the clock source, i.e. it should be monotonic. + +The sched_clock() function may wrap only on unsigned long long boundaries, +i.e. after 64 bits. Since this is a nanosecond value this will mean it wraps +after circa 585 years. (For most practical systems this means "never".) + +If an architecture does not provide its own implementation of this function, +it will fall back to using jiffies, making its maximum resolution 1/HZ of the +jiffy frequency for the architecture. This will affect scheduling accuracy +and will likely show up in system benchmarks. + +The clock driving sched_clock() may stop or reset to zero during system +suspend/sleep. This does not matter to the function it serves of scheduling +events on the system. However it may result in interesting timestamps in +printk(). + +The sched_clock() function should be callable in any context, IRQ- and +NMI-safe and return a sane value in any context. + +Some architectures may have a limited set of time sources and lack a nice +counter to derive a 64-bit nanosecond value, so for example on the ARM +architecture, special helper functions have been created to provide a +sched_clock() nanosecond base from a 16- or 32-bit counter. Sometimes the +same counter that is also used as clock source is used for this purpose. + +On SMP systems, it is crucial for performance that sched_clock() can be called +independently on each CPU without any synchronization performance hits. +Some hardware (such as the x86 TSC) will cause the sched_clock() function to +drift between the CPUs on the system. The kernel can work around this by +enabling the CONFIG_HAVE_UNSTABLE_SCHED_CLOCK option. This is another aspect +that makes sched_clock() different from the ordinary clock source. + + +Delay timers (some architectures only) +-------------------------------------- + +On systems with variable CPU frequency, the various kernel delay() functions +will sometimes behave strangely. Basically these delays usually use a hard +loop to delay a certain number of jiffy fractions using a "lpj" (loops per +jiffy) value, calibrated on boot. + +Let's hope that your system is running on maximum frequency when this value +is calibrated: as an effect when the frequency is geared down to half the +full frequency, any delay() will be twice as long. Usually this does not +hurt, as you're commonly requesting that amount of delay *or more*. But +basically the semantics are quite unpredictable on such systems. + +Enter timer-based delays. Using these, a timer read may be used instead of +a hard-coded loop for providing the desired delay. + +This is done by declaring a struct delay_timer and assigning the appropriate +function pointers and rate settings for this delay timer. + +This is available on some architectures like OpenRISC or ARM. diff --git a/Documentation/timers/timekeeping.txt b/Documentation/timers/timekeeping.txt deleted file mode 100644 index 2d1732b0a868..000000000000 --- a/Documentation/timers/timekeeping.txt +++ /dev/null @@ -1,179 +0,0 @@ -Clock sources, Clock events, sched_clock() and delay timers ------------------------------------------------------------ - -This document tries to briefly explain some basic kernel timekeeping -abstractions. It partly pertains to the drivers usually found in -drivers/clocksource in the kernel tree, but the code may be spread out -across the kernel. - -If you grep through the kernel source you will find a number of architecture- -specific implementations of clock sources, clockevents and several likewise -architecture-specific overrides of the sched_clock() function and some -delay timers. - -To provide timekeeping for your platform, the clock source provides -the basic timeline, whereas clock events shoot interrupts on certain points -on this timeline, providing facilities such as high-resolution timers. -sched_clock() is used for scheduling and timestamping, and delay timers -provide an accurate delay source using hardware counters. - - -Clock sources -------------- - -The purpose of the clock source is to provide a timeline for the system that -tells you where you are in time. For example issuing the command 'date' on -a Linux system will eventually read the clock source to determine exactly -what time it is. - -Typically the clock source is a monotonic, atomic counter which will provide -n bits which count from 0 to (2^n)-1 and then wraps around to 0 and start over. -It will ideally NEVER stop ticking as long as the system is running. It -may stop during system suspend. - -The clock source shall have as high resolution as possible, and the frequency -shall be as stable and correct as possible as compared to a real-world wall -clock. It should not move unpredictably back and forth in time or miss a few -cycles here and there. - -It must be immune to the kind of effects that occur in hardware where e.g. -the counter register is read in two phases on the bus lowest 16 bits first -and the higher 16 bits in a second bus cycle with the counter bits -potentially being updated in between leading to the risk of very strange -values from the counter. - -When the wall-clock accuracy of the clock source isn't satisfactory, there -are various quirks and layers in the timekeeping code for e.g. synchronizing -the user-visible time to RTC clocks in the system or against networked time -servers using NTP, but all they do basically is update an offset against -the clock source, which provides the fundamental timeline for the system. -These measures does not affect the clock source per se, they only adapt the -system to the shortcomings of it. - -The clock source struct shall provide means to translate the provided counter -into a nanosecond value as an unsigned long long (unsigned 64 bit) number. -Since this operation may be invoked very often, doing this in a strict -mathematical sense is not desirable: instead the number is taken as close as -possible to a nanosecond value using only the arithmetic operations -multiply and shift, so in clocksource_cyc2ns() you find: - - ns ~= (clocksource * mult) >> shift - -You will find a number of helper functions in the clock source code intended -to aid in providing these mult and shift values, such as -clocksource_khz2mult(), clocksource_hz2mult() that help determine the -mult factor from a fixed shift, and clocksource_register_hz() and -clocksource_register_khz() which will help out assigning both shift and mult -factors using the frequency of the clock source as the only input. - -For real simple clock sources accessed from a single I/O memory location -there is nowadays even clocksource_mmio_init() which will take a memory -location, bit width, a parameter telling whether the counter in the -register counts up or down, and the timer clock rate, and then conjure all -necessary parameters. - -Since a 32-bit counter at say 100 MHz will wrap around to zero after some 43 -seconds, the code handling the clock source will have to compensate for this. -That is the reason why the clock source struct also contains a 'mask' -member telling how many bits of the source are valid. This way the timekeeping -code knows when the counter will wrap around and can insert the necessary -compensation code on both sides of the wrap point so that the system timeline -remains monotonic. - - -Clock events ------------- - -Clock events are the conceptual reverse of clock sources: they take a -desired time specification value and calculate the values to poke into -hardware timer registers. - -Clock events are orthogonal to clock sources. The same hardware -and register range may be used for the clock event, but it is essentially -a different thing. The hardware driving clock events has to be able to -fire interrupts, so as to trigger events on the system timeline. On an SMP -system, it is ideal (and customary) to have one such event driving timer per -CPU core, so that each core can trigger events independently of any other -core. - -You will notice that the clock event device code is based on the same basic -idea about translating counters to nanoseconds using mult and shift -arithmetic, and you find the same family of helper functions again for -assigning these values. The clock event driver does not need a 'mask' -attribute however: the system will not try to plan events beyond the time -horizon of the clock event. - - -sched_clock() -------------- - -In addition to the clock sources and clock events there is a special weak -function in the kernel called sched_clock(). This function shall return the -number of nanoseconds since the system was started. An architecture may or -may not provide an implementation of sched_clock() on its own. If a local -implementation is not provided, the system jiffy counter will be used as -sched_clock(). - -As the name suggests, sched_clock() is used for scheduling the system, -determining the absolute timeslice for a certain process in the CFS scheduler -for example. It is also used for printk timestamps when you have selected to -include time information in printk for things like bootcharts. - -Compared to clock sources, sched_clock() has to be very fast: it is called -much more often, especially by the scheduler. If you have to do trade-offs -between accuracy compared to the clock source, you may sacrifice accuracy -for speed in sched_clock(). It however requires some of the same basic -characteristics as the clock source, i.e. it should be monotonic. - -The sched_clock() function may wrap only on unsigned long long boundaries, -i.e. after 64 bits. Since this is a nanosecond value this will mean it wraps -after circa 585 years. (For most practical systems this means "never".) - -If an architecture does not provide its own implementation of this function, -it will fall back to using jiffies, making its maximum resolution 1/HZ of the -jiffy frequency for the architecture. This will affect scheduling accuracy -and will likely show up in system benchmarks. - -The clock driving sched_clock() may stop or reset to zero during system -suspend/sleep. This does not matter to the function it serves of scheduling -events on the system. However it may result in interesting timestamps in -printk(). - -The sched_clock() function should be callable in any context, IRQ- and -NMI-safe and return a sane value in any context. - -Some architectures may have a limited set of time sources and lack a nice -counter to derive a 64-bit nanosecond value, so for example on the ARM -architecture, special helper functions have been created to provide a -sched_clock() nanosecond base from a 16- or 32-bit counter. Sometimes the -same counter that is also used as clock source is used for this purpose. - -On SMP systems, it is crucial for performance that sched_clock() can be called -independently on each CPU without any synchronization performance hits. -Some hardware (such as the x86 TSC) will cause the sched_clock() function to -drift between the CPUs on the system. The kernel can work around this by -enabling the CONFIG_HAVE_UNSTABLE_SCHED_CLOCK option. This is another aspect -that makes sched_clock() different from the ordinary clock source. - - -Delay timers (some architectures only) --------------------------------------- - -On systems with variable CPU frequency, the various kernel delay() functions -will sometimes behave strangely. Basically these delays usually use a hard -loop to delay a certain number of jiffy fractions using a "lpj" (loops per -jiffy) value, calibrated on boot. - -Let's hope that your system is running on maximum frequency when this value -is calibrated: as an effect when the frequency is geared down to half the -full frequency, any delay() will be twice as long. Usually this does not -hurt, as you're commonly requesting that amount of delay *or more*. But -basically the semantics are quite unpredictable on such systems. - -Enter timer-based delays. Using these, a timer read may be used instead of -a hard-coded loop for providing the desired delay. - -This is done by declaring a struct delay_timer and assigning the appropriate -function pointers and rate settings for this delay timer. - -This is available on some architectures like OpenRISC or ARM. diff --git a/Documentation/timers/timers-howto.rst b/Documentation/timers/timers-howto.rst new file mode 100644 index 000000000000..7e3167bec2b1 --- /dev/null +++ b/Documentation/timers/timers-howto.rst @@ -0,0 +1,112 @@ +=================================================================== +delays - Information on the various kernel delay / sleep mechanisms +=================================================================== + +This document seeks to answer the common question: "What is the +RightWay (TM) to insert a delay?" + +This question is most often faced by driver writers who have to +deal with hardware delays and who may not be the most intimately +familiar with the inner workings of the Linux Kernel. + + +Inserting Delays +---------------- + +The first, and most important, question you need to ask is "Is my +code in an atomic context?" This should be followed closely by "Does +it really need to delay in atomic context?" If so... + +ATOMIC CONTEXT: + You must use the `*delay` family of functions. These + functions use the jiffie estimation of clock speed + and will busy wait for enough loop cycles to achieve + the desired delay: + + ndelay(unsigned long nsecs) + udelay(unsigned long usecs) + mdelay(unsigned long msecs) + + udelay is the generally preferred API; ndelay-level + precision may not actually exist on many non-PC devices. + + mdelay is macro wrapper around udelay, to account for + possible overflow when passing large arguments to udelay. + In general, use of mdelay is discouraged and code should + be refactored to allow for the use of msleep. + +NON-ATOMIC CONTEXT: + You should use the `*sleep[_range]` family of functions. + There are a few more options here, while any of them may + work correctly, using the "right" sleep function will + help the scheduler, power management, and just make your + driver better :) + + -- Backed by busy-wait loop: + + udelay(unsigned long usecs) + + -- Backed by hrtimers: + + usleep_range(unsigned long min, unsigned long max) + + -- Backed by jiffies / legacy_timers + + msleep(unsigned long msecs) + msleep_interruptible(unsigned long msecs) + + Unlike the `*delay` family, the underlying mechanism + driving each of these calls varies, thus there are + quirks you should be aware of. + + + SLEEPING FOR "A FEW" USECS ( < ~10us? ): + * Use udelay + + - Why not usleep? + On slower systems, (embedded, OR perhaps a speed- + stepped PC!) the overhead of setting up the hrtimers + for usleep *may* not be worth it. Such an evaluation + will obviously depend on your specific situation, but + it is something to be aware of. + + SLEEPING FOR ~USECS OR SMALL MSECS ( 10us - 20ms): + * Use usleep_range + + - Why not msleep for (1ms - 20ms)? + Explained originally here: + http://lkml.org/lkml/2007/8/3/250 + + msleep(1~20) may not do what the caller intends, and + will often sleep longer (~20 ms actual sleep for any + value given in the 1~20ms range). In many cases this + is not the desired behavior. + + - Why is there no "usleep" / What is a good range? + Since usleep_range is built on top of hrtimers, the + wakeup will be very precise (ish), thus a simple + usleep function would likely introduce a large number + of undesired interrupts. + + With the introduction of a range, the scheduler is + free to coalesce your wakeup with any other wakeup + that may have happened for other reasons, or at the + worst case, fire an interrupt for your upper bound. + + The larger a range you supply, the greater a chance + that you will not trigger an interrupt; this should + be balanced with what is an acceptable upper bound on + delay / performance for your specific code path. Exact + tolerances here are very situation specific, thus it + is left to the caller to determine a reasonable range. + + SLEEPING FOR LARGER MSECS ( 10ms+ ) + * Use msleep or possibly msleep_interruptible + + - What's the difference? + msleep sets the current task to TASK_UNINTERRUPTIBLE + whereas msleep_interruptible sets the current task to + TASK_INTERRUPTIBLE before scheduling the sleep. In + short, the difference is whether the sleep can be ended + early by a signal. In general, just use msleep unless + you know you have a need for the interruptible variant. diff --git a/Documentation/timers/timers-howto.txt b/Documentation/timers/timers-howto.txt deleted file mode 100644 index 038f8c77a076..000000000000 --- a/Documentation/timers/timers-howto.txt +++ /dev/null @@ -1,105 +0,0 @@ -delays - Information on the various kernel delay / sleep mechanisms -------------------------------------------------------------------- - -This document seeks to answer the common question: "What is the -RightWay (TM) to insert a delay?" - -This question is most often faced by driver writers who have to -deal with hardware delays and who may not be the most intimately -familiar with the inner workings of the Linux Kernel. - - -Inserting Delays ----------------- - -The first, and most important, question you need to ask is "Is my -code in an atomic context?" This should be followed closely by "Does -it really need to delay in atomic context?" If so... - -ATOMIC CONTEXT: - You must use the *delay family of functions. These - functions use the jiffie estimation of clock speed - and will busy wait for enough loop cycles to achieve - the desired delay: - - ndelay(unsigned long nsecs) - udelay(unsigned long usecs) - mdelay(unsigned long msecs) - - udelay is the generally preferred API; ndelay-level - precision may not actually exist on many non-PC devices. - - mdelay is macro wrapper around udelay, to account for - possible overflow when passing large arguments to udelay. - In general, use of mdelay is discouraged and code should - be refactored to allow for the use of msleep. - -NON-ATOMIC CONTEXT: - You should use the *sleep[_range] family of functions. - There are a few more options here, while any of them may - work correctly, using the "right" sleep function will - help the scheduler, power management, and just make your - driver better :) - - -- Backed by busy-wait loop: - udelay(unsigned long usecs) - -- Backed by hrtimers: - usleep_range(unsigned long min, unsigned long max) - -- Backed by jiffies / legacy_timers - msleep(unsigned long msecs) - msleep_interruptible(unsigned long msecs) - - Unlike the *delay family, the underlying mechanism - driving each of these calls varies, thus there are - quirks you should be aware of. - - - SLEEPING FOR "A FEW" USECS ( < ~10us? ): - * Use udelay - - - Why not usleep? - On slower systems, (embedded, OR perhaps a speed- - stepped PC!) the overhead of setting up the hrtimers - for usleep *may* not be worth it. Such an evaluation - will obviously depend on your specific situation, but - it is something to be aware of. - - SLEEPING FOR ~USECS OR SMALL MSECS ( 10us - 20ms): - * Use usleep_range - - - Why not msleep for (1ms - 20ms)? - Explained originally here: - http://lkml.org/lkml/2007/8/3/250 - msleep(1~20) may not do what the caller intends, and - will often sleep longer (~20 ms actual sleep for any - value given in the 1~20ms range). In many cases this - is not the desired behavior. - - - Why is there no "usleep" / What is a good range? - Since usleep_range is built on top of hrtimers, the - wakeup will be very precise (ish), thus a simple - usleep function would likely introduce a large number - of undesired interrupts. - - With the introduction of a range, the scheduler is - free to coalesce your wakeup with any other wakeup - that may have happened for other reasons, or at the - worst case, fire an interrupt for your upper bound. - - The larger a range you supply, the greater a chance - that you will not trigger an interrupt; this should - be balanced with what is an acceptable upper bound on - delay / performance for your specific code path. Exact - tolerances here are very situation specific, thus it - is left to the caller to determine a reasonable range. - - SLEEPING FOR LARGER MSECS ( 10ms+ ) - * Use msleep or possibly msleep_interruptible - - - What's the difference? - msleep sets the current task to TASK_UNINTERRUPTIBLE - whereas msleep_interruptible sets the current task to - TASK_INTERRUPTIBLE before scheduling the sleep. In - short, the difference is whether the sleep can be ended - early by a signal. In general, just use msleep unless - you know you have a need for the interruptible variant. diff --git a/MAINTAINERS b/MAINTAINERS index 5fe44d5d82b4..0db7f12439f7 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -7192,7 +7192,7 @@ F: drivers/net/ethernet/hp/hp100.* HPET: High Precision Event Timers driver M: Clemens Ladisch S: Maintained -F: Documentation/timers/hpet.txt +F: Documentation/timers/hpet.rst F: drivers/char/hpet.c F: include/linux/hpet.h F: include/uapi/linux/hpet.h diff --git a/drivers/media/usb/dvb-usb-v2/anysee.c b/drivers/media/usb/dvb-usb-v2/anysee.c index 48fb0d41e03b..fb6d99dea31a 100644 --- a/drivers/media/usb/dvb-usb-v2/anysee.c +++ b/drivers/media/usb/dvb-usb-v2/anysee.c @@ -56,7 +56,7 @@ static int anysee_ctrl_msg(struct dvb_usb_device *d, /* TODO FIXME: dvb_usb_generic_rw() fails rarely with error code -32 * (EPIPE, Broken pipe). Function supports currently msleep() as a * parameter but I would not like to use it, since according to - * Documentation/timers/timers-howto.txt it should not be used such + * Documentation/timers/timers-howto.rst it should not be used such * short, under < 20ms, sleeps. Repeating failed message would be * better choice as not to add unwanted delays... * Fixing that correctly is one of those or both; diff --git a/drivers/regulator/core.c b/drivers/regulator/core.c index c894cf0d8a28..c5d8996d5165 100644 --- a/drivers/regulator/core.c +++ b/drivers/regulator/core.c @@ -2304,7 +2304,7 @@ static int regulator_ena_gpio_ctrl(struct regulator_dev *rdev, bool enable) * * Delay for the requested amount of time as per the guidelines in: * - * Documentation/timers/timers-howto.txt + * Documentation/timers/timers-howto.rst * * The assumption here is that regulators will never be enabled in * atomic context and therefore sleeping functions can be used. diff --git a/include/linux/iopoll.h b/include/linux/iopoll.h index 3908353deec6..35e15dfd4155 100644 --- a/include/linux/iopoll.h +++ b/include/linux/iopoll.h @@ -21,7 +21,7 @@ * @cond: Break condition (usually involving @val) * @sleep_us: Maximum time to sleep between reads in us (0 * tight-loops). Should be less than ~20ms since usleep_range - * is used (see Documentation/timers/timers-howto.txt). + * is used (see Documentation/timers/timers-howto.rst). * @timeout_us: Timeout in us, 0 means never timeout * * Returns 0 on success and -ETIMEDOUT upon a timeout. In either @@ -60,7 +60,7 @@ * @cond: Break condition (usually involving @val) * @delay_us: Time to udelay between reads in us (0 tight-loops). Should * be less than ~10us since udelay is used (see - * Documentation/timers/timers-howto.txt). + * Documentation/timers/timers-howto.rst). * @timeout_us: Timeout in us, 0 means never timeout * * Returns 0 on success and -ETIMEDOUT upon a timeout. In either diff --git a/include/linux/regmap.h b/include/linux/regmap.h index daeec7dbd65c..ed5e9d0a1285 100644 --- a/include/linux/regmap.h +++ b/include/linux/regmap.h @@ -112,7 +112,7 @@ struct reg_sequence { * @cond: Break condition (usually involving @val) * @sleep_us: Maximum time to sleep between reads in us (0 * tight-loops). Should be less than ~20ms since usleep_range - * is used (see Documentation/timers/timers-howto.txt). + * is used (see Documentation/timers/timers-howto.rst). * @timeout_us: Timeout in us, 0 means never timeout * * Returns 0 on success and -ETIMEDOUT upon a timeout or the regmap_read @@ -154,7 +154,7 @@ struct reg_sequence { * @cond: Break condition (usually involving @val) * @sleep_us: Maximum time to sleep between reads in us (0 * tight-loops). Should be less than ~20ms since usleep_range - * is used (see Documentation/timers/timers-howto.txt). + * is used (see Documentation/timers/timers-howto.rst). * @timeout_us: Timeout in us, 0 means never timeout * * Returns 0 on success and -ETIMEDOUT upon a timeout or the regmap_field_read diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl index 342c7c781ba5..a6d436809bf5 100755 --- a/scripts/checkpatch.pl +++ b/scripts/checkpatch.pl @@ -5712,7 +5712,7 @@ sub process { # ignore udelay's < 10, however if (! ($delay < 10) ) { CHK("USLEEP_RANGE", - "usleep_range is preferred over udelay; see Documentation/timers/timers-howto.txt\n" . $herecurr); + "usleep_range is preferred over udelay; see Documentation/timers/timers-howto.rst\n" . $herecurr); } if ($delay > 2000) { WARN("LONG_UDELAY", @@ -5724,7 +5724,7 @@ sub process { if ($line =~ /\bmsleep\s*\((\d+)\);/) { if ($1 < 20) { WARN("MSLEEP", - "msleep < 20ms can sleep for up to 20ms; see Documentation/timers/timers-howto.txt\n" . $herecurr); + "msleep < 20ms can sleep for up to 20ms; see Documentation/timers/timers-howto.rst\n" . $herecurr); } } @@ -6115,11 +6115,11 @@ sub process { my $max = $7; if ($min eq $max) { WARN("USLEEP_RANGE", - "usleep_range should not use min == max args; see Documentation/timers/timers-howto.txt\n" . "$here\n$stat\n"); + "usleep_range should not use min == max args; see Documentation/timers/timers-howto.rst\n" . "$here\n$stat\n"); } elsif ($min =~ /^\d+$/ && $max =~ /^\d+$/ && $min > $max) { WARN("USLEEP_RANGE", - "usleep_range args reversed, use min then max; see Documentation/timers/timers-howto.txt\n" . "$here\n$stat\n"); + "usleep_range args reversed, use min then max; see Documentation/timers/timers-howto.rst\n" . "$here\n$stat\n"); } } diff --git a/sound/soc/sof/ops.h b/sound/soc/sof/ops.h index 80fc3b374c2b..8058a6c73082 100644 --- a/sound/soc/sof/ops.h +++ b/sound/soc/sof/ops.h @@ -349,7 +349,7 @@ static inline const struct snd_sof_dsp_ops * @cond: Break condition (usually involving @val) * @sleep_us: Maximum time to sleep between reads in us (0 * tight-loops). Should be less than ~20ms since usleep_range - * is used (see Documentation/timers/timers-howto.txt). + * is used (see Documentation/timers/timers-howto.rst). * @timeout_us: Timeout in us, 0 means never timeout * * Returns 0 on success and -ETIMEDOUT upon a timeout. In either -- cgit v1.2.3 From 407b584d155be67a9311a62da8d7874f62b987ac Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 13 Jun 2019 07:29:17 -0300 Subject: scripts/documentation-file-ref-check: ignore output dir When there's no Documentation/output directory, the script will complain about those missing references: Documentation/doc-guide/sphinx.rst: Documentation/output Documentation/doc-guide/sphinx.rst: Documentation/output Documentation/process/howto.rst: Documentation/output Documentation/translations/it_IT/doc-guide/sphinx.rst: Documentation/output Documentation/translations/it_IT/doc-guide/sphinx.rst: Documentation/output Documentation/translations/it_IT/process/howto.rst: Documentation/output Documentation/translations/ja_JP/howto.rst: Documentation/output Documentation/translations/ko_KR/howto.rst: Documentation/output Those are false positives, so add an ignore rule for them. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/documentation-file-ref-check | 3 +++ 1 file changed, 3 insertions(+) (limited to 'scripts') diff --git a/scripts/documentation-file-ref-check b/scripts/documentation-file-ref-check index a4139a576726..7784c54aa38b 100755 --- a/scripts/documentation-file-ref-check +++ b/scripts/documentation-file-ref-check @@ -90,6 +90,9 @@ while () { # Skip this script next if ($f eq $scriptname); + # Ignore the dir where documentation will be built + next if ($ln =~ m,\b(\S*)Documentation/output,); + if ($ln =~ m,\b(\S*)(Documentation/[A-Za-z0-9\_\.\,\~/\*\[\]\?+-]*)(.*),) { my $prefix = $1; my $ref = $2; -- cgit v1.2.3 From f3c8d4c7a7280cdc6622adb4f8e39d51b3786d68 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Tue, 4 Jun 2019 19:13:55 +0900 Subject: kbuild: remove headers_{install,check}_all headers_install_all does not make much sense any more because different architectures export different set of uapi/linux/ headers. As you see in include/uapi/linux/Kbuild, the installation of a.out.h, kvm.h, and kvm_para.h is arch-dependent. So, headers_install_all repeats the installation/removal of them. If somebody really thinks it is useful to do headers_install for all architectures, it would be possible by small shell-scripting, but the top Makefile does not have to provide entry targets just for that purpose. Signed-off-by: Masahiro Yamada Acked-by: Sam Ravnborg --- Documentation/kbuild/headers_install.txt | 7 ------- Documentation/kbuild/makefiles.txt | 6 +----- Makefile | 15 ++------------- scripts/headers.sh | 29 ----------------------------- 4 files changed, 3 insertions(+), 54 deletions(-) delete mode 100755 scripts/headers.sh (limited to 'scripts') diff --git a/Documentation/kbuild/headers_install.txt b/Documentation/kbuild/headers_install.txt index f0153adb95e2..f07e34eab70b 100644 --- a/Documentation/kbuild/headers_install.txt +++ b/Documentation/kbuild/headers_install.txt @@ -39,12 +39,5 @@ INSTALL_HDR_PATH indicates where to install the headers. It defaults to An 'include' directory is automatically created inside INSTALL_HDR_PATH and headers are installed in 'INSTALL_HDR_PATH/include'. -The command "make headers_install_all" exports headers for all architectures -simultaneously. (This is mostly of interest to distribution maintainers, -who create an architecture-independent tarball from the resulting include -directory.) You also can use HDR_ARCH_LIST to specify list of architectures. -Remember to provide the appropriate linux/asm directory via "mv" or "ln -s" -before building a C library with headers exported this way. - The kernel header export infrastructure is maintained by David Woodhouse . diff --git a/Documentation/kbuild/makefiles.txt b/Documentation/kbuild/makefiles.txt index d65ad5746f94..bac301a73a86 100644 --- a/Documentation/kbuild/makefiles.txt +++ b/Documentation/kbuild/makefiles.txt @@ -897,11 +897,7 @@ When kbuild executes, the following steps are followed (roughly): --- 6.2 Add prerequisites to archheaders: The archheaders: rule is used to generate header files that - may be installed into user space by "make header_install" or - "make headers_install_all". In order to support - "make headers_install_all", this target has to be able to run - on an unconfigured tree, or a tree configured for another - architecture. + may be installed into user space by "make header_install". It is run before "make archprepare" when run on the architecture itself. diff --git a/Makefile b/Makefile index b81e17261250..b4b07e90c969 100644 --- a/Makefile +++ b/Makefile @@ -1181,34 +1181,23 @@ headerdep: #Default location for installed headers export INSTALL_HDR_PATH = $(objtree)/usr -# If we do an all arch process set dst to include/arch-$(SRCARCH) -hdr-dst = $(if $(KBUILD_HEADERS), dst=include/arch-$(SRCARCH), dst=include) - PHONY += archheaders archscripts PHONY += __headers __headers: $(version_h) scripts_basic uapi-asm-generic archheaders archscripts $(Q)$(MAKE) $(build)=scripts build_unifdef -PHONY += headers_install_all -headers_install_all: - $(Q)$(CONFIG_SHELL) $(srctree)/scripts/headers.sh install - PHONY += headers_install headers_install: __headers $(if $(wildcard $(srctree)/arch/$(SRCARCH)/include/uapi/asm/Kbuild),, \ $(error Headers not exportable for the $(SRCARCH) architecture)) $(Q)$(MAKE) $(hdr-inst)=include/uapi dst=include - $(Q)$(MAKE) $(hdr-inst)=arch/$(SRCARCH)/include/uapi $(hdr-dst) - -PHONY += headers_check_all -headers_check_all: headers_install_all - $(Q)$(CONFIG_SHELL) $(srctree)/scripts/headers.sh check + $(Q)$(MAKE) $(hdr-inst)=arch/$(SRCARCH)/include/uapi dst=include PHONY += headers_check headers_check: headers_install $(Q)$(MAKE) $(hdr-inst)=include/uapi dst=include HDRCHECK=1 - $(Q)$(MAKE) $(hdr-inst)=arch/$(SRCARCH)/include/uapi $(hdr-dst) HDRCHECK=1 + $(Q)$(MAKE) $(hdr-inst)=arch/$(SRCARCH)/include/uapi dst=include HDRCHECK=1 ifdef CONFIG_HEADERS_CHECK all: headers_check diff --git a/scripts/headers.sh b/scripts/headers.sh deleted file mode 100755 index e0f883eb39a2..000000000000 --- a/scripts/headers.sh +++ /dev/null @@ -1,29 +0,0 @@ -#!/bin/sh -# SPDX-License-Identifier: GPL-2.0 -# Run headers_$1 command for all suitable architectures - -# Stop on error -set -e - -do_command() -{ - if [ -f ${srctree}/arch/$2/include/asm/Kbuild ]; then - make ARCH=$2 KBUILD_HEADERS=$1 headers_$1 - else - printf "Ignoring arch: %s\n" ${arch} - fi -} - -archs=${HDR_ARCH_LIST:-$(ls ${srctree}/arch)} - -for arch in ${archs}; do - case ${arch} in - um) # no userspace export - ;; - *) - if [ -d ${srctree}/arch/${arch} ]; then - do_command $1 ${arch} - fi - ;; - esac -done -- cgit v1.2.3 From 2b8481be3cc3b8dfb2704f4d33668d930474fac8 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Tue, 4 Jun 2019 19:14:00 +0900 Subject: kbuild: remove build_unifdef target in scripts/Makefile Since commit 2aedcd098a94 ("kbuild: suppress annoying "... is up to date." message"), if_changed and friends nicely suppress "is up to date" messages. We do not need per-Makefile tricks. Signed-off-by: Masahiro Yamada --- Makefile | 2 +- scripts/Makefile | 5 ----- 2 files changed, 1 insertion(+), 6 deletions(-) (limited to 'scripts') diff --git a/Makefile b/Makefile index f3fd2a549970..6abcacface9c 100644 --- a/Makefile +++ b/Makefile @@ -1182,7 +1182,7 @@ PHONY += archheaders archscripts PHONY += __headers __headers: $(version_h) scripts_basic uapi-asm-generic archheaders archscripts - $(Q)$(MAKE) $(build)=scripts build_unifdef + $(Q)$(MAKE) $(build)=scripts scripts/unifdef PHONY += headers_install headers_install: __headers diff --git a/scripts/Makefile b/scripts/Makefile index 9d442ee050bd..16bcb8087899 100644 --- a/scripts/Makefile +++ b/scripts/Makefile @@ -31,11 +31,6 @@ always := $(hostprogs-y) $(hostprogs-m) # The following hostprogs-y programs are only build on demand hostprogs-y += unifdef -# These targets are used internally to avoid "is up to date" messages -PHONY += build_unifdef -build_unifdef: $(obj)/unifdef - @: - subdir-$(CONFIG_GCC_PLUGINS) += gcc-plugins subdir-$(CONFIG_MODVERSIONS) += genksyms subdir-$(CONFIG_SECURITY_SELINUX) += selinux -- cgit v1.2.3 From 59b2bd05f5f4dc62979c2e82ddd384f07e8f10bc Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Tue, 4 Jun 2019 19:14:02 +0900 Subject: kbuild: add 'headers' target to build up uapi headers in usr/include In Linux build system, build targets and installation targets are separated. Examples are: - 'make vmlinux' -> 'make install' - 'make modules' -> 'make modules_install' - 'make dtbs' -> 'make dtbs_install' - 'make vdso' -> 'make vdso_install' The intention is to run the build targets under the normal privilege, then the installation targets under the root privilege since we need the write permission to the system directories. We have 'make headers_install' but the corresponding 'make headers' stage does not exist. The purpose of headers_install is to provide the kernel interface to C library. So, nobody would try to install headers to /usr/include directly. If 'sudo make INSTALL_HDR_PATH=/usr/include headers_install' were run, some build artifacts in the kernel tree would be owned by root because some of uapi headers are generated by 'uapi-asm-generic', 'archheaders' targets. Anyway, I believe it makes sense to split the header installation into two stages. [1] 'make headers' Process headers in uapi directories by scripts/headers_install.sh and copy them to usr/include [2] 'make headers_install' Copy '*.h' verbatim from usr/include to $(INSTALL_HDR_PATH)/include For the backward compatibility, 'headers_install' depends on 'headers'. Some samples expect uapi headers in usr/include. So, the 'headers' target is useful to build up them in the fixed location usr/include irrespective of INSTALL_HDR_PATH. Another benefit is to stop polluting the final destination with the time-stamp files '.install' and '.check'. Maybe you can see them in your toolchains. Lastly, my main motivation is to prepare for compile-testing uapi headers. To build something, we have to save an object and .*.cmd somewhere. The usr/include/ will be the work directory for that. Signed-off-by: Masahiro Yamada --- Makefile | 23 +++++++++++++++-------- lib/Kconfig.debug | 4 +--- scripts/Makefile.headersinst | 8 ++++---- 3 files changed, 20 insertions(+), 15 deletions(-) (limited to 'scripts') diff --git a/Makefile b/Makefile index 39ee585b52b1..11445a7dd820 100644 --- a/Makefile +++ b/Makefile @@ -262,7 +262,7 @@ old_version_h := include/linux/version.h clean-targets := %clean mrproper cleandocs no-dot-config-targets := $(clean-targets) \ cscope gtags TAGS tags help% %docs check% coccicheck \ - $(version_h) headers_% archheaders archscripts \ + $(version_h) headers headers_% archheaders archscripts \ %asm-generic kernelversion %src-pkg no-sync-config-targets := $(no-dot-config-targets) install %install \ kernelrelease @@ -1178,25 +1178,32 @@ headerdep: #Default location for installed headers export INSTALL_HDR_PATH = $(objtree)/usr -PHONY += archheaders archscripts - -PHONY += __headers -__headers: $(version_h) scripts_unifdef uapi-asm-generic archheaders archscripts +quiet_cmd_headers_install = INSTALL $(INSTALL_HDR_PATH)/include + cmd_headers_install = \ + mkdir -p $(INSTALL_HDR_PATH); \ + rsync -mrl --include='*/' --include='*\.h' --exclude='*' \ + usr/include $(INSTALL_HDR_PATH) PHONY += headers_install -headers_install: __headers +headers_install: headers + $(call cmd,headers_install) + +PHONY += archheaders archscripts + +PHONY += headers +headers: $(version_h) scripts_unifdef uapi-asm-generic archheaders archscripts $(if $(wildcard $(srctree)/arch/$(SRCARCH)/include/uapi/asm/Kbuild),, \ $(error Headers not exportable for the $(SRCARCH) architecture)) $(Q)$(MAKE) $(hdr-inst)=include/uapi dst=include $(Q)$(MAKE) $(hdr-inst)=arch/$(SRCARCH)/include/uapi dst=include PHONY += headers_check -headers_check: headers_install +headers_check: headers $(Q)$(MAKE) $(hdr-inst)=include/uapi dst=include HDRCHECK=1 $(Q)$(MAKE) $(hdr-inst)=arch/$(SRCARCH)/include/uapi dst=include HDRCHECK=1 ifdef CONFIG_HEADERS_INSTALL -prepare: headers_install +prepare: headers endif ifdef CONFIG_HEADERS_CHECK diff --git a/lib/Kconfig.debug b/lib/Kconfig.debug index 6a6ea4219d1e..0031a31d98c2 100644 --- a/lib/Kconfig.debug +++ b/lib/Kconfig.debug @@ -324,9 +324,7 @@ config HEADERS_CHECK attempt to include files which were not exported, etc. If you're making modifications to header files which are - relevant for userspace, say 'Y', and check the headers - exported to $(INSTALL_HDR_PATH) (usually 'usr/include' in - your build tree), to make sure they're suitable. + relevant for userspace, say 'Y'. config OPTIMIZE_INLINING bool "Allow compiler to uninline functions marked 'inline'" diff --git a/scripts/Makefile.headersinst b/scripts/Makefile.headersinst index 3d1ebaabd1b6..1af6d0b06585 100644 --- a/scripts/Makefile.headersinst +++ b/scripts/Makefile.headersinst @@ -41,7 +41,7 @@ ifeq ($(skip-inst),) kbuild-file := $(srctree)/$(obj)/Kbuild -include $(kbuild-file) -installdir := $(INSTALL_HDR_PATH)/$(dst) +installdir := usr/$(dst) gendir := $(objtree)/$(subst include/,include/generated/,$(obj)) header-files := $(notdir $(wildcard $(srcdir)/*.h)) header-files := $(filter-out $(no-export-headers), $(header-files)) @@ -60,10 +60,10 @@ output-files := $(addprefix $(installdir)/, $(all-files)) oldheaders := $(patsubst $(installdir)/%,%,$(wildcard $(installdir)/*.h)) unwanted := $(filter-out $(all-files),$(oldheaders)) -# Prefix unwanted with full paths to $(INSTALL_HDR_PATH) +# Prefix unwanted with full paths to objtree unwanted-file := $(addprefix $(installdir)/, $(unwanted)) -printdir = $(patsubst $(INSTALL_HDR_PATH)/%/,%,$(dir $@)) +printdir = $(patsubst %/,%,$(dir $@)) quiet_cmd_install = INSTALL $(printdir) ($(words $(all-files))\ file$(if $(word 2, $(all-files)),s)) @@ -81,7 +81,7 @@ quiet_cmd_check = CHECK $(printdir) ($(words $(all-files)) files) cmd_check = for f in $(all-files); do \ echo "$(installdir)/$${f}"; done \ | xargs \ - $(PERL) $< $(INSTALL_HDR_PATH)/include $(SRCARCH); \ + $(PERL) $< usr/include $(SRCARCH); \ touch $@ ifndef HDRCHECK -- cgit v1.2.3 From d5470d14431e9d39ee2131323589afac2a0bfee4 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Tue, 4 Jun 2019 19:14:03 +0900 Subject: kbuild: re-implement Makefile.headersinst without recursion Since commit fcc8487d477a ("uapi: export all headers under uapi directories"), the headers in uapi directories are all exported by default although exceptional cases are still allowed by the syntax 'no-export-headers'. The traditional directory descending has been kept (in a somewhat hacky way), but it is actually unneeded. Get rid of it to simplify the code. Also, handle files one by one instead of the previous per-directory processing. This will emit much more log, but I like it. Signed-off-by: Masahiro Yamada --- Makefile | 8 +-- include/uapi/Kbuild | 14 +++++ include/uapi/linux/Kbuild | 14 ----- scripts/Makefile.headersinst | 132 ++++++++++++++++++------------------------- 4 files changed, 73 insertions(+), 95 deletions(-) create mode 100644 include/uapi/Kbuild delete mode 100644 include/uapi/linux/Kbuild (limited to 'scripts') diff --git a/Makefile b/Makefile index 11445a7dd820..507ce2c92065 100644 --- a/Makefile +++ b/Makefile @@ -1194,13 +1194,13 @@ PHONY += headers headers: $(version_h) scripts_unifdef uapi-asm-generic archheaders archscripts $(if $(wildcard $(srctree)/arch/$(SRCARCH)/include/uapi/asm/Kbuild),, \ $(error Headers not exportable for the $(SRCARCH) architecture)) - $(Q)$(MAKE) $(hdr-inst)=include/uapi dst=include - $(Q)$(MAKE) $(hdr-inst)=arch/$(SRCARCH)/include/uapi dst=include + $(Q)$(MAKE) $(hdr-inst)=include/uapi + $(Q)$(MAKE) $(hdr-inst)=arch/$(SRCARCH)/include/uapi PHONY += headers_check headers_check: headers - $(Q)$(MAKE) $(hdr-inst)=include/uapi dst=include HDRCHECK=1 - $(Q)$(MAKE) $(hdr-inst)=arch/$(SRCARCH)/include/uapi dst=include HDRCHECK=1 + $(Q)$(MAKE) $(hdr-inst)=include/uapi HDRCHECK=1 + $(Q)$(MAKE) $(hdr-inst)=arch/$(SRCARCH)/include/uapi HDRCHECK=1 ifdef CONFIG_HEADERS_INSTALL prepare: headers diff --git a/include/uapi/Kbuild b/include/uapi/Kbuild new file mode 100644 index 000000000000..61ee6e59c930 --- /dev/null +++ b/include/uapi/Kbuild @@ -0,0 +1,14 @@ +# SPDX-License-Identifier: GPL-2.0 +ifeq ($(wildcard $(srctree)/arch/$(SRCARCH)/include/uapi/asm/a.out.h),) +no-export-headers += linux/a.out.h +endif + +ifeq ($(wildcard $(srctree)/arch/$(SRCARCH)/include/uapi/asm/kvm.h),) +no-export-headers += linux/kvm.h +endif + +ifeq ($(wildcard $(srctree)/arch/$(SRCARCH)/include/uapi/asm/kvm_para.h),) +ifeq ($(wildcard $(objtree)/arch/$(SRCARCH)/include/generated/uapi/asm/kvm_para.h),) +no-export-headers += linux/kvm_para.h +endif +endif diff --git a/include/uapi/linux/Kbuild b/include/uapi/linux/Kbuild deleted file mode 100644 index 34711c5d6968..000000000000 --- a/include/uapi/linux/Kbuild +++ /dev/null @@ -1,14 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 -ifeq ($(wildcard $(srctree)/arch/$(SRCARCH)/include/uapi/asm/a.out.h),) -no-export-headers += a.out.h -endif - -ifeq ($(wildcard $(srctree)/arch/$(SRCARCH)/include/uapi/asm/kvm.h),) -no-export-headers += kvm.h -endif - -ifeq ($(wildcard $(srctree)/arch/$(SRCARCH)/include/uapi/asm/kvm_para.h),) -ifeq ($(wildcard $(objtree)/arch/$(SRCARCH)/include/generated/uapi/asm/kvm_para.h),) -no-export-headers += kvm_para.h -endif -endif diff --git a/scripts/Makefile.headersinst b/scripts/Makefile.headersinst index 1af6d0b06585..c96c4c26e240 100644 --- a/scripts/Makefile.headersinst +++ b/scripts/Makefile.headersinst @@ -14,109 +14,87 @@ __headers: include scripts/Kbuild.include -srcdir := $(srctree)/$(obj) +src := $(srctree)/$(obj) +gen := $(objtree)/$(subst include/,include/generated/,$(obj)) +dst := usr/include -# When make is run under a fakechroot environment, the function -# $(wildcard $(srcdir)/*/.) doesn't only return directories, but also regular -# files. So, we are using a combination of sort/dir/wildcard which works -# with fakechroot. -subdirs := $(patsubst $(srcdir)/%/,%,\ - $(filter-out $(srcdir)/,\ - $(sort $(dir $(wildcard $(srcdir)/*/))))) +-include $(src)/Kbuild -# Recursion -__headers: $(subdirs) +src-subdirs := $(patsubst $(src)/%/,%,$(wildcard $(src)/*/)) +gen-subdirs := $(patsubst $(gen)/%/,%,$(wildcard $(gen)/*/)) +all-subdirs := $(sort $(src-subdirs) $(gen-subdirs)) -PHONY += $(subdirs) -$(subdirs): - $(Q)$(MAKE) $(hdr-inst)=$(obj)/$@ dst=$(dst)/$@ +src-headers := $(if $(src-subdirs), $(shell cd $(src) && find $(src-subdirs) -name '*.h')) +src-headers := $(filter-out $(no-export-headers), $(src-headers)) +gen-headers := $(if $(gen-subdirs), $(shell cd $(gen) && find $(gen-subdirs) -name '*.h')) +gen-headers := $(filter-out $(no-export-headers), $(gen-headers)) -# Skip header install/check for include/uapi and arch/$(SRCARCH)/include/uapi. -# We have only sub-directories there. -skip-inst := $(if $(filter %/uapi,$(obj)),1) +# If the same header is exported from source and generated directories, +# the former takes precedence, but this should be warned. +duplicated := $(filter $(gen-headers), $(src-headers)) +$(if $(duplicated), $(warning duplicated header export: $(duplicated))) -ifeq ($(skip-inst),) +gen-headers := $(filter-out $(duplicated), $(gen-headers)) -# Kbuild file is optional -kbuild-file := $(srctree)/$(obj)/Kbuild --include $(kbuild-file) +# Add dst path prefix +all-subdirs := $(addprefix $(dst)/, $(all-subdirs)) +src-headers := $(addprefix $(dst)/, $(src-headers)) +gen-headers := $(addprefix $(dst)/, $(gen-headers)) +all-headers := $(src-headers) $(gen-headers) -installdir := usr/$(dst) -gendir := $(objtree)/$(subst include/,include/generated/,$(obj)) -header-files := $(notdir $(wildcard $(srcdir)/*.h)) -header-files := $(filter-out $(no-export-headers), $(header-files)) -genhdr-files := $(notdir $(wildcard $(gendir)/*.h)) -genhdr-files := $(filter-out $(header-files), $(genhdr-files)) +# Work out what needs to be removed +old-subdirs := $(wildcard $(all-subdirs)) +old-headers := $(if $(old-subdirs),$(shell find $(old-subdirs) -name '*.h')) +unwanted := $(filter-out $(all-headers), $(old-headers)) -# files used to track state of install/check -install-file := $(installdir)/.install -check-file := $(installdir)/.check +# Create directories +existing-dirs := $(sort $(dir $(old-headers))) +wanted-dirs := $(sort $(dir $(all-headers))) +new-dirs := $(filter-out $(existing-dirs), $(wanted-dirs)) +$(if $(new-dirs), $(shell mkdir -p $(new-dirs))) -# all headers files for this dir -all-files := $(header-files) $(genhdr-files) -output-files := $(addprefix $(installdir)/, $(all-files)) +# Rules -# Work out what needs to be removed -oldheaders := $(patsubst $(installdir)/%,%,$(wildcard $(installdir)/*.h)) -unwanted := $(filter-out $(all-files),$(oldheaders)) +ifndef HDRCHECK -# Prefix unwanted with full paths to objtree -unwanted-file := $(addprefix $(installdir)/, $(unwanted)) +quiet_cmd_install = HDRINST $@ + cmd_install = $(CONFIG_SHELL) $(srctree)/scripts/headers_install.sh $(@D) $( Date: Tue, 4 Jun 2019 19:14:04 +0900 Subject: kbuild: move hdr-inst shorthand to top Makefile Now that hdr-inst is used only in the top Makefile, move it there from scripts/Kbuild.include. Signed-off-by: Masahiro Yamada --- Makefile | 2 ++ scripts/Kbuild.include | 6 ------ 2 files changed, 2 insertions(+), 6 deletions(-) (limited to 'scripts') diff --git a/Makefile b/Makefile index 507ce2c92065..e124a3e73bfe 100644 --- a/Makefile +++ b/Makefile @@ -1190,6 +1190,8 @@ headers_install: headers PHONY += archheaders archscripts +hdr-inst := -f $(srctree)/scripts/Makefile.headersinst obj + PHONY += headers headers: $(version_h) scripts_unifdef uapi-asm-generic archheaders archscripts $(if $(wildcard $(srctree)/arch/$(SRCARCH)/include/uapi/asm/Kbuild),, \ diff --git a/scripts/Kbuild.include b/scripts/Kbuild.include index f641bb0aa63f..0ae07e83d393 100644 --- a/scripts/Kbuild.include +++ b/scripts/Kbuild.include @@ -187,12 +187,6 @@ dtbinst := -f $(srctree)/scripts/Makefile.dtbinst obj # $(Q)$(MAKE) $(clean)=dir clean := -f $(srctree)/scripts/Makefile.clean obj -### -# Shorthand for $(Q)$(MAKE) -f scripts/Makefile.headersinst obj= -# Usage: -# $(Q)$(MAKE) $(hdr-inst)=dir -hdr-inst := -f $(srctree)/scripts/Makefile.headersinst obj - # echo command. # Short version is used, if $(quiet) equals `quiet_', otherwise full one. echo-cmd = $(if $($(quiet)cmd_$(1)),\ -- cgit v1.2.3 From 555187a8791d492bed4dc57aae93b47162f6398d Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Tue, 4 Jun 2019 19:14:05 +0900 Subject: kbuild: simplify scripts/headers_install.sh Now that headers_install.sh is invoked per file, remove the for-loop in the shell script. Signed-off-by: Masahiro Yamada --- scripts/Makefile.headersinst | 2 +- scripts/headers_install.sh | 48 ++++++++++++++++++-------------------------- 2 files changed, 21 insertions(+), 29 deletions(-) (limited to 'scripts') diff --git a/scripts/Makefile.headersinst b/scripts/Makefile.headersinst index c96c4c26e240..d2b572a7a628 100644 --- a/scripts/Makefile.headersinst +++ b/scripts/Makefile.headersinst @@ -58,7 +58,7 @@ $(if $(new-dirs), $(shell mkdir -p $(new-dirs))) ifndef HDRCHECK quiet_cmd_install = HDRINST $@ - cmd_install = $(CONFIG_SHELL) $(srctree)/scripts/headers_install.sh $(@D) $(@@ + s/(^|[^a-zA-Z0-9])__packed([^a-zA-Z0-9_]|$)/\1__attribute__((packed))\2/g + s/(^|[[:space:](])(inline|asm|volatile)([[:space:](]|$)/\1__\2__\3/g + s@#(ifndef|define|endif[[:space:]]*/[*])[[:space:]]*_UAPI@#\1 @ +' $INFILE > $TMPFILE || exit 1 -FILE= -trap 'rm -f "$OUTDIR/$FILE" "$OUTDIR/$FILE.sed"' EXIT -for i in "$@" -do - FILE="$(basename "$i")" - sed -E \ - -e 's/([[:space:](])(__user|__force|__iomem)[[:space:]]/\1/g' \ - -e 's/__attribute_const__([[:space:]]|$)/\1/g' \ - -e 's@^#include @@' \ - -e 's/(^|[^a-zA-Z0-9])__packed([^a-zA-Z0-9_]|$)/\1__attribute__((packed))\2/g' \ - -e 's/(^|[[:space:](])(inline|asm|volatile)([[:space:](]|$)/\1__\2__\3/g' \ - -e 's@#(ifndef|define|endif[[:space:]]*/[*])[[:space:]]*_UAPI@#\1 @' \ - "$SRCDIR/$i" > "$OUTDIR/$FILE.sed" || exit 1 - scripts/unifdef -U__KERNEL__ -D__EXPORTED_HEADERS__ "$OUTDIR/$FILE.sed" \ - > "$OUTDIR/$FILE" - [ $? -gt 1 ] && exit 1 - rm -f "$OUTDIR/$FILE.sed" -done +scripts/unifdef -U__KERNEL__ -D__EXPORTED_HEADERS__ $TMPFILE > $OUTFILE +[ $? -gt 1 ] && exit 1 + +rm -f $TMPFILE trap - EXIT -- cgit v1.2.3 From 0315bb7a25267bfeee2a7aaed5d1b4ba915e0c53 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Tue, 4 Jun 2019 19:14:06 +0900 Subject: kbuild: deb-pkg: do not run headers_check It is absolutely fine to add extra sanity checks in package scripts, but it is not necessary to do so. This is already covered by the daily compile-testing (0day bot etc.) because headers_check is run as a part of the normal build process when CONFIG_HEADERS_CHECK=y. Replace it with the newly-added "make headers". Signed-off-by: Masahiro Yamada --- scripts/package/builddeb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/package/builddeb b/scripts/package/builddeb index b03dd56a4782..e8ca6dc97e96 100755 --- a/scripts/package/builddeb +++ b/scripts/package/builddeb @@ -130,7 +130,7 @@ if is_enabled CONFIG_MODULES; then fi if [ "$ARCH" != "um" ]; then - $MAKE -f $srctree/Makefile headers_check + $MAKE -f $srctree/Makefile headers $MAKE -f $srctree/Makefile headers_install INSTALL_HDR_PATH="$libc_headers_dir/usr" fi -- cgit v1.2.3 From e846f0dc57f441e5e93194d39bc9b8ac2ab5e0a4 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Tue, 4 Jun 2019 15:42:48 +0300 Subject: kbuild: add support for ensuring headers are self-contained Sometimes it's useful to be able to explicitly ensure certain headers remain self-contained, i.e. that they are compilable as standalone units, by including and/or forward declaring everything they depend on. Add special target header-test-y where individual Makefiles can add headers to be tested if CONFIG_HEADER_TEST is enabled. This will generate a dummy C file per header that gets built as part of extra-y. Signed-off-by: Jani Nikula Reviewed-by: Sam Ravnborg Signed-off-by: Masahiro Yamada --- .gitignore | 1 + Documentation/dontdiff | 1 + Documentation/kbuild/makefiles.txt | 7 +++++++ Makefile | 1 + drivers/gpu/drm/i915/.gitignore | 1 - drivers/gpu/drm/i915/Makefile.header-test | 12 +----------- init/Kconfig | 9 +++++++++ scripts/Makefile.build | 9 +++++++++ scripts/Makefile.lib | 3 +++ 9 files changed, 32 insertions(+), 12 deletions(-) delete mode 100644 drivers/gpu/drm/i915/.gitignore (limited to 'scripts') diff --git a/.gitignore b/.gitignore index 7587ef56b92d..4bb60f0fa23b 100644 --- a/.gitignore +++ b/.gitignore @@ -22,6 +22,7 @@ *.elf *.gcno *.gz +*.hdrtest.c *.i *.ko *.lex.c diff --git a/Documentation/dontdiff b/Documentation/dontdiff index 5eba889ea84d..554dfe4883d2 100644 --- a/Documentation/dontdiff +++ b/Documentation/dontdiff @@ -19,6 +19,7 @@ *.grep *.grp *.gz +*.hdrtest.c *.html *.i *.jpeg diff --git a/Documentation/kbuild/makefiles.txt b/Documentation/kbuild/makefiles.txt index bac301a73a86..ca4b24ec0399 100644 --- a/Documentation/kbuild/makefiles.txt +++ b/Documentation/kbuild/makefiles.txt @@ -1018,6 +1018,13 @@ When kbuild executes, the following steps are followed (roughly): In this example, extra-y is used to list object files that shall be built, but shall not be linked as part of built-in.a. + header-test-y + + header-test-y specifies headers (*.h) in the current directory that + should be compile tested to ensure they are self-contained, + i.e. compilable as standalone units. If CONFIG_HEADER_TEST is enabled, + this autogenerates dummy sources to include the headers, and builds them + as part of extra-y. --- 6.7 Commands useful for building a boot image diff --git a/Makefile b/Makefile index e124a3e73bfe..aefdb5661382 100644 --- a/Makefile +++ b/Makefile @@ -1647,6 +1647,7 @@ clean: $(clean-dirs) -o -name '*.dwo' -o -name '*.lst' \ -o -name '*.su' \ -o -name '.*.d' -o -name '.*.tmp' -o -name '*.mod.c' \ + -o -name '*.hdrtest.c' \ -o -name '*.lex.c' -o -name '*.tab.[ch]' \ -o -name '*.asn1.[ch]' \ -o -name '*.symtypes' -o -name 'modules.order' \ diff --git a/drivers/gpu/drm/i915/.gitignore b/drivers/gpu/drm/i915/.gitignore deleted file mode 100644 index cff45d81f42f..000000000000 --- a/drivers/gpu/drm/i915/.gitignore +++ /dev/null @@ -1 +0,0 @@ -header_test_*.c diff --git a/drivers/gpu/drm/i915/Makefile.header-test b/drivers/gpu/drm/i915/Makefile.header-test index c1c391816fa7..639b596a06a9 100644 --- a/drivers/gpu/drm/i915/Makefile.header-test +++ b/drivers/gpu/drm/i915/Makefile.header-test @@ -2,7 +2,7 @@ # Copyright © 2019 Intel Corporation # Test the headers are compilable as standalone units -header_test := \ +header-test-$(CONFIG_DRM_I915_WERROR) := \ i915_active_types.h \ i915_gem_context_types.h \ i915_priolist_types.h \ @@ -35,13 +35,3 @@ header_test := \ intel_sprite.h \ intel_tv.h \ intel_workarounds_types.h - -quiet_cmd_header_test = HDRTEST $@ - cmd_header_test = echo "\#include \"$( $@ - -header_test_%.c: %.h - $(call cmd,header_test) - -i915-$(CONFIG_DRM_I915_WERROR) += $(foreach h,$(header_test),$(patsubst %.h,header_test_%.o,$(h))) - -clean-files += $(foreach h,$(header_test),$(patsubst %.h,header_test_%.c,$(h))) diff --git a/init/Kconfig b/init/Kconfig index 0e2344389501..df5bba27e3fe 100644 --- a/init/Kconfig +++ b/init/Kconfig @@ -96,6 +96,15 @@ config COMPILE_TEST here. If you are a user/distributor, say N here to exclude useless drivers to be distributed. +config HEADER_TEST + bool "Compile test headers that should be standalone compilable" + help + Compile test headers listed in header-test-y target to ensure they are + self-contained, i.e. compilable as standalone units. + + If you are a developer or tester and want to ensure the requested + headers are self-contained, say Y here. Otherwise, choose N. + config LOCALVERSION string "Local version - append to kernel release" help diff --git a/scripts/Makefile.build b/scripts/Makefile.build index ae9cf740633e..ee0319560513 100644 --- a/scripts/Makefile.build +++ b/scripts/Makefile.build @@ -294,6 +294,15 @@ quiet_cmd_cc_lst_c = MKLST $@ $(obj)/%.lst: $(src)/%.c FORCE $(call if_changed_dep,cc_lst_c) +# Dummy C sources for header test (header-test-y target) +# --------------------------------------------------------------------------- + +quiet_cmd_header_test = HDRTEST $@ + cmd_header_test = echo "\#include \"$*.h\"" > $@ + +$(obj)/%.hdrtest.c: + $(call cmd,header_test) + # Compile assembler sources (.S) # --------------------------------------------------------------------------- diff --git a/scripts/Makefile.lib b/scripts/Makefile.lib index f1f38c8cdc74..3e630fcaffd1 100644 --- a/scripts/Makefile.lib +++ b/scripts/Makefile.lib @@ -66,6 +66,9 @@ extra-y += $(patsubst %.dtb,%.dt.yaml, $(dtb-y)) extra-$(CONFIG_OF_ALL_DTBS) += $(patsubst %.dtb,%.dt.yaml, $(dtb-)) endif +# Test self-contained headers +extra-$(CONFIG_HEADER_TEST) += $(patsubst %.h,%.hdrtest.o,$(header-test-y)) + # Add subdir path extra-y := $(addprefix $(obj)/,$(extra-y)) -- cgit v1.2.3 From 4489f161b739f01ab60a58784f6ef7de9d7a1352 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 18 Jun 2019 17:53:27 -0300 Subject: docs: driver-model: convert docs to ReST and rename to *.rst Convert the various documents at the driver-model, preparing them to be part of the driver-api book. The conversion is actually: - add blank lines and identation in order to identify paragraphs; - fix tables markups; - add some lists markups; - mark literal blocks; - adjust title markups. At its new index.rst, let's add a :orphan: while this is not linked to the main index.rst file, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab Acked-by: Jeff Kirsher # ice Signed-off-by: Greg Kroah-Hartman --- Documentation/driver-api/gpio/driver.rst | 2 +- Documentation/driver-model/binding.rst | 98 ++++++ Documentation/driver-model/binding.txt | 98 ------ Documentation/driver-model/bus.rst | 146 ++++++++ Documentation/driver-model/bus.txt | 143 -------- Documentation/driver-model/class.rst | 149 ++++++++ Documentation/driver-model/class.txt | 147 -------- Documentation/driver-model/design-patterns.rst | 116 +++++++ Documentation/driver-model/design-patterns.txt | 116 ------- Documentation/driver-model/device.rst | 109 ++++++ Documentation/driver-model/device.txt | 106 ------ Documentation/driver-model/devres.rst | 414 +++++++++++++++++++++++ Documentation/driver-model/devres.txt | 412 ----------------------- Documentation/driver-model/driver.rst | 223 ++++++++++++ Documentation/driver-model/driver.txt | 215 ------------ Documentation/driver-model/index.rst | 26 ++ Documentation/driver-model/overview.rst | 124 +++++++ Documentation/driver-model/overview.txt | 123 ------- Documentation/driver-model/platform.rst | 246 ++++++++++++++ Documentation/driver-model/platform.txt | 244 -------------- Documentation/driver-model/porting.rst | 448 +++++++++++++++++++++++++ Documentation/driver-model/porting.txt | 447 ------------------------ Documentation/eisa.txt | 4 +- Documentation/hwmon/submitting-patches.rst | 2 +- drivers/base/platform.c | 2 +- drivers/gpio/gpio-cs5535.c | 2 +- drivers/net/ethernet/intel/ice/ice_main.c | 2 +- scripts/coccinelle/free/devm_free.cocci | 2 +- 28 files changed, 2107 insertions(+), 2059 deletions(-) create mode 100644 Documentation/driver-model/binding.rst delete mode 100644 Documentation/driver-model/binding.txt create mode 100644 Documentation/driver-model/bus.rst delete mode 100644 Documentation/driver-model/bus.txt create mode 100644 Documentation/driver-model/class.rst delete mode 100644 Documentation/driver-model/class.txt create mode 100644 Documentation/driver-model/design-patterns.rst delete mode 100644 Documentation/driver-model/design-patterns.txt create mode 100644 Documentation/driver-model/device.rst delete mode 100644 Documentation/driver-model/device.txt create mode 100644 Documentation/driver-model/devres.rst delete mode 100644 Documentation/driver-model/devres.txt create mode 100644 Documentation/driver-model/driver.rst delete mode 100644 Documentation/driver-model/driver.txt create mode 100644 Documentation/driver-model/index.rst create mode 100644 Documentation/driver-model/overview.rst delete mode 100644 Documentation/driver-model/overview.txt create mode 100644 Documentation/driver-model/platform.rst delete mode 100644 Documentation/driver-model/platform.txt create mode 100644 Documentation/driver-model/porting.rst delete mode 100644 Documentation/driver-model/porting.txt (limited to 'scripts') diff --git a/Documentation/driver-api/gpio/driver.rst b/Documentation/driver-api/gpio/driver.rst index 1ce7fcd0f989..f931597fe7be 100644 --- a/Documentation/driver-api/gpio/driver.rst +++ b/Documentation/driver-api/gpio/driver.rst @@ -399,7 +399,7 @@ symbol: will pass the struct gpio_chip* for the chip to all IRQ callbacks, so the callbacks need to embed the gpio_chip in its state container and obtain a pointer to the container using container_of(). - (See Documentation/driver-model/design-patterns.txt) + (See Documentation/driver-model/design-patterns.rst) - gpiochip_irqchip_add_nested(): adds a nested cascaded irqchip to a gpiochip, as discussed above regarding different types of cascaded irqchips. The diff --git a/Documentation/driver-model/binding.rst b/Documentation/driver-model/binding.rst new file mode 100644 index 000000000000..7ea1d7a41e1d --- /dev/null +++ b/Documentation/driver-model/binding.rst @@ -0,0 +1,98 @@ +============== +Driver Binding +============== + +Driver binding is the process of associating a device with a device +driver that can control it. Bus drivers have typically handled this +because there have been bus-specific structures to represent the +devices and the drivers. With generic device and device driver +structures, most of the binding can take place using common code. + + +Bus +~~~ + +The bus type structure contains a list of all devices that are on that bus +type in the system. When device_register is called for a device, it is +inserted into the end of this list. The bus object also contains a +list of all drivers of that bus type. When driver_register is called +for a driver, it is inserted at the end of this list. These are the +two events which trigger driver binding. + + +device_register +~~~~~~~~~~~~~~~ + +When a new device is added, the bus's list of drivers is iterated over +to find one that supports it. In order to determine that, the device +ID of the device must match one of the device IDs that the driver +supports. The format and semantics for comparing IDs is bus-specific. +Instead of trying to derive a complex state machine and matching +algorithm, it is up to the bus driver to provide a callback to compare +a device against the IDs of a driver. The bus returns 1 if a match was +found; 0 otherwise. + +int match(struct device * dev, struct device_driver * drv); + +If a match is found, the device's driver field is set to the driver +and the driver's probe callback is called. This gives the driver a +chance to verify that it really does support the hardware, and that +it's in a working state. + +Device Class +~~~~~~~~~~~~ + +Upon the successful completion of probe, the device is registered with +the class to which it belongs. Device drivers belong to one and only one +class, and that is set in the driver's devclass field. +devclass_add_device is called to enumerate the device within the class +and actually register it with the class, which happens with the +class's register_dev callback. + + +Driver +~~~~~~ + +When a driver is attached to a device, the device is inserted into the +driver's list of devices. + + +sysfs +~~~~~ + +A symlink is created in the bus's 'devices' directory that points to +the device's directory in the physical hierarchy. + +A symlink is created in the driver's 'devices' directory that points +to the device's directory in the physical hierarchy. + +A directory for the device is created in the class's directory. A +symlink is created in that directory that points to the device's +physical location in the sysfs tree. + +A symlink can be created (though this isn't done yet) in the device's +physical directory to either its class directory, or the class's +top-level directory. One can also be created to point to its driver's +directory also. + + +driver_register +~~~~~~~~~~~~~~~ + +The process is almost identical for when a new driver is added. +The bus's list of devices is iterated over to find a match. Devices +that already have a driver are skipped. All the devices are iterated +over, to bind as many devices as possible to the driver. + + +Removal +~~~~~~~ + +When a device is removed, the reference count for it will eventually +go to 0. When it does, the remove callback of the driver is called. It +is removed from the driver's list of devices and the reference count +of the driver is decremented. All symlinks between the two are removed. + +When a driver is removed, the list of devices that it supports is +iterated over, and the driver's remove callback is called for each +one. The device is removed from that list and the symlinks removed. diff --git a/Documentation/driver-model/binding.txt b/Documentation/driver-model/binding.txt deleted file mode 100644 index abfc8e290d53..000000000000 --- a/Documentation/driver-model/binding.txt +++ /dev/null @@ -1,98 +0,0 @@ - -Driver Binding - -Driver binding is the process of associating a device with a device -driver that can control it. Bus drivers have typically handled this -because there have been bus-specific structures to represent the -devices and the drivers. With generic device and device driver -structures, most of the binding can take place using common code. - - -Bus -~~~ - -The bus type structure contains a list of all devices that are on that bus -type in the system. When device_register is called for a device, it is -inserted into the end of this list. The bus object also contains a -list of all drivers of that bus type. When driver_register is called -for a driver, it is inserted at the end of this list. These are the -two events which trigger driver binding. - - -device_register -~~~~~~~~~~~~~~~ - -When a new device is added, the bus's list of drivers is iterated over -to find one that supports it. In order to determine that, the device -ID of the device must match one of the device IDs that the driver -supports. The format and semantics for comparing IDs is bus-specific. -Instead of trying to derive a complex state machine and matching -algorithm, it is up to the bus driver to provide a callback to compare -a device against the IDs of a driver. The bus returns 1 if a match was -found; 0 otherwise. - -int match(struct device * dev, struct device_driver * drv); - -If a match is found, the device's driver field is set to the driver -and the driver's probe callback is called. This gives the driver a -chance to verify that it really does support the hardware, and that -it's in a working state. - -Device Class -~~~~~~~~~~~~ - -Upon the successful completion of probe, the device is registered with -the class to which it belongs. Device drivers belong to one and only one -class, and that is set in the driver's devclass field. -devclass_add_device is called to enumerate the device within the class -and actually register it with the class, which happens with the -class's register_dev callback. - - -Driver -~~~~~~ - -When a driver is attached to a device, the device is inserted into the -driver's list of devices. - - -sysfs -~~~~~ - -A symlink is created in the bus's 'devices' directory that points to -the device's directory in the physical hierarchy. - -A symlink is created in the driver's 'devices' directory that points -to the device's directory in the physical hierarchy. - -A directory for the device is created in the class's directory. A -symlink is created in that directory that points to the device's -physical location in the sysfs tree. - -A symlink can be created (though this isn't done yet) in the device's -physical directory to either its class directory, or the class's -top-level directory. One can also be created to point to its driver's -directory also. - - -driver_register -~~~~~~~~~~~~~~~ - -The process is almost identical for when a new driver is added. -The bus's list of devices is iterated over to find a match. Devices -that already have a driver are skipped. All the devices are iterated -over, to bind as many devices as possible to the driver. - - -Removal -~~~~~~~ - -When a device is removed, the reference count for it will eventually -go to 0. When it does, the remove callback of the driver is called. It -is removed from the driver's list of devices and the reference count -of the driver is decremented. All symlinks between the two are removed. - -When a driver is removed, the list of devices that it supports is -iterated over, and the driver's remove callback is called for each -one. The device is removed from that list and the symlinks removed. - diff --git a/Documentation/driver-model/bus.rst b/Documentation/driver-model/bus.rst new file mode 100644 index 000000000000..016b15a6e8ea --- /dev/null +++ b/Documentation/driver-model/bus.rst @@ -0,0 +1,146 @@ +========= +Bus Types +========= + +Definition +~~~~~~~~~~ +See the kerneldoc for the struct bus_type. + +int bus_register(struct bus_type * bus); + + +Declaration +~~~~~~~~~~~ + +Each bus type in the kernel (PCI, USB, etc) should declare one static +object of this type. They must initialize the name field, and may +optionally initialize the match callback:: + + struct bus_type pci_bus_type = { + .name = "pci", + .match = pci_bus_match, + }; + +The structure should be exported to drivers in a header file: + +extern struct bus_type pci_bus_type; + + +Registration +~~~~~~~~~~~~ + +When a bus driver is initialized, it calls bus_register. This +initializes the rest of the fields in the bus object and inserts it +into a global list of bus types. Once the bus object is registered, +the fields in it are usable by the bus driver. + + +Callbacks +~~~~~~~~~ + +match(): Attaching Drivers to Devices +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The format of device ID structures and the semantics for comparing +them are inherently bus-specific. Drivers typically declare an array +of device IDs of devices they support that reside in a bus-specific +driver structure. + +The purpose of the match callback is to give the bus an opportunity to +determine if a particular driver supports a particular device by +comparing the device IDs the driver supports with the device ID of a +particular device, without sacrificing bus-specific functionality or +type-safety. + +When a driver is registered with the bus, the bus's list of devices is +iterated over, and the match callback is called for each device that +does not have a driver associated with it. + + + +Device and Driver Lists +~~~~~~~~~~~~~~~~~~~~~~~ + +The lists of devices and drivers are intended to replace the local +lists that many buses keep. They are lists of struct devices and +struct device_drivers, respectively. Bus drivers are free to use the +lists as they please, but conversion to the bus-specific type may be +necessary. + +The LDM core provides helper functions for iterating over each list:: + + int bus_for_each_dev(struct bus_type * bus, struct device * start, + void * data, + int (*fn)(struct device *, void *)); + + int bus_for_each_drv(struct bus_type * bus, struct device_driver * start, + void * data, int (*fn)(struct device_driver *, void *)); + +These helpers iterate over the respective list, and call the callback +for each device or driver in the list. All list accesses are +synchronized by taking the bus's lock (read currently). The reference +count on each object in the list is incremented before the callback is +called; it is decremented after the next object has been obtained. The +lock is not held when calling the callback. + + +sysfs +~~~~~~~~ +There is a top-level directory named 'bus'. + +Each bus gets a directory in the bus directory, along with two default +directories:: + + /sys/bus/pci/ + |-- devices + `-- drivers + +Drivers registered with the bus get a directory in the bus's drivers +directory:: + + /sys/bus/pci/ + |-- devices + `-- drivers + |-- Intel ICH + |-- Intel ICH Joystick + |-- agpgart + `-- e100 + +Each device that is discovered on a bus of that type gets a symlink in +the bus's devices directory to the device's directory in the physical +hierarchy:: + + /sys/bus/pci/ + |-- devices + | |-- 00:00.0 -> ../../../root/pci0/00:00.0 + | |-- 00:01.0 -> ../../../root/pci0/00:01.0 + | `-- 00:02.0 -> ../../../root/pci0/00:02.0 + `-- drivers + + +Exporting Attributes +~~~~~~~~~~~~~~~~~~~~ + +:: + + struct bus_attribute { + struct attribute attr; + ssize_t (*show)(struct bus_type *, char * buf); + ssize_t (*store)(struct bus_type *, const char * buf, size_t count); + }; + +Bus drivers can export attributes using the BUS_ATTR_RW macro that works +similarly to the DEVICE_ATTR_RW macro for devices. For example, a +definition like this:: + + static BUS_ATTR_RW(debug); + +is equivalent to declaring:: + + static bus_attribute bus_attr_debug; + +This can then be used to add and remove the attribute from the bus's +sysfs directory using:: + + int bus_create_file(struct bus_type *, struct bus_attribute *); + void bus_remove_file(struct bus_type *, struct bus_attribute *); diff --git a/Documentation/driver-model/bus.txt b/Documentation/driver-model/bus.txt deleted file mode 100644 index c247b488a567..000000000000 --- a/Documentation/driver-model/bus.txt +++ /dev/null @@ -1,143 +0,0 @@ - -Bus Types - -Definition -~~~~~~~~~~ -See the kerneldoc for the struct bus_type. - -int bus_register(struct bus_type * bus); - - -Declaration -~~~~~~~~~~~ - -Each bus type in the kernel (PCI, USB, etc) should declare one static -object of this type. They must initialize the name field, and may -optionally initialize the match callback. - -struct bus_type pci_bus_type = { - .name = "pci", - .match = pci_bus_match, -}; - -The structure should be exported to drivers in a header file: - -extern struct bus_type pci_bus_type; - - -Registration -~~~~~~~~~~~~ - -When a bus driver is initialized, it calls bus_register. This -initializes the rest of the fields in the bus object and inserts it -into a global list of bus types. Once the bus object is registered, -the fields in it are usable by the bus driver. - - -Callbacks -~~~~~~~~~ - -match(): Attaching Drivers to Devices -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The format of device ID structures and the semantics for comparing -them are inherently bus-specific. Drivers typically declare an array -of device IDs of devices they support that reside in a bus-specific -driver structure. - -The purpose of the match callback is to give the bus an opportunity to -determine if a particular driver supports a particular device by -comparing the device IDs the driver supports with the device ID of a -particular device, without sacrificing bus-specific functionality or -type-safety. - -When a driver is registered with the bus, the bus's list of devices is -iterated over, and the match callback is called for each device that -does not have a driver associated with it. - - - -Device and Driver Lists -~~~~~~~~~~~~~~~~~~~~~~~ - -The lists of devices and drivers are intended to replace the local -lists that many buses keep. They are lists of struct devices and -struct device_drivers, respectively. Bus drivers are free to use the -lists as they please, but conversion to the bus-specific type may be -necessary. - -The LDM core provides helper functions for iterating over each list. - -int bus_for_each_dev(struct bus_type * bus, struct device * start, void * data, - int (*fn)(struct device *, void *)); - -int bus_for_each_drv(struct bus_type * bus, struct device_driver * start, - void * data, int (*fn)(struct device_driver *, void *)); - -These helpers iterate over the respective list, and call the callback -for each device or driver in the list. All list accesses are -synchronized by taking the bus's lock (read currently). The reference -count on each object in the list is incremented before the callback is -called; it is decremented after the next object has been obtained. The -lock is not held when calling the callback. - - -sysfs -~~~~~~~~ -There is a top-level directory named 'bus'. - -Each bus gets a directory in the bus directory, along with two default -directories: - - /sys/bus/pci/ - |-- devices - `-- drivers - -Drivers registered with the bus get a directory in the bus's drivers -directory: - - /sys/bus/pci/ - |-- devices - `-- drivers - |-- Intel ICH - |-- Intel ICH Joystick - |-- agpgart - `-- e100 - -Each device that is discovered on a bus of that type gets a symlink in -the bus's devices directory to the device's directory in the physical -hierarchy: - - /sys/bus/pci/ - |-- devices - | |-- 00:00.0 -> ../../../root/pci0/00:00.0 - | |-- 00:01.0 -> ../../../root/pci0/00:01.0 - | `-- 00:02.0 -> ../../../root/pci0/00:02.0 - `-- drivers - - -Exporting Attributes -~~~~~~~~~~~~~~~~~~~~ -struct bus_attribute { - struct attribute attr; - ssize_t (*show)(struct bus_type *, char * buf); - ssize_t (*store)(struct bus_type *, const char * buf, size_t count); -}; - -Bus drivers can export attributes using the BUS_ATTR_RW macro that works -similarly to the DEVICE_ATTR_RW macro for devices. For example, a -definition like this: - -static BUS_ATTR_RW(debug); - -is equivalent to declaring: - -static bus_attribute bus_attr_debug; - -This can then be used to add and remove the attribute from the bus's -sysfs directory using: - -int bus_create_file(struct bus_type *, struct bus_attribute *); -void bus_remove_file(struct bus_type *, struct bus_attribute *); - - diff --git a/Documentation/driver-model/class.rst b/Documentation/driver-model/class.rst new file mode 100644 index 000000000000..fff55b80e86a --- /dev/null +++ b/Documentation/driver-model/class.rst @@ -0,0 +1,149 @@ +============== +Device Classes +============== + +Introduction +~~~~~~~~~~~~ +A device class describes a type of device, like an audio or network +device. The following device classes have been identified: + + + + +Each device class defines a set of semantics and a programming interface +that devices of that class adhere to. Device drivers are the +implementation of that programming interface for a particular device on +a particular bus. + +Device classes are agnostic with respect to what bus a device resides +on. + + +Programming Interface +~~~~~~~~~~~~~~~~~~~~~ +The device class structure looks like:: + + + typedef int (*devclass_add)(struct device *); + typedef void (*devclass_remove)(struct device *); + +See the kerneldoc for the struct class. + +A typical device class definition would look like:: + + struct device_class input_devclass = { + .name = "input", + .add_device = input_add_device, + .remove_device = input_remove_device, + }; + +Each device class structure should be exported in a header file so it +can be used by drivers, extensions and interfaces. + +Device classes are registered and unregistered with the core using:: + + int devclass_register(struct device_class * cls); + void devclass_unregister(struct device_class * cls); + + +Devices +~~~~~~~ +As devices are bound to drivers, they are added to the device class +that the driver belongs to. Before the driver model core, this would +typically happen during the driver's probe() callback, once the device +has been initialized. It now happens after the probe() callback +finishes from the core. + +The device is enumerated in the class. Each time a device is added to +the class, the class's devnum field is incremented and assigned to the +device. The field is never decremented, so if the device is removed +from the class and re-added, it will receive a different enumerated +value. + +The class is allowed to create a class-specific structure for the +device and store it in the device's class_data pointer. + +There is no list of devices in the device class. Each driver has a +list of devices that it supports. The device class has a list of +drivers of that particular class. To access all of the devices in the +class, iterate over the device lists of each driver in the class. + + +Device Drivers +~~~~~~~~~~~~~~ +Device drivers are added to device classes when they are registered +with the core. A driver specifies the class it belongs to by setting +the struct device_driver::devclass field. + + +sysfs directory structure +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +There is a top-level sysfs directory named 'class'. + +Each class gets a directory in the class directory, along with two +default subdirectories:: + + class/ + `-- input + |-- devices + `-- drivers + + +Drivers registered with the class get a symlink in the drivers/ directory +that points to the driver's directory (under its bus directory):: + + class/ + `-- input + |-- devices + `-- drivers + `-- usb:usb_mouse -> ../../../bus/drivers/usb_mouse/ + + +Each device gets a symlink in the devices/ directory that points to the +device's directory in the physical hierarchy:: + + class/ + `-- input + |-- devices + | `-- 1 -> ../../../root/pci0/00:1f.0/usb_bus/00:1f.2-1:0/ + `-- drivers + + +Exporting Attributes +~~~~~~~~~~~~~~~~~~~~ + +:: + + struct devclass_attribute { + struct attribute attr; + ssize_t (*show)(struct device_class *, char * buf, size_t count, loff_t off); + ssize_t (*store)(struct device_class *, const char * buf, size_t count, loff_t off); + }; + +Class drivers can export attributes using the DEVCLASS_ATTR macro that works +similarly to the DEVICE_ATTR macro for devices. For example, a definition +like this:: + + static DEVCLASS_ATTR(debug,0644,show_debug,store_debug); + +is equivalent to declaring:: + + static devclass_attribute devclass_attr_debug; + +The bus driver can add and remove the attribute from the class's +sysfs directory using:: + + int devclass_create_file(struct device_class *, struct devclass_attribute *); + void devclass_remove_file(struct device_class *, struct devclass_attribute *); + +In the example above, the file will be named 'debug' in placed in the +class's directory in sysfs. + + +Interfaces +~~~~~~~~~~ +There may exist multiple mechanisms for accessing the same device of a +particular class type. Device interfaces describe these mechanisms. + +When a device is added to a device class, the core attempts to add it +to every interface that is registered with the device class. diff --git a/Documentation/driver-model/class.txt b/Documentation/driver-model/class.txt deleted file mode 100644 index 1fefc480a80b..000000000000 --- a/Documentation/driver-model/class.txt +++ /dev/null @@ -1,147 +0,0 @@ - -Device Classes - - -Introduction -~~~~~~~~~~~~ -A device class describes a type of device, like an audio or network -device. The following device classes have been identified: - - - - -Each device class defines a set of semantics and a programming interface -that devices of that class adhere to. Device drivers are the -implementation of that programming interface for a particular device on -a particular bus. - -Device classes are agnostic with respect to what bus a device resides -on. - - -Programming Interface -~~~~~~~~~~~~~~~~~~~~~ -The device class structure looks like: - - -typedef int (*devclass_add)(struct device *); -typedef void (*devclass_remove)(struct device *); - -See the kerneldoc for the struct class. - -A typical device class definition would look like: - -struct device_class input_devclass = { - .name = "input", - .add_device = input_add_device, - .remove_device = input_remove_device, -}; - -Each device class structure should be exported in a header file so it -can be used by drivers, extensions and interfaces. - -Device classes are registered and unregistered with the core using: - -int devclass_register(struct device_class * cls); -void devclass_unregister(struct device_class * cls); - - -Devices -~~~~~~~ -As devices are bound to drivers, they are added to the device class -that the driver belongs to. Before the driver model core, this would -typically happen during the driver's probe() callback, once the device -has been initialized. It now happens after the probe() callback -finishes from the core. - -The device is enumerated in the class. Each time a device is added to -the class, the class's devnum field is incremented and assigned to the -device. The field is never decremented, so if the device is removed -from the class and re-added, it will receive a different enumerated -value. - -The class is allowed to create a class-specific structure for the -device and store it in the device's class_data pointer. - -There is no list of devices in the device class. Each driver has a -list of devices that it supports. The device class has a list of -drivers of that particular class. To access all of the devices in the -class, iterate over the device lists of each driver in the class. - - -Device Drivers -~~~~~~~~~~~~~~ -Device drivers are added to device classes when they are registered -with the core. A driver specifies the class it belongs to by setting -the struct device_driver::devclass field. - - -sysfs directory structure -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -There is a top-level sysfs directory named 'class'. - -Each class gets a directory in the class directory, along with two -default subdirectories: - - class/ - `-- input - |-- devices - `-- drivers - - -Drivers registered with the class get a symlink in the drivers/ directory -that points to the driver's directory (under its bus directory): - - class/ - `-- input - |-- devices - `-- drivers - `-- usb:usb_mouse -> ../../../bus/drivers/usb_mouse/ - - -Each device gets a symlink in the devices/ directory that points to the -device's directory in the physical hierarchy: - - class/ - `-- input - |-- devices - | `-- 1 -> ../../../root/pci0/00:1f.0/usb_bus/00:1f.2-1:0/ - `-- drivers - - -Exporting Attributes -~~~~~~~~~~~~~~~~~~~~ -struct devclass_attribute { - struct attribute attr; - ssize_t (*show)(struct device_class *, char * buf, size_t count, loff_t off); - ssize_t (*store)(struct device_class *, const char * buf, size_t count, loff_t off); -}; - -Class drivers can export attributes using the DEVCLASS_ATTR macro that works -similarly to the DEVICE_ATTR macro for devices. For example, a definition -like this: - -static DEVCLASS_ATTR(debug,0644,show_debug,store_debug); - -is equivalent to declaring: - -static devclass_attribute devclass_attr_debug; - -The bus driver can add and remove the attribute from the class's -sysfs directory using: - -int devclass_create_file(struct device_class *, struct devclass_attribute *); -void devclass_remove_file(struct device_class *, struct devclass_attribute *); - -In the example above, the file will be named 'debug' in placed in the -class's directory in sysfs. - - -Interfaces -~~~~~~~~~~ -There may exist multiple mechanisms for accessing the same device of a -particular class type. Device interfaces describe these mechanisms. - -When a device is added to a device class, the core attempts to add it -to every interface that is registered with the device class. - diff --git a/Documentation/driver-model/design-patterns.rst b/Documentation/driver-model/design-patterns.rst new file mode 100644 index 000000000000..41eb8f41f7dd --- /dev/null +++ b/Documentation/driver-model/design-patterns.rst @@ -0,0 +1,116 @@ +============================= +Device Driver Design Patterns +============================= + +This document describes a few common design patterns found in device drivers. +It is likely that subsystem maintainers will ask driver developers to +conform to these design patterns. + +1. State Container +2. container_of() + + +1. State Container +~~~~~~~~~~~~~~~~~~ + +While the kernel contains a few device drivers that assume that they will +only be probed() once on a certain system (singletons), it is custom to assume +that the device the driver binds to will appear in several instances. This +means that the probe() function and all callbacks need to be reentrant. + +The most common way to achieve this is to use the state container design +pattern. It usually has this form:: + + struct foo { + spinlock_t lock; /* Example member */ + (...) + }; + + static int foo_probe(...) + { + struct foo *foo; + + foo = devm_kzalloc(dev, sizeof(*foo), GFP_KERNEL); + if (!foo) + return -ENOMEM; + spin_lock_init(&foo->lock); + (...) + } + +This will create an instance of struct foo in memory every time probe() is +called. This is our state container for this instance of the device driver. +Of course it is then necessary to always pass this instance of the +state around to all functions that need access to the state and its members. + +For example, if the driver is registering an interrupt handler, you would +pass around a pointer to struct foo like this:: + + static irqreturn_t foo_handler(int irq, void *arg) + { + struct foo *foo = arg; + (...) + } + + static int foo_probe(...) + { + struct foo *foo; + + (...) + ret = request_irq(irq, foo_handler, 0, "foo", foo); + } + +This way you always get a pointer back to the correct instance of foo in +your interrupt handler. + + +2. container_of() +~~~~~~~~~~~~~~~~~ + +Continuing on the above example we add an offloaded work:: + + struct foo { + spinlock_t lock; + struct workqueue_struct *wq; + struct work_struct offload; + (...) + }; + + static void foo_work(struct work_struct *work) + { + struct foo *foo = container_of(work, struct foo, offload); + + (...) + } + + static irqreturn_t foo_handler(int irq, void *arg) + { + struct foo *foo = arg; + + queue_work(foo->wq, &foo->offload); + (...) + } + + static int foo_probe(...) + { + struct foo *foo; + + foo->wq = create_singlethread_workqueue("foo-wq"); + INIT_WORK(&foo->offload, foo_work); + (...) + } + +The design pattern is the same for an hrtimer or something similar that will +return a single argument which is a pointer to a struct member in the +callback. + +container_of() is a macro defined in + +What container_of() does is to obtain a pointer to the containing struct from +a pointer to a member by a simple subtraction using the offsetof() macro from +standard C, which allows something similar to object oriented behaviours. +Notice that the contained member must not be a pointer, but an actual member +for this to work. + +We can see here that we avoid having global pointers to our struct foo * +instance this way, while still keeping the number of parameters passed to the +work function to a single pointer. diff --git a/Documentation/driver-model/design-patterns.txt b/Documentation/driver-model/design-patterns.txt deleted file mode 100644 index ba7b2df64904..000000000000 --- a/Documentation/driver-model/design-patterns.txt +++ /dev/null @@ -1,116 +0,0 @@ - -Device Driver Design Patterns -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This document describes a few common design patterns found in device drivers. -It is likely that subsystem maintainers will ask driver developers to -conform to these design patterns. - -1. State Container -2. container_of() - - -1. State Container -~~~~~~~~~~~~~~~~~~ - -While the kernel contains a few device drivers that assume that they will -only be probed() once on a certain system (singletons), it is custom to assume -that the device the driver binds to will appear in several instances. This -means that the probe() function and all callbacks need to be reentrant. - -The most common way to achieve this is to use the state container design -pattern. It usually has this form: - -struct foo { - spinlock_t lock; /* Example member */ - (...) -}; - -static int foo_probe(...) -{ - struct foo *foo; - - foo = devm_kzalloc(dev, sizeof(*foo), GFP_KERNEL); - if (!foo) - return -ENOMEM; - spin_lock_init(&foo->lock); - (...) -} - -This will create an instance of struct foo in memory every time probe() is -called. This is our state container for this instance of the device driver. -Of course it is then necessary to always pass this instance of the -state around to all functions that need access to the state and its members. - -For example, if the driver is registering an interrupt handler, you would -pass around a pointer to struct foo like this: - -static irqreturn_t foo_handler(int irq, void *arg) -{ - struct foo *foo = arg; - (...) -} - -static int foo_probe(...) -{ - struct foo *foo; - - (...) - ret = request_irq(irq, foo_handler, 0, "foo", foo); -} - -This way you always get a pointer back to the correct instance of foo in -your interrupt handler. - - -2. container_of() -~~~~~~~~~~~~~~~~~ - -Continuing on the above example we add an offloaded work: - -struct foo { - spinlock_t lock; - struct workqueue_struct *wq; - struct work_struct offload; - (...) -}; - -static void foo_work(struct work_struct *work) -{ - struct foo *foo = container_of(work, struct foo, offload); - - (...) -} - -static irqreturn_t foo_handler(int irq, void *arg) -{ - struct foo *foo = arg; - - queue_work(foo->wq, &foo->offload); - (...) -} - -static int foo_probe(...) -{ - struct foo *foo; - - foo->wq = create_singlethread_workqueue("foo-wq"); - INIT_WORK(&foo->offload, foo_work); - (...) -} - -The design pattern is the same for an hrtimer or something similar that will -return a single argument which is a pointer to a struct member in the -callback. - -container_of() is a macro defined in - -What container_of() does is to obtain a pointer to the containing struct from -a pointer to a member by a simple subtraction using the offsetof() macro from -standard C, which allows something similar to object oriented behaviours. -Notice that the contained member must not be a pointer, but an actual member -for this to work. - -We can see here that we avoid having global pointers to our struct foo * -instance this way, while still keeping the number of parameters passed to the -work function to a single pointer. diff --git a/Documentation/driver-model/device.rst b/Documentation/driver-model/device.rst new file mode 100644 index 000000000000..2b868d49d349 --- /dev/null +++ b/Documentation/driver-model/device.rst @@ -0,0 +1,109 @@ +========================== +The Basic Device Structure +========================== + +See the kerneldoc for the struct device. + + +Programming Interface +~~~~~~~~~~~~~~~~~~~~~ +The bus driver that discovers the device uses this to register the +device with the core:: + + int device_register(struct device * dev); + +The bus should initialize the following fields: + + - parent + - name + - bus_id + - bus + +A device is removed from the core when its reference count goes to +0. The reference count can be adjusted using:: + + struct device * get_device(struct device * dev); + void put_device(struct device * dev); + +get_device() will return a pointer to the struct device passed to it +if the reference is not already 0 (if it's in the process of being +removed already). + +A driver can access the lock in the device structure using:: + + void lock_device(struct device * dev); + void unlock_device(struct device * dev); + + +Attributes +~~~~~~~~~~ + +:: + + struct device_attribute { + struct attribute attr; + ssize_t (*show)(struct device *dev, struct device_attribute *attr, + char *buf); + ssize_t (*store)(struct device *dev, struct device_attribute *attr, + const char *buf, size_t count); + }; + +Attributes of devices can be exported by a device driver through sysfs. + +Please see Documentation/filesystems/sysfs.txt for more information +on how sysfs works. + +As explained in Documentation/kobject.txt, device attributes must be +created before the KOBJ_ADD uevent is generated. The only way to realize +that is by defining an attribute group. + +Attributes are declared using a macro called DEVICE_ATTR:: + + #define DEVICE_ATTR(name,mode,show,store) + +Example::: + + static DEVICE_ATTR(type, 0444, show_type, NULL); + static DEVICE_ATTR(power, 0644, show_power, store_power); + +This declares two structures of type struct device_attribute with respective +names 'dev_attr_type' and 'dev_attr_power'. These two attributes can be +organized as follows into a group:: + + static struct attribute *dev_attrs[] = { + &dev_attr_type.attr, + &dev_attr_power.attr, + NULL, + }; + + static struct attribute_group dev_attr_group = { + .attrs = dev_attrs, + }; + + static const struct attribute_group *dev_attr_groups[] = { + &dev_attr_group, + NULL, + }; + +This array of groups can then be associated with a device by setting the +group pointer in struct device before device_register() is invoked:: + + dev->groups = dev_attr_groups; + device_register(dev); + +The device_register() function will use the 'groups' pointer to create the +device attributes and the device_unregister() function will use this pointer +to remove the device attributes. + +Word of warning: While the kernel allows device_create_file() and +device_remove_file() to be called on a device at any time, userspace has +strict expectations on when attributes get created. When a new device is +registered in the kernel, a uevent is generated to notify userspace (like +udev) that a new device is available. If attributes are added after the +device is registered, then userspace won't get notified and userspace will +not know about the new attributes. + +This is important for device driver that need to publish additional +attributes for a device at driver probe time. If the device driver simply +calls device_create_file() on the device structure passed to it, then +userspace will never be notified of the new attributes. diff --git a/Documentation/driver-model/device.txt b/Documentation/driver-model/device.txt deleted file mode 100644 index 2403eb856187..000000000000 --- a/Documentation/driver-model/device.txt +++ /dev/null @@ -1,106 +0,0 @@ - -The Basic Device Structure -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -See the kerneldoc for the struct device. - - -Programming Interface -~~~~~~~~~~~~~~~~~~~~~ -The bus driver that discovers the device uses this to register the -device with the core: - -int device_register(struct device * dev); - -The bus should initialize the following fields: - - - parent - - name - - bus_id - - bus - -A device is removed from the core when its reference count goes to -0. The reference count can be adjusted using: - -struct device * get_device(struct device * dev); -void put_device(struct device * dev); - -get_device() will return a pointer to the struct device passed to it -if the reference is not already 0 (if it's in the process of being -removed already). - -A driver can access the lock in the device structure using: - -void lock_device(struct device * dev); -void unlock_device(struct device * dev); - - -Attributes -~~~~~~~~~~ -struct device_attribute { - struct attribute attr; - ssize_t (*show)(struct device *dev, struct device_attribute *attr, - char *buf); - ssize_t (*store)(struct device *dev, struct device_attribute *attr, - const char *buf, size_t count); -}; - -Attributes of devices can be exported by a device driver through sysfs. - -Please see Documentation/filesystems/sysfs.txt for more information -on how sysfs works. - -As explained in Documentation/kobject.txt, device attributes must be -created before the KOBJ_ADD uevent is generated. The only way to realize -that is by defining an attribute group. - -Attributes are declared using a macro called DEVICE_ATTR: - -#define DEVICE_ATTR(name,mode,show,store) - -Example: - -static DEVICE_ATTR(type, 0444, show_type, NULL); -static DEVICE_ATTR(power, 0644, show_power, store_power); - -This declares two structures of type struct device_attribute with respective -names 'dev_attr_type' and 'dev_attr_power'. These two attributes can be -organized as follows into a group: - -static struct attribute *dev_attrs[] = { - &dev_attr_type.attr, - &dev_attr_power.attr, - NULL, -}; - -static struct attribute_group dev_attr_group = { - .attrs = dev_attrs, -}; - -static const struct attribute_group *dev_attr_groups[] = { - &dev_attr_group, - NULL, -}; - -This array of groups can then be associated with a device by setting the -group pointer in struct device before device_register() is invoked: - - dev->groups = dev_attr_groups; - device_register(dev); - -The device_register() function will use the 'groups' pointer to create the -device attributes and the device_unregister() function will use this pointer -to remove the device attributes. - -Word of warning: While the kernel allows device_create_file() and -device_remove_file() to be called on a device at any time, userspace has -strict expectations on when attributes get created. When a new device is -registered in the kernel, a uevent is generated to notify userspace (like -udev) that a new device is available. If attributes are added after the -device is registered, then userspace won't get notified and userspace will -not know about the new attributes. - -This is important for device driver that need to publish additional -attributes for a device at driver probe time. If the device driver simply -calls device_create_file() on the device structure passed to it, then -userspace will never be notified of the new attributes. diff --git a/Documentation/driver-model/devres.rst b/Documentation/driver-model/devres.rst new file mode 100644 index 000000000000..4ac99122b5f1 --- /dev/null +++ b/Documentation/driver-model/devres.rst @@ -0,0 +1,414 @@ +================================ +Devres - Managed Device Resource +================================ + +Tejun Heo + +First draft 10 January 2007 + +.. contents + + 1. Intro : Huh? Devres? + 2. Devres : Devres in a nutshell + 3. Devres Group : Group devres'es and release them together + 4. Details : Life time rules, calling context, ... + 5. Overhead : How much do we have to pay for this? + 6. List of managed interfaces: Currently implemented managed interfaces + + +1. Intro +-------- + +devres came up while trying to convert libata to use iomap. Each +iomapped address should be kept and unmapped on driver detach. For +example, a plain SFF ATA controller (that is, good old PCI IDE) in +native mode makes use of 5 PCI BARs and all of them should be +maintained. + +As with many other device drivers, libata low level drivers have +sufficient bugs in ->remove and ->probe failure path. Well, yes, +that's probably because libata low level driver developers are lazy +bunch, but aren't all low level driver developers? After spending a +day fiddling with braindamaged hardware with no document or +braindamaged document, if it's finally working, well, it's working. + +For one reason or another, low level drivers don't receive as much +attention or testing as core code, and bugs on driver detach or +initialization failure don't happen often enough to be noticeable. +Init failure path is worse because it's much less travelled while +needs to handle multiple entry points. + +So, many low level drivers end up leaking resources on driver detach +and having half broken failure path implementation in ->probe() which +would leak resources or even cause oops when failure occurs. iomap +adds more to this mix. So do msi and msix. + + +2. Devres +--------- + +devres is basically linked list of arbitrarily sized memory areas +associated with a struct device. Each devres entry is associated with +a release function. A devres can be released in several ways. No +matter what, all devres entries are released on driver detach. On +release, the associated release function is invoked and then the +devres entry is freed. + +Managed interface is created for resources commonly used by device +drivers using devres. For example, coherent DMA memory is acquired +using dma_alloc_coherent(). The managed version is called +dmam_alloc_coherent(). It is identical to dma_alloc_coherent() except +for the DMA memory allocated using it is managed and will be +automatically released on driver detach. Implementation looks like +the following:: + + struct dma_devres { + size_t size; + void *vaddr; + dma_addr_t dma_handle; + }; + + static void dmam_coherent_release(struct device *dev, void *res) + { + struct dma_devres *this = res; + + dma_free_coherent(dev, this->size, this->vaddr, this->dma_handle); + } + + dmam_alloc_coherent(dev, size, dma_handle, gfp) + { + struct dma_devres *dr; + void *vaddr; + + dr = devres_alloc(dmam_coherent_release, sizeof(*dr), gfp); + ... + + /* alloc DMA memory as usual */ + vaddr = dma_alloc_coherent(...); + ... + + /* record size, vaddr, dma_handle in dr */ + dr->vaddr = vaddr; + ... + + devres_add(dev, dr); + + return vaddr; + } + +If a driver uses dmam_alloc_coherent(), the area is guaranteed to be +freed whether initialization fails half-way or the device gets +detached. If most resources are acquired using managed interface, a +driver can have much simpler init and exit code. Init path basically +looks like the following:: + + my_init_one() + { + struct mydev *d; + + d = devm_kzalloc(dev, sizeof(*d), GFP_KERNEL); + if (!d) + return -ENOMEM; + + d->ring = dmam_alloc_coherent(...); + if (!d->ring) + return -ENOMEM; + + if (check something) + return -EINVAL; + ... + + return register_to_upper_layer(d); + } + +And exit path:: + + my_remove_one() + { + unregister_from_upper_layer(d); + shutdown_my_hardware(); + } + +As shown above, low level drivers can be simplified a lot by using +devres. Complexity is shifted from less maintained low level drivers +to better maintained higher layer. Also, as init failure path is +shared with exit path, both can get more testing. + +Note though that when converting current calls or assignments to +managed devm_* versions it is up to you to check if internal operations +like allocating memory, have failed. Managed resources pertains to the +freeing of these resources *only* - all other checks needed are still +on you. In some cases this may mean introducing checks that were not +necessary before moving to the managed devm_* calls. + + +3. Devres group +--------------- + +Devres entries can be grouped using devres group. When a group is +released, all contained normal devres entries and properly nested +groups are released. One usage is to rollback series of acquired +resources on failure. For example:: + + if (!devres_open_group(dev, NULL, GFP_KERNEL)) + return -ENOMEM; + + acquire A; + if (failed) + goto err; + + acquire B; + if (failed) + goto err; + ... + + devres_remove_group(dev, NULL); + return 0; + + err: + devres_release_group(dev, NULL); + return err_code; + +As resource acquisition failure usually means probe failure, constructs +like above are usually useful in midlayer driver (e.g. libata core +layer) where interface function shouldn't have side effect on failure. +For LLDs, just returning error code suffices in most cases. + +Each group is identified by `void *id`. It can either be explicitly +specified by @id argument to devres_open_group() or automatically +created by passing NULL as @id as in the above example. In both +cases, devres_open_group() returns the group's id. The returned id +can be passed to other devres functions to select the target group. +If NULL is given to those functions, the latest open group is +selected. + +For example, you can do something like the following:: + + int my_midlayer_create_something() + { + if (!devres_open_group(dev, my_midlayer_create_something, GFP_KERNEL)) + return -ENOMEM; + + ... + + devres_close_group(dev, my_midlayer_create_something); + return 0; + } + + void my_midlayer_destroy_something() + { + devres_release_group(dev, my_midlayer_create_something); + } + + +4. Details +---------- + +Lifetime of a devres entry begins on devres allocation and finishes +when it is released or destroyed (removed and freed) - no reference +counting. + +devres core guarantees atomicity to all basic devres operations and +has support for single-instance devres types (atomic +lookup-and-add-if-not-found). Other than that, synchronizing +concurrent accesses to allocated devres data is caller's +responsibility. This is usually non-issue because bus ops and +resource allocations already do the job. + +For an example of single-instance devres type, read pcim_iomap_table() +in lib/devres.c. + +All devres interface functions can be called without context if the +right gfp mask is given. + + +5. Overhead +----------- + +Each devres bookkeeping info is allocated together with requested data +area. With debug option turned off, bookkeeping info occupies 16 +bytes on 32bit machines and 24 bytes on 64bit (three pointers rounded +up to ull alignment). If singly linked list is used, it can be +reduced to two pointers (8 bytes on 32bit, 16 bytes on 64bit). + +Each devres group occupies 8 pointers. It can be reduced to 6 if +singly linked list is used. + +Memory space overhead on ahci controller with two ports is between 300 +and 400 bytes on 32bit machine after naive conversion (we can +certainly invest a bit more effort into libata core layer). + + +6. List of managed interfaces +----------------------------- + +CLOCK + devm_clk_get() + devm_clk_get_optional() + devm_clk_put() + devm_clk_hw_register() + devm_of_clk_add_hw_provider() + devm_clk_hw_register_clkdev() + +DMA + dmaenginem_async_device_register() + dmam_alloc_coherent() + dmam_alloc_attrs() + dmam_free_coherent() + dmam_pool_create() + dmam_pool_destroy() + +DRM + devm_drm_dev_init() + +GPIO + devm_gpiod_get() + devm_gpiod_get_index() + devm_gpiod_get_index_optional() + devm_gpiod_get_optional() + devm_gpiod_put() + devm_gpiod_unhinge() + devm_gpiochip_add_data() + devm_gpio_request() + devm_gpio_request_one() + devm_gpio_free() + +I2C + devm_i2c_new_dummy_device() + +IIO + devm_iio_device_alloc() + devm_iio_device_free() + devm_iio_device_register() + devm_iio_device_unregister() + devm_iio_kfifo_allocate() + devm_iio_kfifo_free() + devm_iio_triggered_buffer_setup() + devm_iio_triggered_buffer_cleanup() + devm_iio_trigger_alloc() + devm_iio_trigger_free() + devm_iio_trigger_register() + devm_iio_trigger_unregister() + devm_iio_channel_get() + devm_iio_channel_release() + devm_iio_channel_get_all() + devm_iio_channel_release_all() + +INPUT + devm_input_allocate_device() + +IO region + devm_release_mem_region() + devm_release_region() + devm_release_resource() + devm_request_mem_region() + devm_request_region() + devm_request_resource() + +IOMAP + devm_ioport_map() + devm_ioport_unmap() + devm_ioremap() + devm_ioremap_nocache() + devm_ioremap_wc() + devm_ioremap_resource() : checks resource, requests memory region, ioremaps + devm_iounmap() + pcim_iomap() + pcim_iomap_regions() : do request_region() and iomap() on multiple BARs + pcim_iomap_table() : array of mapped addresses indexed by BAR + pcim_iounmap() + +IRQ + devm_free_irq() + devm_request_any_context_irq() + devm_request_irq() + devm_request_threaded_irq() + devm_irq_alloc_descs() + devm_irq_alloc_desc() + devm_irq_alloc_desc_at() + devm_irq_alloc_desc_from() + devm_irq_alloc_descs_from() + devm_irq_alloc_generic_chip() + devm_irq_setup_generic_chip() + devm_irq_sim_init() + +LED + devm_led_classdev_register() + devm_led_classdev_unregister() + +MDIO + devm_mdiobus_alloc() + devm_mdiobus_alloc_size() + devm_mdiobus_free() + +MEM + devm_free_pages() + devm_get_free_pages() + devm_kasprintf() + devm_kcalloc() + devm_kfree() + devm_kmalloc() + devm_kmalloc_array() + devm_kmemdup() + devm_kstrdup() + devm_kvasprintf() + devm_kzalloc() + +MFD + devm_mfd_add_devices() + +MUX + devm_mux_chip_alloc() + devm_mux_chip_register() + devm_mux_control_get() + +PER-CPU MEM + devm_alloc_percpu() + devm_free_percpu() + +PCI + devm_pci_alloc_host_bridge() : managed PCI host bridge allocation + devm_pci_remap_cfgspace() : ioremap PCI configuration space + devm_pci_remap_cfg_resource() : ioremap PCI configuration space resource + pcim_enable_device() : after success, all PCI ops become managed + pcim_pin_device() : keep PCI device enabled after release + +PHY + devm_usb_get_phy() + devm_usb_put_phy() + +PINCTRL + devm_pinctrl_get() + devm_pinctrl_put() + devm_pinctrl_register() + devm_pinctrl_unregister() + +POWER + devm_reboot_mode_register() + devm_reboot_mode_unregister() + +PWM + devm_pwm_get() + devm_pwm_put() + +REGULATOR + devm_regulator_bulk_get() + devm_regulator_get() + devm_regulator_put() + devm_regulator_register() + +RESET + devm_reset_control_get() + devm_reset_controller_register() + +SERDEV + devm_serdev_device_open() + +SLAVE DMA ENGINE + devm_acpi_dma_controller_register() + +SPI + devm_spi_register_master() + +WATCHDOG + devm_watchdog_register_device() diff --git a/Documentation/driver-model/devres.txt b/Documentation/driver-model/devres.txt deleted file mode 100644 index 69c7fa7f616c..000000000000 --- a/Documentation/driver-model/devres.txt +++ /dev/null @@ -1,412 +0,0 @@ -Devres - Managed Device Resource -================================ - -Tejun Heo - -First draft 10 January 2007 - - -1. Intro : Huh? Devres? -2. Devres : Devres in a nutshell -3. Devres Group : Group devres'es and release them together -4. Details : Life time rules, calling context, ... -5. Overhead : How much do we have to pay for this? -6. List of managed interfaces : Currently implemented managed interfaces - - - 1. Intro - -------- - -devres came up while trying to convert libata to use iomap. Each -iomapped address should be kept and unmapped on driver detach. For -example, a plain SFF ATA controller (that is, good old PCI IDE) in -native mode makes use of 5 PCI BARs and all of them should be -maintained. - -As with many other device drivers, libata low level drivers have -sufficient bugs in ->remove and ->probe failure path. Well, yes, -that's probably because libata low level driver developers are lazy -bunch, but aren't all low level driver developers? After spending a -day fiddling with braindamaged hardware with no document or -braindamaged document, if it's finally working, well, it's working. - -For one reason or another, low level drivers don't receive as much -attention or testing as core code, and bugs on driver detach or -initialization failure don't happen often enough to be noticeable. -Init failure path is worse because it's much less travelled while -needs to handle multiple entry points. - -So, many low level drivers end up leaking resources on driver detach -and having half broken failure path implementation in ->probe() which -would leak resources or even cause oops when failure occurs. iomap -adds more to this mix. So do msi and msix. - - - 2. Devres - --------- - -devres is basically linked list of arbitrarily sized memory areas -associated with a struct device. Each devres entry is associated with -a release function. A devres can be released in several ways. No -matter what, all devres entries are released on driver detach. On -release, the associated release function is invoked and then the -devres entry is freed. - -Managed interface is created for resources commonly used by device -drivers using devres. For example, coherent DMA memory is acquired -using dma_alloc_coherent(). The managed version is called -dmam_alloc_coherent(). It is identical to dma_alloc_coherent() except -for the DMA memory allocated using it is managed and will be -automatically released on driver detach. Implementation looks like -the following. - - struct dma_devres { - size_t size; - void *vaddr; - dma_addr_t dma_handle; - }; - - static void dmam_coherent_release(struct device *dev, void *res) - { - struct dma_devres *this = res; - - dma_free_coherent(dev, this->size, this->vaddr, this->dma_handle); - } - - dmam_alloc_coherent(dev, size, dma_handle, gfp) - { - struct dma_devres *dr; - void *vaddr; - - dr = devres_alloc(dmam_coherent_release, sizeof(*dr), gfp); - ... - - /* alloc DMA memory as usual */ - vaddr = dma_alloc_coherent(...); - ... - - /* record size, vaddr, dma_handle in dr */ - dr->vaddr = vaddr; - ... - - devres_add(dev, dr); - - return vaddr; - } - -If a driver uses dmam_alloc_coherent(), the area is guaranteed to be -freed whether initialization fails half-way or the device gets -detached. If most resources are acquired using managed interface, a -driver can have much simpler init and exit code. Init path basically -looks like the following. - - my_init_one() - { - struct mydev *d; - - d = devm_kzalloc(dev, sizeof(*d), GFP_KERNEL); - if (!d) - return -ENOMEM; - - d->ring = dmam_alloc_coherent(...); - if (!d->ring) - return -ENOMEM; - - if (check something) - return -EINVAL; - ... - - return register_to_upper_layer(d); - } - -And exit path, - - my_remove_one() - { - unregister_from_upper_layer(d); - shutdown_my_hardware(); - } - -As shown above, low level drivers can be simplified a lot by using -devres. Complexity is shifted from less maintained low level drivers -to better maintained higher layer. Also, as init failure path is -shared with exit path, both can get more testing. - -Note though that when converting current calls or assignments to -managed devm_* versions it is up to you to check if internal operations -like allocating memory, have failed. Managed resources pertains to the -freeing of these resources *only* - all other checks needed are still -on you. In some cases this may mean introducing checks that were not -necessary before moving to the managed devm_* calls. - - - 3. Devres group - --------------- - -Devres entries can be grouped using devres group. When a group is -released, all contained normal devres entries and properly nested -groups are released. One usage is to rollback series of acquired -resources on failure. For example, - - if (!devres_open_group(dev, NULL, GFP_KERNEL)) - return -ENOMEM; - - acquire A; - if (failed) - goto err; - - acquire B; - if (failed) - goto err; - ... - - devres_remove_group(dev, NULL); - return 0; - - err: - devres_release_group(dev, NULL); - return err_code; - -As resource acquisition failure usually means probe failure, constructs -like above are usually useful in midlayer driver (e.g. libata core -layer) where interface function shouldn't have side effect on failure. -For LLDs, just returning error code suffices in most cases. - -Each group is identified by void *id. It can either be explicitly -specified by @id argument to devres_open_group() or automatically -created by passing NULL as @id as in the above example. In both -cases, devres_open_group() returns the group's id. The returned id -can be passed to other devres functions to select the target group. -If NULL is given to those functions, the latest open group is -selected. - -For example, you can do something like the following. - - int my_midlayer_create_something() - { - if (!devres_open_group(dev, my_midlayer_create_something, GFP_KERNEL)) - return -ENOMEM; - - ... - - devres_close_group(dev, my_midlayer_create_something); - return 0; - } - - void my_midlayer_destroy_something() - { - devres_release_group(dev, my_midlayer_create_something); - } - - - 4. Details - ---------- - -Lifetime of a devres entry begins on devres allocation and finishes -when it is released or destroyed (removed and freed) - no reference -counting. - -devres core guarantees atomicity to all basic devres operations and -has support for single-instance devres types (atomic -lookup-and-add-if-not-found). Other than that, synchronizing -concurrent accesses to allocated devres data is caller's -responsibility. This is usually non-issue because bus ops and -resource allocations already do the job. - -For an example of single-instance devres type, read pcim_iomap_table() -in lib/devres.c. - -All devres interface functions can be called without context if the -right gfp mask is given. - - - 5. Overhead - ----------- - -Each devres bookkeeping info is allocated together with requested data -area. With debug option turned off, bookkeeping info occupies 16 -bytes on 32bit machines and 24 bytes on 64bit (three pointers rounded -up to ull alignment). If singly linked list is used, it can be -reduced to two pointers (8 bytes on 32bit, 16 bytes on 64bit). - -Each devres group occupies 8 pointers. It can be reduced to 6 if -singly linked list is used. - -Memory space overhead on ahci controller with two ports is between 300 -and 400 bytes on 32bit machine after naive conversion (we can -certainly invest a bit more effort into libata core layer). - - - 6. List of managed interfaces - ----------------------------- - -CLOCK - devm_clk_get() - devm_clk_get_optional() - devm_clk_put() - devm_clk_hw_register() - devm_of_clk_add_hw_provider() - devm_clk_hw_register_clkdev() - -DMA - dmaenginem_async_device_register() - dmam_alloc_coherent() - dmam_alloc_attrs() - dmam_free_coherent() - dmam_pool_create() - dmam_pool_destroy() - -DRM - devm_drm_dev_init() - -GPIO - devm_gpiod_get() - devm_gpiod_get_index() - devm_gpiod_get_index_optional() - devm_gpiod_get_optional() - devm_gpiod_put() - devm_gpiod_unhinge() - devm_gpiochip_add_data() - devm_gpio_request() - devm_gpio_request_one() - devm_gpio_free() - -I2C - devm_i2c_new_dummy_device() - -IIO - devm_iio_device_alloc() - devm_iio_device_free() - devm_iio_device_register() - devm_iio_device_unregister() - devm_iio_kfifo_allocate() - devm_iio_kfifo_free() - devm_iio_triggered_buffer_setup() - devm_iio_triggered_buffer_cleanup() - devm_iio_trigger_alloc() - devm_iio_trigger_free() - devm_iio_trigger_register() - devm_iio_trigger_unregister() - devm_iio_channel_get() - devm_iio_channel_release() - devm_iio_channel_get_all() - devm_iio_channel_release_all() - -INPUT - devm_input_allocate_device() - -IO region - devm_release_mem_region() - devm_release_region() - devm_release_resource() - devm_request_mem_region() - devm_request_region() - devm_request_resource() - -IOMAP - devm_ioport_map() - devm_ioport_unmap() - devm_ioremap() - devm_ioremap_nocache() - devm_ioremap_wc() - devm_ioremap_resource() : checks resource, requests memory region, ioremaps - devm_iounmap() - pcim_iomap() - pcim_iomap_regions() : do request_region() and iomap() on multiple BARs - pcim_iomap_table() : array of mapped addresses indexed by BAR - pcim_iounmap() - -IRQ - devm_free_irq() - devm_request_any_context_irq() - devm_request_irq() - devm_request_threaded_irq() - devm_irq_alloc_descs() - devm_irq_alloc_desc() - devm_irq_alloc_desc_at() - devm_irq_alloc_desc_from() - devm_irq_alloc_descs_from() - devm_irq_alloc_generic_chip() - devm_irq_setup_generic_chip() - devm_irq_sim_init() - -LED - devm_led_classdev_register() - devm_led_classdev_unregister() - -MDIO - devm_mdiobus_alloc() - devm_mdiobus_alloc_size() - devm_mdiobus_free() - -MEM - devm_free_pages() - devm_get_free_pages() - devm_kasprintf() - devm_kcalloc() - devm_kfree() - devm_kmalloc() - devm_kmalloc_array() - devm_kmemdup() - devm_kstrdup() - devm_kvasprintf() - devm_kzalloc() - -MFD - devm_mfd_add_devices() - -MUX - devm_mux_chip_alloc() - devm_mux_chip_register() - devm_mux_control_get() - -PER-CPU MEM - devm_alloc_percpu() - devm_free_percpu() - -PCI - devm_pci_alloc_host_bridge() : managed PCI host bridge allocation - devm_pci_remap_cfgspace() : ioremap PCI configuration space - devm_pci_remap_cfg_resource() : ioremap PCI configuration space resource - pcim_enable_device() : after success, all PCI ops become managed - pcim_pin_device() : keep PCI device enabled after release - -PHY - devm_usb_get_phy() - devm_usb_put_phy() - -PINCTRL - devm_pinctrl_get() - devm_pinctrl_put() - devm_pinctrl_register() - devm_pinctrl_unregister() - -POWER - devm_reboot_mode_register() - devm_reboot_mode_unregister() - -PWM - devm_pwm_get() - devm_pwm_put() - -REGULATOR - devm_regulator_bulk_get() - devm_regulator_get() - devm_regulator_put() - devm_regulator_register() - -RESET - devm_reset_control_get() - devm_reset_controller_register() - -SERDEV - devm_serdev_device_open() - -SLAVE DMA ENGINE - devm_acpi_dma_controller_register() - -SPI - devm_spi_register_master() - -WATCHDOG - devm_watchdog_register_device() diff --git a/Documentation/driver-model/driver.rst b/Documentation/driver-model/driver.rst new file mode 100644 index 000000000000..11d281506a04 --- /dev/null +++ b/Documentation/driver-model/driver.rst @@ -0,0 +1,223 @@ +============== +Device Drivers +============== + +See the kerneldoc for the struct device_driver. + + +Allocation +~~~~~~~~~~ + +Device drivers are statically allocated structures. Though there may +be multiple devices in a system that a driver supports, struct +device_driver represents the driver as a whole (not a particular +device instance). + +Initialization +~~~~~~~~~~~~~~ + +The driver must initialize at least the name and bus fields. It should +also initialize the devclass field (when it arrives), so it may obtain +the proper linkage internally. It should also initialize as many of +the callbacks as possible, though each is optional. + +Declaration +~~~~~~~~~~~ + +As stated above, struct device_driver objects are statically +allocated. Below is an example declaration of the eepro100 +driver. This declaration is hypothetical only; it relies on the driver +being converted completely to the new model:: + + static struct device_driver eepro100_driver = { + .name = "eepro100", + .bus = &pci_bus_type, + + .probe = eepro100_probe, + .remove = eepro100_remove, + .suspend = eepro100_suspend, + .resume = eepro100_resume, + }; + +Most drivers will not be able to be converted completely to the new +model because the bus they belong to has a bus-specific structure with +bus-specific fields that cannot be generalized. + +The most common example of this are device ID structures. A driver +typically defines an array of device IDs that it supports. The format +of these structures and the semantics for comparing device IDs are +completely bus-specific. Defining them as bus-specific entities would +sacrifice type-safety, so we keep bus-specific structures around. + +Bus-specific drivers should include a generic struct device_driver in +the definition of the bus-specific driver. Like this:: + + struct pci_driver { + const struct pci_device_id *id_table; + struct device_driver driver; + }; + +A definition that included bus-specific fields would look like +(using the eepro100 driver again):: + + static struct pci_driver eepro100_driver = { + .id_table = eepro100_pci_tbl, + .driver = { + .name = "eepro100", + .bus = &pci_bus_type, + .probe = eepro100_probe, + .remove = eepro100_remove, + .suspend = eepro100_suspend, + .resume = eepro100_resume, + }, + }; + +Some may find the syntax of embedded struct initialization awkward or +even a bit ugly. So far, it's the best way we've found to do what we want... + +Registration +~~~~~~~~~~~~ + +:: + + int driver_register(struct device_driver *drv); + +The driver registers the structure on startup. For drivers that have +no bus-specific fields (i.e. don't have a bus-specific driver +structure), they would use driver_register and pass a pointer to their +struct device_driver object. + +Most drivers, however, will have a bus-specific structure and will +need to register with the bus using something like pci_driver_register. + +It is important that drivers register their driver structure as early as +possible. Registration with the core initializes several fields in the +struct device_driver object, including the reference count and the +lock. These fields are assumed to be valid at all times and may be +used by the device model core or the bus driver. + + +Transition Bus Drivers +~~~~~~~~~~~~~~~~~~~~~~ + +By defining wrapper functions, the transition to the new model can be +made easier. Drivers can ignore the generic structure altogether and +let the bus wrapper fill in the fields. For the callbacks, the bus can +define generic callbacks that forward the call to the bus-specific +callbacks of the drivers. + +This solution is intended to be only temporary. In order to get class +information in the driver, the drivers must be modified anyway. Since +converting drivers to the new model should reduce some infrastructural +complexity and code size, it is recommended that they are converted as +class information is added. + +Access +~~~~~~ + +Once the object has been registered, it may access the common fields of +the object, like the lock and the list of devices:: + + int driver_for_each_dev(struct device_driver *drv, void *data, + int (*callback)(struct device *dev, void *data)); + +The devices field is a list of all the devices that have been bound to +the driver. The LDM core provides a helper function to operate on all +the devices a driver controls. This helper locks the driver on each +node access, and does proper reference counting on each device as it +accesses it. + + +sysfs +~~~~~ + +When a driver is registered, a sysfs directory is created in its +bus's directory. In this directory, the driver can export an interface +to userspace to control operation of the driver on a global basis; +e.g. toggling debugging output in the driver. + +A future feature of this directory will be a 'devices' directory. This +directory will contain symlinks to the directories of devices it +supports. + + + +Callbacks +~~~~~~~~~ + +:: + + int (*probe) (struct device *dev); + +The probe() entry is called in task context, with the bus's rwsem locked +and the driver partially bound to the device. Drivers commonly use +container_of() to convert "dev" to a bus-specific type, both in probe() +and other routines. That type often provides device resource data, such +as pci_dev.resource[] or platform_device.resources, which is used in +addition to dev->platform_data to initialize the driver. + +This callback holds the driver-specific logic to bind the driver to a +given device. That includes verifying that the device is present, that +it's a version the driver can handle, that driver data structures can +be allocated and initialized, and that any hardware can be initialized. +Drivers often store a pointer to their state with dev_set_drvdata(). +When the driver has successfully bound itself to that device, then probe() +returns zero and the driver model code will finish its part of binding +the driver to that device. + +A driver's probe() may return a negative errno value to indicate that +the driver did not bind to this device, in which case it should have +released all resources it allocated:: + + int (*remove) (struct device *dev); + +remove is called to unbind a driver from a device. This may be +called if a device is physically removed from the system, if the +driver module is being unloaded, during a reboot sequence, or +in other cases. + +It is up to the driver to determine if the device is present or +not. It should free any resources allocated specifically for the +device; i.e. anything in the device's driver_data field. + +If the device is still present, it should quiesce the device and place +it into a supported low-power state:: + + int (*suspend) (struct device *dev, pm_message_t state); + +suspend is called to put the device in a low power state:: + + int (*resume) (struct device *dev); + +Resume is used to bring a device back from a low power state. + + +Attributes +~~~~~~~~~~ + +:: + + struct driver_attribute { + struct attribute attr; + ssize_t (*show)(struct device_driver *driver, char *buf); + ssize_t (*store)(struct device_driver *, const char *buf, size_t count); + }; + +Device drivers can export attributes via their sysfs directories. +Drivers can declare attributes using a DRIVER_ATTR_RW and DRIVER_ATTR_RO +macro that works identically to the DEVICE_ATTR_RW and DEVICE_ATTR_RO +macros. + +Example:: + + DRIVER_ATTR_RW(debug); + +This is equivalent to declaring:: + + struct driver_attribute driver_attr_debug; + +This can then be used to add and remove the attribute from the +driver's directory using:: + + int driver_create_file(struct device_driver *, const struct driver_attribute *); + void driver_remove_file(struct device_driver *, const struct driver_attribute *); diff --git a/Documentation/driver-model/driver.txt b/Documentation/driver-model/driver.txt deleted file mode 100644 index d661e6f7e6a0..000000000000 --- a/Documentation/driver-model/driver.txt +++ /dev/null @@ -1,215 +0,0 @@ - -Device Drivers - -See the kerneldoc for the struct device_driver. - - -Allocation -~~~~~~~~~~ - -Device drivers are statically allocated structures. Though there may -be multiple devices in a system that a driver supports, struct -device_driver represents the driver as a whole (not a particular -device instance). - -Initialization -~~~~~~~~~~~~~~ - -The driver must initialize at least the name and bus fields. It should -also initialize the devclass field (when it arrives), so it may obtain -the proper linkage internally. It should also initialize as many of -the callbacks as possible, though each is optional. - -Declaration -~~~~~~~~~~~ - -As stated above, struct device_driver objects are statically -allocated. Below is an example declaration of the eepro100 -driver. This declaration is hypothetical only; it relies on the driver -being converted completely to the new model. - -static struct device_driver eepro100_driver = { - .name = "eepro100", - .bus = &pci_bus_type, - - .probe = eepro100_probe, - .remove = eepro100_remove, - .suspend = eepro100_suspend, - .resume = eepro100_resume, -}; - -Most drivers will not be able to be converted completely to the new -model because the bus they belong to has a bus-specific structure with -bus-specific fields that cannot be generalized. - -The most common example of this are device ID structures. A driver -typically defines an array of device IDs that it supports. The format -of these structures and the semantics for comparing device IDs are -completely bus-specific. Defining them as bus-specific entities would -sacrifice type-safety, so we keep bus-specific structures around. - -Bus-specific drivers should include a generic struct device_driver in -the definition of the bus-specific driver. Like this: - -struct pci_driver { - const struct pci_device_id *id_table; - struct device_driver driver; -}; - -A definition that included bus-specific fields would look like -(using the eepro100 driver again): - -static struct pci_driver eepro100_driver = { - .id_table = eepro100_pci_tbl, - .driver = { - .name = "eepro100", - .bus = &pci_bus_type, - .probe = eepro100_probe, - .remove = eepro100_remove, - .suspend = eepro100_suspend, - .resume = eepro100_resume, - }, -}; - -Some may find the syntax of embedded struct initialization awkward or -even a bit ugly. So far, it's the best way we've found to do what we want... - -Registration -~~~~~~~~~~~~ - -int driver_register(struct device_driver * drv); - -The driver registers the structure on startup. For drivers that have -no bus-specific fields (i.e. don't have a bus-specific driver -structure), they would use driver_register and pass a pointer to their -struct device_driver object. - -Most drivers, however, will have a bus-specific structure and will -need to register with the bus using something like pci_driver_register. - -It is important that drivers register their driver structure as early as -possible. Registration with the core initializes several fields in the -struct device_driver object, including the reference count and the -lock. These fields are assumed to be valid at all times and may be -used by the device model core or the bus driver. - - -Transition Bus Drivers -~~~~~~~~~~~~~~~~~~~~~~ - -By defining wrapper functions, the transition to the new model can be -made easier. Drivers can ignore the generic structure altogether and -let the bus wrapper fill in the fields. For the callbacks, the bus can -define generic callbacks that forward the call to the bus-specific -callbacks of the drivers. - -This solution is intended to be only temporary. In order to get class -information in the driver, the drivers must be modified anyway. Since -converting drivers to the new model should reduce some infrastructural -complexity and code size, it is recommended that they are converted as -class information is added. - -Access -~~~~~~ - -Once the object has been registered, it may access the common fields of -the object, like the lock and the list of devices. - -int driver_for_each_dev(struct device_driver * drv, void * data, - int (*callback)(struct device * dev, void * data)); - -The devices field is a list of all the devices that have been bound to -the driver. The LDM core provides a helper function to operate on all -the devices a driver controls. This helper locks the driver on each -node access, and does proper reference counting on each device as it -accesses it. - - -sysfs -~~~~~ - -When a driver is registered, a sysfs directory is created in its -bus's directory. In this directory, the driver can export an interface -to userspace to control operation of the driver on a global basis; -e.g. toggling debugging output in the driver. - -A future feature of this directory will be a 'devices' directory. This -directory will contain symlinks to the directories of devices it -supports. - - - -Callbacks -~~~~~~~~~ - - int (*probe) (struct device * dev); - -The probe() entry is called in task context, with the bus's rwsem locked -and the driver partially bound to the device. Drivers commonly use -container_of() to convert "dev" to a bus-specific type, both in probe() -and other routines. That type often provides device resource data, such -as pci_dev.resource[] or platform_device.resources, which is used in -addition to dev->platform_data to initialize the driver. - -This callback holds the driver-specific logic to bind the driver to a -given device. That includes verifying that the device is present, that -it's a version the driver can handle, that driver data structures can -be allocated and initialized, and that any hardware can be initialized. -Drivers often store a pointer to their state with dev_set_drvdata(). -When the driver has successfully bound itself to that device, then probe() -returns zero and the driver model code will finish its part of binding -the driver to that device. - -A driver's probe() may return a negative errno value to indicate that -the driver did not bind to this device, in which case it should have -released all resources it allocated. - - int (*remove) (struct device * dev); - -remove is called to unbind a driver from a device. This may be -called if a device is physically removed from the system, if the -driver module is being unloaded, during a reboot sequence, or -in other cases. - -It is up to the driver to determine if the device is present or -not. It should free any resources allocated specifically for the -device; i.e. anything in the device's driver_data field. - -If the device is still present, it should quiesce the device and place -it into a supported low-power state. - - int (*suspend) (struct device * dev, pm_message_t state); - -suspend is called to put the device in a low power state. - - int (*resume) (struct device * dev); - -Resume is used to bring a device back from a low power state. - - -Attributes -~~~~~~~~~~ -struct driver_attribute { - struct attribute attr; - ssize_t (*show)(struct device_driver *driver, char *buf); - ssize_t (*store)(struct device_driver *, const char * buf, size_t count); -}; - -Device drivers can export attributes via their sysfs directories. -Drivers can declare attributes using a DRIVER_ATTR_RW and DRIVER_ATTR_RO -macro that works identically to the DEVICE_ATTR_RW and DEVICE_ATTR_RO -macros. - -Example: - -DRIVER_ATTR_RW(debug); - -This is equivalent to declaring: - -struct driver_attribute driver_attr_debug; - -This can then be used to add and remove the attribute from the -driver's directory using: - -int driver_create_file(struct device_driver *, const struct driver_attribute *); -void driver_remove_file(struct device_driver *, const struct driver_attribute *); diff --git a/Documentation/driver-model/index.rst b/Documentation/driver-model/index.rst new file mode 100644 index 000000000000..9f85d579ce56 --- /dev/null +++ b/Documentation/driver-model/index.rst @@ -0,0 +1,26 @@ +:orphan: + +============ +Driver Model +============ + +.. toctree:: + :maxdepth: 1 + + binding + bus + class + design-patterns + device + devres + driver + overview + platform + porting + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/driver-model/overview.rst b/Documentation/driver-model/overview.rst new file mode 100644 index 000000000000..d4d1e9b40e0c --- /dev/null +++ b/Documentation/driver-model/overview.rst @@ -0,0 +1,124 @@ +============================= +The Linux Kernel Device Model +============================= + +Patrick Mochel + +Drafted 26 August 2002 +Updated 31 January 2006 + + +Overview +~~~~~~~~ + +The Linux Kernel Driver Model is a unification of all the disparate driver +models that were previously used in the kernel. It is intended to augment the +bus-specific drivers for bridges and devices by consolidating a set of data +and operations into globally accessible data structures. + +Traditional driver models implemented some sort of tree-like structure +(sometimes just a list) for the devices they control. There wasn't any +uniformity across the different bus types. + +The current driver model provides a common, uniform data model for describing +a bus and the devices that can appear under the bus. The unified bus +model includes a set of common attributes which all busses carry, and a set +of common callbacks, such as device discovery during bus probing, bus +shutdown, bus power management, etc. + +The common device and bridge interface reflects the goals of the modern +computer: namely the ability to do seamless device "plug and play", power +management, and hot plug. In particular, the model dictated by Intel and +Microsoft (namely ACPI) ensures that almost every device on almost any bus +on an x86-compatible system can work within this paradigm. Of course, +not every bus is able to support all such operations, although most +buses support most of those operations. + + +Downstream Access +~~~~~~~~~~~~~~~~~ + +Common data fields have been moved out of individual bus layers into a common +data structure. These fields must still be accessed by the bus layers, +and sometimes by the device-specific drivers. + +Other bus layers are encouraged to do what has been done for the PCI layer. +struct pci_dev now looks like this:: + + struct pci_dev { + ... + + struct device dev; /* Generic device interface */ + ... + }; + +Note first that the struct device dev within the struct pci_dev is +statically allocated. This means only one allocation on device discovery. + +Note also that that struct device dev is not necessarily defined at the +front of the pci_dev structure. This is to make people think about what +they're doing when switching between the bus driver and the global driver, +and to discourage meaningless and incorrect casts between the two. + +The PCI bus layer freely accesses the fields of struct device. It knows about +the structure of struct pci_dev, and it should know the structure of struct +device. Individual PCI device drivers that have been converted to the current +driver model generally do not and should not touch the fields of struct device, +unless there is a compelling reason to do so. + +The above abstraction prevents unnecessary pain during transitional phases. +If it were not done this way, then when a field was renamed or removed, every +downstream driver would break. On the other hand, if only the bus layer +(and not the device layer) accesses the struct device, it is only the bus +layer that needs to change. + + +User Interface +~~~~~~~~~~~~~~ + +By virtue of having a complete hierarchical view of all the devices in the +system, exporting a complete hierarchical view to userspace becomes relatively +easy. This has been accomplished by implementing a special purpose virtual +file system named sysfs. + +Almost all mainstream Linux distros mount this filesystem automatically; you +can see some variation of the following in the output of the "mount" command:: + + $ mount + ... + none on /sys type sysfs (rw,noexec,nosuid,nodev) + ... + $ + +The auto-mounting of sysfs is typically accomplished by an entry similar to +the following in the /etc/fstab file:: + + none /sys sysfs defaults 0 0 + +or something similar in the /lib/init/fstab file on Debian-based systems:: + + none /sys sysfs nodev,noexec,nosuid 0 0 + +If sysfs is not automatically mounted, you can always do it manually with:: + + # mount -t sysfs sysfs /sys + +Whenever a device is inserted into the tree, a directory is created for it. +This directory may be populated at each layer of discovery - the global layer, +the bus layer, or the device layer. + +The global layer currently creates two files - 'name' and 'power'. The +former only reports the name of the device. The latter reports the +current power state of the device. It will also be used to set the current +power state. + +The bus layer may also create files for the devices it finds while probing the +bus. For example, the PCI layer currently creates 'irq' and 'resource' files +for each PCI device. + +A device-specific driver may also export files in its directory to expose +device-specific data or tunable interfaces. + +More information about the sysfs directory layout can be found in +the other documents in this directory and in the file +Documentation/filesystems/sysfs.txt. diff --git a/Documentation/driver-model/overview.txt b/Documentation/driver-model/overview.txt deleted file mode 100644 index 6a8f9a8075d8..000000000000 --- a/Documentation/driver-model/overview.txt +++ /dev/null @@ -1,123 +0,0 @@ -The Linux Kernel Device Model - -Patrick Mochel - -Drafted 26 August 2002 -Updated 31 January 2006 - - -Overview -~~~~~~~~ - -The Linux Kernel Driver Model is a unification of all the disparate driver -models that were previously used in the kernel. It is intended to augment the -bus-specific drivers for bridges and devices by consolidating a set of data -and operations into globally accessible data structures. - -Traditional driver models implemented some sort of tree-like structure -(sometimes just a list) for the devices they control. There wasn't any -uniformity across the different bus types. - -The current driver model provides a common, uniform data model for describing -a bus and the devices that can appear under the bus. The unified bus -model includes a set of common attributes which all busses carry, and a set -of common callbacks, such as device discovery during bus probing, bus -shutdown, bus power management, etc. - -The common device and bridge interface reflects the goals of the modern -computer: namely the ability to do seamless device "plug and play", power -management, and hot plug. In particular, the model dictated by Intel and -Microsoft (namely ACPI) ensures that almost every device on almost any bus -on an x86-compatible system can work within this paradigm. Of course, -not every bus is able to support all such operations, although most -buses support most of those operations. - - -Downstream Access -~~~~~~~~~~~~~~~~~ - -Common data fields have been moved out of individual bus layers into a common -data structure. These fields must still be accessed by the bus layers, -and sometimes by the device-specific drivers. - -Other bus layers are encouraged to do what has been done for the PCI layer. -struct pci_dev now looks like this: - -struct pci_dev { - ... - - struct device dev; /* Generic device interface */ - ... -}; - -Note first that the struct device dev within the struct pci_dev is -statically allocated. This means only one allocation on device discovery. - -Note also that that struct device dev is not necessarily defined at the -front of the pci_dev structure. This is to make people think about what -they're doing when switching between the bus driver and the global driver, -and to discourage meaningless and incorrect casts between the two. - -The PCI bus layer freely accesses the fields of struct device. It knows about -the structure of struct pci_dev, and it should know the structure of struct -device. Individual PCI device drivers that have been converted to the current -driver model generally do not and should not touch the fields of struct device, -unless there is a compelling reason to do so. - -The above abstraction prevents unnecessary pain during transitional phases. -If it were not done this way, then when a field was renamed or removed, every -downstream driver would break. On the other hand, if only the bus layer -(and not the device layer) accesses the struct device, it is only the bus -layer that needs to change. - - -User Interface -~~~~~~~~~~~~~~ - -By virtue of having a complete hierarchical view of all the devices in the -system, exporting a complete hierarchical view to userspace becomes relatively -easy. This has been accomplished by implementing a special purpose virtual -file system named sysfs. - -Almost all mainstream Linux distros mount this filesystem automatically; you -can see some variation of the following in the output of the "mount" command: - -$ mount -... -none on /sys type sysfs (rw,noexec,nosuid,nodev) -... -$ - -The auto-mounting of sysfs is typically accomplished by an entry similar to -the following in the /etc/fstab file: - -none /sys sysfs defaults 0 0 - -or something similar in the /lib/init/fstab file on Debian-based systems: - -none /sys sysfs nodev,noexec,nosuid 0 0 - -If sysfs is not automatically mounted, you can always do it manually with: - -# mount -t sysfs sysfs /sys - -Whenever a device is inserted into the tree, a directory is created for it. -This directory may be populated at each layer of discovery - the global layer, -the bus layer, or the device layer. - -The global layer currently creates two files - 'name' and 'power'. The -former only reports the name of the device. The latter reports the -current power state of the device. It will also be used to set the current -power state. - -The bus layer may also create files for the devices it finds while probing the -bus. For example, the PCI layer currently creates 'irq' and 'resource' files -for each PCI device. - -A device-specific driver may also export files in its directory to expose -device-specific data or tunable interfaces. - -More information about the sysfs directory layout can be found in -the other documents in this directory and in the file -Documentation/filesystems/sysfs.txt. - diff --git a/Documentation/driver-model/platform.rst b/Documentation/driver-model/platform.rst new file mode 100644 index 000000000000..334dd4071ae4 --- /dev/null +++ b/Documentation/driver-model/platform.rst @@ -0,0 +1,246 @@ +============================ +Platform Devices and Drivers +============================ + +See for the driver model interface to the +platform bus: platform_device, and platform_driver. This pseudo-bus +is used to connect devices on busses with minimal infrastructure, +like those used to integrate peripherals on many system-on-chip +processors, or some "legacy" PC interconnects; as opposed to large +formally specified ones like PCI or USB. + + +Platform devices +~~~~~~~~~~~~~~~~ +Platform devices are devices that typically appear as autonomous +entities in the system. This includes legacy port-based devices and +host bridges to peripheral buses, and most controllers integrated +into system-on-chip platforms. What they usually have in common +is direct addressing from a CPU bus. Rarely, a platform_device will +be connected through a segment of some other kind of bus; but its +registers will still be directly addressable. + +Platform devices are given a name, used in driver binding, and a +list of resources such as addresses and IRQs:: + + struct platform_device { + const char *name; + u32 id; + struct device dev; + u32 num_resources; + struct resource *resource; + }; + + +Platform drivers +~~~~~~~~~~~~~~~~ +Platform drivers follow the standard driver model convention, where +discovery/enumeration is handled outside the drivers, and drivers +provide probe() and remove() methods. They support power management +and shutdown notifications using the standard conventions:: + + struct platform_driver { + int (*probe)(struct platform_device *); + int (*remove)(struct platform_device *); + void (*shutdown)(struct platform_device *); + int (*suspend)(struct platform_device *, pm_message_t state); + int (*suspend_late)(struct platform_device *, pm_message_t state); + int (*resume_early)(struct platform_device *); + int (*resume)(struct platform_device *); + struct device_driver driver; + }; + +Note that probe() should in general verify that the specified device hardware +actually exists; sometimes platform setup code can't be sure. The probing +can use device resources, including clocks, and device platform_data. + +Platform drivers register themselves the normal way:: + + int platform_driver_register(struct platform_driver *drv); + +Or, in common situations where the device is known not to be hot-pluggable, +the probe() routine can live in an init section to reduce the driver's +runtime memory footprint:: + + int platform_driver_probe(struct platform_driver *drv, + int (*probe)(struct platform_device *)) + +Kernel modules can be composed of several platform drivers. The platform core +provides helpers to register and unregister an array of drivers:: + + int __platform_register_drivers(struct platform_driver * const *drivers, + unsigned int count, struct module *owner); + void platform_unregister_drivers(struct platform_driver * const *drivers, + unsigned int count); + +If one of the drivers fails to register, all drivers registered up to that +point will be unregistered in reverse order. Note that there is a convenience +macro that passes THIS_MODULE as owner parameter:: + + #define platform_register_drivers(drivers, count) + + +Device Enumeration +~~~~~~~~~~~~~~~~~~ +As a rule, platform specific (and often board-specific) setup code will +register platform devices:: + + int platform_device_register(struct platform_device *pdev); + + int platform_add_devices(struct platform_device **pdevs, int ndev); + +The general rule is to register only those devices that actually exist, +but in some cases extra devices might be registered. For example, a kernel +might be configured to work with an external network adapter that might not +be populated on all boards, or likewise to work with an integrated controller +that some boards might not hook up to any peripherals. + +In some cases, boot firmware will export tables describing the devices +that are populated on a given board. Without such tables, often the +only way for system setup code to set up the correct devices is to build +a kernel for a specific target board. Such board-specific kernels are +common with embedded and custom systems development. + +In many cases, the memory and IRQ resources associated with the platform +device are not enough to let the device's driver work. Board setup code +will often provide additional information using the device's platform_data +field to hold additional information. + +Embedded systems frequently need one or more clocks for platform devices, +which are normally kept off until they're actively needed (to save power). +System setup also associates those clocks with the device, so that that +calls to clk_get(&pdev->dev, clock_name) return them as needed. + + +Legacy Drivers: Device Probing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Some drivers are not fully converted to the driver model, because they take +on a non-driver role: the driver registers its platform device, rather than +leaving that for system infrastructure. Such drivers can't be hotplugged +or coldplugged, since those mechanisms require device creation to be in a +different system component than the driver. + +The only "good" reason for this is to handle older system designs which, like +original IBM PCs, rely on error-prone "probe-the-hardware" models for hardware +configuration. Newer systems have largely abandoned that model, in favor of +bus-level support for dynamic configuration (PCI, USB), or device tables +provided by the boot firmware (e.g. PNPACPI on x86). There are too many +conflicting options about what might be where, and even educated guesses by +an operating system will be wrong often enough to make trouble. + +This style of driver is discouraged. If you're updating such a driver, +please try to move the device enumeration to a more appropriate location, +outside the driver. This will usually be cleanup, since such drivers +tend to already have "normal" modes, such as ones using device nodes that +were created by PNP or by platform device setup. + +None the less, there are some APIs to support such legacy drivers. Avoid +using these calls except with such hotplug-deficient drivers:: + + struct platform_device *platform_device_alloc( + const char *name, int id); + +You can use platform_device_alloc() to dynamically allocate a device, which +you will then initialize with resources and platform_device_register(). +A better solution is usually:: + + struct platform_device *platform_device_register_simple( + const char *name, int id, + struct resource *res, unsigned int nres); + +You can use platform_device_register_simple() as a one-step call to allocate +and register a device. + + +Device Naming and Driver Binding +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The platform_device.dev.bus_id is the canonical name for the devices. +It's built from two components: + + * platform_device.name ... which is also used to for driver matching. + + * platform_device.id ... the device instance number, or else "-1" + to indicate there's only one. + +These are concatenated, so name/id "serial"/0 indicates bus_id "serial.0", and +"serial/3" indicates bus_id "serial.3"; both would use the platform_driver +named "serial". While "my_rtc"/-1 would be bus_id "my_rtc" (no instance id) +and use the platform_driver called "my_rtc". + +Driver binding is performed automatically by the driver core, invoking +driver probe() after finding a match between device and driver. If the +probe() succeeds, the driver and device are bound as usual. There are +three different ways to find such a match: + + - Whenever a device is registered, the drivers for that bus are + checked for matches. Platform devices should be registered very + early during system boot. + + - When a driver is registered using platform_driver_register(), all + unbound devices on that bus are checked for matches. Drivers + usually register later during booting, or by module loading. + + - Registering a driver using platform_driver_probe() works just like + using platform_driver_register(), except that the driver won't + be probed later if another device registers. (Which is OK, since + this interface is only for use with non-hotpluggable devices.) + + +Early Platform Devices and Drivers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The early platform interfaces provide platform data to platform device +drivers early on during the system boot. The code is built on top of the +early_param() command line parsing and can be executed very early on. + +Example: "earlyprintk" class early serial console in 6 steps + +1. Registering early platform device data +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The architecture code registers platform device data using the function +early_platform_add_devices(). In the case of early serial console this +should be hardware configuration for the serial port. Devices registered +at this point will later on be matched against early platform drivers. + +2. Parsing kernel command line +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The architecture code calls parse_early_param() to parse the kernel +command line. This will execute all matching early_param() callbacks. +User specified early platform devices will be registered at this point. +For the early serial console case the user can specify port on the +kernel command line as "earlyprintk=serial.0" where "earlyprintk" is +the class string, "serial" is the name of the platform driver and +0 is the platform device id. If the id is -1 then the dot and the +id can be omitted. + +3. Installing early platform drivers belonging to a certain class +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The architecture code may optionally force registration of all early +platform drivers belonging to a certain class using the function +early_platform_driver_register_all(). User specified devices from +step 2 have priority over these. This step is omitted by the serial +driver example since the early serial driver code should be disabled +unless the user has specified port on the kernel command line. + +4. Early platform driver registration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Compiled-in platform drivers making use of early_platform_init() are +automatically registered during step 2 or 3. The serial driver example +should use early_platform_init("earlyprintk", &platform_driver). + +5. Probing of early platform drivers belonging to a certain class +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The architecture code calls early_platform_driver_probe() to match +registered early platform devices associated with a certain class with +registered early platform drivers. Matched devices will get probed(). +This step can be executed at any point during the early boot. As soon +as possible may be good for the serial port case. + +6. Inside the early platform driver probe() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The driver code needs to take special care during early boot, especially +when it comes to memory allocation and interrupt registration. The code +in the probe() function can use is_early_platform_device() to check if +it is called at early platform device or at the regular platform device +time. The early serial driver performs register_console() at this point. + +For further information, see . diff --git a/Documentation/driver-model/platform.txt b/Documentation/driver-model/platform.txt deleted file mode 100644 index 9d9e47dfc013..000000000000 --- a/Documentation/driver-model/platform.txt +++ /dev/null @@ -1,244 +0,0 @@ -Platform Devices and Drivers -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -See for the driver model interface to the -platform bus: platform_device, and platform_driver. This pseudo-bus -is used to connect devices on busses with minimal infrastructure, -like those used to integrate peripherals on many system-on-chip -processors, or some "legacy" PC interconnects; as opposed to large -formally specified ones like PCI or USB. - - -Platform devices -~~~~~~~~~~~~~~~~ -Platform devices are devices that typically appear as autonomous -entities in the system. This includes legacy port-based devices and -host bridges to peripheral buses, and most controllers integrated -into system-on-chip platforms. What they usually have in common -is direct addressing from a CPU bus. Rarely, a platform_device will -be connected through a segment of some other kind of bus; but its -registers will still be directly addressable. - -Platform devices are given a name, used in driver binding, and a -list of resources such as addresses and IRQs. - -struct platform_device { - const char *name; - u32 id; - struct device dev; - u32 num_resources; - struct resource *resource; -}; - - -Platform drivers -~~~~~~~~~~~~~~~~ -Platform drivers follow the standard driver model convention, where -discovery/enumeration is handled outside the drivers, and drivers -provide probe() and remove() methods. They support power management -and shutdown notifications using the standard conventions. - -struct platform_driver { - int (*probe)(struct platform_device *); - int (*remove)(struct platform_device *); - void (*shutdown)(struct platform_device *); - int (*suspend)(struct platform_device *, pm_message_t state); - int (*suspend_late)(struct platform_device *, pm_message_t state); - int (*resume_early)(struct platform_device *); - int (*resume)(struct platform_device *); - struct device_driver driver; -}; - -Note that probe() should in general verify that the specified device hardware -actually exists; sometimes platform setup code can't be sure. The probing -can use device resources, including clocks, and device platform_data. - -Platform drivers register themselves the normal way: - - int platform_driver_register(struct platform_driver *drv); - -Or, in common situations where the device is known not to be hot-pluggable, -the probe() routine can live in an init section to reduce the driver's -runtime memory footprint: - - int platform_driver_probe(struct platform_driver *drv, - int (*probe)(struct platform_device *)) - -Kernel modules can be composed of several platform drivers. The platform core -provides helpers to register and unregister an array of drivers: - - int __platform_register_drivers(struct platform_driver * const *drivers, - unsigned int count, struct module *owner); - void platform_unregister_drivers(struct platform_driver * const *drivers, - unsigned int count); - -If one of the drivers fails to register, all drivers registered up to that -point will be unregistered in reverse order. Note that there is a convenience -macro that passes THIS_MODULE as owner parameter: - - #define platform_register_drivers(drivers, count) - - -Device Enumeration -~~~~~~~~~~~~~~~~~~ -As a rule, platform specific (and often board-specific) setup code will -register platform devices: - - int platform_device_register(struct platform_device *pdev); - - int platform_add_devices(struct platform_device **pdevs, int ndev); - -The general rule is to register only those devices that actually exist, -but in some cases extra devices might be registered. For example, a kernel -might be configured to work with an external network adapter that might not -be populated on all boards, or likewise to work with an integrated controller -that some boards might not hook up to any peripherals. - -In some cases, boot firmware will export tables describing the devices -that are populated on a given board. Without such tables, often the -only way for system setup code to set up the correct devices is to build -a kernel for a specific target board. Such board-specific kernels are -common with embedded and custom systems development. - -In many cases, the memory and IRQ resources associated with the platform -device are not enough to let the device's driver work. Board setup code -will often provide additional information using the device's platform_data -field to hold additional information. - -Embedded systems frequently need one or more clocks for platform devices, -which are normally kept off until they're actively needed (to save power). -System setup also associates those clocks with the device, so that that -calls to clk_get(&pdev->dev, clock_name) return them as needed. - - -Legacy Drivers: Device Probing -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Some drivers are not fully converted to the driver model, because they take -on a non-driver role: the driver registers its platform device, rather than -leaving that for system infrastructure. Such drivers can't be hotplugged -or coldplugged, since those mechanisms require device creation to be in a -different system component than the driver. - -The only "good" reason for this is to handle older system designs which, like -original IBM PCs, rely on error-prone "probe-the-hardware" models for hardware -configuration. Newer systems have largely abandoned that model, in favor of -bus-level support for dynamic configuration (PCI, USB), or device tables -provided by the boot firmware (e.g. PNPACPI on x86). There are too many -conflicting options about what might be where, and even educated guesses by -an operating system will be wrong often enough to make trouble. - -This style of driver is discouraged. If you're updating such a driver, -please try to move the device enumeration to a more appropriate location, -outside the driver. This will usually be cleanup, since such drivers -tend to already have "normal" modes, such as ones using device nodes that -were created by PNP or by platform device setup. - -None the less, there are some APIs to support such legacy drivers. Avoid -using these calls except with such hotplug-deficient drivers. - - struct platform_device *platform_device_alloc( - const char *name, int id); - -You can use platform_device_alloc() to dynamically allocate a device, which -you will then initialize with resources and platform_device_register(). -A better solution is usually: - - struct platform_device *platform_device_register_simple( - const char *name, int id, - struct resource *res, unsigned int nres); - -You can use platform_device_register_simple() as a one-step call to allocate -and register a device. - - -Device Naming and Driver Binding -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The platform_device.dev.bus_id is the canonical name for the devices. -It's built from two components: - - * platform_device.name ... which is also used to for driver matching. - - * platform_device.id ... the device instance number, or else "-1" - to indicate there's only one. - -These are concatenated, so name/id "serial"/0 indicates bus_id "serial.0", and -"serial/3" indicates bus_id "serial.3"; both would use the platform_driver -named "serial". While "my_rtc"/-1 would be bus_id "my_rtc" (no instance id) -and use the platform_driver called "my_rtc". - -Driver binding is performed automatically by the driver core, invoking -driver probe() after finding a match between device and driver. If the -probe() succeeds, the driver and device are bound as usual. There are -three different ways to find such a match: - - - Whenever a device is registered, the drivers for that bus are - checked for matches. Platform devices should be registered very - early during system boot. - - - When a driver is registered using platform_driver_register(), all - unbound devices on that bus are checked for matches. Drivers - usually register later during booting, or by module loading. - - - Registering a driver using platform_driver_probe() works just like - using platform_driver_register(), except that the driver won't - be probed later if another device registers. (Which is OK, since - this interface is only for use with non-hotpluggable devices.) - - -Early Platform Devices and Drivers -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The early platform interfaces provide platform data to platform device -drivers early on during the system boot. The code is built on top of the -early_param() command line parsing and can be executed very early on. - -Example: "earlyprintk" class early serial console in 6 steps - -1. Registering early platform device data -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The architecture code registers platform device data using the function -early_platform_add_devices(). In the case of early serial console this -should be hardware configuration for the serial port. Devices registered -at this point will later on be matched against early platform drivers. - -2. Parsing kernel command line -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The architecture code calls parse_early_param() to parse the kernel -command line. This will execute all matching early_param() callbacks. -User specified early platform devices will be registered at this point. -For the early serial console case the user can specify port on the -kernel command line as "earlyprintk=serial.0" where "earlyprintk" is -the class string, "serial" is the name of the platform driver and -0 is the platform device id. If the id is -1 then the dot and the -id can be omitted. - -3. Installing early platform drivers belonging to a certain class -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The architecture code may optionally force registration of all early -platform drivers belonging to a certain class using the function -early_platform_driver_register_all(). User specified devices from -step 2 have priority over these. This step is omitted by the serial -driver example since the early serial driver code should be disabled -unless the user has specified port on the kernel command line. - -4. Early platform driver registration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Compiled-in platform drivers making use of early_platform_init() are -automatically registered during step 2 or 3. The serial driver example -should use early_platform_init("earlyprintk", &platform_driver). - -5. Probing of early platform drivers belonging to a certain class -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The architecture code calls early_platform_driver_probe() to match -registered early platform devices associated with a certain class with -registered early platform drivers. Matched devices will get probed(). -This step can be executed at any point during the early boot. As soon -as possible may be good for the serial port case. - -6. Inside the early platform driver probe() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The driver code needs to take special care during early boot, especially -when it comes to memory allocation and interrupt registration. The code -in the probe() function can use is_early_platform_device() to check if -it is called at early platform device or at the regular platform device -time. The early serial driver performs register_console() at this point. - -For further information, see . diff --git a/Documentation/driver-model/porting.rst b/Documentation/driver-model/porting.rst new file mode 100644 index 000000000000..ae4bf843c1d6 --- /dev/null +++ b/Documentation/driver-model/porting.rst @@ -0,0 +1,448 @@ +======================================= +Porting Drivers to the New Driver Model +======================================= + +Patrick Mochel + +7 January 2003 + + +Overview + +Please refer to `Documentation/driver-model/*.rst` for definitions of +various driver types and concepts. + +Most of the work of porting devices drivers to the new model happens +at the bus driver layer. This was intentional, to minimize the +negative effect on kernel drivers, and to allow a gradual transition +of bus drivers. + +In a nutshell, the driver model consists of a set of objects that can +be embedded in larger, bus-specific objects. Fields in these generic +objects can replace fields in the bus-specific objects. + +The generic objects must be registered with the driver model core. By +doing so, they will exported via the sysfs filesystem. sysfs can be +mounted by doing:: + + # mount -t sysfs sysfs /sys + + + +The Process + +Step 0: Read include/linux/device.h for object and function definitions. + +Step 1: Registering the bus driver. + + +- Define a struct bus_type for the bus driver:: + + struct bus_type pci_bus_type = { + .name = "pci", + }; + + +- Register the bus type. + + This should be done in the initialization function for the bus type, + which is usually the module_init(), or equivalent, function:: + + static int __init pci_driver_init(void) + { + return bus_register(&pci_bus_type); + } + + subsys_initcall(pci_driver_init); + + + The bus type may be unregistered (if the bus driver may be compiled + as a module) by doing:: + + bus_unregister(&pci_bus_type); + + +- Export the bus type for others to use. + + Other code may wish to reference the bus type, so declare it in a + shared header file and export the symbol. + +From include/linux/pci.h:: + + extern struct bus_type pci_bus_type; + + +From file the above code appears in:: + + EXPORT_SYMBOL(pci_bus_type); + + + +- This will cause the bus to show up in /sys/bus/pci/ with two + subdirectories: 'devices' and 'drivers':: + + # tree -d /sys/bus/pci/ + /sys/bus/pci/ + |-- devices + `-- drivers + + + +Step 2: Registering Devices. + +struct device represents a single device. It mainly contains metadata +describing the relationship the device has to other entities. + + +- Embed a struct device in the bus-specific device type:: + + + struct pci_dev { + ... + struct device dev; /* Generic device interface */ + ... + }; + + It is recommended that the generic device not be the first item in + the struct to discourage programmers from doing mindless casts + between the object types. Instead macros, or inline functions, + should be created to convert from the generic object type:: + + + #define to_pci_dev(n) container_of(n, struct pci_dev, dev) + + or + + static inline struct pci_dev * to_pci_dev(struct kobject * kobj) + { + return container_of(n, struct pci_dev, dev); + } + + This allows the compiler to verify type-safety of the operations + that are performed (which is Good). + + +- Initialize the device on registration. + + When devices are discovered or registered with the bus type, the + bus driver should initialize the generic device. The most important + things to initialize are the bus_id, parent, and bus fields. + + The bus_id is an ASCII string that contains the device's address on + the bus. The format of this string is bus-specific. This is + necessary for representing devices in sysfs. + + parent is the physical parent of the device. It is important that + the bus driver sets this field correctly. + + The driver model maintains an ordered list of devices that it uses + for power management. This list must be in order to guarantee that + devices are shutdown before their physical parents, and vice versa. + The order of this list is determined by the parent of registered + devices. + + Also, the location of the device's sysfs directory depends on a + device's parent. sysfs exports a directory structure that mirrors + the device hierarchy. Accurately setting the parent guarantees that + sysfs will accurately represent the hierarchy. + + The device's bus field is a pointer to the bus type the device + belongs to. This should be set to the bus_type that was declared + and initialized before. + + Optionally, the bus driver may set the device's name and release + fields. + + The name field is an ASCII string describing the device, like + + "ATI Technologies Inc Radeon QD" + + The release field is a callback that the driver model core calls + when the device has been removed, and all references to it have + been released. More on this in a moment. + + +- Register the device. + + Once the generic device has been initialized, it can be registered + with the driver model core by doing:: + + device_register(&dev->dev); + + It can later be unregistered by doing:: + + device_unregister(&dev->dev); + + This should happen on buses that support hotpluggable devices. + If a bus driver unregisters a device, it should not immediately free + it. It should instead wait for the driver model core to call the + device's release method, then free the bus-specific object. + (There may be other code that is currently referencing the device + structure, and it would be rude to free the device while that is + happening). + + + When the device is registered, a directory in sysfs is created. + The PCI tree in sysfs looks like:: + + /sys/devices/pci0/ + |-- 00:00.0 + |-- 00:01.0 + | `-- 01:00.0 + |-- 00:02.0 + | `-- 02:1f.0 + | `-- 03:00.0 + |-- 00:1e.0 + | `-- 04:04.0 + |-- 00:1f.0 + |-- 00:1f.1 + | |-- ide0 + | | |-- 0.0 + | | `-- 0.1 + | `-- ide1 + | `-- 1.0 + |-- 00:1f.2 + |-- 00:1f.3 + `-- 00:1f.5 + + Also, symlinks are created in the bus's 'devices' directory + that point to the device's directory in the physical hierarchy:: + + /sys/bus/pci/devices/ + |-- 00:00.0 -> ../../../devices/pci0/00:00.0 + |-- 00:01.0 -> ../../../devices/pci0/00:01.0 + |-- 00:02.0 -> ../../../devices/pci0/00:02.0 + |-- 00:1e.0 -> ../../../devices/pci0/00:1e.0 + |-- 00:1f.0 -> ../../../devices/pci0/00:1f.0 + |-- 00:1f.1 -> ../../../devices/pci0/00:1f.1 + |-- 00:1f.2 -> ../../../devices/pci0/00:1f.2 + |-- 00:1f.3 -> ../../../devices/pci0/00:1f.3 + |-- 00:1f.5 -> ../../../devices/pci0/00:1f.5 + |-- 01:00.0 -> ../../../devices/pci0/00:01.0/01:00.0 + |-- 02:1f.0 -> ../../../devices/pci0/00:02.0/02:1f.0 + |-- 03:00.0 -> ../../../devices/pci0/00:02.0/02:1f.0/03:00.0 + `-- 04:04.0 -> ../../../devices/pci0/00:1e.0/04:04.0 + + + +Step 3: Registering Drivers. + +struct device_driver is a simple driver structure that contains a set +of operations that the driver model core may call. + + +- Embed a struct device_driver in the bus-specific driver. + + Just like with devices, do something like:: + + struct pci_driver { + ... + struct device_driver driver; + }; + + +- Initialize the generic driver structure. + + When the driver registers with the bus (e.g. doing pci_register_driver()), + initialize the necessary fields of the driver: the name and bus + fields. + + +- Register the driver. + + After the generic driver has been initialized, call:: + + driver_register(&drv->driver); + + to register the driver with the core. + + When the driver is unregistered from the bus, unregister it from the + core by doing:: + + driver_unregister(&drv->driver); + + Note that this will block until all references to the driver have + gone away. Normally, there will not be any. + + +- Sysfs representation. + + Drivers are exported via sysfs in their bus's 'driver's directory. + For example:: + + /sys/bus/pci/drivers/ + |-- 3c59x + |-- Ensoniq AudioPCI + |-- agpgart-amdk7 + |-- e100 + `-- serial + + +Step 4: Define Generic Methods for Drivers. + +struct device_driver defines a set of operations that the driver model +core calls. Most of these operations are probably similar to +operations the bus already defines for drivers, but taking different +parameters. + +It would be difficult and tedious to force every driver on a bus to +simultaneously convert their drivers to generic format. Instead, the +bus driver should define single instances of the generic methods that +forward call to the bus-specific drivers. For instance:: + + + static int pci_device_remove(struct device * dev) + { + struct pci_dev * pci_dev = to_pci_dev(dev); + struct pci_driver * drv = pci_dev->driver; + + if (drv) { + if (drv->remove) + drv->remove(pci_dev); + pci_dev->driver = NULL; + } + return 0; + } + + +The generic driver should be initialized with these methods before it +is registered:: + + /* initialize common driver fields */ + drv->driver.name = drv->name; + drv->driver.bus = &pci_bus_type; + drv->driver.probe = pci_device_probe; + drv->driver.resume = pci_device_resume; + drv->driver.suspend = pci_device_suspend; + drv->driver.remove = pci_device_remove; + + /* register with core */ + driver_register(&drv->driver); + + +Ideally, the bus should only initialize the fields if they are not +already set. This allows the drivers to implement their own generic +methods. + + +Step 5: Support generic driver binding. + +The model assumes that a device or driver can be dynamically +registered with the bus at any time. When registration happens, +devices must be bound to a driver, or drivers must be bound to all +devices that it supports. + +A driver typically contains a list of device IDs that it supports. The +bus driver compares these IDs to the IDs of devices registered with it. +The format of the device IDs, and the semantics for comparing them are +bus-specific, so the generic model does attempt to generalize them. + +Instead, a bus may supply a method in struct bus_type that does the +comparison:: + + int (*match)(struct device * dev, struct device_driver * drv); + +match should return positive value if the driver supports the device, +and zero otherwise. It may also return error code (for example +-EPROBE_DEFER) if determining that given driver supports the device is +not possible. + +When a device is registered, the bus's list of drivers is iterated +over. bus->match() is called for each one until a match is found. + +When a driver is registered, the bus's list of devices is iterated +over. bus->match() is called for each device that is not already +claimed by a driver. + +When a device is successfully bound to a driver, device->driver is +set, the device is added to a per-driver list of devices, and a +symlink is created in the driver's sysfs directory that points to the +device's physical directory:: + + /sys/bus/pci/drivers/ + |-- 3c59x + | `-- 00:0b.0 -> ../../../../devices/pci0/00:0b.0 + |-- Ensoniq AudioPCI + |-- agpgart-amdk7 + | `-- 00:00.0 -> ../../../../devices/pci0/00:00.0 + |-- e100 + | `-- 00:0c.0 -> ../../../../devices/pci0/00:0c.0 + `-- serial + + +This driver binding should replace the existing driver binding +mechanism the bus currently uses. + + +Step 6: Supply a hotplug callback. + +Whenever a device is registered with the driver model core, the +userspace program /sbin/hotplug is called to notify userspace. +Users can define actions to perform when a device is inserted or +removed. + +The driver model core passes several arguments to userspace via +environment variables, including + +- ACTION: set to 'add' or 'remove' +- DEVPATH: set to the device's physical path in sysfs. + +A bus driver may also supply additional parameters for userspace to +consume. To do this, a bus must implement the 'hotplug' method in +struct bus_type:: + + int (*hotplug) (struct device *dev, char **envp, + int num_envp, char *buffer, int buffer_size); + +This is called immediately before /sbin/hotplug is executed. + + +Step 7: Cleaning up the bus driver. + +The generic bus, device, and driver structures provide several fields +that can replace those defined privately to the bus driver. + +- Device list. + +struct bus_type contains a list of all devices registered with the bus +type. This includes all devices on all instances of that bus type. +An internal list that the bus uses may be removed, in favor of using +this one. + +The core provides an iterator to access these devices:: + + int bus_for_each_dev(struct bus_type * bus, struct device * start, + void * data, int (*fn)(struct device *, void *)); + + +- Driver list. + +struct bus_type also contains a list of all drivers registered with +it. An internal list of drivers that the bus driver maintains may +be removed in favor of using the generic one. + +The drivers may be iterated over, like devices:: + + int bus_for_each_drv(struct bus_type * bus, struct device_driver * start, + void * data, int (*fn)(struct device_driver *, void *)); + + +Please see drivers/base/bus.c for more information. + + +- rwsem + +struct bus_type contains an rwsem that protects all core accesses to +the device and driver lists. This can be used by the bus driver +internally, and should be used when accessing the device or driver +lists the bus maintains. + + +- Device and driver fields. + +Some of the fields in struct device and struct device_driver duplicate +fields in the bus-specific representations of these objects. Feel free +to remove the bus-specific ones and favor the generic ones. Note +though, that this will likely mean fixing up all the drivers that +reference the bus-specific fields (though those should all be 1-line +changes). diff --git a/Documentation/driver-model/porting.txt b/Documentation/driver-model/porting.txt deleted file mode 100644 index 453053f1661f..000000000000 --- a/Documentation/driver-model/porting.txt +++ /dev/null @@ -1,447 +0,0 @@ - -Porting Drivers to the New Driver Model - -Patrick Mochel - -7 January 2003 - - -Overview - -Please refer to Documentation/driver-model/*.txt for definitions of -various driver types and concepts. - -Most of the work of porting devices drivers to the new model happens -at the bus driver layer. This was intentional, to minimize the -negative effect on kernel drivers, and to allow a gradual transition -of bus drivers. - -In a nutshell, the driver model consists of a set of objects that can -be embedded in larger, bus-specific objects. Fields in these generic -objects can replace fields in the bus-specific objects. - -The generic objects must be registered with the driver model core. By -doing so, they will exported via the sysfs filesystem. sysfs can be -mounted by doing - - # mount -t sysfs sysfs /sys - - - -The Process - -Step 0: Read include/linux/device.h for object and function definitions. - -Step 1: Registering the bus driver. - - -- Define a struct bus_type for the bus driver. - -struct bus_type pci_bus_type = { - .name = "pci", -}; - - -- Register the bus type. - This should be done in the initialization function for the bus type, - which is usually the module_init(), or equivalent, function. - -static int __init pci_driver_init(void) -{ - return bus_register(&pci_bus_type); -} - -subsys_initcall(pci_driver_init); - - - The bus type may be unregistered (if the bus driver may be compiled - as a module) by doing: - - bus_unregister(&pci_bus_type); - - -- Export the bus type for others to use. - - Other code may wish to reference the bus type, so declare it in a - shared header file and export the symbol. - -From include/linux/pci.h: - -extern struct bus_type pci_bus_type; - - -From file the above code appears in: - -EXPORT_SYMBOL(pci_bus_type); - - - -- This will cause the bus to show up in /sys/bus/pci/ with two - subdirectories: 'devices' and 'drivers'. - -# tree -d /sys/bus/pci/ -/sys/bus/pci/ -|-- devices -`-- drivers - - - -Step 2: Registering Devices. - -struct device represents a single device. It mainly contains metadata -describing the relationship the device has to other entities. - - -- Embed a struct device in the bus-specific device type. - - -struct pci_dev { - ... - struct device dev; /* Generic device interface */ - ... -}; - - It is recommended that the generic device not be the first item in - the struct to discourage programmers from doing mindless casts - between the object types. Instead macros, or inline functions, - should be created to convert from the generic object type. - - -#define to_pci_dev(n) container_of(n, struct pci_dev, dev) - -or - -static inline struct pci_dev * to_pci_dev(struct kobject * kobj) -{ - return container_of(n, struct pci_dev, dev); -} - - This allows the compiler to verify type-safety of the operations - that are performed (which is Good). - - -- Initialize the device on registration. - - When devices are discovered or registered with the bus type, the - bus driver should initialize the generic device. The most important - things to initialize are the bus_id, parent, and bus fields. - - The bus_id is an ASCII string that contains the device's address on - the bus. The format of this string is bus-specific. This is - necessary for representing devices in sysfs. - - parent is the physical parent of the device. It is important that - the bus driver sets this field correctly. - - The driver model maintains an ordered list of devices that it uses - for power management. This list must be in order to guarantee that - devices are shutdown before their physical parents, and vice versa. - The order of this list is determined by the parent of registered - devices. - - Also, the location of the device's sysfs directory depends on a - device's parent. sysfs exports a directory structure that mirrors - the device hierarchy. Accurately setting the parent guarantees that - sysfs will accurately represent the hierarchy. - - The device's bus field is a pointer to the bus type the device - belongs to. This should be set to the bus_type that was declared - and initialized before. - - Optionally, the bus driver may set the device's name and release - fields. - - The name field is an ASCII string describing the device, like - - "ATI Technologies Inc Radeon QD" - - The release field is a callback that the driver model core calls - when the device has been removed, and all references to it have - been released. More on this in a moment. - - -- Register the device. - - Once the generic device has been initialized, it can be registered - with the driver model core by doing: - - device_register(&dev->dev); - - It can later be unregistered by doing: - - device_unregister(&dev->dev); - - This should happen on buses that support hotpluggable devices. - If a bus driver unregisters a device, it should not immediately free - it. It should instead wait for the driver model core to call the - device's release method, then free the bus-specific object. - (There may be other code that is currently referencing the device - structure, and it would be rude to free the device while that is - happening). - - - When the device is registered, a directory in sysfs is created. - The PCI tree in sysfs looks like: - -/sys/devices/pci0/ -|-- 00:00.0 -|-- 00:01.0 -| `-- 01:00.0 -|-- 00:02.0 -| `-- 02:1f.0 -| `-- 03:00.0 -|-- 00:1e.0 -| `-- 04:04.0 -|-- 00:1f.0 -|-- 00:1f.1 -| |-- ide0 -| | |-- 0.0 -| | `-- 0.1 -| `-- ide1 -| `-- 1.0 -|-- 00:1f.2 -|-- 00:1f.3 -`-- 00:1f.5 - - Also, symlinks are created in the bus's 'devices' directory - that point to the device's directory in the physical hierarchy. - -/sys/bus/pci/devices/ -|-- 00:00.0 -> ../../../devices/pci0/00:00.0 -|-- 00:01.0 -> ../../../devices/pci0/00:01.0 -|-- 00:02.0 -> ../../../devices/pci0/00:02.0 -|-- 00:1e.0 -> ../../../devices/pci0/00:1e.0 -|-- 00:1f.0 -> ../../../devices/pci0/00:1f.0 -|-- 00:1f.1 -> ../../../devices/pci0/00:1f.1 -|-- 00:1f.2 -> ../../../devices/pci0/00:1f.2 -|-- 00:1f.3 -> ../../../devices/pci0/00:1f.3 -|-- 00:1f.5 -> ../../../devices/pci0/00:1f.5 -|-- 01:00.0 -> ../../../devices/pci0/00:01.0/01:00.0 -|-- 02:1f.0 -> ../../../devices/pci0/00:02.0/02:1f.0 -|-- 03:00.0 -> ../../../devices/pci0/00:02.0/02:1f.0/03:00.0 -`-- 04:04.0 -> ../../../devices/pci0/00:1e.0/04:04.0 - - - -Step 3: Registering Drivers. - -struct device_driver is a simple driver structure that contains a set -of operations that the driver model core may call. - - -- Embed a struct device_driver in the bus-specific driver. - - Just like with devices, do something like: - -struct pci_driver { - ... - struct device_driver driver; -}; - - -- Initialize the generic driver structure. - - When the driver registers with the bus (e.g. doing pci_register_driver()), - initialize the necessary fields of the driver: the name and bus - fields. - - -- Register the driver. - - After the generic driver has been initialized, call - - driver_register(&drv->driver); - - to register the driver with the core. - - When the driver is unregistered from the bus, unregister it from the - core by doing: - - driver_unregister(&drv->driver); - - Note that this will block until all references to the driver have - gone away. Normally, there will not be any. - - -- Sysfs representation. - - Drivers are exported via sysfs in their bus's 'driver's directory. - For example: - -/sys/bus/pci/drivers/ -|-- 3c59x -|-- Ensoniq AudioPCI -|-- agpgart-amdk7 -|-- e100 -`-- serial - - -Step 4: Define Generic Methods for Drivers. - -struct device_driver defines a set of operations that the driver model -core calls. Most of these operations are probably similar to -operations the bus already defines for drivers, but taking different -parameters. - -It would be difficult and tedious to force every driver on a bus to -simultaneously convert their drivers to generic format. Instead, the -bus driver should define single instances of the generic methods that -forward call to the bus-specific drivers. For instance: - - -static int pci_device_remove(struct device * dev) -{ - struct pci_dev * pci_dev = to_pci_dev(dev); - struct pci_driver * drv = pci_dev->driver; - - if (drv) { - if (drv->remove) - drv->remove(pci_dev); - pci_dev->driver = NULL; - } - return 0; -} - - -The generic driver should be initialized with these methods before it -is registered. - - /* initialize common driver fields */ - drv->driver.name = drv->name; - drv->driver.bus = &pci_bus_type; - drv->driver.probe = pci_device_probe; - drv->driver.resume = pci_device_resume; - drv->driver.suspend = pci_device_suspend; - drv->driver.remove = pci_device_remove; - - /* register with core */ - driver_register(&drv->driver); - - -Ideally, the bus should only initialize the fields if they are not -already set. This allows the drivers to implement their own generic -methods. - - -Step 5: Support generic driver binding. - -The model assumes that a device or driver can be dynamically -registered with the bus at any time. When registration happens, -devices must be bound to a driver, or drivers must be bound to all -devices that it supports. - -A driver typically contains a list of device IDs that it supports. The -bus driver compares these IDs to the IDs of devices registered with it. -The format of the device IDs, and the semantics for comparing them are -bus-specific, so the generic model does attempt to generalize them. - -Instead, a bus may supply a method in struct bus_type that does the -comparison: - - int (*match)(struct device * dev, struct device_driver * drv); - -match should return positive value if the driver supports the device, -and zero otherwise. It may also return error code (for example --EPROBE_DEFER) if determining that given driver supports the device is -not possible. - -When a device is registered, the bus's list of drivers is iterated -over. bus->match() is called for each one until a match is found. - -When a driver is registered, the bus's list of devices is iterated -over. bus->match() is called for each device that is not already -claimed by a driver. - -When a device is successfully bound to a driver, device->driver is -set, the device is added to a per-driver list of devices, and a -symlink is created in the driver's sysfs directory that points to the -device's physical directory: - -/sys/bus/pci/drivers/ -|-- 3c59x -| `-- 00:0b.0 -> ../../../../devices/pci0/00:0b.0 -|-- Ensoniq AudioPCI -|-- agpgart-amdk7 -| `-- 00:00.0 -> ../../../../devices/pci0/00:00.0 -|-- e100 -| `-- 00:0c.0 -> ../../../../devices/pci0/00:0c.0 -`-- serial - - -This driver binding should replace the existing driver binding -mechanism the bus currently uses. - - -Step 6: Supply a hotplug callback. - -Whenever a device is registered with the driver model core, the -userspace program /sbin/hotplug is called to notify userspace. -Users can define actions to perform when a device is inserted or -removed. - -The driver model core passes several arguments to userspace via -environment variables, including - -- ACTION: set to 'add' or 'remove' -- DEVPATH: set to the device's physical path in sysfs. - -A bus driver may also supply additional parameters for userspace to -consume. To do this, a bus must implement the 'hotplug' method in -struct bus_type: - - int (*hotplug) (struct device *dev, char **envp, - int num_envp, char *buffer, int buffer_size); - -This is called immediately before /sbin/hotplug is executed. - - -Step 7: Cleaning up the bus driver. - -The generic bus, device, and driver structures provide several fields -that can replace those defined privately to the bus driver. - -- Device list. - -struct bus_type contains a list of all devices registered with the bus -type. This includes all devices on all instances of that bus type. -An internal list that the bus uses may be removed, in favor of using -this one. - -The core provides an iterator to access these devices. - -int bus_for_each_dev(struct bus_type * bus, struct device * start, - void * data, int (*fn)(struct device *, void *)); - - -- Driver list. - -struct bus_type also contains a list of all drivers registered with -it. An internal list of drivers that the bus driver maintains may -be removed in favor of using the generic one. - -The drivers may be iterated over, like devices: - -int bus_for_each_drv(struct bus_type * bus, struct device_driver * start, - void * data, int (*fn)(struct device_driver *, void *)); - - -Please see drivers/base/bus.c for more information. - - -- rwsem - -struct bus_type contains an rwsem that protects all core accesses to -the device and driver lists. This can be used by the bus driver -internally, and should be used when accessing the device or driver -lists the bus maintains. - - -- Device and driver fields. - -Some of the fields in struct device and struct device_driver duplicate -fields in the bus-specific representations of these objects. Feel free -to remove the bus-specific ones and favor the generic ones. Note -though, that this will likely mean fixing up all the drivers that -reference the bus-specific fields (though those should all be 1-line -changes). - diff --git a/Documentation/eisa.txt b/Documentation/eisa.txt index 2806e5544e43..f388545a85a7 100644 --- a/Documentation/eisa.txt +++ b/Documentation/eisa.txt @@ -103,7 +103,7 @@ id_table an array of NULL terminated EISA id strings, (driver_data). driver a generic driver, such as described in - Documentation/driver-model/driver.txt. Only .name, + Documentation/driver-model/driver.rst. Only .name, .probe and .remove members are mandatory. =============== ==================================================== @@ -152,7 +152,7 @@ state set of flags indicating the state of the device. Current flags are EISA_CONFIG_ENABLED and EISA_CONFIG_FORCED. res set of four 256 bytes I/O regions allocated to this device dma_mask DMA mask set from the parent device. -dev generic device (see Documentation/driver-model/device.txt) +dev generic device (see Documentation/driver-model/device.rst) ======== ============================================================ You can get the 'struct eisa_device' from 'struct device' using the diff --git a/Documentation/hwmon/submitting-patches.rst b/Documentation/hwmon/submitting-patches.rst index f9796b9d9db6..d5b05d3e54ba 100644 --- a/Documentation/hwmon/submitting-patches.rst +++ b/Documentation/hwmon/submitting-patches.rst @@ -89,7 +89,7 @@ increase the chances of your change being accepted. console. Excessive logging can seriously affect system performance. * Use devres functions whenever possible to allocate resources. For rationale - and supported functions, please see Documentation/driver-model/devres.txt. + and supported functions, please see Documentation/driver-model/devres.rst. If a function is not supported by devres, consider using devm_add_action(). * If the driver has a detect function, make sure it is silent. Debug messages diff --git a/drivers/base/platform.c b/drivers/base/platform.c index 4d1729853d1a..713903290385 100644 --- a/drivers/base/platform.c +++ b/drivers/base/platform.c @@ -5,7 +5,7 @@ * Copyright (c) 2002-3 Patrick Mochel * Copyright (c) 2002-3 Open Source Development Labs * - * Please see Documentation/driver-model/platform.txt for more + * Please see Documentation/driver-model/platform.rst for more * information. */ diff --git a/drivers/gpio/gpio-cs5535.c b/drivers/gpio/gpio-cs5535.c index 6314225dbed0..3611a0571667 100644 --- a/drivers/gpio/gpio-cs5535.c +++ b/drivers/gpio/gpio-cs5535.c @@ -41,7 +41,7 @@ MODULE_PARM_DESC(mask, "GPIO channel mask."); /* * FIXME: convert this singleton driver to use the state container - * design pattern, see Documentation/driver-model/design-patterns.txt + * design pattern, see Documentation/driver-model/design-patterns.rst */ static struct cs5535_gpio_chip { struct gpio_chip chip; diff --git a/drivers/net/ethernet/intel/ice/ice_main.c b/drivers/net/ethernet/intel/ice/ice_main.c index 7843abf4d44d..98a62072d81e 100644 --- a/drivers/net/ethernet/intel/ice/ice_main.c +++ b/drivers/net/ethernet/intel/ice/ice_main.c @@ -2237,7 +2237,7 @@ ice_probe(struct pci_dev *pdev, const struct pci_device_id __always_unused *ent) struct ice_hw *hw; int err; - /* this driver uses devres, see Documentation/driver-model/devres.txt */ + /* this driver uses devres, see Documentation/driver-model/devres.rst */ err = pcim_enable_device(pdev); if (err) return err; diff --git a/scripts/coccinelle/free/devm_free.cocci b/scripts/coccinelle/free/devm_free.cocci index b2a2cf8bf81f..e32236a979a8 100644 --- a/scripts/coccinelle/free/devm_free.cocci +++ b/scripts/coccinelle/free/devm_free.cocci @@ -2,7 +2,7 @@ /// functions. Values allocated using the devm_functions are freed when /// the device is detached, and thus the use of the standard freeing /// function would cause a double free. -/// See Documentation/driver-model/devres.txt for more information. +/// See Documentation/driver-model/devres.rst for more information. /// /// A difficulty of detecting this problem is that the standard freeing /// function might be called from a different function than the one -- cgit v1.2.3 From bbc249f2b85916da489111f6d33bf1da2be444bb Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 20 Jun 2019 14:22:55 -0300 Subject: scripts: add an script to parse the ABI files Add a script to parse the Documentation/ABI files and produce an output with all entries inside an ABI (sub)directory. Right now, it outputs its contents on ReST format. It shouldn't be hard to make it produce other kind of outputs, since the ABI file parser is implemented in separate than the output generator. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 212 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 212 insertions(+) create mode 100755 scripts/get_abi.pl (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl new file mode 100755 index 000000000000..f7c9944a833c --- /dev/null +++ b/scripts/get_abi.pl @@ -0,0 +1,212 @@ +#!/usr/bin/perl + +use strict; +use Pod::Usage; +use Getopt::Long; +use File::Find; +use Fcntl ':mode'; + +my $help; +my $man; +my $debug; + +GetOptions( + "debug|d+" => \$debug, + 'help|?' => \$help, + man => \$man +) or pod2usage(2); + +pod2usage(1) if $help; +pod2usage(-exitstatus => 0, -verbose => 2) if $man; + +pod2usage(2) if (scalar @ARGV != 1); + +my ($prefix) = @ARGV; + +require Data::Dumper if ($debug); + +my %data; + +# +# Displays an error message, printing file name and line +# +sub parse_error($$$$) { + my ($file, $ln, $msg, $data) = @_; + + print STDERR "file $file#$ln: $msg at\n\t$data"; +} + +# +# Parse an ABI file, storing its contents at %data +# +sub parse_abi { + my $file = $File::Find::name; + + my $mode = (stat($file))[2]; + return if ($mode & S_IFDIR); + return if ($file =~ m,/README,); + + my $name = $file; + $name =~ s,.*/,,; + + my $type = $file; + $type =~ s,.*/(.*)/.*,$1,; + + my $what; + my $new_what; + my $tag; + my $ln; + + print STDERR "Opening $file\n" if ($debug > 1); + open IN, $file; + while() { + $ln++; + if (m/^(\S+):\s*(.*)/i) { + my $new_tag = lc($1); + my $content = $2; + + if (!($new_tag =~ m/(what|date|kernelversion|contact|description|users)/)) { + if ($tag eq "description") { + $data{$what}->{$tag} .= "\n$content";; + $data{$what}->{$tag} =~ s/\n+$//; + next; + } else { + parse_error($file, $ln, "tag '$tag' is invalid", $_); + } + } + + if ($new_tag =~ m/what/) { + if ($tag =~ m/what/) { + $what .= ", " . $content; + } else { + $what = $content; + $new_what = 1; + } + $tag = $new_tag; + next; + } + + $tag = $new_tag; + + if ($new_what) { + $new_what = 0; + + $data{$what}->{type} = $type; + $data{$what}->{file} = $name; + print STDERR "\twhat: $what\n" if ($debug > 1); + } + + if (!$what) { + parse_error($file, $ln, "'What:' should come first:", $_); + next; + } + $data{$what}->{$tag} = $content; + next; + } + + # Silently ignore any headers before the database + next if (!$tag); + + if (m/^\s*(.*)/) { + $data{$what}->{$tag} .= "\n$1"; + $data{$what}->{$tag} =~ s/\n+$//; + next; + } + + # Everything else is error + parse_error($file, $ln, "Unexpected line:", $_); + } + close IN; +} + +# Outputs the output on ReST format +sub output_rest { + foreach my $what (sort keys %data) { + my $type = $data{$what}->{type}; + my $file = $data{$what}->{file}; + + my $w = $what; + $w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g; + + print "$w\n\n"; + print "- defined on file $file (type: $type)\n\n::\n\n"; + + my $desc = $data{$what}->{description}; + $desc =~ s/^\s+//; + + # Remove title markups from the description, as they won't work + $desc =~ s/\n[\-\*\=\^\~]+\n/\n/g; + + # put everything inside a code block + $desc =~ s/\n/\n /g; + + + if (!($desc =~ /^\s*$/)) { + print " $desc\n\n"; + } else { + print " DESCRIPTION MISSING\n\n"; + } + } +} + +# +# Parses all ABI files located at $prefix dir +# +find({wanted =>\&parse_abi, no_chdir => 1}, $prefix); + +print STDERR Data::Dumper->Dump([\%data], [qw(*data)]) if ($debug); + +# +# Outputs an ReST file with the ABI contents +# +output_rest + + +__END__ + +=head1 NAME + +abi_book.pl - parse the Linux ABI files and produce a ReST book. + +=head1 SYNOPSIS + +B [--debug] ] + +=head1 OPTIONS + +=over 8 + +=item B<--debug> + +Put the script in verbose mode, useful for debugging. Can be called multiple +times, to increase verbosity. + +=item B<--help> + +Prints a brief help message and exits. + +=item B<--man> + +Prints the manual page and exits. + +=back + +=head1 DESCRIPTION + +Parse the Linux ABI files from ABI DIR (usually located at Documentation/ABI) +and produce a ReST book containing the Linux ABI. + +=head1 BUGS + +Report bugs to Mauro Carvalho Chehab + +=head1 COPYRIGHT + +Copyright (c) 2016 by Mauro Carvalho Chehab . + +License GPLv2: GNU GPL version 2 . + +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. + +=cut -- cgit v1.2.3 From 6619c6617a88e3b5e35b12aed069aabe35c370e0 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 20 Jun 2019 14:22:56 -0300 Subject: scripts/get_abi.pl: parse files with text at beginning It sounds usefult o parse files with has some text at the beginning. Add support for it. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 59 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 54 insertions(+), 5 deletions(-) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index f7c9944a833c..ef9b6e108973 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -55,7 +55,10 @@ sub parse_abi { my $what; my $new_what; my $tag; + my $label; my $ln; + my $has_file; + my $xrefs; print STDERR "Opening $file\n" if ($debug > 1); open IN, $file; @@ -67,7 +70,7 @@ sub parse_abi { if (!($new_tag =~ m/(what|date|kernelversion|contact|description|users)/)) { if ($tag eq "description") { - $data{$what}->{$tag} .= "\n$content";; + $data{$what}->{$tag} .= "\n$content"; $data{$what}->{$tag} =~ s/\n+$//; next; } else { @@ -83,6 +86,25 @@ sub parse_abi { $new_what = 1; } $tag = $new_tag; + + if ($has_file) { + $label = "abi_" . $content . " "; + $label =~ tr/A-Z/a-z/; + + # Convert special chars to "_" + $label =~s/[\x00-\x2f]+/_/g; + $label =~s/[\x3a-\x40]+/_/g; + $label =~s/[\x7b-\xff]+/_/g; + $label =~ s,_+,_,g; + $label =~ s,_$,,; + + $data{$what}->{label} .= $label; + + # Escape special chars from content + $content =~s/([\x00-\x1f\x21-\x2f\x3a-\x40\x7b-\xff])/\\$1/g; + + $xrefs .= "- :ref:`$content <$label>`\n\n"; + } next; } @@ -104,8 +126,18 @@ sub parse_abi { next; } - # Silently ignore any headers before the database - next if (!$tag); + # Store any contents before the database + if (!$tag) { + next if (/^\n/); + + my $my_what = "File $name"; + $data{$my_what}->{what} = "File $name"; + $data{$my_what}->{type} = "File"; + $data{$my_what}->{file} = $name; + $data{$my_what}->{description} .= $_; + $has_file = 1; + next; + } if (m/^\s*(.*)/) { $data{$what}->{$tag} .= "\n$1"; @@ -117,6 +149,11 @@ sub parse_abi { parse_error($file, $ln, "Unexpected line:", $_); } close IN; + + if ($has_file) { + my $my_what = "File $name"; + $data{$my_what}->{xrefs} = $xrefs; + } } # Outputs the output on ReST format @@ -128,8 +165,17 @@ sub output_rest { my $w = $what; $w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g; + if ($data{$what}->{label}) { + my @labels = split(/\s/, $data{$what}->{label}); + foreach my $label (@labels) { + printf ".. _%s:\n\n", $label; + } + } + print "$w\n\n"; - print "- defined on file $file (type: $type)\n\n::\n\n"; + + print "- defined on file $file (type: $type)\n\n" if ($type ne "File"); + print "::\n\n"; my $desc = $data{$what}->{description}; $desc =~ s/^\s+//; @@ -144,8 +190,11 @@ sub output_rest { if (!($desc =~ /^\s*$/)) { print " $desc\n\n"; } else { - print " DESCRIPTION MISSING\n\n"; + print " DESCRIPTION MISSING for $what\n\n"; } + + printf "Has the following ABI:\n\n%s", $data{$what}->{xrefs} if ($data{$what}->{xrefs}); + } } -- cgit v1.2.3 From 4e6a6234da84496c6173ebe991060fe382ec4f15 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 20 Jun 2019 14:22:57 -0300 Subject: scripts/get_abi.pl: avoid use literal blocks when not needed The usage of literal blocks make the document very complex, causing the browser to take a long time to load. On most ABI descriptions, they're a plain text, and don't require a literal block. So, add a logic there with identifies when a literal block is needed. As, on literal blocks, we need to respect the original document space, the most complex part of this patch is to preserve the original spacing where needed. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 102 ++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 77 insertions(+), 25 deletions(-) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index ef9b6e108973..0ede9593c639 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -59,29 +59,34 @@ sub parse_abi { my $ln; my $has_file; my $xrefs; + my $space; print STDERR "Opening $file\n" if ($debug > 1); open IN, $file; while() { $ln++; - if (m/^(\S+):\s*(.*)/i) { + if (m/^(\S+)(:\s*)(.*)/i) { my $new_tag = lc($1); - my $content = $2; + my $sep = $2; + my $content = $3; if (!($new_tag =~ m/(what|date|kernelversion|contact|description|users)/)) { if ($tag eq "description") { - $data{$what}->{$tag} .= "\n$content"; - $data{$what}->{$tag} =~ s/\n+$//; - next; + # New "tag" is actually part of + # description. Don't consider it a tag + $new_tag = ""; } else { parse_error($file, $ln, "tag '$tag' is invalid", $_); } } if ($new_tag =~ m/what/) { + $space = ""; if ($tag =~ m/what/) { $what .= ", " . $content; } else { + parse_error($file, $ln, "What '$what' doesn't have a description", "") if ($what && !$data{$what}->{description}); + $what = $content; $new_what = 1; } @@ -108,25 +113,38 @@ sub parse_abi { next; } - $tag = $new_tag; + if ($new_tag) { + $tag = $new_tag; - if ($new_what) { - $new_what = 0; + if ($new_what) { + $new_what = 0; - $data{$what}->{type} = $type; - $data{$what}->{file} = $name; - print STDERR "\twhat: $what\n" if ($debug > 1); - } + $data{$what}->{type} = $type; + $data{$what}->{file} = $name; + print STDERR "\twhat: $what\n" if ($debug > 1); + } - if (!$what) { - parse_error($file, $ln, "'What:' should come first:", $_); + if (!$what) { + parse_error($file, $ln, "'What:' should come first:", $_); + next; + } + if ($tag eq "description") { + next if ($content =~ m/^\s*$/); + if ($content =~ m/^(\s*)(.*)/) { + my $new_content = $2; + $space = $new_tag . $sep . $1; + while ($space =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {} + $space =~ s/./ /g; + $data{$what}->{$tag} .= "$new_content\n"; + } + } else { + $data{$what}->{$tag} = $content; + } next; } - $data{$what}->{$tag} = $content; - next; } - # Store any contents before the database + # Store any contents before tags at the database if (!$tag) { next if (/^\n/); @@ -139,6 +157,32 @@ sub parse_abi { next; } + if ($tag eq "description") { + if (!$data{$what}->{description}) { + next if (m/^\s*\n/); + if (m/^(\s*)(.*)/) { + $space = $1; + while ($space =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {} + $data{$what}->{$tag} .= "$2\n"; + } + } else { + my $content = $_; + if (m/^\s*\n/) { + $data{$what}->{$tag} .= $content; + next; + } + + while ($content =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {} + $space = "" if (!($content =~ s/^($space)//)); + + # Compress spaces with tabs + $content =~ s<^ {8}> <\t>; + $content =~ s<^ {1,7}\t> <\t>; + $content =~ s< {1,7}\t> <\t>; + $data{$what}->{$tag} .= $content; + } + next; + } if (m/^\s*(.*)/) { $data{$what}->{$tag} .= "\n$1"; $data{$what}->{$tag} =~ s/\n+$//; @@ -165,6 +209,9 @@ sub output_rest { my $w = $what; $w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g; + my $bar = $w; + $bar =~ s/./-/g; + if ($data{$what}->{label}) { my @labels = split(/\s/, $data{$what}->{label}); foreach my $label (@labels) { @@ -172,10 +219,9 @@ sub output_rest { } } - print "$w\n\n"; + print "$w\n$bar\n\n"; print "- defined on file $file (type: $type)\n\n" if ($type ne "File"); - print "::\n\n"; my $desc = $data{$what}->{description}; $desc =~ s/^\s+//; @@ -183,18 +229,24 @@ sub output_rest { # Remove title markups from the description, as they won't work $desc =~ s/\n[\-\*\=\^\~]+\n/\n/g; - # put everything inside a code block - $desc =~ s/\n/\n /g; + if (!($desc =~ /^\s*$/)) { + if ($desc =~ m/\:\n/ || $desc =~ m/\n[\t ]+/ || $desc =~ m/[\x00-\x08\x0b-\x1f\x7b-\xff]/) { + # put everything inside a code block + $desc =~ s/\n/\n /g; + print "::\n\n"; + print " $desc\n\n"; + } else { + # Escape any special chars from description + $desc =~s/([\x00-\x08\x0b-\x1f\x21-\x2a\x2d\x2f\x3c-\x40\x5c\x5e-\x60\x7b-\xff])/\\$1/g; - if (!($desc =~ /^\s*$/)) { - print " $desc\n\n"; + print "$desc\n\n"; + } } else { - print " DESCRIPTION MISSING for $what\n\n"; + print "DESCRIPTION MISSING for $what\n\n"; } printf "Has the following ABI:\n\n%s", $data{$what}->{xrefs} if ($data{$what}->{xrefs}); - } } -- cgit v1.2.3 From d0ebaf51d219b63f87f3dc1da4c9da501d0519a4 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 20 Jun 2019 14:22:58 -0300 Subject: scripts/get_abi.pl: split label naming from xref logic Instead of using a ReST compilant label while parsing, move the label to ReST output. That makes the parsing logic more generic, allowing it to provide other types of output. As a side effect, now all files used to generate the output will be output. We can later add command line arguments to filter. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 94 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 53 insertions(+), 41 deletions(-) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index 0ede9593c639..f84d321a72bb 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -49,17 +49,23 @@ sub parse_abi { my $name = $file; $name =~ s,.*/,,; + my $nametag = "File $name"; + $data{$nametag}->{what} = "File $name"; + $data{$nametag}->{type} = "File"; + $data{$nametag}->{file} = $name; + $data{$nametag}->{is_file} = 1; + my $type = $file; $type =~ s,.*/(.*)/.*,$1,; my $what; my $new_what; my $tag; - my $label; my $ln; - my $has_file; my $xrefs; my $space; + my @labels; + my $label; print STDERR "Opening $file\n" if ($debug > 1); open IN, $file; @@ -88,28 +94,13 @@ sub parse_abi { parse_error($file, $ln, "What '$what' doesn't have a description", "") if ($what && !$data{$what}->{description}); $what = $content; + $label = $content; $new_what = 1; } + push @labels, [($content, $label)]; $tag = $new_tag; - if ($has_file) { - $label = "abi_" . $content . " "; - $label =~ tr/A-Z/a-z/; - - # Convert special chars to "_" - $label =~s/[\x00-\x2f]+/_/g; - $label =~s/[\x3a-\x40]+/_/g; - $label =~s/[\x7b-\xff]+/_/g; - $label =~ s,_+,_,g; - $label =~ s,_$,,; - - $data{$what}->{label} .= $label; - - # Escape special chars from content - $content =~s/([\x00-\x1f\x21-\x2f\x3a-\x40\x7b-\xff])/\\$1/g; - - $xrefs .= "- :ref:`$content <$label>`\n\n"; - } + push @{$data{$nametag}->{xrefs}}, [($content, $label)] if ($data{$nametag}->{what}); next; } @@ -117,6 +108,9 @@ sub parse_abi { $tag = $new_tag; if ($new_what) { + @{$data{$what}->{label}} = @labels if ($data{$nametag}->{what}); + @labels = (); + $label = ""; $new_what = 0; $data{$what}->{type} = $type; @@ -145,15 +139,8 @@ sub parse_abi { } # Store any contents before tags at the database - if (!$tag) { - next if (/^\n/); - - my $my_what = "File $name"; - $data{$my_what}->{what} = "File $name"; - $data{$my_what}->{type} = "File"; - $data{$my_what}->{file} = $name; - $data{$my_what}->{description} .= $_; - $has_file = 1; + if (!$tag && $data{$nametag}->{what}) { + $data{$nametag}->{description} .= $_; next; } @@ -192,12 +179,8 @@ sub parse_abi { # Everything else is error parse_error($file, $ln, "Unexpected line:", $_); } + $data{$nametag}->{description} =~ s/^\n+//; close IN; - - if ($has_file) { - my $my_what = "File $name"; - $data{$my_what}->{xrefs} = $xrefs; - } } # Outputs the output on ReST format @@ -212,11 +195,22 @@ sub output_rest { my $bar = $w; $bar =~ s/./-/g; - if ($data{$what}->{label}) { - my @labels = split(/\s/, $data{$what}->{label}); - foreach my $label (@labels) { - printf ".. _%s:\n\n", $label; - } + foreach my $p (@{$data{$what}->{label}}) { + my ($content, $label) = @{$p}; + $label = "abi_" . $label . " "; + $label =~ tr/A-Z/a-z/; + + # Convert special chars to "_" + $label =~s/([\x00-\x2f\x3a-\x40\x5b-\x60\x7b-\xff])/_/g; + $label =~ s,_+,_,g; + $label =~ s,_$,,; + + $data{$what}->{label} .= $label; + + printf ".. _%s:\n\n", $label; + + # only one label is enough + last; } print "$w\n$bar\n\n"; @@ -243,10 +237,28 @@ sub output_rest { print "$desc\n\n"; } } else { - print "DESCRIPTION MISSING for $what\n\n"; + print "DESCRIPTION MISSING for $what\n\n" if (!$data{$what}->{is_file}); } - printf "Has the following ABI:\n\n%s", $data{$what}->{xrefs} if ($data{$what}->{xrefs}); + if ($data{$what}->{xrefs}) { + printf "Has the following ABI:\n\n"; + + foreach my $p(@{$data{$what}->{xrefs}}) { + my ($content, $label) = @{$p}; + $label = "abi_" . $label . " "; + $label =~ tr/A-Z/a-z/; + + # Convert special chars to "_" + $label =~s/([\x00-\x2f\x3a-\x40\x5b-\x60\x7b-\xff])/_/g; + $label =~ s,_+,_,g; + $label =~ s,_$,,; + + # Escape special chars from content + $content =~s/([\x00-\x1f\x21-\x2f\x3a-\x40\x7b-\xff])/\\$1/g; + + print "- :ref:`$content <$label>`\n\n"; + } + } } } -- cgit v1.2.3 From 33e3e9913e22481fd90fa0c50d4a04dded0ee1e1 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 20 Jun 2019 14:22:59 -0300 Subject: scripts/get_abi.pl: add support for searching for ABI symbols Change its syntax to allow switching between ReST output mode and a new search mode, with allows to seek for ABI symbols using regex. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 112 ++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 103 insertions(+), 9 deletions(-) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index f84d321a72bb..ecf6b91df7c4 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -9,9 +9,11 @@ use Fcntl ':mode'; my $help; my $man; my $debug; +my $prefix="Documentation/ABI"; GetOptions( "debug|d+" => \$debug, + "dir=s" => \$prefix, 'help|?' => \$help, man => \$man ) or pod2usage(2); @@ -19,9 +21,12 @@ GetOptions( pod2usage(1) if $help; pod2usage(-exitstatus => 0, -verbose => 2) if $man; -pod2usage(2) if (scalar @ARGV != 1); +pod2usage(2) if (scalar @ARGV < 1 || @ARGV > 2); -my ($prefix) = @ARGV; +my ($cmd, $arg) = @ARGV; + +pod2usage(2) if ($cmd ne "search" && $cmd ne "rest"); +pod2usage(2) if ($cmd eq "search" && !$arg); require Data::Dumper if ($debug); @@ -53,6 +58,7 @@ sub parse_abi { $data{$nametag}->{what} = "File $name"; $data{$nametag}->{type} = "File"; $data{$nametag}->{file} = $name; + $data{$nametag}->{filepath} = $file; $data{$nametag}->{is_file} = 1; my $type = $file; @@ -115,6 +121,7 @@ sub parse_abi { $data{$what}->{type} = $type; $data{$what}->{file} = $name; + $data{$what}->{filepath} = $file; print STDERR "\twhat: $what\n" if ($debug > 1); } @@ -183,7 +190,9 @@ sub parse_abi { close IN; } -# Outputs the output on ReST format +# +# Outputs the book on ReST format +# sub output_rest { foreach my $what (sort keys %data) { my $type = $data{$what}->{type}; @@ -262,6 +271,45 @@ sub output_rest { } } +# +# Searches for ABI symbols +# +sub search_symbols { + foreach my $what (sort keys %data) { + next if (!($what =~ m/($arg)/)); + + my $type = $data{$what}->{type}; + next if ($type eq "File"); + + my $file = $data{$what}->{filepath}; + + my $bar = $what; + $bar =~ s/./-/g; + + print "\n$what\n$bar\n\n"; + + my $kernelversion = $data{$what}->{kernelversion}; + my $contact = $data{$what}->{contact}; + my $users = $data{$what}->{users}; + my $date = $data{$what}->{date}; + my $desc = $data{$what}->{description}; + $kernelversion =~ s/^\s+//; + $contact =~ s/^\s+//; + $users =~ s/^\s+//; + $users =~ s/\n//g; + $date =~ s/^\s+//; + $desc =~ s/^\s+//; + + printf "Kernel version:\t\t%s\n", $kernelversion if ($kernelversion); + printf "Date:\t\t\t%s\n", $date if ($date); + printf "Contact:\t\t%s\n", $contact if ($contact); + printf "Users:\t\t\t%s\n", $users if ($users); + print "Defined on file:\t$file\n\n"; + print "Description:\n\n$desc"; + } +} + + # # Parses all ABI files located at $prefix dir # @@ -270,9 +318,13 @@ find({wanted =>\&parse_abi, no_chdir => 1}, $prefix); print STDERR Data::Dumper->Dump([\%data], [qw(*data)]) if ($debug); # -# Outputs an ReST file with the ABI contents +# Handles the command # -output_rest +if ($cmd eq "rest") { + output_rest; +} else { + search_symbols; +} __END__ @@ -283,12 +335,27 @@ abi_book.pl - parse the Linux ABI files and produce a ReST book. =head1 SYNOPSIS -B [--debug] ] +B [--debug] [] + +Where can be: + +=over 8 + +B [SEARCH_REGEX] - search for [SEARCH_REGEX] inside ABI + +B - output the ABI in ReST markup language + +=back =head1 OPTIONS =over 8 +=item B<--dir> + +Changes the location of the ABI search. By default, it uses +the Documentation/ABI directory. + =item B<--debug> Put the script in verbose mode, useful for debugging. Can be called multiple @@ -306,8 +373,35 @@ Prints the manual page and exits. =head1 DESCRIPTION -Parse the Linux ABI files from ABI DIR (usually located at Documentation/ABI) -and produce a ReST book containing the Linux ABI. +Parse the Linux ABI files from ABI DIR (usually located at Documentation/ABI), +allowing to search for ABI symbols or to produce a ReST book containing +the Linux ABI documentation. + +=head1 EXAMPLES + +Search for all stable symbols with the word "usb": + +=over 8 + +$ scripts/get_abi.pl search usb --dir Documentation/ABI/stable + +=back + +Search for all symbols that match the regex expression "usb.*cap": + +=over 8 + +$ scripts/get_abi.pl search usb.*cap + +=back + +Output all obsoleted symbols in ReST format + +=over 8 + +$ scripts/get_abi.pl rest --dir Documentation/ABI/obsolete + +=back =head1 BUGS @@ -315,7 +409,7 @@ Report bugs to Mauro Carvalho Chehab =head1 COPYRIGHT -Copyright (c) 2016 by Mauro Carvalho Chehab . +Copyright (c) 2016-2017 by Mauro Carvalho Chehab . License GPLv2: GNU GPL version 2 . -- cgit v1.2.3 From 45f965179560f26227d87641da0d055d5751f49f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 20 Jun 2019 14:23:00 -0300 Subject: scripts/get_abi.pl: represent what in tables Several entries at the ABI have multiple What: with the same description. Instead of showing those symbols as sections, let's show them as tables. That makes easier to read on the final output, and avoid too much recursion at Sphinx parsing. We need to put file references at the end, as we don't want non-file tables to be mangled with other entries. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 41 ++++++++++++++++++++++++++++++++++++----- 1 file changed, 36 insertions(+), 5 deletions(-) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index ecf6b91df7c4..7d454e359d25 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -193,16 +193,19 @@ sub parse_abi { # # Outputs the book on ReST format # + sub output_rest { - foreach my $what (sort keys %data) { + foreach my $what (sort { + ($data{$a}->{type} eq "File") cmp ($data{$b}->{type} eq "File") || + $a cmp $b + } keys %data) { my $type = $data{$what}->{type}; my $file = $data{$what}->{file}; + my $filepath = $data{$what}->{filepath}; my $w = $what; $w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g; - my $bar = $w; - $bar =~ s/./-/g; foreach my $p (@{$data{$what}->{label}}) { my ($content, $label) = @{$p}; @@ -222,9 +225,37 @@ sub output_rest { last; } - print "$w\n$bar\n\n"; - print "- defined on file $file (type: $type)\n\n" if ($type ne "File"); + $filepath =~ s,.*/(.*/.*),\1,;; + $filepath =~ s,[/\-],_,g;; + my $fileref = "abi_file_".$filepath; + + if ($type eq "File") { + my $bar = $w; + $bar =~ s/./-/g; + + print ".. _$fileref:\n\n"; + print "$w\n$bar\n\n"; + } else { + my @names = split /\s*,\s*/,$w; + + my $len = 0; + + foreach my $name (@names) { + $len = length($name) if (length($name) > $len); + } + + print "What:\n\n"; + + print "+-" . "-" x $len . "-+\n"; + foreach my $name (@names) { + printf "| %s", $name . " " x ($len - length($name)) . " |\n"; + print "+-" . "-" x $len . "-+\n"; + } + print "\n"; + } + + print "Defined on file :ref:`$file <$fileref>`\n\n" if ($type ne "File"); my $desc = $data{$what}->{description}; $desc =~ s/^\s+//; -- cgit v1.2.3 From 7d7ea8d2409fca0796f87676e489ed4ac0690a1b Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 20 Jun 2019 14:23:01 -0300 Subject: scripts/get_abi.pl: fix parse issues with some files A few files are failing to parse: Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats Documentation/ABI/testing/sysfs-class-pktcdvd Documentation/ABI/testing/sysfs-bus-nfit On all three files, the problem is that there is a ":" character at the initial file description. Improve the parse in order to handle those special cases. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index 7d454e359d25..116f0c33c16d 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -87,7 +87,7 @@ sub parse_abi { # New "tag" is actually part of # description. Don't consider it a tag $new_tag = ""; - } else { + } elsif ($tag ne "") { parse_error($file, $ln, "tag '$tag' is invalid", $_); } } @@ -110,7 +110,7 @@ sub parse_abi { next; } - if ($new_tag) { + if ($tag ne "" && $new_tag) { $tag = $new_tag; if ($new_what) { -- cgit v1.2.3 From 2e7ce05593b39f0a947819ca8b73f2185f372f12 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 20 Jun 2019 14:23:02 -0300 Subject: scripts/get_abi.pl: avoid creating duplicate names The file the Documentation/ABI/testing/sysfs-class-power has voltage_min, voltage_max and voltage_now symbols duplicated. They are defined first for "General Properties" and then for "USB Properties". This cause those warnings: get_abi.pl rest --dir $srctree/Documentation/ABI/testing:26933: WARNING: Duplicate explicit target name: "abi_sys_class_power_supply_supply_name_voltage_max". get_abi.pl rest --dir $srctree/Documentation/ABI/testing:26968: WARNING: Duplicate explicit target name: "abi_sys_class_power_supply_supply_name_voltage_min". get_abi.pl rest --dir $srctree/Documentation/ABI/testing:27008: WARNING: Duplicate explicit target name: "abi_sys_class_power_supply_supply_name_voltage_now". And, as the references are not valid, it will also generate warnings about links to undefined references. Fix it by storing labels into a hash table and, when a duplicated one is found, appending random characters at the end. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index 116f0c33c16d..329ace635ac2 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -194,6 +194,8 @@ sub parse_abi { # Outputs the book on ReST format # +my %labels; + sub output_rest { foreach my $what (sort { ($data{$a}->{type} eq "File") cmp ($data{$b}->{type} eq "File") || @@ -217,6 +219,13 @@ sub output_rest { $label =~ s,_+,_,g; $label =~ s,_$,,; + # Avoid duplicated labels + while (defined($labels{$label})) { + my @chars = ("A".."Z", "a".."z"); + $label .= $chars[rand @chars]; + } + $labels{$label} = 1; + $data{$what}->{label} .= $label; printf ".. _%s:\n\n", $label; -- cgit v1.2.3 From 2c0700e7afa40330f2d21defe2a7bffcb0eecb1e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 20 Jun 2019 14:23:03 -0300 Subject: scripts/get_abi.pl: add a handler for invalid "where" tag The ABI README file doesn't provide any meaning for a Where: tag. Yet, a few ABI symbols use it. So, make the parser handle it, emitting a warning. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index 329ace635ac2..c5038a0a7313 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -92,6 +92,12 @@ sub parse_abi { } } + # Invalid, but it is a common mistake + if ($new_tag eq "where") { + parse_error($file, $ln, "tag 'Where' is invalid. Should be 'What:' instead", $_); + $new_tag = "what"; + } + if ($new_tag =~ m/what/) { $space = ""; if ($tag =~ m/what/) { -- cgit v1.2.3 From 7ce7b89bf565b4e86d37fd32577272e98d3359cd Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 20 Jun 2019 14:23:04 -0300 Subject: scripts/get_abi.pl: add a validate command Sometimes, we just want the parser to retrieve all symbols from ABI, in order to check for parsing errors. So, add a new "validate" command. While here, update the man/help pages. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index c5038a0a7313..774e9b809ead 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -25,7 +25,7 @@ pod2usage(2) if (scalar @ARGV < 1 || @ARGV > 2); my ($cmd, $arg) = @ARGV; -pod2usage(2) if ($cmd ne "search" && $cmd ne "rest"); +pod2usage(2) if ($cmd ne "search" && $cmd ne "rest" && $cmd ne "validate"); pod2usage(2) if ($cmd eq "search" && !$arg); require Data::Dumper if ($debug); @@ -82,7 +82,7 @@ sub parse_abi { my $sep = $2; my $content = $3; - if (!($new_tag =~ m/(what|date|kernelversion|contact|description|users)/)) { + if (!($new_tag =~ m/(what|where|date|kernelversion|contact|description|users)/)) { if ($tag eq "description") { # New "tag" is actually part of # description. Don't consider it a tag @@ -368,7 +368,7 @@ print STDERR Data::Dumper->Dump([\%data], [qw(*data)]) if ($debug); # if ($cmd eq "rest") { output_rest; -} else { +} elsif ($cmd eq "search") { search_symbols; } @@ -381,7 +381,7 @@ abi_book.pl - parse the Linux ABI files and produce a ReST book. =head1 SYNOPSIS -B [--debug] [] +B [--debug] [--man] [--help] [--dir=] [] Where can be: @@ -389,7 +389,9 @@ Where can be: B [SEARCH_REGEX] - search for [SEARCH_REGEX] inside ABI -B - output the ABI in ReST markup language +B - output the ABI in ReST markup language + +B - validate the ABI contents =back @@ -451,11 +453,11 @@ $ scripts/get_abi.pl rest --dir Documentation/ABI/obsolete =head1 BUGS -Report bugs to Mauro Carvalho Chehab +Report bugs to Mauro Carvalho Chehab =head1 COPYRIGHT -Copyright (c) 2016-2017 by Mauro Carvalho Chehab . +Copyright (c) 2016-2019 by Mauro Carvalho Chehab . License GPLv2: GNU GPL version 2 . -- cgit v1.2.3 From ecb351f1c4475d11ce6b4fa443fe71764027d409 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 20 Jun 2019 14:23:10 -0300 Subject: doc: ABI scripts: add a SPDX header file released under GPL v2. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 1 + 1 file changed, 1 insertion(+) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index 774e9b809ead..c738cb795514 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -1,4 +1,5 @@ #!/usr/bin/perl +# SPDX-License-Identifier: GPL-2.0 use strict; use Pod::Usage; -- cgit v1.2.3 From 12869ecd5eef299cf3745bbeb9c6ce37f3b52cb3 Mon Sep 17 00:00:00 2001 From: Rob Herring Date: Fri, 21 Jun 2019 08:18:32 -0600 Subject: scripts/dtc: Update to upstream version v1.5.0-30-g702c1b6c0e73 Pull in SPDX tag conversion from upstream dtc. This will replace the conversion done in the kernel tree copy in v5.2-rc2. This adds the following commits from upstream: 702c1b6c0e73 README.license: Update to reflect SPDX tag usage 4097bbffcf1d dtc: Add GPLv2 SPDX tags to files missing license text 94f87cd5b7c5 libfdt: Add dual GPL/BSD SPDX tags to files missing license text c4ffc05574b1 tests: Replace license boilerplate with SPDX tags a5ac29baacd2 pylibfdt: Replace dual GPLv2/BSD license boilerplate with SPDX tags 7fb0f4db2eb7 libfdt: Replace GPL/BSD boilerplate/reference with SPDX tags acfe84f2c47e dtc: Replace GPLv2 boilerplate/reference with SPDX tags Reviewed-by: Greg Kroah-Hartman Signed-off-by: Rob Herring --- scripts/dtc/Makefile.dtc | 1 + scripts/dtc/checks.c | 17 +------------ scripts/dtc/data.c | 17 +------------ scripts/dtc/dtc-lexer.l | 17 +------------ scripts/dtc/dtc-parser.y | 17 +------------ scripts/dtc/dtc.c | 17 +------------ scripts/dtc/dtc.h | 17 +------------ scripts/dtc/flattree.c | 17 +------------ scripts/dtc/fstree.c | 17 +------------ scripts/dtc/libfdt/Makefile.libfdt | 1 + scripts/dtc/libfdt/fdt.c | 47 +----------------------------------- scripts/dtc/libfdt/fdt.h | 47 +----------------------------------- scripts/dtc/libfdt/fdt_addresses.c | 47 +----------------------------------- scripts/dtc/libfdt/fdt_empty_tree.c | 47 +----------------------------------- scripts/dtc/libfdt/fdt_overlay.c | 47 +----------------------------------- scripts/dtc/libfdt/fdt_ro.c | 47 +----------------------------------- scripts/dtc/libfdt/fdt_rw.c | 47 +----------------------------------- scripts/dtc/libfdt/fdt_strerror.c | 46 +---------------------------------- scripts/dtc/libfdt/fdt_sw.c | 47 +----------------------------------- scripts/dtc/libfdt/fdt_wip.c | 47 +----------------------------------- scripts/dtc/libfdt/libfdt.h | 47 +----------------------------------- scripts/dtc/libfdt/libfdt_env.h | 47 +----------------------------------- scripts/dtc/libfdt/libfdt_internal.h | 47 +----------------------------------- scripts/dtc/livetree.c | 17 +------------ scripts/dtc/srcpos.c | 16 +----------- scripts/dtc/srcpos.h | 16 +----------- scripts/dtc/treesource.c | 17 +------------ scripts/dtc/util.c | 16 +----------- scripts/dtc/util.h | 16 +----------- scripts/dtc/version_gen.h | 2 +- scripts/dtc/yamltree.c | 16 +----------- 31 files changed, 31 insertions(+), 833 deletions(-) (limited to 'scripts') diff --git a/scripts/dtc/Makefile.dtc b/scripts/dtc/Makefile.dtc index d4375630a7f7..9c467b096f03 100644 --- a/scripts/dtc/Makefile.dtc +++ b/scripts/dtc/Makefile.dtc @@ -1,3 +1,4 @@ +# SPDX-License-Identifier: GPL-2.0-or-later # Makefile.dtc # # This is not a complete Makefile of itself. Instead, it is designed to diff --git a/scripts/dtc/checks.c b/scripts/dtc/checks.c index 4719d658432b..d7986ee18012 100644 --- a/scripts/dtc/checks.c +++ b/scripts/dtc/checks.c @@ -1,21 +1,6 @@ +// SPDX-License-Identifier: GPL-2.0-or-later /* * (C) Copyright David Gibson , IBM Corporation. 2007. - * - * - * This program is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License as - * published by the Free Software Foundation; either version 2 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 - * USA */ #include "dtc.h" diff --git a/scripts/dtc/data.c b/scripts/dtc/data.c index 4a204145cc7b..0a43b6de3264 100644 --- a/scripts/dtc/data.c +++ b/scripts/dtc/data.c @@ -1,21 +1,6 @@ +// SPDX-License-Identifier: GPL-2.0-or-later /* * (C) Copyright David Gibson , IBM Corporation. 2005. - * - * - * This program is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License as - * published by the Free Software Foundation; either version 2 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 - * USA */ #include "dtc.h" diff --git a/scripts/dtc/dtc-lexer.l b/scripts/dtc/dtc-lexer.l index 06c040902444..5c6c3fd557d7 100644 --- a/scripts/dtc/dtc-lexer.l +++ b/scripts/dtc/dtc-lexer.l @@ -1,21 +1,6 @@ +/* SPDX-License-Identifier: GPL-2.0-or-later */ /* * (C) Copyright David Gibson , IBM Corporation. 2005. - * - * - * This program is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License as - * published by the Free Software Foundation; either version 2 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 - * USA */ %option noyywrap nounput noinput never-interactive diff --git a/scripts/dtc/dtc-parser.y b/scripts/dtc/dtc-parser.y index 2ec981e86111..2ed4dc1f07fd 100644 --- a/scripts/dtc/dtc-parser.y +++ b/scripts/dtc/dtc-parser.y @@ -1,21 +1,6 @@ +// SPDX-License-Identifier: GPL-2.0-or-later /* * (C) Copyright David Gibson , IBM Corporation. 2005. - * - * - * This program is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License as - * published by the Free Software Foundation; either version 2 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 - * USA */ %{ #include diff --git a/scripts/dtc/dtc.c b/scripts/dtc/dtc.c index 695e1f789fc7..bdb3f5945699 100644 --- a/scripts/dtc/dtc.c +++ b/scripts/dtc/dtc.c @@ -1,21 +1,6 @@ +// SPDX-License-Identifier: GPL-2.0-or-later /* * (C) Copyright David Gibson , IBM Corporation. 2005. - * - * - * This program is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License as - * published by the Free Software Foundation; either version 2 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 - * USA */ #include diff --git a/scripts/dtc/dtc.h b/scripts/dtc/dtc.h index 0d5fa215ac87..6e74ecea55a3 100644 --- a/scripts/dtc/dtc.h +++ b/scripts/dtc/dtc.h @@ -1,24 +1,9 @@ +/* SPDX-License-Identifier: GPL-2.0-or-later */ #ifndef DTC_H #define DTC_H /* * (C) Copyright David Gibson , IBM Corporation. 2005. - * - * - * This program is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License as - * published by the Free Software Foundation; either version 2 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 - * USA */ #include diff --git a/scripts/dtc/flattree.c b/scripts/dtc/flattree.c index f7f70769d73f..bd6977eedcb8 100644 --- a/scripts/dtc/flattree.c +++ b/scripts/dtc/flattree.c @@ -1,21 +1,6 @@ +// SPDX-License-Identifier: GPL-2.0-or-later /* * (C) Copyright David Gibson , IBM Corporation. 2005. - * - * - * This program is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License as - * published by the Free Software Foundation; either version 2 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 - * USA */ #include "dtc.h" diff --git a/scripts/dtc/fstree.c b/scripts/dtc/fstree.c index 1e7eeba47ff6..9871689b4afb 100644 --- a/scripts/dtc/fstree.c +++ b/scripts/dtc/fstree.c @@ -1,21 +1,6 @@ +// SPDX-License-Identifier: GPL-2.0-or-later /* * (C) Copyright David Gibson , IBM Corporation. 2005. - * - * - * This program is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License as - * published by the Free Software Foundation; either version 2 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 - * USA */ #include "dtc.h" diff --git a/scripts/dtc/libfdt/Makefile.libfdt b/scripts/dtc/libfdt/Makefile.libfdt index 193da8c99d83..e54639738c8e 100644 --- a/scripts/dtc/libfdt/Makefile.libfdt +++ b/scripts/dtc/libfdt/Makefile.libfdt @@ -1,3 +1,4 @@ +# SPDX-License-Identifier: (GPL-2.0-or-later OR BSD-2-Clause) # Makefile.libfdt # # This is not a complete Makefile of itself. Instead, it is designed to diff --git a/scripts/dtc/libfdt/fdt.c b/scripts/dtc/libfdt/fdt.c index ae03b1112961..179168ec63e9 100644 --- a/scripts/dtc/libfdt/fdt.c +++ b/scripts/dtc/libfdt/fdt.c @@ -1,52 +1,7 @@ +// SPDX-License-Identifier: (GPL-2.0-or-later OR BSD-2-Clause) /* * libfdt - Flat Device Tree manipulation * Copyright (C) 2006 David Gibson, IBM Corporation. - * - * libfdt is dual licensed: you can use it either under the terms of - * the GPL, or the BSD license, at your option. - * - * a) This library is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License as - * published by the Free Software Foundation; either version 2 of the - * License, or (at your option) any later version. - * - * This library is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public - * License along with this library; if not, write to the Free - * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, - * MA 02110-1301 USA - * - * Alternatively, - * - * b) Redistribution and use in source and binary forms, with or - * without modification, are permitted provided that the following - * conditions are met: - * - * 1. Redistributions of source code must retain the above - * copyright notice, this list of conditions and the following - * disclaimer. - * 2. Redistributions in binary form must reproduce the above - * copyright notice, this list of conditions and the following - * disclaimer in the documentation and/or other materials - * provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND - * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, - * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF - * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR - * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT - * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; - * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR - * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, - * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ #include "libfdt_env.h" diff --git a/scripts/dtc/libfdt/fdt.h b/scripts/dtc/libfdt/fdt.h index 74961f9026d1..f2e68807f277 100644 --- a/scripts/dtc/libfdt/fdt.h +++ b/scripts/dtc/libfdt/fdt.h @@ -1,55 +1,10 @@ +/* SPDX-License-Identifier: (GPL-2.0-or-later OR BSD-2-Clause) */ #ifndef FDT_H #define FDT_H /* * libfdt - Flat Device Tree manipulation * Copyright (C) 2006 David Gibson, IBM Corporation. * Copyright 2012 Kim Phillips, Freescale Semiconductor. - * - * libfdt is dual licensed: you can use it either under the terms of - * the GPL, or the BSD license, at your option. - * - * a) This library is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License as - * published by the Free Software Foundation; either version 2 of the - * License, or (at your option) any later version. - * - * This library is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public - * License along with this library; if not, write to the Free - * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, - * MA 02110-1301 USA - * - * Alternatively, - * - * b) Redistribution and use in source and binary forms, with or - * without modification, are permitted provided that the following - * conditions are met: - * - * 1. Redistributions of source code must retain the above - * copyright notice, this list of conditions and the following - * disclaimer. - * 2. Redistributions in binary form must reproduce the above - * copyright notice, this list of conditions and the following - * disclaimer in the documentation and/or other materials - * provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND - * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, - * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF - * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR - * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT - * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; - * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR - * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, - * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ #ifndef __ASSEMBLY__ diff --git a/scripts/dtc/libfdt/fdt_addresses.c b/scripts/dtc/libfdt/fdt_addresses.c index 2cc997ea5012..d8ba8ec60c6c 100644 --- a/scripts/dtc/libfdt/fdt_addresses.c +++ b/scripts/dtc/libfdt/fdt_addresses.c @@ -1,53 +1,8 @@ +// SPDX-License-Identifier: (GPL-2.0-or-later OR BSD-2-Clause) /* * libfdt - Flat Device Tree manipulation * Copyright (C) 2014 David Gibson * Copyright (C) 2018 embedded brains GmbH - * - * libfdt is dual licensed: you can use it either under the terms of - * the GPL, or the BSD license, at your option. - * - * a) This library is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License as - * published by the Free Software Foundation; either version 2 of the - * License, or (at your option) any later version. - * - * This library is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public - * License along with this library; if not, write to the Free - * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, - * MA 02110-1301 USA - * - * Alternatively, - * - * b) Redistribution and use in source and binary forms, with or - * without modification, are permitted provided that the following - * conditions are met: - * - * 1. Redistributions of source code must retain the above - * copyright notice, this list of conditions and the following - * disclaimer. - * 2. Redistributions in binary form must reproduce the above - * copyright notice, this list of conditions and the following - * disclaimer in the documentation and/or other materials - * provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND - * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, - * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF - * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR - * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT - * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; - * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR - * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, - * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ #include "libfdt_env.h" diff --git a/scripts/dtc/libfdt/fdt_empty_tree.c b/scripts/dtc/libfdt/fdt_empty_tree.c index f2ae9b77c285..49d54d44b8e7 100644 --- a/scripts/dtc/libfdt/fdt_empty_tree.c +++ b/scripts/dtc/libfdt/fdt_empty_tree.c @@ -1,52 +1,7 @@ +// SPDX-License-Identifier: (GPL-2.0-or-later OR BSD-2-Clause) /* * libfdt - Flat Device Tree manipulation * Copyright (C) 2012 David Gibson, IBM Corporation. - * - * libfdt is dual licensed: you can use it either under the terms of - * the GPL, or the BSD license, at your option. - * - * a) This library is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License as - * published by the Free Software Foundation; either version 2 of the - * License, or (at your option) any later version. - * - * This library is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public - * License along with this library; if not, write to the Free - * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, - * MA 02110-1301 USA - * - * Alternatively, - * - * b) Redistribution and use in source and binary forms, with or - * without modification, are permitted provided that the following - * conditions are met: - * - * 1. Redistributions of source code must retain the above - * copyright notice, this list of conditions and the following - * disclaimer. - * 2. Redistributions in binary form must reproduce the above - * copyright notice, this list of conditions and the following - * disclaimer in the documentation and/or other materials - * provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND - * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, - * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF - * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR - * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT - * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; - * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR - * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, - * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ #include "libfdt_env.h" diff --git a/scripts/dtc/libfdt/fdt_overlay.c b/scripts/dtc/libfdt/fdt_overlay.c index d3e9ab2dbb7b..e97f12b1a780 100644 --- a/scripts/dtc/libfdt/fdt_overlay.c +++ b/scripts/dtc/libfdt/fdt_overlay.c @@ -1,53 +1,8 @@ +// SPDX-License-Identifier: (GPL-2.0-or-later OR BSD-2-Clause) /* * libfdt - Flat Device Tree manipulation * Copyright (C) 2016 Free Electrons * Copyright (C) 2016 NextThing Co. - * - * libfdt is dual licensed: you can use it either under the terms of - * the GPL, or the BSD license, at your option. - * - * a) This library is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License as - * published by the Free Software Foundation; either version 2 of the - * License, or (at your option) any later version. - * - * This library is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public - * License along with this library; if not, write to the Free - * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, - * MA 02110-1301 USA - * - * Alternatively, - * - * b) Redistribution and use in source and binary forms, with or - * without modification, are permitted provided that the following - * conditions are met: - * - * 1. Redistributions of source code must retain the above - * copyright notice, this list of conditions and the following - * disclaimer. - * 2. Redistributions in binary form must reproduce the above - * copyright notice, this list of conditions and the following - * disclaimer in the documentation and/or other materials - * provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND - * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, - * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF - * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR - * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT - * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; - * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR - * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, - * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ #include "libfdt_env.h" diff --git a/scripts/dtc/libfdt/fdt_ro.c b/scripts/dtc/libfdt/fdt_ro.c index 2c393a100bfc..6fd9ec170dbe 100644 --- a/scripts/dtc/libfdt/fdt_ro.c +++ b/scripts/dtc/libfdt/fdt_ro.c @@ -1,52 +1,7 @@ +// SPDX-License-Identifier: (GPL-2.0-or-later OR BSD-2-Clause) /* * libfdt - Flat Device Tree manipulation * Copyright (C) 2006 David Gibson, IBM Corporation. - * - * libfdt is dual licensed: you can use it either under the terms of - * the GPL, or the BSD license, at your option. - * - * a) This library is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License as - * published by the Free Software Foundation; either version 2 of the - * License, or (at your option) any later version. - * - * This library is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public - * License along with this library; if not, write to the Free - * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, - * MA 02110-1301 USA - * - * Alternatively, - * - * b) Redistribution and use in source and binary forms, with or - * without modification, are permitted provided that the following - * conditions are met: - * - * 1. Redistributions of source code must retain the above - * copyright notice, this list of conditions and the following - * disclaimer. - * 2. Redistributions in binary form must reproduce the above - * copyright notice, this list of conditions and the following - * disclaimer in the documentation and/or other materials - * provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND - * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, - * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF - * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR - * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT - * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; - * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR - * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, - * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ #include "libfdt_env.h" diff --git a/scripts/dtc/libfdt/fdt_rw.c b/scripts/dtc/libfdt/fdt_rw.c index 9e7661509e9f..8795947c00dd 100644 --- a/scripts/dtc/libfdt/fdt_rw.c +++ b/scripts/dtc/libfdt/fdt_rw.c @@ -1,52 +1,7 @@ +// SPDX-License-Identifier: (GPL-2.0-or-later OR BSD-2-Clause) /* * libfdt - Flat Device Tree manipulation * Copyright (C) 2006 David Gibson, IBM Corporation. - * - * libfdt is dual licensed: you can use it either under the terms of - * the GPL, or the BSD license, at your option. - * - * a) This library is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License as - * published by the Free Software Foundation; either version 2 of the - * License, or (at your option) any later version. - * - * This library is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public - * License along with this library; if not, write to the Free - * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, - * MA 02110-1301 USA - * - * Alternatively, - * - * b) Redistribution and use in source and binary forms, with or - * without modification, are permitted provided that the following - * conditions are met: - * - * 1. Redistributions of source code must retain the above - * copyright notice, this list of conditions and the following - * disclaimer. - * 2. Redistributions in binary form must reproduce the above - * copyright notice, this list of conditions and the following - * disclaimer in the documentation and/or other materials - * provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND - * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, - * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF - * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR - * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT - * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; - * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR - * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, - * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ #include "libfdt_env.h" diff --git a/scripts/dtc/libfdt/fdt_strerror.c b/scripts/dtc/libfdt/fdt_strerror.c index 0e6b4fd5e7ce..768db66eada5 100644 --- a/scripts/dtc/libfdt/fdt_strerror.c +++ b/scripts/dtc/libfdt/fdt_strerror.c @@ -1,51 +1,7 @@ +// SPDX-License-Identifier: (GPL-2.0-or-later OR BSD-2-Clause) /* * libfdt - Flat Device Tree manipulation * Copyright (C) 2006 David Gibson, IBM Corporation. - * - * libfdt is dual licensed: you can use it either under the terms of - * the GPL, or the BSD license, at your option. - * - * a) This library is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License as - * published by the Free Software Foundation; either version 2 of the - * License, or (at your option) any later version. - * - * This library is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public - * License along with this library; if not, write to the Free - * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, - * MA 02110-1301 USA - * - * Alternatively, - * - * b) Redistribution and use in source and binary forms, with or - * without modification, are permitted provided that the following - * conditions are met: - * - * 1. Redistributions of source code must retain the above - * copyright notice, this list of conditions and the following - * disclaimer. - * 2. Redistributions in binary form must reproduce the above - * copyright notice, this list of conditions and the following - * disclaimer in the documentation and/or other materials - * provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND - * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, - * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF - * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR - * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT - * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; - * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR - * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ #include "libfdt_env.h" diff --git a/scripts/dtc/libfdt/fdt_sw.c b/scripts/dtc/libfdt/fdt_sw.c index e773157d0fc4..76bea22f734f 100644 --- a/scripts/dtc/libfdt/fdt_sw.c +++ b/scripts/dtc/libfdt/fdt_sw.c @@ -1,52 +1,7 @@ +// SPDX-License-Identifier: (GPL-2.0-or-later OR BSD-2-Clause) /* * libfdt - Flat Device Tree manipulation * Copyright (C) 2006 David Gibson, IBM Corporation. - * - * libfdt is dual licensed: you can use it either under the terms of - * the GPL, or the BSD license, at your option. - * - * a) This library is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License as - * published by the Free Software Foundation; either version 2 of the - * License, or (at your option) any later version. - * - * This library is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public - * License along with this library; if not, write to the Free - * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, - * MA 02110-1301 USA - * - * Alternatively, - * - * b) Redistribution and use in source and binary forms, with or - * without modification, are permitted provided that the following - * conditions are met: - * - * 1. Redistributions of source code must retain the above - * copyright notice, this list of conditions and the following - * disclaimer. - * 2. Redistributions in binary form must reproduce the above - * copyright notice, this list of conditions and the following - * disclaimer in the documentation and/or other materials - * provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND - * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, - * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF - * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR - * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT - * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; - * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR - * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, - * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ #include "libfdt_env.h" diff --git a/scripts/dtc/libfdt/fdt_wip.c b/scripts/dtc/libfdt/fdt_wip.c index 534c1cbbb2f3..f64139e0b3dc 100644 --- a/scripts/dtc/libfdt/fdt_wip.c +++ b/scripts/dtc/libfdt/fdt_wip.c @@ -1,52 +1,7 @@ +// SPDX-License-Identifier: (GPL-2.0-or-later OR BSD-2-Clause) /* * libfdt - Flat Device Tree manipulation * Copyright (C) 2006 David Gibson, IBM Corporation. - * - * libfdt is dual licensed: you can use it either under the terms of - * the GPL, or the BSD license, at your option. - * - * a) This library is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License as - * published by the Free Software Foundation; either version 2 of the - * License, or (at your option) any later version. - * - * This library is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public - * License along with this library; if not, write to the Free - * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, - * MA 02110-1301 USA - * - * Alternatively, - * - * b) Redistribution and use in source and binary forms, with or - * without modification, are permitted provided that the following - * conditions are met: - * - * 1. Redistributions of source code must retain the above - * copyright notice, this list of conditions and the following - * disclaimer. - * 2. Redistributions in binary form must reproduce the above - * copyright notice, this list of conditions and the following - * disclaimer in the documentation and/or other materials - * provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND - * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, - * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF - * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR - * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT - * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; - * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR - * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, - * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ #include "libfdt_env.h" diff --git a/scripts/dtc/libfdt/libfdt.h b/scripts/dtc/libfdt/libfdt.h index be14bf63e577..7b5ffd13a887 100644 --- a/scripts/dtc/libfdt/libfdt.h +++ b/scripts/dtc/libfdt/libfdt.h @@ -1,54 +1,9 @@ +/* SPDX-License-Identifier: (GPL-2.0-or-later OR BSD-2-Clause) */ #ifndef LIBFDT_H #define LIBFDT_H /* * libfdt - Flat Device Tree manipulation * Copyright (C) 2006 David Gibson, IBM Corporation. - * - * libfdt is dual licensed: you can use it either under the terms of - * the GPL, or the BSD license, at your option. - * - * a) This library is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License as - * published by the Free Software Foundation; either version 2 of the - * License, or (at your option) any later version. - * - * This library is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public - * License along with this library; if not, write to the Free - * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, - * MA 02110-1301 USA - * - * Alternatively, - * - * b) Redistribution and use in source and binary forms, with or - * without modification, are permitted provided that the following - * conditions are met: - * - * 1. Redistributions of source code must retain the above - * copyright notice, this list of conditions and the following - * disclaimer. - * 2. Redistributions in binary form must reproduce the above - * copyright notice, this list of conditions and the following - * disclaimer in the documentation and/or other materials - * provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND - * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, - * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF - * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR - * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT - * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; - * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR - * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, - * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ #include "libfdt_env.h" diff --git a/scripts/dtc/libfdt/libfdt_env.h b/scripts/dtc/libfdt/libfdt_env.h index 4d1cdfa58547..73b6d40450ac 100644 --- a/scripts/dtc/libfdt/libfdt_env.h +++ b/scripts/dtc/libfdt/libfdt_env.h @@ -1,55 +1,10 @@ +/* SPDX-License-Identifier: (GPL-2.0-or-later OR BSD-2-Clause) */ #ifndef LIBFDT_ENV_H #define LIBFDT_ENV_H /* * libfdt - Flat Device Tree manipulation * Copyright (C) 2006 David Gibson, IBM Corporation. * Copyright 2012 Kim Phillips, Freescale Semiconductor. - * - * libfdt is dual licensed: you can use it either under the terms of - * the GPL, or the BSD license, at your option. - * - * a) This library is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License as - * published by the Free Software Foundation; either version 2 of the - * License, or (at your option) any later version. - * - * This library is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public - * License along with this library; if not, write to the Free - * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, - * MA 02110-1301 USA - * - * Alternatively, - * - * b) Redistribution and use in source and binary forms, with or - * without modification, are permitted provided that the following - * conditions are met: - * - * 1. Redistributions of source code must retain the above - * copyright notice, this list of conditions and the following - * disclaimer. - * 2. Redistributions in binary form must reproduce the above - * copyright notice, this list of conditions and the following - * disclaimer in the documentation and/or other materials - * provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND - * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, - * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF - * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR - * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT - * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; - * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR - * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, - * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ #include diff --git a/scripts/dtc/libfdt/libfdt_internal.h b/scripts/dtc/libfdt/libfdt_internal.h index 4109f890ae60..7830e550c37a 100644 --- a/scripts/dtc/libfdt/libfdt_internal.h +++ b/scripts/dtc/libfdt/libfdt_internal.h @@ -1,54 +1,9 @@ +/* SPDX-License-Identifier: (GPL-2.0-or-later OR BSD-2-Clause) */ #ifndef LIBFDT_INTERNAL_H #define LIBFDT_INTERNAL_H /* * libfdt - Flat Device Tree manipulation * Copyright (C) 2006 David Gibson, IBM Corporation. - * - * libfdt is dual licensed: you can use it either under the terms of - * the GPL, or the BSD license, at your option. - * - * a) This library is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License as - * published by the Free Software Foundation; either version 2 of the - * License, or (at your option) any later version. - * - * This library is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public - * License along with this library; if not, write to the Free - * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, - * MA 02110-1301 USA - * - * Alternatively, - * - * b) Redistribution and use in source and binary forms, with or - * without modification, are permitted provided that the following - * conditions are met: - * - * 1. Redistributions of source code must retain the above - * copyright notice, this list of conditions and the following - * disclaimer. - * 2. Redistributions in binary form must reproduce the above - * copyright notice, this list of conditions and the following - * disclaimer in the documentation and/or other materials - * provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND - * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, - * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF - * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR - * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT - * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; - * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR - * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, - * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ #include diff --git a/scripts/dtc/livetree.c b/scripts/dtc/livetree.c index 21c274125c2c..0c039993953a 100644 --- a/scripts/dtc/livetree.c +++ b/scripts/dtc/livetree.c @@ -1,21 +1,6 @@ +// SPDX-License-Identifier: GPL-2.0-or-later /* * (C) Copyright David Gibson , IBM Corporation. 2005. - * - * - * This program is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License as - * published by the Free Software Foundation; either version 2 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 - * USA */ #include "dtc.h" diff --git a/scripts/dtc/srcpos.c b/scripts/dtc/srcpos.c index 41f83700ee91..f5205fb9c1ff 100644 --- a/scripts/dtc/srcpos.c +++ b/scripts/dtc/srcpos.c @@ -1,20 +1,6 @@ +// SPDX-License-Identifier: GPL-2.0-or-later /* * Copyright 2007 Jon Loeliger, Freescale Semiconductor, Inc. - * - * This program is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License as - * published by the Free Software Foundation; either version 2 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 - * USA */ #define _GNU_SOURCE diff --git a/scripts/dtc/srcpos.h b/scripts/dtc/srcpos.h index 6326a952c40e..4318d7ad34d9 100644 --- a/scripts/dtc/srcpos.h +++ b/scripts/dtc/srcpos.h @@ -1,20 +1,6 @@ +/* SPDX-License-Identifier: GPL-2.0-or-later */ /* * Copyright 2007 Jon Loeliger, Freescale Semiconductor, Inc. - * - * This program is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License as - * published by the Free Software Foundation; either version 2 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 - * USA */ #ifndef SRCPOS_H diff --git a/scripts/dtc/treesource.c b/scripts/dtc/treesource.c index 1af36628b75f..c9d980c8abfc 100644 --- a/scripts/dtc/treesource.c +++ b/scripts/dtc/treesource.c @@ -1,21 +1,6 @@ +// SPDX-License-Identifier: GPL-2.0-or-later /* * (C) Copyright David Gibson , IBM Corporation. 2005. - * - * - * This program is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License as - * published by the Free Software Foundation; either version 2 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 - * USA */ #include "dtc.h" diff --git a/scripts/dtc/util.c b/scripts/dtc/util.c index 9c6fb5f286ae..48af961dcc8c 100644 --- a/scripts/dtc/util.c +++ b/scripts/dtc/util.c @@ -1,24 +1,10 @@ +// SPDX-License-Identifier: GPL-2.0-or-later /* * Copyright 2011 The Chromium Authors, All Rights Reserved. * Copyright 2008 Jon Loeliger, Freescale Semiconductor, Inc. * * util_is_printable_string contributed by * Pantelis Antoniou - * - * This program is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License as - * published by the Free Software Foundation; either version 2 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 - * USA */ #include diff --git a/scripts/dtc/util.h b/scripts/dtc/util.h index fc3c0d05ada3..ca5cb52928e3 100644 --- a/scripts/dtc/util.h +++ b/scripts/dtc/util.h @@ -1,3 +1,4 @@ +/* SPDX-License-Identifier: GPL-2.0-or-later */ #ifndef UTIL_H #define UTIL_H @@ -8,21 +9,6 @@ /* * Copyright 2011 The Chromium Authors, All Rights Reserved. * Copyright 2008 Jon Loeliger, Freescale Semiconductor, Inc. - * - * This program is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License as - * published by the Free Software Foundation; either version 2 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 - * USA */ #ifdef __GNUC__ diff --git a/scripts/dtc/version_gen.h b/scripts/dtc/version_gen.h index 2111a6e351f9..f2761e24cf40 100644 --- a/scripts/dtc/version_gen.h +++ b/scripts/dtc/version_gen.h @@ -1 +1 @@ -#define DTC_VERSION "DTC 1.5.0-g87963ee2" +#define DTC_VERSION "DTC 1.5.0-g702c1b6c" diff --git a/scripts/dtc/yamltree.c b/scripts/dtc/yamltree.c index a00285a5a9ec..5b6ea8ea862f 100644 --- a/scripts/dtc/yamltree.c +++ b/scripts/dtc/yamltree.c @@ -1,22 +1,8 @@ +// SPDX-License-Identifier: GPL-2.0-or-later /* * (C) Copyright Linaro, Ltd. 2018 * (C) Copyright Arm Holdings. 2017 * (C) Copyright David Gibson , IBM Corporation. 2005. - * - * This program is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License as - * published by the Free Software Foundation; either version 2 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 - * USA */ #include -- cgit v1.2.3 From 3a61925e91ba9f0ece1b444eb1aa49caa59e4ae7 Mon Sep 17 00:00:00 2001 From: Nathan Chancellor Date: Fri, 14 Jun 2019 09:52:42 -0700 Subject: kbuild: Enable -Wuninitialized This helps fine very dodgy behavior through both -Wuninitialized (warning that a variable is always uninitialized) and -Wsometimes-uninitialized (warning that a variable is sometimes uninitialized, like GCC's -Wmaybe-uninitialized). These warnings catch things that GCC doesn't such as: https://lore.kernel.org/lkml/86649ee4-9794-77a3-502c-f4cd10019c36@lca.pw/ We very much want to catch these so turn this warning on so that CI is aware of it. Link: https://github.com/ClangBuiltLinux/linux/issues/381 Signed-off-by: Nathan Chancellor Reviewed-by: Nick Desaulniers Signed-off-by: Masahiro Yamada --- scripts/Makefile.extrawarn | 1 - 1 file changed, 1 deletion(-) (limited to 'scripts') diff --git a/scripts/Makefile.extrawarn b/scripts/Makefile.extrawarn index 98081ab300e5..699683a7c116 100644 --- a/scripts/Makefile.extrawarn +++ b/scripts/Makefile.extrawarn @@ -71,6 +71,5 @@ KBUILD_CFLAGS += -Wno-unused-value KBUILD_CFLAGS += -Wno-format KBUILD_CFLAGS += -Wno-sign-compare KBUILD_CFLAGS += -Wno-format-zero-length -KBUILD_CFLAGS += -Wno-uninitialized endif endif -- cgit v1.2.3 From 4df607cc6fe8e46b258ff2a53d0a60ca3008ffc7 Mon Sep 17 00:00:00 2001 From: Nathan Huckleberry Date: Mon, 17 Jun 2019 10:28:29 -0700 Subject: kbuild: Remove unnecessary -Wno-unused-value This flag turns off several other warnings that would be useful. Most notably -warn_unused_result is disabled. All of the following warnings are currently disabled: UnusedValue |-UnusedComparison |-warn_unused_comparison |-UnusedResult |-warn_unused_result |-UnevaluatedExpression |-PotentiallyEvaluatedExpression |-warn_side_effects_typeid |-warn_side_effects_unevaluated_context |-warn_unused_expr |-warn_unused_voidptr |-warn_unused_container_subscript_expr |-warn_unused_call With this flag removed there are ~10 warnings. Patches have been submitted for each of these warnings. Reported-by: Nick Desaulniers Cc: clang-built-linux@googlegroups.com Link: https://github.com/ClangBuiltLinux/linux/issues/520 Signed-off-by: Nathan Huckleberry Reviewed-by: Nick Desaulniers Signed-off-by: Masahiro Yamada --- scripts/Makefile.extrawarn | 1 - 1 file changed, 1 deletion(-) (limited to 'scripts') diff --git a/scripts/Makefile.extrawarn b/scripts/Makefile.extrawarn index 699683a7c116..a74ce2e3c33e 100644 --- a/scripts/Makefile.extrawarn +++ b/scripts/Makefile.extrawarn @@ -67,7 +67,6 @@ else ifdef CONFIG_CC_IS_CLANG KBUILD_CFLAGS += -Wno-initializer-overrides -KBUILD_CFLAGS += -Wno-unused-value KBUILD_CFLAGS += -Wno-format KBUILD_CFLAGS += -Wno-sign-compare KBUILD_CFLAGS += -Wno-format-zero-length -- cgit v1.2.3 From a222061b85234d8a44486a46bd4df7e2cda52385 Mon Sep 17 00:00:00 2001 From: Will Deacon Date: Tue, 18 Jun 2019 14:10:48 +0100 Subject: genksyms: Teach parser about 128-bit built-in types __uint128_t crops up in a few files that export symbols to modules, so teach genksyms about it and the other GCC built-in 128-bit integer types so that we don't end up skipping the CRC generation for some symbols due to the parser failing to spot them: | WARNING: EXPORT symbol "kernel_neon_begin" [vmlinux] version | generation failed, symbol will not be versioned. | ld: arch/arm64/kernel/fpsimd.o: relocation R_AARCH64_ABS32 against | `__crc_kernel_neon_begin' can not be used when making a shared | object | ld: arch/arm64/kernel/fpsimd.o:(.data+0x0): dangerous relocation: | unsupported relocation Reported-by: Arnd Bergmann Signed-off-by: Will Deacon Signed-off-by: Masahiro Yamada --- scripts/genksyms/keywords.c | 4 ++++ scripts/genksyms/parse.y | 2 ++ 2 files changed, 6 insertions(+) (limited to 'scripts') diff --git a/scripts/genksyms/keywords.c b/scripts/genksyms/keywords.c index e93336baaaed..c586d32dd2c3 100644 --- a/scripts/genksyms/keywords.c +++ b/scripts/genksyms/keywords.c @@ -25,6 +25,10 @@ static struct resword { { "__volatile__", VOLATILE_KEYW }, { "__builtin_va_list", VA_LIST_KEYW }, + { "__int128", BUILTIN_INT_KEYW }, + { "__int128_t", BUILTIN_INT_KEYW }, + { "__uint128_t", BUILTIN_INT_KEYW }, + // According to rth, c99 defines "_Bool", __restrict", __restrict__", "restrict". KAO { "_Bool", BOOL_KEYW }, { "_restrict", RESTRICT_KEYW }, diff --git a/scripts/genksyms/parse.y b/scripts/genksyms/parse.y index 00a6d7e54971..1ebcf52cd0f9 100644 --- a/scripts/genksyms/parse.y +++ b/scripts/genksyms/parse.y @@ -76,6 +76,7 @@ static void record_compound(struct string_list **keyw, %token ATTRIBUTE_KEYW %token AUTO_KEYW %token BOOL_KEYW +%token BUILTIN_INT_KEYW %token CHAR_KEYW %token CONST_KEYW %token DOUBLE_KEYW @@ -263,6 +264,7 @@ simple_type_specifier: | VOID_KEYW | BOOL_KEYW | VA_LIST_KEYW + | BUILTIN_INT_KEYW | TYPE { (*$1)->tag = SYM_TYPEDEF; $$ = $1; } ; -- cgit v1.2.3 From 7ff4f0805eb5056662093b9886a819d2352e188b Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Sat, 22 Jun 2019 15:55:20 +0900 Subject: kbuild: fix 'No such file or directory' warning for headers_install MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Since commit d5470d14431e ("kbuild: re-implement Makefile.headersinst without recursion"), headers_install emits an ugly warning. $ make headers_install [ snip ] UPD include/generated/uapi/linux/version.h find: ‘./include/uapi/Kbuild’: No such file or directory HDRINST usr/include/video/uvesafb.h ... This happens for GNU Make <= 4.2.1 When I wrote that commit, I missed this warning because I was using the state-of-the-art Make version compiled from the git tree. $(wildcard $(src)/*/) is intended to match to only existing directories since it has a trailing slash, but actually matches to regular files too. (include/uapi/Kbuild in this case) This is a bug of GNU Make, and was fixed by: | commit b7acb10e86dc8f5fdf2a2bbd87e1059c315e31d6 | Author: spagoveanu@gmail.com | Date: Wed Jun 20 02:03:48 2018 +0300 | | * src/dir.c: Preserve glob d_type field We need to cater to old Make versions. Add '$(filter %/,...) to filter out the regular files. Fixes: d5470d14431e ("kbuild: re-implement Makefile.headersinst without recursion") Signed-off-by: Masahiro Yamada --- scripts/Makefile.headersinst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/Makefile.headersinst b/scripts/Makefile.headersinst index d2b572a7a628..1b405a7ed14f 100644 --- a/scripts/Makefile.headersinst +++ b/scripts/Makefile.headersinst @@ -20,8 +20,10 @@ dst := usr/include -include $(src)/Kbuild -src-subdirs := $(patsubst $(src)/%/,%,$(wildcard $(src)/*/)) -gen-subdirs := $(patsubst $(gen)/%/,%,$(wildcard $(gen)/*/)) +# $(filter %/, ...) is a workaround for GNU Make <= 4.2.1, where +# $(wildcard $(src)/*/) contains not only directories but also regular files. +src-subdirs := $(patsubst $(src)/%/,%,$(filter %/, $(wildcard $(src)/*/))) +gen-subdirs := $(patsubst $(gen)/%/,%,$(filter %/, $(wildcard $(gen)/*/))) all-subdirs := $(sort $(src-subdirs) $(gen-subdirs)) src-headers := $(if $(src-subdirs), $(shell cd $(src) && find $(src-subdirs) -name '*.h')) -- cgit v1.2.3 From 344fdb28a0dfac2e42925f149029748b34d2effa Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Fri, 21 Jun 2019 17:34:30 -0600 Subject: kernel-doc: Don't try to mark up function names We now have better automarkup in sphinx itself and, besides, this markup was incorrect and left :c:func: gunk in the processed docs. Sort of discouraging that nobody ever noticed...:) As a first step toward the removal of impenetrable regex magic from kernel-doc it's a tiny one, but you have to start somewhere. Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index c0cb41e65b9b..6b03012750da 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -249,7 +249,7 @@ my @highlights_rst = ( [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"], [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"], [$type_fp_param, "**\$1\\\\(\\\\)**"], - [$type_func, "\\:c\\:func\\:`\$1()`"], + [$type_func, "\$1()"], [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"], [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"], [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"], -- cgit v1.2.3 From 8c69b77a0175d6e14df9cdf386a8b69f6cfa2c6a Mon Sep 17 00:00:00 2001 From: Mike Rapoport Date: Mon, 24 Jun 2019 08:25:07 +0300 Subject: scripts/sphinx-pre-install: fix out-of-tree build Build of htmldocs fails for out-of-tree builds: $ make V=1 O=~/build/kernel/ htmldocs make -C /home/rppt/build/kernel -f /home/rppt/git/linux-docs/Makefile htmldocs make[1]: Entering directory '/home/rppt/build/kernel' make -f /home/rppt/git/linux-docs/scripts/Makefile.build obj=scripts/basic rm -f .tmp_quiet_recordmcount make -f /home/rppt/git/linux-docs/scripts/Makefile.build obj=Documentation htmldocs Can't open Documentation/conf.py at /home/rppt/git/linux-docs/scripts/sphinx-pre-install line 230. /home/rppt/git/linux-docs/Documentation/Makefile:80: recipe for target 'htmldocs' failed make[2]: *** [htmldocs] Error 2 The scripts/sphinx-pre-install is trying to open files in the current directory which is $KBUILD_OUTPUT rather than in $srctree. Fix it. Signed-off-by: Mike Rapoport Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/sphinx-pre-install | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index 0b44d51c4991..f230e65329a2 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -5,8 +5,11 @@ use strict; # Copyright (c) 2017-2019 Mauro Carvalho Chehab # -my $conf = "Documentation/conf.py"; -my $requirement_file = "Documentation/sphinx/requirements.txt"; +my $prefix = "./"; +$prefix = "$ENV{'srctree'}/" if ($ENV{'srctree'}); + +my $conf = $prefix . "Documentation/conf.py"; +my $requirement_file = $prefix . "Documentation/sphinx/requirements.txt"; my $virtenv_prefix = "sphinx_"; # -- cgit v1.2.3 From 50bcca6ac417bfd18fa84d45eeaa4a30155fe3c8 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Sun, 23 Jun 2019 01:07:03 +0900 Subject: kbuild: rename arg-check to cmd-check I prefer 'cmd-check' for consistency. We have 'echo-cmd', 'cmd', 'cmd_and_fixdep', etc. in this file. Signed-off-by: Masahiro Yamada --- scripts/Kbuild.include | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'scripts') diff --git a/scripts/Kbuild.include b/scripts/Kbuild.include index 0ae07e83d393..ee3fec40111e 100644 --- a/scripts/Kbuild.include +++ b/scripts/Kbuild.include @@ -207,12 +207,12 @@ objectify = $(foreach o,$(1),$(if $(filter /%,$(o)),$(o),$(obj)/$(o))) # See Documentation/kbuild/makefiles.txt for more info ifneq ($(KBUILD_NOCMDDEP),1) -# Check if both arguments are the same including their order. Result is empty +# Check if both commands are the same including their order. Result is empty # string if equal. User may override this check using make KBUILD_NOCMDDEP=1 -arg-check = $(filter-out $(subst $(space),$(space_escape),$(strip $(cmd_$@))), \ +cmd-check = $(filter-out $(subst $(space),$(space_escape),$(strip $(cmd_$@))), \ $(subst $(space),$(space_escape),$(strip $(cmd_$1)))) else -arg-check = $(if $(strip $(cmd_$@)),,1) +cmd-check = $(if $(strip $(cmd_$@)),,1) endif # Replace >$< with >$$< to preserve $ when reloading the .cmd file @@ -228,12 +228,12 @@ make-cmd = $(call escsq,$(subst $(pound),$$(pound),$(subst $$,$$$$,$(cmd_$(1)))) any-prereq = $(filter-out $(PHONY),$?) $(filter-out $(PHONY) $(wildcard $^),$^) # Execute command if command has changed or prerequisite(s) are updated. -if_changed = $(if $(strip $(any-prereq) $(arg-check)), \ +if_changed = $(if $(strip $(any-prereq) $(cmd-check)), \ $(cmd); \ printf '%s\n' 'cmd_$@ := $(make-cmd)' > $(dot-target).cmd, @:) # Execute the command and also postprocess generated .d dependencies file. -if_changed_dep = $(if $(strip $(any-prereq) $(arg-check)),$(cmd_and_fixdep),@:) +if_changed_dep = $(if $(strip $(any-prereq) $(cmd-check)),$(cmd_and_fixdep),@:) cmd_and_fixdep = \ $(cmd); \ @@ -243,7 +243,7 @@ cmd_and_fixdep = \ # Usage: $(call if_changed_rule,foo) # Will check if $(cmd_foo) or any of the prerequisites changed, # and if so will execute $(rule_foo). -if_changed_rule = $(if $(strip $(any-prereq) $(arg-check)),$(rule_$(1)),@:) +if_changed_rule = $(if $(strip $(any-prereq) $(cmd-check)),$(rule_$(1)),@:) ### # why - tell why a target got built @@ -269,7 +269,7 @@ why = \ $(if $(filter $@, $(PHONY)),- due to target is PHONY, \ $(if $(wildcard $@), \ $(if $(strip $(any-prereq)),- due to: $(any-prereq), \ - $(if $(arg-check), \ + $(if $(cmd-check), \ $(if $(cmd_$@),- due to command line change, \ $(if $(filter $@, $(targets)), \ - due to missing .cmd file, \ -- cgit v1.2.3 From 93f31bbda43603da1e8af06667b45b410c6c897a Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Sun, 23 Jun 2019 01:07:04 +0900 Subject: kbuild: save $(strip ...) for calling any-prepreq The string returned by $(filter-out ...) does not contain any leading or trailing spaces. So, only the space that matters is the one between $(filter-out $(PHONY),$?) and $(filter-out $(PHONY) $(wildcard $^),$^) By removing it from the code, we can save $(strip ...) evaluation. This refactoring is possible because $(any-prereq) is only passed to the first argument of $(if ...), so we are only interested in whether or not it is empty. This is also the prerequisite for the next commit. Signed-off-by: Masahiro Yamada --- scripts/Kbuild.include | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/Kbuild.include b/scripts/Kbuild.include index ee3fec40111e..6f9e88716ff4 100644 --- a/scripts/Kbuild.include +++ b/scripts/Kbuild.include @@ -225,7 +225,7 @@ make-cmd = $(call escsq,$(subst $(pound),$$(pound),$(subst $$,$$$$,$(cmd_$(1)))) # Find any prerequisites that is newer than target or that does not exist. # PHONY targets skipped in both cases. -any-prereq = $(filter-out $(PHONY),$?) $(filter-out $(PHONY) $(wildcard $^),$^) +any-prereq = $(filter-out $(PHONY),$?)$(filter-out $(PHONY) $(wildcard $^),$^) # Execute command if command has changed or prerequisite(s) are updated. if_changed = $(if $(strip $(any-prereq) $(cmd-check)), \ @@ -268,7 +268,7 @@ ifeq ($(KBUILD_VERBOSE),2) why = \ $(if $(filter $@, $(PHONY)),- due to target is PHONY, \ $(if $(wildcard $@), \ - $(if $(strip $(any-prereq)),- due to: $(any-prereq), \ + $(if $(any-prereq),- due to: $(any-prereq), \ $(if $(cmd-check), \ $(if $(cmd_$@),- due to command line change, \ $(if $(filter $@, $(targets)), \ -- cgit v1.2.3 From c2341e2a4f58d8e27d89c5edfefdaa52547f792d Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Sun, 23 Jun 2019 01:07:05 +0900 Subject: kbuild: save $(strip ...) for calling if_changed and friends The string returned by $(filter-out ...) does not contain any leading or trailing spaces. With the previous commit, 'any-prereq' no longer contains any excessive spaces. Nor does 'cmd-check' since it expands to a $(filter-out ...) call. So, only the space that matters is the one between 'any-prereq' and 'cmd-check'. By removing it from the code, we can save $(strip ...) evaluation. This refactoring is possible because $(any-prereq)$(cmd-check) is only passed to the first argument of $(if ...), so we are only interested in whether or not it is empty. Signed-off-by: Masahiro Yamada --- scripts/Kbuild.include | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'scripts') diff --git a/scripts/Kbuild.include b/scripts/Kbuild.include index 6f9e88716ff4..222fd1d7d3ae 100644 --- a/scripts/Kbuild.include +++ b/scripts/Kbuild.include @@ -228,12 +228,12 @@ make-cmd = $(call escsq,$(subst $(pound),$$(pound),$(subst $$,$$$$,$(cmd_$(1)))) any-prereq = $(filter-out $(PHONY),$?)$(filter-out $(PHONY) $(wildcard $^),$^) # Execute command if command has changed or prerequisite(s) are updated. -if_changed = $(if $(strip $(any-prereq) $(cmd-check)), \ +if_changed = $(if $(any-prereq)$(cmd-check), \ $(cmd); \ printf '%s\n' 'cmd_$@ := $(make-cmd)' > $(dot-target).cmd, @:) # Execute the command and also postprocess generated .d dependencies file. -if_changed_dep = $(if $(strip $(any-prereq) $(cmd-check)),$(cmd_and_fixdep),@:) +if_changed_dep = $(if $(any-prereq)$(cmd-check),$(cmd_and_fixdep),@:) cmd_and_fixdep = \ $(cmd); \ @@ -243,7 +243,7 @@ cmd_and_fixdep = \ # Usage: $(call if_changed_rule,foo) # Will check if $(cmd_foo) or any of the prerequisites changed, # and if so will execute $(rule_foo). -if_changed_rule = $(if $(strip $(any-prereq) $(cmd-check)),$(rule_$(1)),@:) +if_changed_rule = $(if $(any-prereq)$(cmd-check),$(rule_$(1)),@:) ### # why - tell why a target got built -- cgit v1.2.3 From 6f9ac9f4427ec0470ccffbf852cfaf326677cc21 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Tue, 25 Jun 2019 15:54:19 +0900 Subject: fixdep: check return value of printf() and putchar() When there is not enough space on your storage device, the build will fail with 'No space left on device' error message. The reason is obvious from the message, so you will free up some disk space, then you will resume the build. However, sometimes you may still see a mysterious error message: unterminated call to function 'wildcard': missing ')'. If you run out of the disk space, fixdep may end up with generating incomplete .*.cmd files. For example, if the disk-full error occurs while fixdep is running print_dep(), the .*.cmd might be truncated like this: $(wildcard include/config/ When you run 'make' next time, this broken .*.cmd will be included, then Make will terminate parsing since it is a wrong syntax. Once this happens, you need to run 'make clean' or delete the broken .*.cmd file manually. Even if you do not see any error message, the .*.cmd files after any error could be potentially incomplete, and unreliable. You may miss the re-compilation due to missing header dependency. If printf() cannot output the string for disk shortage or whatever reason, it returns a negative value, but currently fixdep does not check it at all. Consequently, fixdep *successfully* generates a broken .*.cmd file. Make never notices that since fixdep exits with 0, which means success. Given the intended usage of fixdep, it must respect the return value of not only malloc(), but also printf() and putchar(). This seems a long-standing issue since the introduction of fixdep. In old days, Kbuild tried to provide an extra safety by letting fixdep output to a temporary file and renaming it after everything is done: scripts/basic/fixdep $(depfile) $@ '$(make-cmd)' > $(dot-target).tmp;\ rm -f $(depfile); \ mv -f $(dot-target).tmp $(dot-target).cmd) It was no help to avoid the current issue; fixdep successfully created a truncated tmp file, which would be renamed to a .*.cmd file. This problem should be fixed by propagating the error status to the build system because: [1] Since commit 9c2af1c7377a ("kbuild: add .DELETE_ON_ERROR special target"), Make will delete the target automatically on any failure in the recipe. [2] Since commit 392885ee82d3 ("kbuild: let fixdep directly write to .*.cmd files"), .*.cmd file is included only when the corresponding target already exists. Signed-off-by: Masahiro Yamada --- scripts/basic/fixdep.c | 51 ++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 41 insertions(+), 10 deletions(-) (limited to 'scripts') diff --git a/scripts/basic/fixdep.c b/scripts/basic/fixdep.c index facbd603adf6..9ba47b0a47b9 100644 --- a/scripts/basic/fixdep.c +++ b/scripts/basic/fixdep.c @@ -99,6 +99,7 @@ #include #include #include +#include #include #include #include @@ -109,6 +110,36 @@ static void usage(void) exit(1); } +/* + * In the intended usage of this program, the stdout is redirected to .*.cmd + * files. The return value of printf() and putchar() must be checked to catch + * any error, e.g. "No space left on device". + */ +static void xprintf(const char *format, ...) +{ + va_list ap; + int ret; + + va_start(ap, format); + ret = vprintf(format, ap); + if (ret < 0) { + perror("fixdep"); + exit(1); + } + va_end(ap); +} + +static void xputchar(int c) +{ + int ret; + + ret = putchar(c); + if (ret == EOF) { + perror("fixdep"); + exit(1); + } +} + /* * Print out a dependency path from a symbol name */ @@ -116,7 +147,7 @@ static void print_dep(const char *m, int slen, const char *dir) { int c, prev_c = '/', i; - printf(" $(wildcard %s/", dir); + xprintf(" $(wildcard %s/", dir); for (i = 0; i < slen; i++) { c = m[i]; if (c == '_') @@ -124,10 +155,10 @@ static void print_dep(const char *m, int slen, const char *dir) else c = tolower(c); if (c != '/' || prev_c != '/') - putchar(c); + xputchar(c); prev_c = c; } - printf(".h) \\\n"); + xprintf(".h) \\\n"); } struct item { @@ -324,13 +355,13 @@ static void parse_dep_file(char *m, const char *target) */ if (!saw_any_target) { saw_any_target = 1; - printf("source_%s := %s\n\n", - target, m); - printf("deps_%s := \\\n", target); + xprintf("source_%s := %s\n\n", + target, m); + xprintf("deps_%s := \\\n", target); } is_first_dep = 0; } else { - printf(" %s \\\n", m); + xprintf(" %s \\\n", m); } buf = read_file(m); @@ -353,8 +384,8 @@ static void parse_dep_file(char *m, const char *target) exit(1); } - printf("\n%s: $(deps_%s)\n\n", target, target); - printf("$(deps_%s):\n", target); + xprintf("\n%s: $(deps_%s)\n\n", target, target); + xprintf("$(deps_%s):\n", target); } int main(int argc, char *argv[]) @@ -369,7 +400,7 @@ int main(int argc, char *argv[]) target = argv[2]; cmdline = argv[3]; - printf("cmd_%s := %s\n\n", target, cmdline); + xprintf("cmd_%s := %s\n\n", target, cmdline); buf = read_file(depfile); parse_dep_file(buf, target); -- cgit v1.2.3 From 80e5302e4bc85a6b685b7668c36c6487b5f90e9a Mon Sep 17 00:00:00 2001 From: "Naveen N. Rao" Date: Thu, 27 Jun 2019 00:08:01 +0530 Subject: recordmcount: Fix spurious mcount entries on powerpc An impending change to enable HAVE_C_RECORDMCOUNT on powerpc leads to warnings such as the following: # modprobe kprobe_example ftrace-powerpc: Not expected bl: opcode is 3c4c0001 WARNING: CPU: 0 PID: 227 at kernel/trace/ftrace.c:2001 ftrace_bug+0x90/0x318 Modules linked in: CPU: 0 PID: 227 Comm: modprobe Not tainted 5.2.0-rc6-00678-g1c329100b942 #2 NIP: c000000000264318 LR: c00000000025d694 CTR: c000000000f5cd30 REGS: c000000001f2b7b0 TRAP: 0700 Not tainted (5.2.0-rc6-00678-g1c329100b942) MSR: 900000010282b033 CR: 28228222 XER: 00000000 CFAR: c0000000002642fc IRQMASK: 0 NIP [c000000000264318] ftrace_bug+0x90/0x318 LR [c00000000025d694] ftrace_process_locs+0x4f4/0x5e0 Call Trace: [c000000001f2ba40] [0000000000000004] 0x4 (unreliable) [c000000001f2bad0] [c00000000025d694] ftrace_process_locs+0x4f4/0x5e0 [c000000001f2bb90] [c00000000020ff10] load_module+0x25b0/0x30c0 [c000000001f2bd00] [c000000000210cb0] sys_finit_module+0xc0/0x130 [c000000001f2be20] [c00000000000bda4] system_call+0x5c/0x70 Instruction dump: 419e0018 2f83ffff 419e00bc 2f83ffea 409e00cc 4800001c 0fe00000 3c62ff96 39000001 39400000 386386d0 480000c4 <0fe00000> 3ce20003 39000001 3c62ff96 ---[ end trace 4c438d5cebf78381 ]--- ftrace failed to modify [] 0xc0080000012a0008 actual: 01:00:4c:3c Initializing ftrace call sites ftrace record flags: 2000000 (0) expected tramp: c00000000006af4c Looking at the relocation records in __mcount_loc shows a few spurious entries: RELOCATION RECORDS FOR [__mcount_loc]: OFFSET TYPE VALUE 0000000000000000 R_PPC64_ADDR64 .text.unlikely+0x0000000000000008 0000000000000008 R_PPC64_ADDR64 .text.unlikely+0x0000000000000014 0000000000000010 R_PPC64_ADDR64 .text.unlikely+0x0000000000000060 0000000000000018 R_PPC64_ADDR64 .text.unlikely+0x00000000000000b4 0000000000000020 R_PPC64_ADDR64 .init.text+0x0000000000000008 0000000000000028 R_PPC64_ADDR64 .init.text+0x0000000000000014 The first entry in each section is incorrect. Looking at the relocation records, the spurious entries correspond to the R_PPC64_ENTRY records: RELOCATION RECORDS FOR [.text.unlikely]: OFFSET TYPE VALUE 0000000000000000 R_PPC64_REL64 .TOC.-0x0000000000000008 0000000000000008 R_PPC64_ENTRY *ABS* 0000000000000014 R_PPC64_REL24 _mcount The problem is that we are not validating the return value from get_mcountsym() in sift_rel_mcount(). With this entry, mcountsym is 0, but Elf_r_sym(relp) also ends up being 0. Fix this by ensuring mcountsym is valid before processing the entry. Signed-off-by: Naveen N. Rao Acked-by: Steven Rostedt (VMware) Tested-by: Satheesh Rajendran Signed-off-by: Michael Ellerman --- scripts/recordmcount.h | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/recordmcount.h b/scripts/recordmcount.h index 2e7793735e14..ccfbfde61556 100644 --- a/scripts/recordmcount.h +++ b/scripts/recordmcount.h @@ -326,7 +326,8 @@ static uint_t *sift_rel_mcount(uint_t *mlocp, if (!mcountsym) mcountsym = get_mcountsym(sym0, relp, str0); - if (mcountsym == Elf_r_sym(relp) && !is_fake_mcount(relp)) { + if (mcountsym && mcountsym == Elf_r_sym(relp) && + !is_fake_mcount(relp)) { uint_t const addend = _w(_w(relp->r_offset) - recval + mcount_adjust); mrelp->r_offset = _w(offbase -- cgit v1.2.3 From baa23ec860920ebf3e897c4bbb3420a88ea80ec1 Mon Sep 17 00:00:00 2001 From: Marco Ammon Date: Thu, 4 Jul 2019 12:50:41 +0200 Subject: kconfig: Fix spelling of sym_is_changable There is a spelling mistake in "changable", it is corrected to "changeable" and all call sites are updated accordingly. Signed-off-by: Marco Ammon Signed-off-by: Masahiro Yamada --- scripts/kconfig/conf.c | 6 +++--- scripts/kconfig/confdata.c | 2 +- scripts/kconfig/lkc_proto.h | 2 +- scripts/kconfig/mconf.c | 10 +++++----- scripts/kconfig/nconf.c | 10 +++++----- scripts/kconfig/qconf.cc | 2 +- scripts/kconfig/symbol.c | 2 +- 7 files changed, 17 insertions(+), 17 deletions(-) (limited to 'scripts') diff --git a/scripts/kconfig/conf.c b/scripts/kconfig/conf.c index 0d4c4f3a8f29..40e16e871ae2 100644 --- a/scripts/kconfig/conf.c +++ b/scripts/kconfig/conf.c @@ -90,7 +90,7 @@ static int conf_askvalue(struct symbol *sym, const char *def) line[0] = '\n'; line[1] = 0; - if (!sym_is_changable(sym)) { + if (!sym_is_changeable(sym)) { printf("%s\n", def); line[0] = '\n'; line[1] = 0; @@ -234,7 +234,7 @@ static int conf_choice(struct menu *menu) sym = menu->sym; is_new = !sym_has_value(sym); - if (sym_is_changable(sym)) { + if (sym_is_changeable(sym)) { conf_sym(menu); sym_calc_value(sym); switch (sym_get_tristate_value(sym)) { @@ -418,7 +418,7 @@ static void check_conf(struct menu *menu) sym = menu->sym; if (sym && !sym_has_value(sym)) { - if (sym_is_changable(sym) || + if (sym_is_changeable(sym) || (sym_is_choice(sym) && sym_get_tristate_value(sym) == yes)) { if (input_mode == listnewconfig) { if (sym->name) { diff --git a/scripts/kconfig/confdata.c b/scripts/kconfig/confdata.c index 18e8051d89d7..caab7336abc1 100644 --- a/scripts/kconfig/confdata.c +++ b/scripts/kconfig/confdata.c @@ -796,7 +796,7 @@ int conf_write_defconfig(const char *filename) goto next_menu; sym->flags &= ~SYMBOL_WRITE; /* If we cannot change the symbol - skip */ - if (!sym_is_changable(sym)) + if (!sym_is_changeable(sym)) goto next_menu; /* If symbol equals to default value - skip */ if (strcmp(sym_get_string_value(sym), sym_get_string_default(sym)) == 0) diff --git a/scripts/kconfig/lkc_proto.h b/scripts/kconfig/lkc_proto.h index 38a32b1c1a28..f9ab98238aef 100644 --- a/scripts/kconfig/lkc_proto.h +++ b/scripts/kconfig/lkc_proto.h @@ -42,7 +42,7 @@ tristate sym_toggle_tristate_value(struct symbol *sym); bool sym_string_valid(struct symbol *sym, const char *newval); bool sym_string_within_range(struct symbol *sym, const char *str); bool sym_set_string_value(struct symbol *sym, const char *newval); -bool sym_is_changable(struct symbol *sym); +bool sym_is_changeable(struct symbol *sym); struct property * sym_get_choice_prop(struct symbol *sym); const char * sym_get_string_value(struct symbol *sym); diff --git a/scripts/kconfig/mconf.c b/scripts/kconfig/mconf.c index 694091f3ef9d..49c26ea9dd98 100644 --- a/scripts/kconfig/mconf.c +++ b/scripts/kconfig/mconf.c @@ -536,7 +536,7 @@ static void build_conf(struct menu *menu) } val = sym_get_tristate_value(sym); - if (sym_is_changable(sym)) { + if (sym_is_changeable(sym)) { switch (type) { case S_BOOLEAN: item_make("[%c]", val == no ? ' ' : '*'); @@ -587,7 +587,7 @@ static void build_conf(struct menu *menu) } else { switch (type) { case S_BOOLEAN: - if (sym_is_changable(sym)) + if (sym_is_changeable(sym)) item_make("[%c]", val == no ? ' ' : '*'); else item_make("-%c-", val == no ? ' ' : '*'); @@ -600,7 +600,7 @@ static void build_conf(struct menu *menu) case mod: ch = 'M'; break; default: ch = ' '; break; } - if (sym_is_changable(sym)) { + if (sym_is_changeable(sym)) { if (sym->rev_dep.tri == mod) item_make("{%c}", ch); else @@ -617,7 +617,7 @@ static void build_conf(struct menu *menu) if (tmp < 0) tmp = 0; item_add_str("%*c%s%s", tmp, ' ', menu_get_prompt(menu), - (sym_has_value(sym) || !sym_is_changable(sym)) ? + (sym_has_value(sym) || !sym_is_changeable(sym)) ? "" : " (NEW)"); item_set_tag('s'); item_set_data(menu); @@ -625,7 +625,7 @@ static void build_conf(struct menu *menu) } } item_add_str("%*c%s%s", indent + 1, ' ', menu_get_prompt(menu), - (sym_has_value(sym) || !sym_is_changable(sym)) ? + (sym_has_value(sym) || !sym_is_changeable(sym)) ? "" : " (NEW)"); if (menu->prompt->type == P_MENU) { item_add_str(" %s", menu_is_empty(menu) ? "----" : "--->"); diff --git a/scripts/kconfig/nconf.c b/scripts/kconfig/nconf.c index cbafe3bf082e..b7c1ef757178 100644 --- a/scripts/kconfig/nconf.c +++ b/scripts/kconfig/nconf.c @@ -803,7 +803,7 @@ static void build_conf(struct menu *menu) } val = sym_get_tristate_value(sym); - if (sym_is_changable(sym)) { + if (sym_is_changeable(sym)) { switch (type) { case S_BOOLEAN: item_make(menu, 't', "[%c]", @@ -857,7 +857,7 @@ static void build_conf(struct menu *menu) } else { switch (type) { case S_BOOLEAN: - if (sym_is_changable(sym)) + if (sym_is_changeable(sym)) item_make(menu, 't', "[%c]", val == no ? ' ' : '*'); else @@ -876,7 +876,7 @@ static void build_conf(struct menu *menu) ch = ' '; break; } - if (sym_is_changable(sym)) { + if (sym_is_changeable(sym)) { if (sym->rev_dep.tri == mod) item_make(menu, 't', "{%c}", ch); @@ -896,14 +896,14 @@ static void build_conf(struct menu *menu) item_add_str("%*c%s%s", tmp, ' ', menu_get_prompt(menu), (sym_has_value(sym) || - !sym_is_changable(sym)) ? "" : + !sym_is_changeable(sym)) ? "" : " (NEW)"); goto conf_childs; } } item_add_str("%*c%s%s", indent + 1, ' ', menu_get_prompt(menu), - (sym_has_value(sym) || !sym_is_changable(sym)) ? + (sym_has_value(sym) || !sym_is_changeable(sym)) ? "" : " (NEW)"); if (menu->prompt && menu->prompt->type == P_MENU) { item_add_str(" %s", menu_is_empty(menu) ? "----" : "--->"); diff --git a/scripts/kconfig/qconf.cc b/scripts/kconfig/qconf.cc index ce7fc87a49a7..82773cc35d35 100644 --- a/scripts/kconfig/qconf.cc +++ b/scripts/kconfig/qconf.cc @@ -152,7 +152,7 @@ void ConfigItem::updateMenu(void) case S_TRISTATE: char ch; - if (!sym_is_changable(sym) && list->optMode == normalOpt) { + if (!sym_is_changeable(sym) && list->optMode == normalOpt) { setPixmap(promptColIdx, QIcon()); setText(noColIdx, QString::null); setText(modColIdx, QString::null); diff --git a/scripts/kconfig/symbol.c b/scripts/kconfig/symbol.c index 1f9266dadedf..b78650cf2dbe 100644 --- a/scripts/kconfig/symbol.c +++ b/scripts/kconfig/symbol.c @@ -785,7 +785,7 @@ const char *sym_get_string_value(struct symbol *sym) return (const char *)sym->curr.val; } -bool sym_is_changable(struct symbol *sym) +bool sym_is_changeable(struct symbol *sym) { return sym->visible > sym->rev_dep.tri; } -- cgit v1.2.3 From a3b0b6f953ecd51c98bc84efd043a4aad786801b Mon Sep 17 00:00:00 2001 From: Rikard Falkeborn Date: Mon, 8 Apr 2019 21:14:32 +0200 Subject: coccinelle: kstrdup: Fix typo in warning messages Replace 'kstrdep' with 'kstrdup' in warning messages. Signed-off-by: Rikard Falkeborn Acked-by: Julia Lawall Signed-off-by: Masahiro Yamada --- scripts/coccinelle/api/kstrdup.cocci | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'scripts') diff --git a/scripts/coccinelle/api/kstrdup.cocci b/scripts/coccinelle/api/kstrdup.cocci index 09cba54ed0cf..6d13d54a6ee6 100644 --- a/scripts/coccinelle/api/kstrdup.cocci +++ b/scripts/coccinelle/api/kstrdup.cocci @@ -76,7 +76,7 @@ p1 << r1.p1; p2 << r1.p2; @@ -cocci.print_main("WARNING opportunity for kstrdep",p1) +cocci.print_main("WARNING opportunity for kstrdup",p1) cocci.print_secs("strcpy",p2) @script:python depends on org@ @@ -84,7 +84,7 @@ p1 << r2.p1; p2 << r2.p2; @@ -cocci.print_main("WARNING opportunity for kstrdep",p1) +cocci.print_main("WARNING opportunity for kstrdup",p1) cocci.print_secs("memcpy",p2) @script:python depends on report@ @@ -92,7 +92,7 @@ p1 << r1.p1; p2 << r1.p2; @@ -msg = "WARNING opportunity for kstrdep (strcpy on line %s)" % (p2[0].line) +msg = "WARNING opportunity for kstrdup (strcpy on line %s)" % (p2[0].line) coccilib.report.print_report(p1[0], msg) @script:python depends on report@ @@ -100,5 +100,5 @@ p1 << r2.p1; p2 << r2.p2; @@ -msg = "WARNING opportunity for kstrdep (memcpy on line %s)" % (p2[0].line) +msg = "WARNING opportunity for kstrdup (memcpy on line %s)" % (p2[0].line) coccilib.report.print_report(p1[0], msg) -- cgit v1.2.3 From 30a70e806d938ed9fd9bfd2074c4458e63efc3ed Mon Sep 17 00:00:00 2001 From: Markus Elfring Date: Tue, 7 May 2019 11:20:48 +0200 Subject: coccinelle: put_device: Adjust a message construction The Linux coding style tolerates long string literals so that the provided information can be easier found also by search tools like grep. Thus simplify a message construction in a SmPL rule by concatenating text with two plus operators less. Signed-off-by: Markus Elfring Signed-off-by: Masahiro Yamada --- scripts/coccinelle/free/put_device.cocci | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) (limited to 'scripts') diff --git a/scripts/coccinelle/free/put_device.cocci b/scripts/coccinelle/free/put_device.cocci index c9f071b0a0ab..3ebebc064f10 100644 --- a/scripts/coccinelle/free/put_device.cocci +++ b/scripts/coccinelle/free/put_device.cocci @@ -42,11 +42,10 @@ p1 << search.p1; p2 << search.p2; @@ -coccilib.report.print_report(p2[0], "ERROR: missing put_device; " - + "call of_find_device_by_node on line " - + p1[0].line - + ", but without a corresponding object release " - + "within this function.") +coccilib.report.print_report(p2[0], + "ERROR: missing put_device; call of_find_device_by_node on line " + + p1[0].line + + ", but without a corresponding object release within this function.") @script:python depends on org@ p1 << search.p1; -- cgit v1.2.3 From f58c17c202e7aec9623754a7ec0b0669e043b838 Mon Sep 17 00:00:00 2001 From: Markus Elfring Date: Wed, 8 May 2019 13:50:49 +0200 Subject: coccinelle: put_device: Add a cast to an expression for an assignment Extend a when constraint in a SmPL rule so that an additional cast is optionally excluded from source code searches for an expression in assignments. Signed-off-by: Markus Elfring Suggested-by: Julia Lawall Link: https://lore.kernel.org/lkml/alpine.DEB.2.21.1902160934400.3212@hadrien/ Link: https://systeme.lip6.fr/pipermail/cocci/2019-February/005592.html Acked-by: Julia Lawall Signed-off-by: Masahiro Yamada --- scripts/coccinelle/free/put_device.cocci | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/coccinelle/free/put_device.cocci b/scripts/coccinelle/free/put_device.cocci index 3ebebc064f10..120921366e84 100644 --- a/scripts/coccinelle/free/put_device.cocci +++ b/scripts/coccinelle/free/put_device.cocci @@ -24,7 +24,7 @@ if (id == NULL || ...) { ... return ...; } when != of_dev_put(id) when != if (id) { ... put_device(&id->dev) ... } when != e1 = (T)id - when != e1 = &id->dev + when != e1 = (T)(&id->dev) when != e1 = get_device(&id->dev) when != e1 = (T1)platform_get_drvdata(id) ( -- cgit v1.2.3 From 0c4ab18fc33bba70299f51fac83e32397cf9a04b Mon Sep 17 00:00:00 2001 From: Kirill Smelkov Date: Sun, 23 Jun 2019 07:28:53 +0000 Subject: coccinelle: api/stream_open: treat all wait_.*() calls as blocking Previously steam_open.cocci was treating only wait_event_.* - e.g. wait_event_interruptible - as a blocking operation. However e.g. wait_for_completion_interruptible is also blocking, and so from this point of view it would be more logical to treat all wait_.* as a blocking point. The logic of this change actually came up for real when drivers/pci/switch/switchtec.c changed from using wait_event_interruptible to wait_for_completion_interruptible: https://lore.kernel.org/linux-pci/20190413170056.GA11293@deco.navytux.spb.ru/ https://lore.kernel.org/linux-pci/20190415145456.GA15280@deco.navytux.spb.ru/ https://lore.kernel.org/linux-pci/20190415154102.GB17661@deco.navytux.spb.ru/ For a driver that uses nonseekable_open with read/write having stream semantic and read also calling e.g. wait_for_completion_interruptible, running stream_open.cocci before this patch would produce: WARNING: _fops: .read() and .write() have stream semantic; safe to change nonseekable_open -> stream_open. while after this patch it will report: ERROR: _fops: .read() can deadlock .write(); change nonseekable_open -> stream_open to fix. Signed-off-by: Kirill Smelkov Acked-by: Julia Lawall Signed-off-by: Masahiro Yamada --- scripts/coccinelle/api/stream_open.cocci | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'scripts') diff --git a/scripts/coccinelle/api/stream_open.cocci b/scripts/coccinelle/api/stream_open.cocci index 350145da7669..12ce18fa6b74 100644 --- a/scripts/coccinelle/api/stream_open.cocci +++ b/scripts/coccinelle/api/stream_open.cocci @@ -35,11 +35,11 @@ type loff_t; // a function that blocks @ blocks @ identifier block_f; -identifier wait_event =~ "^wait_event_.*"; +identifier wait =~ "^wait_.*"; @@ block_f(...) { ... when exists - wait_event(...) + wait(...) ... when exists } @@ -49,12 +49,12 @@ identifier wait_event =~ "^wait_event_.*"; // XXX currently reader_blocks supports only direct and 1-level indirect cases. @ reader_blocks_direct @ identifier stream_reader.readstream; -identifier wait_event =~ "^wait_event_.*"; +identifier wait =~ "^wait_.*"; @@ readstream(...) { ... when exists - wait_event(...) + wait(...) ... when exists } -- cgit v1.2.3 From 33177f01ca3fe550146bb9001bec2fd806b2f40c Mon Sep 17 00:00:00 2001 From: Vasily Gorbik Date: Fri, 28 Jun 2019 19:22:47 +0200 Subject: kallsyms: exclude kasan local symbols on s390 gcc asan instrumentation emits the following sequence to store frame pc when the kernel is built with CONFIG_RELOCATABLE: debug/vsprintf.s: .section .data.rel.ro.local,"aw" .align 8 .LC3: .quad .LASANPC4826@GOTOFF .text .align 8 .type number, @function number: .LASANPC4826: and in case reloc is issued for LASANPC label it also gets into .symtab with the same address as actual function symbol: $ nm -n vmlinux | grep 0000000001397150 0000000001397150 t .LASANPC4826 0000000001397150 t number In the end kernel backtraces are almost unreadable: [ 143.748476] Call Trace: [ 143.748484] ([<000000002da3e62c>] .LASANPC2671+0x114/0x190) [ 143.748492] [<000000002eca1a58>] .LASANPC2612+0x110/0x160 [ 143.748502] [<000000002de9d830>] print_address_description+0x80/0x3b0 [ 143.748511] [<000000002de9dd64>] __kasan_report+0x15c/0x1c8 [ 143.748521] [<000000002ecb56d4>] strrchr+0x34/0x60 [ 143.748534] [<000003ff800a9a40>] kasan_strings+0xb0/0x148 [test_kasan] [ 143.748547] [<000003ff800a9bba>] kmalloc_tests_init+0xe2/0x528 [test_kasan] [ 143.748555] [<000000002da2117c>] .LASANPC4069+0x354/0x748 [ 143.748563] [<000000002dbfbb16>] do_init_module+0x136/0x3b0 [ 143.748571] [<000000002dbff3f4>] .LASANPC3191+0x2164/0x25d0 [ 143.748580] [<000000002dbffc4c>] .LASANPC3196+0x184/0x1b8 [ 143.748587] [<000000002ecdf2ec>] system_call+0xd8/0x2d8 Since LASANPC labels are not even unique and get into .symtab only due to relocs filter them out in kallsyms. Signed-off-by: Vasily Gorbik Signed-off-by: Masahiro Yamada --- scripts/kallsyms.c | 3 +++ 1 file changed, 3 insertions(+) (limited to 'scripts') diff --git a/scripts/kallsyms.c b/scripts/kallsyms.c index e17837f1d3f2..ae6504d07fd6 100644 --- a/scripts/kallsyms.c +++ b/scripts/kallsyms.c @@ -150,6 +150,9 @@ static int read_symbol(FILE *in, struct sym_entry *s) /* exclude debugging symbols */ else if (stype == 'N' || stype == 'n') return -1; + /* exclude s390 kasan local symbols */ + else if (!strncmp(sym, ".LASANPC", 8)) + return -1; /* include the type field in the symbol name, so that it gets * compressed together */ -- cgit v1.2.3 From c93a0368aaa2962e6c89da20f79b8789b42e3387 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Mon, 1 Jul 2019 09:58:41 +0900 Subject: kbuild: do not create wrappers for header-test-y header-test-y does not work with headers in sub-directories. For example, you may want to write a Makefile, like this: include/linux/Kbuild: header-test-y += mtd/nand.h This entry will create a wrapper include/linux/mtd/nand.hdrtest.c with the following content: #include "mtd/nand.h" To make this work, we need to add $(srctree)/include/linux to the header search path. It would be tedious to add ccflags-y. Instead, we could change the *.hdrtest.c rule to wrap: #include "nand.h" This works for in-tree build since #include "..." searches in the relative path from the header with this directive. For O=... build, we need to add $(srctree)/include/linux/mtd to the header search path, which will be even more tedious. After all, I thought it would be handier to compile headers directly without creating wrappers. I added a new build rule to compile %.h into %.h.s The target is %.h.s instead of %.h.o because it is slightly faster. Also, as for GCC, an empty assembly is smaller than an empty object. I wrote the build rule: $(CC) $(c_flags) -S -o $@ -x c /dev/null -include $< instead of: $(CC) $(c_flags) -S -o $@ -x c $< Both work fine with GCC, but the latter is bad for Clang. This comes down to the difference in the -Wunused-function policy. GCC does not warn about unused 'static inline' functions at all. Clang does not warn about the ones in included headers, but does about the ones in the source. So, we should handle headers as headers, not as source files. In fact, this has been hidden since commit abb2ea7dfd82 ("compiler, clang: suppress warning for unused static inline functions"), but we should not rely on that. Signed-off-by: Masahiro Yamada Acked-by: Jani Nikula Tested-by: Jani Nikula --- .gitignore | 1 - Documentation/dontdiff | 1 - Documentation/kbuild/makefiles.txt | 3 +-- Makefile | 1 - scripts/Makefile.build | 10 +++++----- scripts/Makefile.lib | 2 +- scripts/package/mkspec | 2 +- 7 files changed, 8 insertions(+), 12 deletions(-) (limited to 'scripts') diff --git a/.gitignore b/.gitignore index 4bb60f0fa23b..7587ef56b92d 100644 --- a/.gitignore +++ b/.gitignore @@ -22,7 +22,6 @@ *.elf *.gcno *.gz -*.hdrtest.c *.i *.ko *.lex.c diff --git a/Documentation/dontdiff b/Documentation/dontdiff index 554dfe4883d2..5eba889ea84d 100644 --- a/Documentation/dontdiff +++ b/Documentation/dontdiff @@ -19,7 +19,6 @@ *.grep *.grp *.gz -*.hdrtest.c *.html *.i *.jpeg diff --git a/Documentation/kbuild/makefiles.txt b/Documentation/kbuild/makefiles.txt index ca4b24ec0399..5080fec34609 100644 --- a/Documentation/kbuild/makefiles.txt +++ b/Documentation/kbuild/makefiles.txt @@ -1023,8 +1023,7 @@ When kbuild executes, the following steps are followed (roughly): header-test-y specifies headers (*.h) in the current directory that should be compile tested to ensure they are self-contained, i.e. compilable as standalone units. If CONFIG_HEADER_TEST is enabled, - this autogenerates dummy sources to include the headers, and builds them - as part of extra-y. + this builds them as part of extra-y. --- 6.7 Commands useful for building a boot image diff --git a/Makefile b/Makefile index fca827bc3f77..82fccd37a1ad 100644 --- a/Makefile +++ b/Makefile @@ -1663,7 +1663,6 @@ clean: $(clean-dirs) -o -name '*.dwo' -o -name '*.lst' \ -o -name '*.su' \ -o -name '.*.d' -o -name '.*.tmp' -o -name '*.mod.c' \ - -o -name '*.hdrtest.c' \ -o -name '*.lex.c' -o -name '*.tab.[ch]' \ -o -name '*.asn1.[ch]' \ -o -name '*.symtypes' -o -name 'modules.order' \ diff --git a/scripts/Makefile.build b/scripts/Makefile.build index ee0319560513..776842b7e6a3 100644 --- a/scripts/Makefile.build +++ b/scripts/Makefile.build @@ -294,14 +294,14 @@ quiet_cmd_cc_lst_c = MKLST $@ $(obj)/%.lst: $(src)/%.c FORCE $(call if_changed_dep,cc_lst_c) -# Dummy C sources for header test (header-test-y target) +# header test (header-test-y target) # --------------------------------------------------------------------------- -quiet_cmd_header_test = HDRTEST $@ - cmd_header_test = echo "\#include \"$*.h\"" > $@ +quiet_cmd_cc_s_h = CC $@ + cmd_cc_s_h = $(CC) $(c_flags) -S -o $@ -x c /dev/null -include $< -$(obj)/%.hdrtest.c: - $(call cmd,header_test) +$(obj)/%.h.s: $(src)/%.h FORCE + $(call if_changed_dep,cc_s_h) # Compile assembler sources (.S) # --------------------------------------------------------------------------- diff --git a/scripts/Makefile.lib b/scripts/Makefile.lib index 3e630fcaffd1..55ae1ec65342 100644 --- a/scripts/Makefile.lib +++ b/scripts/Makefile.lib @@ -67,7 +67,7 @@ extra-$(CONFIG_OF_ALL_DTBS) += $(patsubst %.dtb,%.dt.yaml, $(dtb-)) endif # Test self-contained headers -extra-$(CONFIG_HEADER_TEST) += $(patsubst %.h,%.hdrtest.o,$(header-test-y)) +extra-$(CONFIG_HEADER_TEST) += $(addsuffix .s, $(header-test-y)) # Add subdir path diff --git a/scripts/package/mkspec b/scripts/package/mkspec index 009147d4718e..2d29df4a0a53 100755 --- a/scripts/package/mkspec +++ b/scripts/package/mkspec @@ -31,7 +31,7 @@ PROVIDES="$PROVIDES kernel-$KERNELRELEASE" __KERNELRELEASE=$(echo $KERNELRELEASE | sed -e "s/-/_/g") EXCLUDES="$RCS_TAR_IGNORE --exclude=.tmp_versions --exclude=*vmlinux* \ --exclude=*.o --exclude=*.ko --exclude=*.cmd --exclude=Documentation \ ---exclude=.config.old --exclude=.missing-syscalls.d" +--exclude=.config.old --exclude=.missing-syscalls.d --exclude=*.s" # We can label the here-doc lines for conditional output to the spec file # -- cgit v1.2.3 From 1e21cbfada87f697a2a7c450542a7d28925abee6 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Mon, 1 Jul 2019 09:58:42 +0900 Subject: kbuild: support header-test-pattern-y In my view, most of headers can be self-contained. So, it would be tedious to add every header to header-test-y explicitly. We usually end up with "all headers with some exceptions". There are two types in exceptions: [1] headers that are never compiled as standalone units For examples, include/linux/compiler-gcc.h is not intended for direct inclusion. We should always exclude such ones. [2] headers that are conditionally compiled as standalone units Some headers can be compiled only for particular architectures. For example, include/linux/arm-cci.h can be compiled only for arm/arm64 because it requires to exist. Clang can compile include/soc/nps/mtm.h only for arc because it contains an arch-specific register in inline assembler. So, you can write Makefile like this: header-test- += linux/compiler-gcc.h header-test-$(CONFIG_ARM) += linux/arm-cci.h header-test-$(CONFIG_ARM64) += linux/arm-cci.h header-test-$(CONFIG_ARC) += soc/nps/mtm.h The new syntax header-test-pattern-y will be useful to specify "the rest". The typical usage is like this: header-test-pattern-y += */*.h This will add all the headers in sub-directories to the test coverage, excluding $(header-test-). In this regards, header-test-pattern-y behaves like a weaker variant of header-test-y. Caveat: The patterns in header-test-pattern-y are prefixed with $(srctree)/$(src)/ but not $(objtree)/$(obj)/. Stale generated headers are often left over when you traverse the git history without cleaning. Wildcard patterns for $(objtree) may match to stale headers, which could fail to compile. One pitfall is $(srctree)/$(src)/ and $(objtree)/$(obj)/ point to the same directory for in-tree building. So, header-test-pattern-y should be used with care since it can potentially match to stale headers. Caveat2: You could use wildcard for header-test-. For example, header-test- += asm-generic/% ... will exclude headers in asm-generic directory. Unfortunately, the wildcard character is '%' instead of '*' here because this is evaluated by $(filter-out ...) whereas header-test-pattern-y is evaluated by $(wildcard ...). This is a kludge, but seems useful in some places... Signed-off-by: Masahiro Yamada Tested-by: Jani Nikula --- Documentation/kbuild/makefiles.txt | 10 ++++++++++ scripts/Makefile.lib | 11 +++++++++++ 2 files changed, 21 insertions(+) (limited to 'scripts') diff --git a/Documentation/kbuild/makefiles.txt b/Documentation/kbuild/makefiles.txt index 5080fec34609..b817e6cefb77 100644 --- a/Documentation/kbuild/makefiles.txt +++ b/Documentation/kbuild/makefiles.txt @@ -1025,6 +1025,16 @@ When kbuild executes, the following steps are followed (roughly): i.e. compilable as standalone units. If CONFIG_HEADER_TEST is enabled, this builds them as part of extra-y. + header-test-pattern-y + + This works as a weaker version of header-test-y, and accepts wildcard + patterns. The typical usage is: + + header-test-pattern-y += *.h + + This specifies all the files that matches to '*.h' in the current + directory, but the files in 'header-test-' are excluded. + --- 6.7 Commands useful for building a boot image Kbuild provides a few macros that are useful when building a diff --git a/scripts/Makefile.lib b/scripts/Makefile.lib index 55ae1ec65342..281864fcf0fe 100644 --- a/scripts/Makefile.lib +++ b/scripts/Makefile.lib @@ -67,6 +67,17 @@ extra-$(CONFIG_OF_ALL_DTBS) += $(patsubst %.dtb,%.dt.yaml, $(dtb-)) endif # Test self-contained headers + +# Wildcard searches in $(srctree)/$(src)/, but not in $(objtree)/$(obj)/. +# Stale generated headers are often left over, so pattern matching should +# be avoided. Please notice $(srctree)/$(src)/ and $(objtree)/$(obj) point +# to the same location for in-tree building. So, header-test-pattern-y should +# be used with care. +header-test-y += $(filter-out $(header-test-), \ + $(patsubst $(srctree)/$(src)/%, %, \ + $(wildcard $(addprefix $(srctree)/$(src)/, \ + $(header-test-pattern-y))))) + extra-$(CONFIG_HEADER_TEST) += $(addsuffix .s, $(header-test-y)) # Add subdir path -- cgit v1.2.3 From d1db881d9bf16f2c51bdef8f0dfc2e4088a76bbf Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Sat, 6 Jul 2019 00:14:30 +0900 Subject: scripts/tags.sh: drop SUBARCH support for ARM Our goal is to have more and more sub-architectures to join the ARM multi-platform, and support them in a single configuration. Remove the ARM SUBARCH support because it is ugly. Signed-off-by: Masahiro Yamada --- scripts/tags.sh | 36 ++---------------------------------- 1 file changed, 2 insertions(+), 34 deletions(-) (limited to 'scripts') diff --git a/scripts/tags.sh b/scripts/tags.sh index d46be47633af..207c854825b4 100755 --- a/scripts/tags.sh +++ b/scripts/tags.sh @@ -42,15 +42,13 @@ find_arch_sources() for i in $archincludedir; do prune="$prune -wholename $i -prune -o" done - find ${tree}arch/$1 $ignore $subarchprune $prune -name "$2" \ - -not -type l -print; + find ${tree}arch/$1 $ignore $prune -name "$2" -not -type l -print; } # find sources in arch/$1/include find_arch_include_sources() { - include=$(find ${tree}arch/$1/ $subarchprune \ - -name include -type d -print); + include=$(find ${tree}arch/$1/ -name include -type d -print); if [ -n "$include" ]; then archincludedir="$archincludedir $include" find $include $ignore -name "$2" -not -type l -print; @@ -306,36 +304,6 @@ if [ "${ARCH}" = "um" ]; then else archinclude=${SUBARCH} fi -elif [ "${SRCARCH}" = "arm" -a "${SUBARCH}" != "" ]; then - subarchdir=$(find ${tree}arch/$SRCARCH/ -name "mach-*" -type d -o \ - -name "plat-*" -type d); - mach_suffix=$SUBARCH - plat_suffix=$SUBARCH - - # Special cases when $plat_suffix != $mach_suffix - case $mach_suffix in - "omap1" | "omap2") - plat_suffix="omap" - ;; - esac - - if [ ! -d ${tree}arch/$SRCARCH/mach-$mach_suffix ]; then - echo "Warning: arch/arm/mach-$mach_suffix/ not found." >&2 - echo " Fix your \$SUBARCH appropriately" >&2 - fi - - for i in $subarchdir; do - case "$i" in - *"mach-"${mach_suffix}) - ;; - *"plat-"${plat_suffix}) - ;; - *) - subarchprune="$subarchprune \ - -wholename $i -prune -o" - ;; - esac - done fi remove_structs= -- cgit v1.2.3 From b3b3eb9dadfcb6c706f5fa97bc841d4e069af3de Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Sat, 6 Jul 2019 00:14:31 +0900 Subject: scripts/tags.sh: remove unused environment variables from comments This script has no reference to ${ARCH}, ${src}, ${obj}. Signed-off-by: Masahiro Yamada --- scripts/tags.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/tags.sh b/scripts/tags.sh index 207c854825b4..7fea4044749b 100755 --- a/scripts/tags.sh +++ b/scripts/tags.sh @@ -6,7 +6,7 @@ # mode may be any of: tags, TAGS, cscope # # Uses the following environment variables: -# ARCH, SUBARCH, SRCARCH, srctree, src, obj +# SUBARCH, SRCARCH, srctree if [ "$KBUILD_VERBOSE" = "1" ]; then set -x @@ -36,7 +36,7 @@ elif [ "${ALLSOURCE_ARCHS}" = "all" ]; then ALLSOURCE_ARCHS=$(find ${tree}arch/ -mindepth 1 -maxdepth 1 -type d -printf '%f ') fi -# find sources in arch/$ARCH +# find sources in arch/$1 find_arch_sources() { for i in $archincludedir; do -- cgit v1.2.3 From 051f278e9d81bed253bf89c66c80b8b921aafa8a Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Sat, 6 Jul 2019 12:07:12 +0900 Subject: kbuild: replace KBUILD_SRCTREE with boolean building_out_of_srctree Commit 25b146c5b8ce ("kbuild: allow Kbuild to start from any directory") deprecated KBUILD_SRCTREE. It is only used in tools/testing/selftest/ to distinguish out-of-tree build. Replace it with a new boolean flag, building_out_of_srctree. I also replaced the conditional ($(srctree),.) because the next commit will allow an absolute path to be used for $(srctree) even when building in the source tree. Signed-off-by: Masahiro Yamada --- Makefile | 19 ++++++++----------- scripts/Makefile.build | 2 +- scripts/Makefile.host | 2 +- scripts/Makefile.lib | 2 +- scripts/Makefile.modbuiltin | 2 +- scripts/gdb/linux/Makefile | 2 +- tools/testing/selftests/Makefile | 2 +- tools/testing/selftests/lib.mk | 4 ++-- 8 files changed, 16 insertions(+), 19 deletions(-) (limited to 'scripts') diff --git a/Makefile b/Makefile index 99336b60f1a4..91ad737ff538 100644 --- a/Makefile +++ b/Makefile @@ -228,9 +228,12 @@ ifeq ("$(origin M)", "command line") KBUILD_EXTMOD := $(M) endif +export KBUILD_CHECKSRC KBUILD_EXTMOD + ifeq ($(abs_srctree),$(abs_objtree)) # building in the source tree srctree := . + building_out_of_srctree := else ifeq ($(abs_srctree)/,$(dir $(abs_objtree))) # building in a subdirectory of the source tree @@ -238,19 +241,13 @@ else else srctree := $(abs_srctree) endif - - # TODO: - # KBUILD_SRC is only used to distinguish in-tree/out-of-tree build. - # Replace it with $(srctree) or something. - KBUILD_SRC := $(abs_srctree) + building_out_of_srctree := 1 endif -export KBUILD_CHECKSRC KBUILD_EXTMOD KBUILD_SRC - objtree := . VPATH := $(srctree) -export srctree objtree VPATH +export building_out_of_srctree srctree objtree VPATH # To make sure we do not include .config for any of the *config targets # catch them early, and hand them over to scripts/kconfig/Makefile @@ -453,7 +450,7 @@ USERINCLUDE := \ LINUXINCLUDE := \ -I$(srctree)/arch/$(SRCARCH)/include \ -I$(objtree)/arch/$(SRCARCH)/include/generated \ - $(if $(filter .,$(srctree)),,-I$(srctree)/include) \ + $(if $(building_out_of_srctree),-I$(srctree)/include) \ -I$(objtree)/include \ $(USERINCLUDE) @@ -514,7 +511,7 @@ PHONY += outputmakefile # At the same time when output Makefile generated, generate .gitignore to # ignore whole output directory outputmakefile: -ifneq ($(srctree),.) +ifdef building_out_of_srctree $(Q)ln -fsn $(srctree) source $(Q)$(CONFIG_SHELL) $(srctree)/scripts/mkmakefile $(srctree) $(Q)test -e .gitignore || \ @@ -1101,7 +1098,7 @@ PHONY += prepare archprepare prepare1 prepare3 # and if so do: # 1) Check that make has not been executed in the kernel src $(srctree) prepare3: include/config/kernel.release -ifneq ($(srctree),.) +ifdef building_out_of_srctree @$(kecho) ' Using $(srctree) as source for kernel' $(Q)if [ -f $(srctree)/.config -o \ -d $(srctree)/include/config -o \ diff --git a/scripts/Makefile.build b/scripts/Makefile.build index 776842b7e6a3..be38198d98b2 100644 --- a/scripts/Makefile.build +++ b/scripts/Makefile.build @@ -513,7 +513,7 @@ existing-targets := $(wildcard $(sort $(targets))) -include $(foreach f,$(existing-targets),$(dir $(f)).$(notdir $(f)).cmd) -ifneq ($(srctree),.) +ifdef building_out_of_srctree # Create directories for object files if they do not exist obj-dirs := $(sort $(obj) $(patsubst %/,%, $(dir $(targets)))) # If targets exist, their directories apparently exist. Skip mkdir. diff --git a/scripts/Makefile.host b/scripts/Makefile.host index b6a54bdf0965..fcf0213e6ac8 100644 --- a/scripts/Makefile.host +++ b/scripts/Makefile.host @@ -69,7 +69,7 @@ _hostcxx_flags = $(KBUILD_HOSTCXXFLAGS) $(HOST_EXTRACXXFLAGS) \ # $(objtree)/$(obj) for including generated headers from checkin source files ifeq ($(KBUILD_EXTMOD),) -ifneq ($(srctree),.) +ifdef building_out_of_srctree _hostc_flags += -I $(objtree)/$(obj) _hostcxx_flags += -I $(objtree)/$(obj) endif diff --git a/scripts/Makefile.lib b/scripts/Makefile.lib index 281864fcf0fe..8f2eb799a9b2 100644 --- a/scripts/Makefile.lib +++ b/scripts/Makefile.lib @@ -154,7 +154,7 @@ endif # $(srctree)/$(src) for including checkin headers from generated source files # $(objtree)/$(obj) for including generated headers from checkin source files ifeq ($(KBUILD_EXTMOD),) -ifneq ($(srctree),.) +ifdef building_out_of_srctree _c_flags += -I $(srctree)/$(src) -I $(objtree)/$(obj) _a_flags += -I $(srctree)/$(src) -I $(objtree)/$(obj) _cpp_flags += -I $(srctree)/$(src) -I $(objtree)/$(obj) diff --git a/scripts/Makefile.modbuiltin b/scripts/Makefile.modbuiltin index ea90a90b41a0..50a9990760f3 100644 --- a/scripts/Makefile.modbuiltin +++ b/scripts/Makefile.modbuiltin @@ -15,7 +15,7 @@ include include/config/tristate.conf include scripts/Kbuild.include -ifneq ($(srctree),.) +ifdef building_out_of_srctree # Create output directory if not already present _dummy := $(shell [ -d $(obj) ] || mkdir -p $(obj)) endif diff --git a/scripts/gdb/linux/Makefile b/scripts/gdb/linux/Makefile index 9fd3d8ed731a..124755087510 100644 --- a/scripts/gdb/linux/Makefile +++ b/scripts/gdb/linux/Makefile @@ -1,6 +1,6 @@ # SPDX-License-Identifier: GPL-2.0 -ifneq ($(srctree),.) +ifdef building_out_of_srctree symlinks := $(patsubst $(srctree)/$(src)/%,%,$(wildcard $(srctree)/$(src)/*.py)) diff --git a/tools/testing/selftests/Makefile b/tools/testing/selftests/Makefile index 9781ca79794a..25b43a8c2b15 100644 --- a/tools/testing/selftests/Makefile +++ b/tools/testing/selftests/Makefile @@ -74,7 +74,7 @@ endif # Append kselftest to KBUILD_OUTPUT to avoid cluttering # KBUILD_OUTPUT with selftest objects and headers installed # by selftests Makefile or lib.mk. -ifneq ($(KBUILD_SRC),) +ifdef building_out_of_srctree override LDFLAGS = endif diff --git a/tools/testing/selftests/lib.mk b/tools/testing/selftests/lib.mk index 077337195783..1c8a1963d03f 100644 --- a/tools/testing/selftests/lib.mk +++ b/tools/testing/selftests/lib.mk @@ -70,7 +70,7 @@ define RUN_TESTS endef run_tests: all -ifneq ($(KBUILD_SRC),) +ifdef building_out_of_srctree @if [ "X$(TEST_PROGS) $(TEST_PROGS_EXTENDED) $(TEST_FILES)" != "X" ]; then @rsync -aq $(TEST_PROGS) $(TEST_PROGS_EXTENDED) $(TEST_FILES) $(OUTPUT) fi @@ -125,7 +125,7 @@ clean: # When make O= with kselftest target from main level # the following aren't defined. # -ifneq ($(KBUILD_SRC),) +ifdef building_out_of_srctree LINK.c = $(CC) $(CFLAGS) $(CPPFLAGS) $(LDFLAGS) $(TARGET_ARCH) COMPILE.S = $(CC) $(ASFLAGS) $(CPPFLAGS) $(TARGET_ARCH) -c LINK.S = $(CC) $(ASFLAGS) $(CPPFLAGS) $(LDFLAGS) $(TARGET_ARCH) -- cgit v1.2.3 From 95fd3f87bfbe8edaa5e955e0f858a0a573c09ab6 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Sat, 6 Jul 2019 12:07:13 +0900 Subject: kbuild: add a flag to force absolute path for srctree In old days, Kbuild always used an absolute path for $(srctree). Since commit 890676c65d69 ("kbuild: Use relative path when building in the source tree"), $(srctree) is '.' when O= was not passed from the command line. Yet, using absolute paths is useful in some cases even without O=, for instance, to create a cscope file with absolute path tags. 'O=.' was known to work as a workaround to force Kbuild to use absolute paths even when you are building in the source tree. Since commit 25b146c5b8ce ("kbuild: allow Kbuild to start from any directory"), Kbuild is too clever to be tricked. Even if you pass 'O=.' Kbuild notices you are building in the source tree, then use '.' for $(srctree). So, 'make O=. cscope' is no help to create absolute path tags. We cannot force one or the other according to commit e93bc1a0cab3 ("Revert "kbuild: specify absolute paths for cscope""). Both of relative path and absolute path have pros and cons. This commit adds a new flag KBUILD_ABS_SRCTREE to allow users to choose the absolute path for $(srctree). 'make KBUILD_ABS_SRCTREE=1 cscope' will work as a replacement of 'make O=. cscope'. Reported-by: Pawan Gupta Signed-off-by: Masahiro Yamada --- Documentation/kbuild/kbuild.txt | 9 +++++++++ Makefile | 4 ++++ scripts/tags.sh | 3 +-- 3 files changed, 14 insertions(+), 2 deletions(-) (limited to 'scripts') diff --git a/Documentation/kbuild/kbuild.txt b/Documentation/kbuild/kbuild.txt index 9c230ea71963..dcfeb32e3360 100644 --- a/Documentation/kbuild/kbuild.txt +++ b/Documentation/kbuild/kbuild.txt @@ -183,6 +183,15 @@ The output directory is often set using "O=..." on the commandline. The value can be overridden in which case the default value is ignored. +KBUILD_ABS_SRCTREE +-------------------------------------------------- +Kbuild uses a relative path to point to the tree when possible. For instance, +when building in the source tree, the source tree path is '.' + +Setting this flag requests Kbuild to use absolute path to the source tree. +There are some useful cases to do so, like when generating tag files with +absolute path entries etc. + KBUILD_SIGN_PIN -------------------------------------------------- This variable allows a passphrase or PIN to be passed to the sign-file diff --git a/Makefile b/Makefile index 91ad737ff538..357fd3623144 100644 --- a/Makefile +++ b/Makefile @@ -244,6 +244,10 @@ else building_out_of_srctree := 1 endif +ifneq ($(KBUILD_ABS_SRCTREE),) +srctree := $(abs_srctree) +endif + objtree := . VPATH := $(srctree) diff --git a/scripts/tags.sh b/scripts/tags.sh index 7fea4044749b..4e18ae5282a6 100755 --- a/scripts/tags.sh +++ b/scripts/tags.sh @@ -17,8 +17,7 @@ ignore="$(echo "$RCS_FIND_IGNORE" | sed 's|\\||g' )" # tags and cscope files should also ignore MODVERSION *.mod.c files ignore="$ignore ( -name *.mod.c ) -prune -o" -# Do not use full path if we do not use O=.. builds -# Use make O=. {tags|cscope} +# Use make KBUILD_ABS_SRCTREE=1 {tags|cscope} # to force full paths for a non-O= build if [ "${srctree}" = "." -o -z "${srctree}" ]; then tree= -- cgit v1.2.3 From b956c7a6df3aa01f357f8ac5bc3e44bc3ab7befb Mon Sep 17 00:00:00 2001 From: Harald Seiler Date: Tue, 9 Jul 2019 12:50:50 +0200 Subject: kbuild: fix compression errors getting ignored A missing compression utility or other errors were not picked up by make and an empty kernel image was produced. By removing the &&, errors will no longer be ignored. Signed-off-by: Harald Seiler Signed-off-by: Masahiro Yamada --- scripts/Makefile.lib | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'scripts') diff --git a/scripts/Makefile.lib b/scripts/Makefile.lib index 8f2eb799a9b2..6cb3aa5cbc79 100644 --- a/scripts/Makefile.lib +++ b/scripts/Makefile.lib @@ -345,19 +345,19 @@ printf "%08x\n" $$dec_size | \ ) quiet_cmd_bzip2 = BZIP2 $@ - cmd_bzip2 = { cat $(real-prereqs) | bzip2 -9 && $(size_append); } > $@ + cmd_bzip2 = { cat $(real-prereqs) | bzip2 -9; $(size_append); } > $@ # Lzma # --------------------------------------------------------------------------- quiet_cmd_lzma = LZMA $@ - cmd_lzma = { cat $(real-prereqs) | lzma -9 && $(size_append); } > $@ + cmd_lzma = { cat $(real-prereqs) | lzma -9; $(size_append); } > $@ quiet_cmd_lzo = LZO $@ - cmd_lzo = { cat $(real-prereqs) | lzop -9 && $(size_append); } > $@ + cmd_lzo = { cat $(real-prereqs) | lzop -9; $(size_append); } > $@ quiet_cmd_lz4 = LZ4 $@ - cmd_lz4 = { cat $(real-prereqs) | lz4c -l -c1 stdin stdout && \ + cmd_lz4 = { cat $(real-prereqs) | lz4c -l -c1 stdin stdout; \ $(size_append); } > $@ # U-Boot mkimage @@ -400,7 +400,7 @@ quiet_cmd_uimage = UIMAGE $@ # big dictionary would increase the memory usage too much in the multi-call # decompression mode. A BCJ filter isn't used either. quiet_cmd_xzkern = XZKERN $@ - cmd_xzkern = { cat $(real-prereqs) | sh $(srctree)/scripts/xz_wrap.sh && \ + cmd_xzkern = { cat $(real-prereqs) | sh $(srctree)/scripts/xz_wrap.sh; \ $(size_append); } > $@ quiet_cmd_xzmisc = XZMISC $@ -- cgit v1.2.3 From d4a74bbfee03acf7bbddc77b9c9236462c744fc7 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Tue, 9 Jul 2019 15:13:00 +0900 Subject: kbuild: use -- separater intead of $(filter-out ...) for cc-cross-prefix arch/mips/Makefile passes prefixes that start with '-' to cc-cross-prefix when $(tool-archpref) evaluates to the empty string. They are filtered-out before the $(shell ...) invocation. Otherwise, 'command -v' would be confused. $ command -v -linux-gcc bash: command: -l: invalid option command: usage: command [-pVv] command [arg ...] Since commit 913ab9780fc0 ("kbuild: use more portable 'command -v' for cc-cross-prefix"), cc-cross-prefix throws away the stderr output, so the console is not polluted in any way. This is not a big deal in practice, but I see a slightly better taste in adding '--' to teach it that '-linux-gcc' is an argument instead of a command option. This will cause extra forking of subshell, but it will not be noticeable performance regression. Signed-off-by: Masahiro Yamada --- scripts/Kbuild.include | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/Kbuild.include b/scripts/Kbuild.include index 222fd1d7d3ae..c62d690c7dcf 100644 --- a/scripts/Kbuild.include +++ b/scripts/Kbuild.include @@ -79,8 +79,8 @@ endef # would try to directly execute the shell builtin 'command'. This workaround # should be kept for a long time since this issue was fixed only after the # GNU Make 4.2.1 release. -cc-cross-prefix = $(firstword $(foreach c, $(filter-out -%, $(1)), \ - $(if $(shell command -v $(c)gcc 2>/dev/null), $(c)))) +cc-cross-prefix = $(firstword $(foreach c, $(1), \ + $(if $(shell command -v -- $(c)gcc 2>/dev/null), $(c)))) # output directory for tests below TMPOUT := $(if $(KBUILD_EXTMOD),$(firstword $(KBUILD_EXTMOD))/) -- cgit v1.2.3 From e3cd5136a4ecece6a7599a07add0dfb811a7f49d Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Thu, 11 Jul 2019 16:33:17 +0900 Subject: kconfig: remove meaningless if-conditional in conf_read() sym_is_choice(sym) has already been checked by previous if-block: if (sym_is_choice(sym) || (sym->flags & SYMBOL_NO_WRITE)) continue; Hence, the following code is redundant, and the comment is misleading: if (!sym_is_choice(sym)) continue; /* fall through */ It always takes 'continue', never falls though. Clean up the dead code. Signed-off-by: Masahiro Yamada --- scripts/kconfig/confdata.c | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) (limited to 'scripts') diff --git a/scripts/kconfig/confdata.c b/scripts/kconfig/confdata.c index caab7336abc1..501fdcc5e999 100644 --- a/scripts/kconfig/confdata.c +++ b/scripts/kconfig/confdata.c @@ -534,11 +534,9 @@ int conf_read(const char *name) switch (sym->type) { case S_BOOLEAN: case S_TRISTATE: - if (sym->def[S_DEF_USER].tri != sym_get_tristate_value(sym)) - break; - if (!sym_is_choice(sym)) + if (sym->def[S_DEF_USER].tri == sym_get_tristate_value(sym)) continue; - /* fall through */ + break; default: if (!strcmp(sym->curr.val, sym->def[S_DEF_USER].val)) continue; -- cgit v1.2.3 From 31013836a71e07751a6827f9d2ad41ef502ddaff Mon Sep 17 00:00:00 2001 From: Nicolas Boichat Date: Thu, 11 Jul 2019 20:52:27 -0700 Subject: scripts/decode_stacktrace: match basepath using shell prefix operator, not regex The basepath may contain special characters, which would confuse the regex matcher. ${var#prefix} does the right thing. Link: http://lkml.kernel.org/r/20190518055946.181563-1-drinkcat@chromium.org Fixes: 67a28de47faa8358 ("scripts/decode_stacktrace: only strip base path when a prefix of the path") Signed-off-by: Nicolas Boichat Reviewed-by: Stephen Boyd Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- scripts/decode_stacktrace.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/decode_stacktrace.sh b/scripts/decode_stacktrace.sh index a7a36209a193..6c2c05a75b54 100755 --- a/scripts/decode_stacktrace.sh +++ b/scripts/decode_stacktrace.sh @@ -85,7 +85,7 @@ parse_symbol() { fi # Strip out the base of the path - code=${code//^$basepath/""} + code=${code#$basepath/} # In the case of inlines, move everything to same line code=${code//$'\n'/' '} -- cgit v1.2.3 From fe7d14f174f18745d8dc141377e5f85ae7757d66 Mon Sep 17 00:00:00 2001 From: Nicolas Boichat Date: Thu, 11 Jul 2019 20:52:30 -0700 Subject: scripts/decode_stacktrace: look for modules with .ko.debug extension In Chromium OS kernel builds, we split the debug information as .ko.debug files, and that's what decode_stacktrace.sh needs to use. Relax objfile matching rule to allow any .ko* file to be matched. [drinkcat@chromium.org: add quotes around name pattern] Link: http://lkml.kernel.org/r/20190528103346.42720-1-drinkcat@chromium.org Link: http://lkml.kernel.org/r/20190521234148.64060-1-drinkcat@chromium.org Signed-off-by: Nicolas Boichat Cc: Marc Zyngier Cc: Konstantin Khlebnikov Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- scripts/decode_stacktrace.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/decode_stacktrace.sh b/scripts/decode_stacktrace.sh index 6c2c05a75b54..fa704f17275e 100755 --- a/scripts/decode_stacktrace.sh +++ b/scripts/decode_stacktrace.sh @@ -28,7 +28,7 @@ parse_symbol() { local objfile=${modcache[$module]} else [[ $modpath == "" ]] && return - local objfile=$(find "$modpath" -name $module.ko -print -quit) + local objfile=$(find "$modpath" -name "$module.ko*" -print -quit) [[ $objfile == "" ]] && return modcache[$module]=$objfile fi -- cgit v1.2.3 From cc0e5f1ce0a8017c68983eb6b41a1dbd0d24aa98 Mon Sep 17 00:00:00 2001 From: Paul Walmsley Date: Thu, 11 Jul 2019 20:52:33 -0700 Subject: scripts/spelling.txt: drop "sepc" from the misspelling list The RISC-V architecture has a register named the "Supervisor Exception Program Counter", or "sepc". This abbreviation triggers checkpatch.pl's misspelling detector, resulting in noise in the checkpatch output. The risk that this noise could cause more useful warnings to be missed seems to outweigh the harm of an occasional misspelling of "spec". Thus drop the "sepc" entry from the misspelling list. [akpm@linux-foundation.org: fix existing "sepc" instances, per Joe] Link: http://lkml.kernel.org/r/20190518210037.13674-1-paul.walmsley@sifive.com Signed-off-by: Paul Walmsley Cc: Joe Perches Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- arch/powerpc/kvm/book3s_xics.c | 2 +- arch/unicore32/include/mach/regs-gpio.h | 2 +- drivers/net/wireless/realtek/rtlwifi/wifi.h | 2 +- drivers/scsi/lpfc/lpfc_init.c | 2 +- drivers/staging/rtl8723bs/hal/rtl8723b_phycfg.c | 2 +- scripts/spelling.txt | 1 - 6 files changed, 5 insertions(+), 6 deletions(-) (limited to 'scripts') diff --git a/arch/powerpc/kvm/book3s_xics.c b/arch/powerpc/kvm/book3s_xics.c index e8276161872e..381bf8dea193 100644 --- a/arch/powerpc/kvm/book3s_xics.c +++ b/arch/powerpc/kvm/book3s_xics.c @@ -827,7 +827,7 @@ static noinline int kvmppc_h_eoi(struct kvm_vcpu *vcpu, unsigned long xirr) * * Note: If EOI is incorrectly used by SW to lower the CPPR * value (ie more favored), we do not check for rejection of - * a pending interrupt, this is a SW error and PAPR sepcifies + * a pending interrupt, this is a SW error and PAPR specifies * that we don't have to deal with it. * * The sending of an EOI to the ICS is handled after the diff --git a/arch/unicore32/include/mach/regs-gpio.h b/arch/unicore32/include/mach/regs-gpio.h index 806350e1ccb6..5fc701ee33e3 100644 --- a/arch/unicore32/include/mach/regs-gpio.h +++ b/arch/unicore32/include/mach/regs-gpio.h @@ -32,7 +32,7 @@ */ #define GPIO_GEDR (PKUNITY_GPIO_BASE + 0x0018) /* - * Sepcial Voltage Detect Reg GPIO_GPIR. + * Special Voltage Detect Reg GPIO_GPIR. */ #define GPIO_GPIR (PKUNITY_GPIO_BASE + 0x0020) diff --git a/drivers/net/wireless/realtek/rtlwifi/wifi.h b/drivers/net/wireless/realtek/rtlwifi/wifi.h index 81caa3782ec0..3bdda1c98339 100644 --- a/drivers/net/wireless/realtek/rtlwifi/wifi.h +++ b/drivers/net/wireless/realtek/rtlwifi/wifi.h @@ -598,7 +598,7 @@ enum ht_channel_width { HT_CHANNEL_WIDTH_MAX, }; -/* Ref: 802.11i sepc D10.0 7.3.2.25.1 +/* Ref: 802.11i spec D10.0 7.3.2.25.1 * Cipher Suites Encryption Algorithms */ enum rt_enc_alg { diff --git a/drivers/scsi/lpfc/lpfc_init.c b/drivers/scsi/lpfc/lpfc_init.c index eaaef682de25..adfc2ec0f4fc 100644 --- a/drivers/scsi/lpfc/lpfc_init.c +++ b/drivers/scsi/lpfc/lpfc_init.c @@ -2963,7 +2963,7 @@ lpfc_stop_hba_timers(struct lpfc_hba *phba) del_timer_sync(&phba->fcp_poll_timer); break; case LPFC_PCI_DEV_OC: - /* Stop any OneConnect device sepcific driver timers */ + /* Stop any OneConnect device specific driver timers */ lpfc_sli4_stop_fcf_redisc_wait_timer(phba); break; default: diff --git a/drivers/staging/rtl8723bs/hal/rtl8723b_phycfg.c b/drivers/staging/rtl8723bs/hal/rtl8723b_phycfg.c index 4f2ad54af398..6da7f8e7bdae 100644 --- a/drivers/staging/rtl8723bs/hal/rtl8723b_phycfg.c +++ b/drivers/staging/rtl8723bs/hal/rtl8723b_phycfg.c @@ -45,7 +45,7 @@ static u32 phy_CalculateBitShift(u32 BitMask) /** * Function: PHY_QueryBBReg * -* OverView: Read "sepcific bits" from BB register +* OverView: Read "specific bits" from BB register * * Input: * struct adapter * Adapter, diff --git a/scripts/spelling.txt b/scripts/spelling.txt index 86b87332b9e5..5ae83ce31902 100644 --- a/scripts/spelling.txt +++ b/scripts/spelling.txt @@ -1145,7 +1145,6 @@ senarios||scenarios sentivite||sensitive separatly||separately sepcify||specify -sepc||spec seperated||separated seperately||separately seperate||separate -- cgit v1.2.3 From 85f946ffd3b61ffccefd41a52f267437d878dd3e Mon Sep 17 00:00:00 2001 From: Chris Paterson Date: Thu, 11 Jul 2019 20:52:36 -0700 Subject: scripts/spelling.txt: add spelling fix for prohibited Misspelling 'prohibited' is quite common in the real world, although surprisingly not so much in the Linux Kernel. In addition to fixing the typo we may as well add it to the spelling checker. Also adding the present participle (prohibiting). Link: http://lkml.kernel.org/r/20190514153341.22540-1-chris.paterson2@renesas.com Fixes: 5bf2fbbef50c ("clk: renesas: cpg-mssr: Add r8a77470 support") Signed-off-by: Chris Paterson Acked-by: Stephen Boyd Acked-by: Geert Uytterhoeven Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- drivers/clk/renesas/r8a77470-cpg-mssr.c | 2 +- scripts/spelling.txt | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) (limited to 'scripts') diff --git a/drivers/clk/renesas/r8a77470-cpg-mssr.c b/drivers/clk/renesas/r8a77470-cpg-mssr.c index ab0fb10b6bf0..d81ae65f0d18 100644 --- a/drivers/clk/renesas/r8a77470-cpg-mssr.c +++ b/drivers/clk/renesas/r8a77470-cpg-mssr.c @@ -175,7 +175,7 @@ static const unsigned int r8a77470_crit_mod_clks[] __initconst = { *--------------------------------------------------- * 0 0 20 x80 x78 x50 * 0 1 26 x60 x60 x56 - * 1 0 Prohibitted setting + * 1 0 Prohibited setting * 1 1 30 x52 x52 x50 * * *1 : Table 7.4 indicates VCO output (PLL0 = VCO) diff --git a/scripts/spelling.txt b/scripts/spelling.txt index 5ae83ce31902..99f82a2a5b54 100644 --- a/scripts/spelling.txt +++ b/scripts/spelling.txt @@ -1009,6 +1009,8 @@ programers||programmers programm||program programms||programs progresss||progress +prohibitted||prohibited +prohibitting||prohibiting promiscous||promiscuous promps||prompts pronnounced||pronounced -- cgit v1.2.3 From ca90bbd410a1dc4b607210a5483786726043e9ec Mon Sep 17 00:00:00 2001 From: Evan Green Date: Thu, 11 Jul 2019 20:52:39 -0700 Subject: scripts/decode_stacktrace: Accept dash/underscore in modules The manpage for modprobe mentions that dashes and underscores are treated interchangeably in module names. The stack trace dumps seem to print module names with underscores. Use bash to replace _ with the pattern [-_] so that file names with dashes or underscores can be found. For example, this line: [ 27.919759] hda_widget_sysfs_init+0x2b8/0x3a5 [snd_hda_core] should find a module named snd-hda-core.ko. Link: http://lkml.kernel.org/r/20190531205926.42474-1-evgreen@chromium.org Signed-off-by: Evan Green Reviewed-by: Douglas Anderson Acked-by: Konstantin Khlebnikov Cc: Stephen Rothwell Cc: Douglas Anderson Cc: Evan Green Cc: Nicolas Boichat Cc: Marc Zyngier Cc: Manuel Traut Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- scripts/decode_stacktrace.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/decode_stacktrace.sh b/scripts/decode_stacktrace.sh index fa704f17275e..13e5fbafdf2f 100755 --- a/scripts/decode_stacktrace.sh +++ b/scripts/decode_stacktrace.sh @@ -28,7 +28,7 @@ parse_symbol() { local objfile=${modcache[$module]} else [[ $modpath == "" ]] && return - local objfile=$(find "$modpath" -name "$module.ko*" -print -quit) + local objfile=$(find "$modpath" -name "${module//_/[-_]}.ko*" -print -quit) [[ $objfile == "" ]] && return modcache[$module]=$objfile fi -- cgit v1.2.3 From 6e22fd003e28d4414d2a84eb51f1491f49a70ab9 Mon Sep 17 00:00:00 2001 From: Colin Ian King Date: Thu, 11 Jul 2019 20:52:42 -0700 Subject: scripts/spelling.txt: add more spellings to spelling.txt Here are some of the more common spelling mistakes and typos that I've found while fixing up spelling mistakes in the kernel over the past few months. Developers keep on coming up with more inventive ways to spell words. Link: http://lkml.kernel.org/r/20190618134807.9729-1-colin.king@canonical.com Signed-off-by: Colin Ian King Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- scripts/spelling.txt | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) (limited to 'scripts') diff --git a/scripts/spelling.txt b/scripts/spelling.txt index 99f82a2a5b54..de75b9feaaed 100644 --- a/scripts/spelling.txt +++ b/scripts/spelling.txt @@ -41,6 +41,7 @@ accquired||acquired accross||across acessable||accessible acess||access +acessing||accessing achitecture||architecture acient||ancient acitions||actions @@ -54,6 +55,7 @@ activete||activate actived||activated actualy||actually acumulating||accumulating +acumulative||accumulative acumulator||accumulator adapater||adapter addional||additional @@ -103,6 +105,7 @@ alogrithm||algorithm alot||a lot alow||allow alows||allows +alredy||already altough||although alue||value ambigious||ambiguous @@ -223,6 +226,7 @@ boardcast||broadcast borad||board boundry||boundary brievely||briefly +brigde||bridge broadcase||broadcast broadcat||broadcast bufufer||buffer @@ -239,6 +243,7 @@ calulate||calculate cancelation||cancellation cancle||cancel capabilites||capabilities +capabilties||capabilities capabilty||capability capabitilies||capabilities capablity||capability @@ -325,6 +330,7 @@ conector||connector connecetd||connected configuartion||configuration configuation||configuration +configued||configured configuratoin||configuration configuraton||configuration configuretion||configuration @@ -407,6 +413,7 @@ depreacte||deprecate desactivate||deactivate desciptor||descriptor desciptors||descriptors +descripto||descriptor descripton||description descrition||description descritptor||descriptor @@ -432,6 +439,7 @@ deveolpment||development devided||divided deviece||device diable||disable +dicline||decline dictionnary||dictionary didnt||didn't diferent||different @@ -461,6 +469,7 @@ disharge||discharge disnabled||disabled dispertion||dispersion dissapears||disappears +dissconect||disconnect distiction||distinction divisable||divisible divsiors||divisors @@ -469,11 +478,14 @@ documantation||documentation documentaion||documentation documment||document doesnt||doesn't +donwload||download +donwloading||downloading dorp||drop dosen||doesn downlad||download downlads||downloads droped||dropped +droput||dropout druing||during dynmaic||dynamic eanable||enable @@ -482,6 +494,7 @@ ecspecially||especially edditable||editable editting||editing efective||effective +effectivness||effectiveness efficently||efficiently ehther||ether eigth||eight @@ -543,6 +556,7 @@ extensability||extensibility extention||extension extenstion||extension extracter||extractor +faied||failed faield||failed falied||failed faild||failed @@ -567,6 +581,7 @@ fetaures||features fileystem||filesystem fimware||firmware firmare||firmware +firmaware||firmware firware||firmware finanize||finalize findn||find @@ -601,6 +616,8 @@ funtions||functions furthur||further futhermore||furthermore futrue||future +gatable||gateable +gateing||gating gauage||gauge gaurenteed||guaranteed generiously||generously @@ -641,9 +658,11 @@ iomaped||iomapped imblance||imbalance immeadiately||immediately immedaite||immediate +immedate||immediate immediatelly||immediately immediatly||immediately immidiate||immediate +immutible||immutable impelentation||implementation impementated||implemented implemantation||implementation @@ -661,10 +680,12 @@ incative||inactive incomming||incoming incompatabilities||incompatibilities incompatable||incompatible +incompatble||incompatible inconsistant||inconsistent increas||increase incremeted||incremented incrment||increment +inculde||include indendation||indentation indended||intended independant||independent @@ -778,6 +799,7 @@ libary||library librairies||libraries libraris||libraries licenceing||licencing +logaritmic||logarithmic loggging||logging loggin||login logile||logfile @@ -832,6 +854,7 @@ mispelled||misspelled mispelt||misspelt mising||missing mismactch||mismatch +missign||missing missmanaged||mismanaged missmatch||mismatch miximum||maximum @@ -848,6 +871,7 @@ mopdule||module mroe||more mulitplied||multiplied multidimensionnal||multidimensional +multipe||multiple multple||multiple mumber||number muticast||multicast @@ -870,7 +894,9 @@ nescessary||necessary nessessary||necessary noticable||noticeable notications||notifications +notifcations||notifications notifed||notified +notity||notify numebr||number numner||number obtaion||obtain @@ -887,6 +913,7 @@ occuring||occurring offser||offset offet||offset offloded||offloaded +offseting||offsetting omited||omitted omiting||omitting omitt||omit @@ -1025,6 +1052,7 @@ prosess||process protable||portable protcol||protocol protecion||protection +protedcted||protected protocoll||protocol promixity||proximity psudo||pseudo @@ -1039,6 +1067,7 @@ reasearcher||researcher reasearchers||researchers reasearch||research recepient||recipient +recevied||received receving||receiving recieved||received recieve||receive @@ -1112,6 +1141,7 @@ retreived||retrieved retreive||retrieve retreiving||retrieving retrive||retrieve +retrived||retrieved retuned||returned reudce||reduce reuest||request @@ -1178,6 +1208,7 @@ singaled||signaled singal||signal singed||signed sleeped||slept +sliped||slipped softwares||software speach||speech specfic||specific @@ -1284,6 +1315,7 @@ threds||threads threshhold||threshold thresold||threshold throught||through +trackling||tracking troughput||throughput thses||these tiggers||triggers @@ -1410,5 +1442,6 @@ wnat||want workarould||workaround writeing||writing writting||writing +wtih||with zombe||zombie zomebie||zombie -- cgit v1.2.3 From 3975b097e577bac77267ed8df0f525e3ad3499ec Mon Sep 17 00:00:00 2001 From: Kirill Smelkov Date: Wed, 19 Jun 2019 20:26:56 +0300 Subject: *: convert stream-like files -> stream_open, even if they use noop_llseek This patch continues 10dce8af3422 (fs: stream_open - opener for stream-like files so that read and write can run simultaneously without deadlock) and c5bf68fe0c86 (*: convert stream-like files from nonseekable_open -> stream_open) and teaches steam_open.cocci to consider files as being stream-like not only if they have .llseek=no_llseek, but also if they have .llseek=noop_llseek. This is safe to do: the comment about noop_llseek says This is an implementation of ->llseek useable for the rare special case when userspace expects the seek to succeed but the (device) file is actually not able to perform the seek. In this case you use noop_llseek() instead of falling back to the default implementation of ->llseek. and in general noop_llseek was massively added to drivers in 6038f373a3dc (llseek: automatically add .llseek fop) when changing default for NULL .llseek from NOP to no_llseek with the idea to avoid breaking compatibility, if maybe some user-space program was using lseek on a device without caring about the result, but caring if it was an error or not. Amended semantic patch produces two changes when applied tree-wide: drivers/hid/hid-sensor-custom.c:690:8-24: WARNING: hid_sensor_custom_fops: .read() has stream semantic; safe to change nonseekable_open -> stream_open. drivers/input/mousedev.c:564:1-17: ERROR: mousedev_fops: .read() can deadlock .write(); change nonseekable_open -> stream_open to fix. Cc: Julia Lawall Cc: Jan Blunck Cc: Arnd Bergmann Cc: Jiri Kosina Cc: Jonathan Cameron Cc: Srinivas Pandruvada Cc: Benjamin Tissoires Cc: Dmitry Torokhov Signed-off-by: Kirill Smelkov --- drivers/hid/hid-sensor-custom.c | 2 +- drivers/input/mousedev.c | 2 +- scripts/coccinelle/api/stream_open.cocci | 9 ++++++++- 3 files changed, 10 insertions(+), 3 deletions(-) (limited to 'scripts') diff --git a/drivers/hid/hid-sensor-custom.c b/drivers/hid/hid-sensor-custom.c index c60f82673cf2..fb827c295842 100644 --- a/drivers/hid/hid-sensor-custom.c +++ b/drivers/hid/hid-sensor-custom.c @@ -687,7 +687,7 @@ static int hid_sensor_custom_open(struct inode *inode, struct file *file) if (test_and_set_bit(0, &sensor_inst->misc_opened)) return -EBUSY; - return nonseekable_open(inode, file); + return stream_open(inode, file); } static __poll_t hid_sensor_custom_poll(struct file *file, diff --git a/drivers/input/mousedev.c b/drivers/input/mousedev.c index 3b73e0f17848..505c562a5daa 100644 --- a/drivers/input/mousedev.c +++ b/drivers/input/mousedev.c @@ -558,7 +558,7 @@ static int mousedev_open(struct inode *inode, struct file *file) goto err_free_client; file->private_data = client; - nonseekable_open(inode, file); + stream_open(inode, file); return 0; diff --git a/scripts/coccinelle/api/stream_open.cocci b/scripts/coccinelle/api/stream_open.cocci index 350145da7669..f00c05d207d9 100644 --- a/scripts/coccinelle/api/stream_open.cocci +++ b/scripts/coccinelle/api/stream_open.cocci @@ -134,6 +134,13 @@ identifier fops0.fops; .llseek = no_llseek, }; +@ has_noop_llseek @ +identifier fops0.fops; +@@ + struct file_operations fops = { + .llseek = noop_llseek, + }; + @ has_mmap @ identifier fops0.fops; identifier mmap_f; @@ -180,7 +187,7 @@ identifier splice_write_f; // // XXX for simplicity require no .{read/write}_iter and no .splice_{read/write} for now. // XXX maybe_steam.fops cannot be used in other rules - it gives "bad rule maybe_stream or bad variable fops". -@ maybe_stream depends on (!has_llseek || has_no_llseek) && !has_mmap && !has_copy_file_range && !has_remap_file_range && !has_read_iter && !has_write_iter && !has_splice_read && !has_splice_write @ +@ maybe_stream depends on (!has_llseek || has_no_llseek || has_noop_llseek) && !has_mmap && !has_copy_file_range && !has_remap_file_range && !has_read_iter && !has_write_iter && !has_splice_read && !has_splice_write @ identifier fops0.fops; @@ struct file_operations fops = { -- cgit v1.2.3 From d5ccd65ab6272f21f442695b0022a4f553d818e5 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 19 Apr 2019 19:01:18 -0300 Subject: docs: move gcc_plugins.txt to core-api and rename to .rst The gcc_plugins.txt file is already a ReST file. Move it to the core-api book while renaming it. Signed-off-by: Mauro Carvalho Chehab Acked-by: Kees Cook --- Documentation/core-api/gcc-plugins.rst | 93 ++++++++++++++++++++++++++++++++++ Documentation/core-api/index.rst | 1 + Documentation/gcc-plugins.txt | 93 ---------------------------------- MAINTAINERS | 2 +- scripts/gcc-plugins/Kconfig | 2 +- 5 files changed, 96 insertions(+), 95 deletions(-) create mode 100644 Documentation/core-api/gcc-plugins.rst delete mode 100644 Documentation/gcc-plugins.txt (limited to 'scripts') diff --git a/Documentation/core-api/gcc-plugins.rst b/Documentation/core-api/gcc-plugins.rst new file mode 100644 index 000000000000..8502f24396fb --- /dev/null +++ b/Documentation/core-api/gcc-plugins.rst @@ -0,0 +1,93 @@ +========================= +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 + +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 322ac954b390..da0ed972d224 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -36,6 +36,7 @@ Core utilities memory-hotplug protection-keys ../RCU/index + gcc-plugins Interfaces for kernel debugging diff --git a/Documentation/gcc-plugins.txt b/Documentation/gcc-plugins.txt deleted file mode 100644 index 8502f24396fb..000000000000 --- a/Documentation/gcc-plugins.txt +++ /dev/null @@ -1,93 +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 - -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/MAINTAINERS b/MAINTAINERS index 4b9fd11466a2..db96cd4a229b 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -6655,7 +6655,7 @@ S: Maintained F: scripts/gcc-plugins/ F: scripts/gcc-plugin.sh F: scripts/Makefile.gcc-plugins -F: Documentation/gcc-plugins.txt +F: Documentation/core-api/gcc-plugins.rst GASKET DRIVER FRAMEWORK M: Rob Springer diff --git a/scripts/gcc-plugins/Kconfig b/scripts/gcc-plugins/Kconfig index e9c677a53c74..d33de0b9f4f5 100644 --- a/scripts/gcc-plugins/Kconfig +++ b/scripts/gcc-plugins/Kconfig @@ -23,7 +23,7 @@ config 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/gcc-plugins.txt for details. + See Documentation/core-api/gcc-plugins.rst for details. menu "GCC plugins" depends on GCC_PLUGINS -- cgit v1.2.3 From fe34c89d25429e079ba67416529514120dd715f8 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 18 Jun 2019 12:34:59 -0300 Subject: docs: driver-model: move it to the driver-api book The audience for the Kernel driver-model is clearly Kernel hackers. Signed-off-by: Mauro Carvalho Chehab Acked-by: Jeff Kirsher # ice driver changes --- Documentation/driver-api/driver-model/binding.rst | 98 +++++ Documentation/driver-api/driver-model/bus.rst | 146 +++++++ Documentation/driver-api/driver-model/class.rst | 149 +++++++ .../driver-api/driver-model/design-patterns.rst | 116 ++++++ Documentation/driver-api/driver-model/device.rst | 109 +++++ Documentation/driver-api/driver-model/devres.rst | 414 +++++++++++++++++++ Documentation/driver-api/driver-model/driver.rst | 223 ++++++++++ Documentation/driver-api/driver-model/index.rst | 24 ++ Documentation/driver-api/driver-model/overview.rst | 124 ++++++ Documentation/driver-api/driver-model/platform.rst | 246 +++++++++++ Documentation/driver-api/driver-model/porting.rst | 448 +++++++++++++++++++++ Documentation/driver-api/gpio/driver.rst | 2 +- Documentation/driver-api/index.rst | 1 + Documentation/driver-model/binding.rst | 98 ----- Documentation/driver-model/bus.rst | 146 ------- Documentation/driver-model/class.rst | 149 ------- Documentation/driver-model/design-patterns.rst | 116 ------ Documentation/driver-model/device.rst | 109 ----- Documentation/driver-model/devres.rst | 414 ------------------- Documentation/driver-model/driver.rst | 223 ---------- Documentation/driver-model/index.rst | 26 -- Documentation/driver-model/overview.rst | 124 ------ Documentation/driver-model/platform.rst | 246 ----------- Documentation/driver-model/porting.rst | 448 --------------------- Documentation/eisa.txt | 4 +- Documentation/filesystems/sysfs.txt | 2 +- Documentation/hwmon/submitting-patches.rst | 2 +- .../translations/zh_CN/filesystems/sysfs.txt | 2 +- drivers/base/platform.c | 2 +- drivers/gpio/gpio-cs5535.c | 2 +- drivers/net/ethernet/intel/ice/ice_main.c | 2 +- drivers/staging/unisys/Documentation/overview.txt | 4 +- include/linux/device.h | 2 +- include/linux/platform_device.h | 2 +- scripts/coccinelle/free/devm_free.cocci | 2 +- 35 files changed, 2112 insertions(+), 2113 deletions(-) create mode 100644 Documentation/driver-api/driver-model/binding.rst create mode 100644 Documentation/driver-api/driver-model/bus.rst create mode 100644 Documentation/driver-api/driver-model/class.rst create mode 100644 Documentation/driver-api/driver-model/design-patterns.rst create mode 100644 Documentation/driver-api/driver-model/device.rst create mode 100644 Documentation/driver-api/driver-model/devres.rst create mode 100644 Documentation/driver-api/driver-model/driver.rst create mode 100644 Documentation/driver-api/driver-model/index.rst create mode 100644 Documentation/driver-api/driver-model/overview.rst create mode 100644 Documentation/driver-api/driver-model/platform.rst create mode 100644 Documentation/driver-api/driver-model/porting.rst delete mode 100644 Documentation/driver-model/binding.rst delete mode 100644 Documentation/driver-model/bus.rst delete mode 100644 Documentation/driver-model/class.rst delete mode 100644 Documentation/driver-model/design-patterns.rst delete mode 100644 Documentation/driver-model/device.rst delete mode 100644 Documentation/driver-model/devres.rst delete mode 100644 Documentation/driver-model/driver.rst delete mode 100644 Documentation/driver-model/index.rst delete mode 100644 Documentation/driver-model/overview.rst delete mode 100644 Documentation/driver-model/platform.rst delete mode 100644 Documentation/driver-model/porting.rst (limited to 'scripts') diff --git a/Documentation/driver-api/driver-model/binding.rst b/Documentation/driver-api/driver-model/binding.rst new file mode 100644 index 000000000000..7ea1d7a41e1d --- /dev/null +++ b/Documentation/driver-api/driver-model/binding.rst @@ -0,0 +1,98 @@ +============== +Driver Binding +============== + +Driver binding is the process of associating a device with a device +driver that can control it. Bus drivers have typically handled this +because there have been bus-specific structures to represent the +devices and the drivers. With generic device and device driver +structures, most of the binding can take place using common code. + + +Bus +~~~ + +The bus type structure contains a list of all devices that are on that bus +type in the system. When device_register is called for a device, it is +inserted into the end of this list. The bus object also contains a +list of all drivers of that bus type. When driver_register is called +for a driver, it is inserted at the end of this list. These are the +two events which trigger driver binding. + + +device_register +~~~~~~~~~~~~~~~ + +When a new device is added, the bus's list of drivers is iterated over +to find one that supports it. In order to determine that, the device +ID of the device must match one of the device IDs that the driver +supports. The format and semantics for comparing IDs is bus-specific. +Instead of trying to derive a complex state machine and matching +algorithm, it is up to the bus driver to provide a callback to compare +a device against the IDs of a driver. The bus returns 1 if a match was +found; 0 otherwise. + +int match(struct device * dev, struct device_driver * drv); + +If a match is found, the device's driver field is set to the driver +and the driver's probe callback is called. This gives the driver a +chance to verify that it really does support the hardware, and that +it's in a working state. + +Device Class +~~~~~~~~~~~~ + +Upon the successful completion of probe, the device is registered with +the class to which it belongs. Device drivers belong to one and only one +class, and that is set in the driver's devclass field. +devclass_add_device is called to enumerate the device within the class +and actually register it with the class, which happens with the +class's register_dev callback. + + +Driver +~~~~~~ + +When a driver is attached to a device, the device is inserted into the +driver's list of devices. + + +sysfs +~~~~~ + +A symlink is created in the bus's 'devices' directory that points to +the device's directory in the physical hierarchy. + +A symlink is created in the driver's 'devices' directory that points +to the device's directory in the physical hierarchy. + +A directory for the device is created in the class's directory. A +symlink is created in that directory that points to the device's +physical location in the sysfs tree. + +A symlink can be created (though this isn't done yet) in the device's +physical directory to either its class directory, or the class's +top-level directory. One can also be created to point to its driver's +directory also. + + +driver_register +~~~~~~~~~~~~~~~ + +The process is almost identical for when a new driver is added. +The bus's list of devices is iterated over to find a match. Devices +that already have a driver are skipped. All the devices are iterated +over, to bind as many devices as possible to the driver. + + +Removal +~~~~~~~ + +When a device is removed, the reference count for it will eventually +go to 0. When it does, the remove callback of the driver is called. It +is removed from the driver's list of devices and the reference count +of the driver is decremented. All symlinks between the two are removed. + +When a driver is removed, the list of devices that it supports is +iterated over, and the driver's remove callback is called for each +one. The device is removed from that list and the symlinks removed. diff --git a/Documentation/driver-api/driver-model/bus.rst b/Documentation/driver-api/driver-model/bus.rst new file mode 100644 index 000000000000..016b15a6e8ea --- /dev/null +++ b/Documentation/driver-api/driver-model/bus.rst @@ -0,0 +1,146 @@ +========= +Bus Types +========= + +Definition +~~~~~~~~~~ +See the kerneldoc for the struct bus_type. + +int bus_register(struct bus_type * bus); + + +Declaration +~~~~~~~~~~~ + +Each bus type in the kernel (PCI, USB, etc) should declare one static +object of this type. They must initialize the name field, and may +optionally initialize the match callback:: + + struct bus_type pci_bus_type = { + .name = "pci", + .match = pci_bus_match, + }; + +The structure should be exported to drivers in a header file: + +extern struct bus_type pci_bus_type; + + +Registration +~~~~~~~~~~~~ + +When a bus driver is initialized, it calls bus_register. This +initializes the rest of the fields in the bus object and inserts it +into a global list of bus types. Once the bus object is registered, +the fields in it are usable by the bus driver. + + +Callbacks +~~~~~~~~~ + +match(): Attaching Drivers to Devices +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The format of device ID structures and the semantics for comparing +them are inherently bus-specific. Drivers typically declare an array +of device IDs of devices they support that reside in a bus-specific +driver structure. + +The purpose of the match callback is to give the bus an opportunity to +determine if a particular driver supports a particular device by +comparing the device IDs the driver supports with the device ID of a +particular device, without sacrificing bus-specific functionality or +type-safety. + +When a driver is registered with the bus, the bus's list of devices is +iterated over, and the match callback is called for each device that +does not have a driver associated with it. + + + +Device and Driver Lists +~~~~~~~~~~~~~~~~~~~~~~~ + +The lists of devices and drivers are intended to replace the local +lists that many buses keep. They are lists of struct devices and +struct device_drivers, respectively. Bus drivers are free to use the +lists as they please, but conversion to the bus-specific type may be +necessary. + +The LDM core provides helper functions for iterating over each list:: + + int bus_for_each_dev(struct bus_type * bus, struct device * start, + void * data, + int (*fn)(struct device *, void *)); + + int bus_for_each_drv(struct bus_type * bus, struct device_driver * start, + void * data, int (*fn)(struct device_driver *, void *)); + +These helpers iterate over the respective list, and call the callback +for each device or driver in the list. All list accesses are +synchronized by taking the bus's lock (read currently). The reference +count on each object in the list is incremented before the callback is +called; it is decremented after the next object has been obtained. The +lock is not held when calling the callback. + + +sysfs +~~~~~~~~ +There is a top-level directory named 'bus'. + +Each bus gets a directory in the bus directory, along with two default +directories:: + + /sys/bus/pci/ + |-- devices + `-- drivers + +Drivers registered with the bus get a directory in the bus's drivers +directory:: + + /sys/bus/pci/ + |-- devices + `-- drivers + |-- Intel ICH + |-- Intel ICH Joystick + |-- agpgart + `-- e100 + +Each device that is discovered on a bus of that type gets a symlink in +the bus's devices directory to the device's directory in the physical +hierarchy:: + + /sys/bus/pci/ + |-- devices + | |-- 00:00.0 -> ../../../root/pci0/00:00.0 + | |-- 00:01.0 -> ../../../root/pci0/00:01.0 + | `-- 00:02.0 -> ../../../root/pci0/00:02.0 + `-- drivers + + +Exporting Attributes +~~~~~~~~~~~~~~~~~~~~ + +:: + + struct bus_attribute { + struct attribute attr; + ssize_t (*show)(struct bus_type *, char * buf); + ssize_t (*store)(struct bus_type *, const char * buf, size_t count); + }; + +Bus drivers can export attributes using the BUS_ATTR_RW macro that works +similarly to the DEVICE_ATTR_RW macro for devices. For example, a +definition like this:: + + static BUS_ATTR_RW(debug); + +is equivalent to declaring:: + + static bus_attribute bus_attr_debug; + +This can then be used to add and remove the attribute from the bus's +sysfs directory using:: + + int bus_create_file(struct bus_type *, struct bus_attribute *); + void bus_remove_file(struct bus_type *, struct bus_attribute *); diff --git a/Documentation/driver-api/driver-model/class.rst b/Documentation/driver-api/driver-model/class.rst new file mode 100644 index 000000000000..fff55b80e86a --- /dev/null +++ b/Documentation/driver-api/driver-model/class.rst @@ -0,0 +1,149 @@ +============== +Device Classes +============== + +Introduction +~~~~~~~~~~~~ +A device class describes a type of device, like an audio or network +device. The following device classes have been identified: + + + + +Each device class defines a set of semantics and a programming interface +that devices of that class adhere to. Device drivers are the +implementation of that programming interface for a particular device on +a particular bus. + +Device classes are agnostic with respect to what bus a device resides +on. + + +Programming Interface +~~~~~~~~~~~~~~~~~~~~~ +The device class structure looks like:: + + + typedef int (*devclass_add)(struct device *); + typedef void (*devclass_remove)(struct device *); + +See the kerneldoc for the struct class. + +A typical device class definition would look like:: + + struct device_class input_devclass = { + .name = "input", + .add_device = input_add_device, + .remove_device = input_remove_device, + }; + +Each device class structure should be exported in a header file so it +can be used by drivers, extensions and interfaces. + +Device classes are registered and unregistered with the core using:: + + int devclass_register(struct device_class * cls); + void devclass_unregister(struct device_class * cls); + + +Devices +~~~~~~~ +As devices are bound to drivers, they are added to the device class +that the driver belongs to. Before the driver model core, this would +typically happen during the driver's probe() callback, once the device +has been initialized. It now happens after the probe() callback +finishes from the core. + +The device is enumerated in the class. Each time a device is added to +the class, the class's devnum field is incremented and assigned to the +device. The field is never decremented, so if the device is removed +from the class and re-added, it will receive a different enumerated +value. + +The class is allowed to create a class-specific structure for the +device and store it in the device's class_data pointer. + +There is no list of devices in the device class. Each driver has a +list of devices that it supports. The device class has a list of +drivers of that particular class. To access all of the devices in the +class, iterate over the device lists of each driver in the class. + + +Device Drivers +~~~~~~~~~~~~~~ +Device drivers are added to device classes when they are registered +with the core. A driver specifies the class it belongs to by setting +the struct device_driver::devclass field. + + +sysfs directory structure +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +There is a top-level sysfs directory named 'class'. + +Each class gets a directory in the class directory, along with two +default subdirectories:: + + class/ + `-- input + |-- devices + `-- drivers + + +Drivers registered with the class get a symlink in the drivers/ directory +that points to the driver's directory (under its bus directory):: + + class/ + `-- input + |-- devices + `-- drivers + `-- usb:usb_mouse -> ../../../bus/drivers/usb_mouse/ + + +Each device gets a symlink in the devices/ directory that points to the +device's directory in the physical hierarchy:: + + class/ + `-- input + |-- devices + | `-- 1 -> ../../../root/pci0/00:1f.0/usb_bus/00:1f.2-1:0/ + `-- drivers + + +Exporting Attributes +~~~~~~~~~~~~~~~~~~~~ + +:: + + struct devclass_attribute { + struct attribute attr; + ssize_t (*show)(struct device_class *, char * buf, size_t count, loff_t off); + ssize_t (*store)(struct device_class *, const char * buf, size_t count, loff_t off); + }; + +Class drivers can export attributes using the DEVCLASS_ATTR macro that works +similarly to the DEVICE_ATTR macro for devices. For example, a definition +like this:: + + static DEVCLASS_ATTR(debug,0644,show_debug,store_debug); + +is equivalent to declaring:: + + static devclass_attribute devclass_attr_debug; + +The bus driver can add and remove the attribute from the class's +sysfs directory using:: + + int devclass_create_file(struct device_class *, struct devclass_attribute *); + void devclass_remove_file(struct device_class *, struct devclass_attribute *); + +In the example above, the file will be named 'debug' in placed in the +class's directory in sysfs. + + +Interfaces +~~~~~~~~~~ +There may exist multiple mechanisms for accessing the same device of a +particular class type. Device interfaces describe these mechanisms. + +When a device is added to a device class, the core attempts to add it +to every interface that is registered with the device class. diff --git a/Documentation/driver-api/driver-model/design-patterns.rst b/Documentation/driver-api/driver-model/design-patterns.rst new file mode 100644 index 000000000000..41eb8f41f7dd --- /dev/null +++ b/Documentation/driver-api/driver-model/design-patterns.rst @@ -0,0 +1,116 @@ +============================= +Device Driver Design Patterns +============================= + +This document describes a few common design patterns found in device drivers. +It is likely that subsystem maintainers will ask driver developers to +conform to these design patterns. + +1. State Container +2. container_of() + + +1. State Container +~~~~~~~~~~~~~~~~~~ + +While the kernel contains a few device drivers that assume that they will +only be probed() once on a certain system (singletons), it is custom to assume +that the device the driver binds to will appear in several instances. This +means that the probe() function and all callbacks need to be reentrant. + +The most common way to achieve this is to use the state container design +pattern. It usually has this form:: + + struct foo { + spinlock_t lock; /* Example member */ + (...) + }; + + static int foo_probe(...) + { + struct foo *foo; + + foo = devm_kzalloc(dev, sizeof(*foo), GFP_KERNEL); + if (!foo) + return -ENOMEM; + spin_lock_init(&foo->lock); + (...) + } + +This will create an instance of struct foo in memory every time probe() is +called. This is our state container for this instance of the device driver. +Of course it is then necessary to always pass this instance of the +state around to all functions that need access to the state and its members. + +For example, if the driver is registering an interrupt handler, you would +pass around a pointer to struct foo like this:: + + static irqreturn_t foo_handler(int irq, void *arg) + { + struct foo *foo = arg; + (...) + } + + static int foo_probe(...) + { + struct foo *foo; + + (...) + ret = request_irq(irq, foo_handler, 0, "foo", foo); + } + +This way you always get a pointer back to the correct instance of foo in +your interrupt handler. + + +2. container_of() +~~~~~~~~~~~~~~~~~ + +Continuing on the above example we add an offloaded work:: + + struct foo { + spinlock_t lock; + struct workqueue_struct *wq; + struct work_struct offload; + (...) + }; + + static void foo_work(struct work_struct *work) + { + struct foo *foo = container_of(work, struct foo, offload); + + (...) + } + + static irqreturn_t foo_handler(int irq, void *arg) + { + struct foo *foo = arg; + + queue_work(foo->wq, &foo->offload); + (...) + } + + static int foo_probe(...) + { + struct foo *foo; + + foo->wq = create_singlethread_workqueue("foo-wq"); + INIT_WORK(&foo->offload, foo_work); + (...) + } + +The design pattern is the same for an hrtimer or something similar that will +return a single argument which is a pointer to a struct member in the +callback. + +container_of() is a macro defined in + +What container_of() does is to obtain a pointer to the containing struct from +a pointer to a member by a simple subtraction using the offsetof() macro from +standard C, which allows something similar to object oriented behaviours. +Notice that the contained member must not be a pointer, but an actual member +for this to work. + +We can see here that we avoid having global pointers to our struct foo * +instance this way, while still keeping the number of parameters passed to the +work function to a single pointer. diff --git a/Documentation/driver-api/driver-model/device.rst b/Documentation/driver-api/driver-model/device.rst new file mode 100644 index 000000000000..2b868d49d349 --- /dev/null +++ b/Documentation/driver-api/driver-model/device.rst @@ -0,0 +1,109 @@ +========================== +The Basic Device Structure +========================== + +See the kerneldoc for the struct device. + + +Programming Interface +~~~~~~~~~~~~~~~~~~~~~ +The bus driver that discovers the device uses this to register the +device with the core:: + + int device_register(struct device * dev); + +The bus should initialize the following fields: + + - parent + - name + - bus_id + - bus + +A device is removed from the core when its reference count goes to +0. The reference count can be adjusted using:: + + struct device * get_device(struct device * dev); + void put_device(struct device * dev); + +get_device() will return a pointer to the struct device passed to it +if the reference is not already 0 (if it's in the process of being +removed already). + +A driver can access the lock in the device structure using:: + + void lock_device(struct device * dev); + void unlock_device(struct device * dev); + + +Attributes +~~~~~~~~~~ + +:: + + struct device_attribute { + struct attribute attr; + ssize_t (*show)(struct device *dev, struct device_attribute *attr, + char *buf); + ssize_t (*store)(struct device *dev, struct device_attribute *attr, + const char *buf, size_t count); + }; + +Attributes of devices can be exported by a device driver through sysfs. + +Please see Documentation/filesystems/sysfs.txt for more information +on how sysfs works. + +As explained in Documentation/kobject.txt, device attributes must be +created before the KOBJ_ADD uevent is generated. The only way to realize +that is by defining an attribute group. + +Attributes are declared using a macro called DEVICE_ATTR:: + + #define DEVICE_ATTR(name,mode,show,store) + +Example::: + + static DEVICE_ATTR(type, 0444, show_type, NULL); + static DEVICE_ATTR(power, 0644, show_power, store_power); + +This declares two structures of type struct device_attribute with respective +names 'dev_attr_type' and 'dev_attr_power'. These two attributes can be +organized as follows into a group:: + + static struct attribute *dev_attrs[] = { + &dev_attr_type.attr, + &dev_attr_power.attr, + NULL, + }; + + static struct attribute_group dev_attr_group = { + .attrs = dev_attrs, + }; + + static const struct attribute_group *dev_attr_groups[] = { + &dev_attr_group, + NULL, + }; + +This array of groups can then be associated with a device by setting the +group pointer in struct device before device_register() is invoked:: + + dev->groups = dev_attr_groups; + device_register(dev); + +The device_register() function will use the 'groups' pointer to create the +device attributes and the device_unregister() function will use this pointer +to remove the device attributes. + +Word of warning: While the kernel allows device_create_file() and +device_remove_file() to be called on a device at any time, userspace has +strict expectations on when attributes get created. When a new device is +registered in the kernel, a uevent is generated to notify userspace (like +udev) that a new device is available. If attributes are added after the +device is registered, then userspace won't get notified and userspace will +not know about the new attributes. + +This is important for device driver that need to publish additional +attributes for a device at driver probe time. If the device driver simply +calls device_create_file() on the device structure passed to it, then +userspace will never be notified of the new attributes. diff --git a/Documentation/driver-api/driver-model/devres.rst b/Documentation/driver-api/driver-model/devres.rst new file mode 100644 index 000000000000..4ac99122b5f1 --- /dev/null +++ b/Documentation/driver-api/driver-model/devres.rst @@ -0,0 +1,414 @@ +================================ +Devres - Managed Device Resource +================================ + +Tejun Heo + +First draft 10 January 2007 + +.. contents + + 1. Intro : Huh? Devres? + 2. Devres : Devres in a nutshell + 3. Devres Group : Group devres'es and release them together + 4. Details : Life time rules, calling context, ... + 5. Overhead : How much do we have to pay for this? + 6. List of managed interfaces: Currently implemented managed interfaces + + +1. Intro +-------- + +devres came up while trying to convert libata to use iomap. Each +iomapped address should be kept and unmapped on driver detach. For +example, a plain SFF ATA controller (that is, good old PCI IDE) in +native mode makes use of 5 PCI BARs and all of them should be +maintained. + +As with many other device drivers, libata low level drivers have +sufficient bugs in ->remove and ->probe failure path. Well, yes, +that's probably because libata low level driver developers are lazy +bunch, but aren't all low level driver developers? After spending a +day fiddling with braindamaged hardware with no document or +braindamaged document, if it's finally working, well, it's working. + +For one reason or another, low level drivers don't receive as much +attention or testing as core code, and bugs on driver detach or +initialization failure don't happen often enough to be noticeable. +Init failure path is worse because it's much less travelled while +needs to handle multiple entry points. + +So, many low level drivers end up leaking resources on driver detach +and having half broken failure path implementation in ->probe() which +would leak resources or even cause oops when failure occurs. iomap +adds more to this mix. So do msi and msix. + + +2. Devres +--------- + +devres is basically linked list of arbitrarily sized memory areas +associated with a struct device. Each devres entry is associated with +a release function. A devres can be released in several ways. No +matter what, all devres entries are released on driver detach. On +release, the associated release function is invoked and then the +devres entry is freed. + +Managed interface is created for resources commonly used by device +drivers using devres. For example, coherent DMA memory is acquired +using dma_alloc_coherent(). The managed version is called +dmam_alloc_coherent(). It is identical to dma_alloc_coherent() except +for the DMA memory allocated using it is managed and will be +automatically released on driver detach. Implementation looks like +the following:: + + struct dma_devres { + size_t size; + void *vaddr; + dma_addr_t dma_handle; + }; + + static void dmam_coherent_release(struct device *dev, void *res) + { + struct dma_devres *this = res; + + dma_free_coherent(dev, this->size, this->vaddr, this->dma_handle); + } + + dmam_alloc_coherent(dev, size, dma_handle, gfp) + { + struct dma_devres *dr; + void *vaddr; + + dr = devres_alloc(dmam_coherent_release, sizeof(*dr), gfp); + ... + + /* alloc DMA memory as usual */ + vaddr = dma_alloc_coherent(...); + ... + + /* record size, vaddr, dma_handle in dr */ + dr->vaddr = vaddr; + ... + + devres_add(dev, dr); + + return vaddr; + } + +If a driver uses dmam_alloc_coherent(), the area is guaranteed to be +freed whether initialization fails half-way or the device gets +detached. If most resources are acquired using managed interface, a +driver can have much simpler init and exit code. Init path basically +looks like the following:: + + my_init_one() + { + struct mydev *d; + + d = devm_kzalloc(dev, sizeof(*d), GFP_KERNEL); + if (!d) + return -ENOMEM; + + d->ring = dmam_alloc_coherent(...); + if (!d->ring) + return -ENOMEM; + + if (check something) + return -EINVAL; + ... + + return register_to_upper_layer(d); + } + +And exit path:: + + my_remove_one() + { + unregister_from_upper_layer(d); + shutdown_my_hardware(); + } + +As shown above, low level drivers can be simplified a lot by using +devres. Complexity is shifted from less maintained low level drivers +to better maintained higher layer. Also, as init failure path is +shared with exit path, both can get more testing. + +Note though that when converting current calls or assignments to +managed devm_* versions it is up to you to check if internal operations +like allocating memory, have failed. Managed resources pertains to the +freeing of these resources *only* - all other checks needed are still +on you. In some cases this may mean introducing checks that were not +necessary before moving to the managed devm_* calls. + + +3. Devres group +--------------- + +Devres entries can be grouped using devres group. When a group is +released, all contained normal devres entries and properly nested +groups are released. One usage is to rollback series of acquired +resources on failure. For example:: + + if (!devres_open_group(dev, NULL, GFP_KERNEL)) + return -ENOMEM; + + acquire A; + if (failed) + goto err; + + acquire B; + if (failed) + goto err; + ... + + devres_remove_group(dev, NULL); + return 0; + + err: + devres_release_group(dev, NULL); + return err_code; + +As resource acquisition failure usually means probe failure, constructs +like above are usually useful in midlayer driver (e.g. libata core +layer) where interface function shouldn't have side effect on failure. +For LLDs, just returning error code suffices in most cases. + +Each group is identified by `void *id`. It can either be explicitly +specified by @id argument to devres_open_group() or automatically +created by passing NULL as @id as in the above example. In both +cases, devres_open_group() returns the group's id. The returned id +can be passed to other devres functions to select the target group. +If NULL is given to those functions, the latest open group is +selected. + +For example, you can do something like the following:: + + int my_midlayer_create_something() + { + if (!devres_open_group(dev, my_midlayer_create_something, GFP_KERNEL)) + return -ENOMEM; + + ... + + devres_close_group(dev, my_midlayer_create_something); + return 0; + } + + void my_midlayer_destroy_something() + { + devres_release_group(dev, my_midlayer_create_something); + } + + +4. Details +---------- + +Lifetime of a devres entry begins on devres allocation and finishes +when it is released or destroyed (removed and freed) - no reference +counting. + +devres core guarantees atomicity to all basic devres operations and +has support for single-instance devres types (atomic +lookup-and-add-if-not-found). Other than that, synchronizing +concurrent accesses to allocated devres data is caller's +responsibility. This is usually non-issue because bus ops and +resource allocations already do the job. + +For an example of single-instance devres type, read pcim_iomap_table() +in lib/devres.c. + +All devres interface functions can be called without context if the +right gfp mask is given. + + +5. Overhead +----------- + +Each devres bookkeeping info is allocated together with requested data +area. With debug option turned off, bookkeeping info occupies 16 +bytes on 32bit machines and 24 bytes on 64bit (three pointers rounded +up to ull alignment). If singly linked list is used, it can be +reduced to two pointers (8 bytes on 32bit, 16 bytes on 64bit). + +Each devres group occupies 8 pointers. It can be reduced to 6 if +singly linked list is used. + +Memory space overhead on ahci controller with two ports is between 300 +and 400 bytes on 32bit machine after naive conversion (we can +certainly invest a bit more effort into libata core layer). + + +6. List of managed interfaces +----------------------------- + +CLOCK + devm_clk_get() + devm_clk_get_optional() + devm_clk_put() + devm_clk_hw_register() + devm_of_clk_add_hw_provider() + devm_clk_hw_register_clkdev() + +DMA + dmaenginem_async_device_register() + dmam_alloc_coherent() + dmam_alloc_attrs() + dmam_free_coherent() + dmam_pool_create() + dmam_pool_destroy() + +DRM + devm_drm_dev_init() + +GPIO + devm_gpiod_get() + devm_gpiod_get_index() + devm_gpiod_get_index_optional() + devm_gpiod_get_optional() + devm_gpiod_put() + devm_gpiod_unhinge() + devm_gpiochip_add_data() + devm_gpio_request() + devm_gpio_request_one() + devm_gpio_free() + +I2C + devm_i2c_new_dummy_device() + +IIO + devm_iio_device_alloc() + devm_iio_device_free() + devm_iio_device_register() + devm_iio_device_unregister() + devm_iio_kfifo_allocate() + devm_iio_kfifo_free() + devm_iio_triggered_buffer_setup() + devm_iio_triggered_buffer_cleanup() + devm_iio_trigger_alloc() + devm_iio_trigger_free() + devm_iio_trigger_register() + devm_iio_trigger_unregister() + devm_iio_channel_get() + devm_iio_channel_release() + devm_iio_channel_get_all() + devm_iio_channel_release_all() + +INPUT + devm_input_allocate_device() + +IO region + devm_release_mem_region() + devm_release_region() + devm_release_resource() + devm_request_mem_region() + devm_request_region() + devm_request_resource() + +IOMAP + devm_ioport_map() + devm_ioport_unmap() + devm_ioremap() + devm_ioremap_nocache() + devm_ioremap_wc() + devm_ioremap_resource() : checks resource, requests memory region, ioremaps + devm_iounmap() + pcim_iomap() + pcim_iomap_regions() : do request_region() and iomap() on multiple BARs + pcim_iomap_table() : array of mapped addresses indexed by BAR + pcim_iounmap() + +IRQ + devm_free_irq() + devm_request_any_context_irq() + devm_request_irq() + devm_request_threaded_irq() + devm_irq_alloc_descs() + devm_irq_alloc_desc() + devm_irq_alloc_desc_at() + devm_irq_alloc_desc_from() + devm_irq_alloc_descs_from() + devm_irq_alloc_generic_chip() + devm_irq_setup_generic_chip() + devm_irq_sim_init() + +LED + devm_led_classdev_register() + devm_led_classdev_unregister() + +MDIO + devm_mdiobus_alloc() + devm_mdiobus_alloc_size() + devm_mdiobus_free() + +MEM + devm_free_pages() + devm_get_free_pages() + devm_kasprintf() + devm_kcalloc() + devm_kfree() + devm_kmalloc() + devm_kmalloc_array() + devm_kmemdup() + devm_kstrdup() + devm_kvasprintf() + devm_kzalloc() + +MFD + devm_mfd_add_devices() + +MUX + devm_mux_chip_alloc() + devm_mux_chip_register() + devm_mux_control_get() + +PER-CPU MEM + devm_alloc_percpu() + devm_free_percpu() + +PCI + devm_pci_alloc_host_bridge() : managed PCI host bridge allocation + devm_pci_remap_cfgspace() : ioremap PCI configuration space + devm_pci_remap_cfg_resource() : ioremap PCI configuration space resource + pcim_enable_device() : after success, all PCI ops become managed + pcim_pin_device() : keep PCI device enabled after release + +PHY + devm_usb_get_phy() + devm_usb_put_phy() + +PINCTRL + devm_pinctrl_get() + devm_pinctrl_put() + devm_pinctrl_register() + devm_pinctrl_unregister() + +POWER + devm_reboot_mode_register() + devm_reboot_mode_unregister() + +PWM + devm_pwm_get() + devm_pwm_put() + +REGULATOR + devm_regulator_bulk_get() + devm_regulator_get() + devm_regulator_put() + devm_regulator_register() + +RESET + devm_reset_control_get() + devm_reset_controller_register() + +SERDEV + devm_serdev_device_open() + +SLAVE DMA ENGINE + devm_acpi_dma_controller_register() + +SPI + devm_spi_register_master() + +WATCHDOG + devm_watchdog_register_device() diff --git a/Documentation/driver-api/driver-model/driver.rst b/Documentation/driver-api/driver-model/driver.rst new file mode 100644 index 000000000000..11d281506a04 --- /dev/null +++ b/Documentation/driver-api/driver-model/driver.rst @@ -0,0 +1,223 @@ +============== +Device Drivers +============== + +See the kerneldoc for the struct device_driver. + + +Allocation +~~~~~~~~~~ + +Device drivers are statically allocated structures. Though there may +be multiple devices in a system that a driver supports, struct +device_driver represents the driver as a whole (not a particular +device instance). + +Initialization +~~~~~~~~~~~~~~ + +The driver must initialize at least the name and bus fields. It should +also initialize the devclass field (when it arrives), so it may obtain +the proper linkage internally. It should also initialize as many of +the callbacks as possible, though each is optional. + +Declaration +~~~~~~~~~~~ + +As stated above, struct device_driver objects are statically +allocated. Below is an example declaration of the eepro100 +driver. This declaration is hypothetical only; it relies on the driver +being converted completely to the new model:: + + static struct device_driver eepro100_driver = { + .name = "eepro100", + .bus = &pci_bus_type, + + .probe = eepro100_probe, + .remove = eepro100_remove, + .suspend = eepro100_suspend, + .resume = eepro100_resume, + }; + +Most drivers will not be able to be converted completely to the new +model because the bus they belong to has a bus-specific structure with +bus-specific fields that cannot be generalized. + +The most common example of this are device ID structures. A driver +typically defines an array of device IDs that it supports. The format +of these structures and the semantics for comparing device IDs are +completely bus-specific. Defining them as bus-specific entities would +sacrifice type-safety, so we keep bus-specific structures around. + +Bus-specific drivers should include a generic struct device_driver in +the definition of the bus-specific driver. Like this:: + + struct pci_driver { + const struct pci_device_id *id_table; + struct device_driver driver; + }; + +A definition that included bus-specific fields would look like +(using the eepro100 driver again):: + + static struct pci_driver eepro100_driver = { + .id_table = eepro100_pci_tbl, + .driver = { + .name = "eepro100", + .bus = &pci_bus_type, + .probe = eepro100_probe, + .remove = eepro100_remove, + .suspend = eepro100_suspend, + .resume = eepro100_resume, + }, + }; + +Some may find the syntax of embedded struct initialization awkward or +even a bit ugly. So far, it's the best way we've found to do what we want... + +Registration +~~~~~~~~~~~~ + +:: + + int driver_register(struct device_driver *drv); + +The driver registers the structure on startup. For drivers that have +no bus-specific fields (i.e. don't have a bus-specific driver +structure), they would use driver_register and pass a pointer to their +struct device_driver object. + +Most drivers, however, will have a bus-specific structure and will +need to register with the bus using something like pci_driver_register. + +It is important that drivers register their driver structure as early as +possible. Registration with the core initializes several fields in the +struct device_driver object, including the reference count and the +lock. These fields are assumed to be valid at all times and may be +used by the device model core or the bus driver. + + +Transition Bus Drivers +~~~~~~~~~~~~~~~~~~~~~~ + +By defining wrapper functions, the transition to the new model can be +made easier. Drivers can ignore the generic structure altogether and +let the bus wrapper fill in the fields. For the callbacks, the bus can +define generic callbacks that forward the call to the bus-specific +callbacks of the drivers. + +This solution is intended to be only temporary. In order to get class +information in the driver, the drivers must be modified anyway. Since +converting drivers to the new model should reduce some infrastructural +complexity and code size, it is recommended that they are converted as +class information is added. + +Access +~~~~~~ + +Once the object has been registered, it may access the common fields of +the object, like the lock and the list of devices:: + + int driver_for_each_dev(struct device_driver *drv, void *data, + int (*callback)(struct device *dev, void *data)); + +The devices field is a list of all the devices that have been bound to +the driver. The LDM core provides a helper function to operate on all +the devices a driver controls. This helper locks the driver on each +node access, and does proper reference counting on each device as it +accesses it. + + +sysfs +~~~~~ + +When a driver is registered, a sysfs directory is created in its +bus's directory. In this directory, the driver can export an interface +to userspace to control operation of the driver on a global basis; +e.g. toggling debugging output in the driver. + +A future feature of this directory will be a 'devices' directory. This +directory will contain symlinks to the directories of devices it +supports. + + + +Callbacks +~~~~~~~~~ + +:: + + int (*probe) (struct device *dev); + +The probe() entry is called in task context, with the bus's rwsem locked +and the driver partially bound to the device. Drivers commonly use +container_of() to convert "dev" to a bus-specific type, both in probe() +and other routines. That type often provides device resource data, such +as pci_dev.resource[] or platform_device.resources, which is used in +addition to dev->platform_data to initialize the driver. + +This callback holds the driver-specific logic to bind the driver to a +given device. That includes verifying that the device is present, that +it's a version the driver can handle, that driver data structures can +be allocated and initialized, and that any hardware can be initialized. +Drivers often store a pointer to their state with dev_set_drvdata(). +When the driver has successfully bound itself to that device, then probe() +returns zero and the driver model code will finish its part of binding +the driver to that device. + +A driver's probe() may return a negative errno value to indicate that +the driver did not bind to this device, in which case it should have +released all resources it allocated:: + + int (*remove) (struct device *dev); + +remove is called to unbind a driver from a device. This may be +called if a device is physically removed from the system, if the +driver module is being unloaded, during a reboot sequence, or +in other cases. + +It is up to the driver to determine if the device is present or +not. It should free any resources allocated specifically for the +device; i.e. anything in the device's driver_data field. + +If the device is still present, it should quiesce the device and place +it into a supported low-power state:: + + int (*suspend) (struct device *dev, pm_message_t state); + +suspend is called to put the device in a low power state:: + + int (*resume) (struct device *dev); + +Resume is used to bring a device back from a low power state. + + +Attributes +~~~~~~~~~~ + +:: + + struct driver_attribute { + struct attribute attr; + ssize_t (*show)(struct device_driver *driver, char *buf); + ssize_t (*store)(struct device_driver *, const char *buf, size_t count); + }; + +Device drivers can export attributes via their sysfs directories. +Drivers can declare attributes using a DRIVER_ATTR_RW and DRIVER_ATTR_RO +macro that works identically to the DEVICE_ATTR_RW and DEVICE_ATTR_RO +macros. + +Example:: + + DRIVER_ATTR_RW(debug); + +This is equivalent to declaring:: + + struct driver_attribute driver_attr_debug; + +This can then be used to add and remove the attribute from the +driver's directory using:: + + int driver_create_file(struct device_driver *, const struct driver_attribute *); + void driver_remove_file(struct device_driver *, const struct driver_attribute *); diff --git a/Documentation/driver-api/driver-model/index.rst b/Documentation/driver-api/driver-model/index.rst new file mode 100644 index 000000000000..755016422269 --- /dev/null +++ b/Documentation/driver-api/driver-model/index.rst @@ -0,0 +1,24 @@ +============ +Driver Model +============ + +.. toctree:: + :maxdepth: 1 + + binding + bus + class + design-patterns + device + devres + driver + overview + platform + porting + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/driver-api/driver-model/overview.rst b/Documentation/driver-api/driver-model/overview.rst new file mode 100644 index 000000000000..d4d1e9b40e0c --- /dev/null +++ b/Documentation/driver-api/driver-model/overview.rst @@ -0,0 +1,124 @@ +============================= +The Linux Kernel Device Model +============================= + +Patrick Mochel + +Drafted 26 August 2002 +Updated 31 January 2006 + + +Overview +~~~~~~~~ + +The Linux Kernel Driver Model is a unification of all the disparate driver +models that were previously used in the kernel. It is intended to augment the +bus-specific drivers for bridges and devices by consolidating a set of data +and operations into globally accessible data structures. + +Traditional driver models implemented some sort of tree-like structure +(sometimes just a list) for the devices they control. There wasn't any +uniformity across the different bus types. + +The current driver model provides a common, uniform data model for describing +a bus and the devices that can appear under the bus. The unified bus +model includes a set of common attributes which all busses carry, and a set +of common callbacks, such as device discovery during bus probing, bus +shutdown, bus power management, etc. + +The common device and bridge interface reflects the goals of the modern +computer: namely the ability to do seamless device "plug and play", power +management, and hot plug. In particular, the model dictated by Intel and +Microsoft (namely ACPI) ensures that almost every device on almost any bus +on an x86-compatible system can work within this paradigm. Of course, +not every bus is able to support all such operations, although most +buses support most of those operations. + + +Downstream Access +~~~~~~~~~~~~~~~~~ + +Common data fields have been moved out of individual bus layers into a common +data structure. These fields must still be accessed by the bus layers, +and sometimes by the device-specific drivers. + +Other bus layers are encouraged to do what has been done for the PCI layer. +struct pci_dev now looks like this:: + + struct pci_dev { + ... + + struct device dev; /* Generic device interface */ + ... + }; + +Note first that the struct device dev within the struct pci_dev is +statically allocated. This means only one allocation on device discovery. + +Note also that that struct device dev is not necessarily defined at the +front of the pci_dev structure. This is to make people think about what +they're doing when switching between the bus driver and the global driver, +and to discourage meaningless and incorrect casts between the two. + +The PCI bus layer freely accesses the fields of struct device. It knows about +the structure of struct pci_dev, and it should know the structure of struct +device. Individual PCI device drivers that have been converted to the current +driver model generally do not and should not touch the fields of struct device, +unless there is a compelling reason to do so. + +The above abstraction prevents unnecessary pain during transitional phases. +If it were not done this way, then when a field was renamed or removed, every +downstream driver would break. On the other hand, if only the bus layer +(and not the device layer) accesses the struct device, it is only the bus +layer that needs to change. + + +User Interface +~~~~~~~~~~~~~~ + +By virtue of having a complete hierarchical view of all the devices in the +system, exporting a complete hierarchical view to userspace becomes relatively +easy. This has been accomplished by implementing a special purpose virtual +file system named sysfs. + +Almost all mainstream Linux distros mount this filesystem automatically; you +can see some variation of the following in the output of the "mount" command:: + + $ mount + ... + none on /sys type sysfs (rw,noexec,nosuid,nodev) + ... + $ + +The auto-mounting of sysfs is typically accomplished by an entry similar to +the following in the /etc/fstab file:: + + none /sys sysfs defaults 0 0 + +or something similar in the /lib/init/fstab file on Debian-based systems:: + + none /sys sysfs nodev,noexec,nosuid 0 0 + +If sysfs is not automatically mounted, you can always do it manually with:: + + # mount -t sysfs sysfs /sys + +Whenever a device is inserted into the tree, a directory is created for it. +This directory may be populated at each layer of discovery - the global layer, +the bus layer, or the device layer. + +The global layer currently creates two files - 'name' and 'power'. The +former only reports the name of the device. The latter reports the +current power state of the device. It will also be used to set the current +power state. + +The bus layer may also create files for the devices it finds while probing the +bus. For example, the PCI layer currently creates 'irq' and 'resource' files +for each PCI device. + +A device-specific driver may also export files in its directory to expose +device-specific data or tunable interfaces. + +More information about the sysfs directory layout can be found in +the other documents in this directory and in the file +Documentation/filesystems/sysfs.txt. diff --git a/Documentation/driver-api/driver-model/platform.rst b/Documentation/driver-api/driver-model/platform.rst new file mode 100644 index 000000000000..334dd4071ae4 --- /dev/null +++ b/Documentation/driver-api/driver-model/platform.rst @@ -0,0 +1,246 @@ +============================ +Platform Devices and Drivers +============================ + +See for the driver model interface to the +platform bus: platform_device, and platform_driver. This pseudo-bus +is used to connect devices on busses with minimal infrastructure, +like those used to integrate peripherals on many system-on-chip +processors, or some "legacy" PC interconnects; as opposed to large +formally specified ones like PCI or USB. + + +Platform devices +~~~~~~~~~~~~~~~~ +Platform devices are devices that typically appear as autonomous +entities in the system. This includes legacy port-based devices and +host bridges to peripheral buses, and most controllers integrated +into system-on-chip platforms. What they usually have in common +is direct addressing from a CPU bus. Rarely, a platform_device will +be connected through a segment of some other kind of bus; but its +registers will still be directly addressable. + +Platform devices are given a name, used in driver binding, and a +list of resources such as addresses and IRQs:: + + struct platform_device { + const char *name; + u32 id; + struct device dev; + u32 num_resources; + struct resource *resource; + }; + + +Platform drivers +~~~~~~~~~~~~~~~~ +Platform drivers follow the standard driver model convention, where +discovery/enumeration is handled outside the drivers, and drivers +provide probe() and remove() methods. They support power management +and shutdown notifications using the standard conventions:: + + struct platform_driver { + int (*probe)(struct platform_device *); + int (*remove)(struct platform_device *); + void (*shutdown)(struct platform_device *); + int (*suspend)(struct platform_device *, pm_message_t state); + int (*suspend_late)(struct platform_device *, pm_message_t state); + int (*resume_early)(struct platform_device *); + int (*resume)(struct platform_device *); + struct device_driver driver; + }; + +Note that probe() should in general verify that the specified device hardware +actually exists; sometimes platform setup code can't be sure. The probing +can use device resources, including clocks, and device platform_data. + +Platform drivers register themselves the normal way:: + + int platform_driver_register(struct platform_driver *drv); + +Or, in common situations where the device is known not to be hot-pluggable, +the probe() routine can live in an init section to reduce the driver's +runtime memory footprint:: + + int platform_driver_probe(struct platform_driver *drv, + int (*probe)(struct platform_device *)) + +Kernel modules can be composed of several platform drivers. The platform core +provides helpers to register and unregister an array of drivers:: + + int __platform_register_drivers(struct platform_driver * const *drivers, + unsigned int count, struct module *owner); + void platform_unregister_drivers(struct platform_driver * const *drivers, + unsigned int count); + +If one of the drivers fails to register, all drivers registered up to that +point will be unregistered in reverse order. Note that there is a convenience +macro that passes THIS_MODULE as owner parameter:: + + #define platform_register_drivers(drivers, count) + + +Device Enumeration +~~~~~~~~~~~~~~~~~~ +As a rule, platform specific (and often board-specific) setup code will +register platform devices:: + + int platform_device_register(struct platform_device *pdev); + + int platform_add_devices(struct platform_device **pdevs, int ndev); + +The general rule is to register only those devices that actually exist, +but in some cases extra devices might be registered. For example, a kernel +might be configured to work with an external network adapter that might not +be populated on all boards, or likewise to work with an integrated controller +that some boards might not hook up to any peripherals. + +In some cases, boot firmware will export tables describing the devices +that are populated on a given board. Without such tables, often the +only way for system setup code to set up the correct devices is to build +a kernel for a specific target board. Such board-specific kernels are +common with embedded and custom systems development. + +In many cases, the memory and IRQ resources associated with the platform +device are not enough to let the device's driver work. Board setup code +will often provide additional information using the device's platform_data +field to hold additional information. + +Embedded systems frequently need one or more clocks for platform devices, +which are normally kept off until they're actively needed (to save power). +System setup also associates those clocks with the device, so that that +calls to clk_get(&pdev->dev, clock_name) return them as needed. + + +Legacy Drivers: Device Probing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Some drivers are not fully converted to the driver model, because they take +on a non-driver role: the driver registers its platform device, rather than +leaving that for system infrastructure. Such drivers can't be hotplugged +or coldplugged, since those mechanisms require device creation to be in a +different system component than the driver. + +The only "good" reason for this is to handle older system designs which, like +original IBM PCs, rely on error-prone "probe-the-hardware" models for hardware +configuration. Newer systems have largely abandoned that model, in favor of +bus-level support for dynamic configuration (PCI, USB), or device tables +provided by the boot firmware (e.g. PNPACPI on x86). There are too many +conflicting options about what might be where, and even educated guesses by +an operating system will be wrong often enough to make trouble. + +This style of driver is discouraged. If you're updating such a driver, +please try to move the device enumeration to a more appropriate location, +outside the driver. This will usually be cleanup, since such drivers +tend to already have "normal" modes, such as ones using device nodes that +were created by PNP or by platform device setup. + +None the less, there are some APIs to support such legacy drivers. Avoid +using these calls except with such hotplug-deficient drivers:: + + struct platform_device *platform_device_alloc( + const char *name, int id); + +You can use platform_device_alloc() to dynamically allocate a device, which +you will then initialize with resources and platform_device_register(). +A better solution is usually:: + + struct platform_device *platform_device_register_simple( + const char *name, int id, + struct resource *res, unsigned int nres); + +You can use platform_device_register_simple() as a one-step call to allocate +and register a device. + + +Device Naming and Driver Binding +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The platform_device.dev.bus_id is the canonical name for the devices. +It's built from two components: + + * platform_device.name ... which is also used to for driver matching. + + * platform_device.id ... the device instance number, or else "-1" + to indicate there's only one. + +These are concatenated, so name/id "serial"/0 indicates bus_id "serial.0", and +"serial/3" indicates bus_id "serial.3"; both would use the platform_driver +named "serial". While "my_rtc"/-1 would be bus_id "my_rtc" (no instance id) +and use the platform_driver called "my_rtc". + +Driver binding is performed automatically by the driver core, invoking +driver probe() after finding a match between device and driver. If the +probe() succeeds, the driver and device are bound as usual. There are +three different ways to find such a match: + + - Whenever a device is registered, the drivers for that bus are + checked for matches. Platform devices should be registered very + early during system boot. + + - When a driver is registered using platform_driver_register(), all + unbound devices on that bus are checked for matches. Drivers + usually register later during booting, or by module loading. + + - Registering a driver using platform_driver_probe() works just like + using platform_driver_register(), except that the driver won't + be probed later if another device registers. (Which is OK, since + this interface is only for use with non-hotpluggable devices.) + + +Early Platform Devices and Drivers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The early platform interfaces provide platform data to platform device +drivers early on during the system boot. The code is built on top of the +early_param() command line parsing and can be executed very early on. + +Example: "earlyprintk" class early serial console in 6 steps + +1. Registering early platform device data +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The architecture code registers platform device data using the function +early_platform_add_devices(). In the case of early serial console this +should be hardware configuration for the serial port. Devices registered +at this point will later on be matched against early platform drivers. + +2. Parsing kernel command line +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The architecture code calls parse_early_param() to parse the kernel +command line. This will execute all matching early_param() callbacks. +User specified early platform devices will be registered at this point. +For the early serial console case the user can specify port on the +kernel command line as "earlyprintk=serial.0" where "earlyprintk" is +the class string, "serial" is the name of the platform driver and +0 is the platform device id. If the id is -1 then the dot and the +id can be omitted. + +3. Installing early platform drivers belonging to a certain class +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The architecture code may optionally force registration of all early +platform drivers belonging to a certain class using the function +early_platform_driver_register_all(). User specified devices from +step 2 have priority over these. This step is omitted by the serial +driver example since the early serial driver code should be disabled +unless the user has specified port on the kernel command line. + +4. Early platform driver registration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Compiled-in platform drivers making use of early_platform_init() are +automatically registered during step 2 or 3. The serial driver example +should use early_platform_init("earlyprintk", &platform_driver). + +5. Probing of early platform drivers belonging to a certain class +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The architecture code calls early_platform_driver_probe() to match +registered early platform devices associated with a certain class with +registered early platform drivers. Matched devices will get probed(). +This step can be executed at any point during the early boot. As soon +as possible may be good for the serial port case. + +6. Inside the early platform driver probe() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The driver code needs to take special care during early boot, especially +when it comes to memory allocation and interrupt registration. The code +in the probe() function can use is_early_platform_device() to check if +it is called at early platform device or at the regular platform device +time. The early serial driver performs register_console() at this point. + +For further information, see . diff --git a/Documentation/driver-api/driver-model/porting.rst b/Documentation/driver-api/driver-model/porting.rst new file mode 100644 index 000000000000..931ea879af3f --- /dev/null +++ b/Documentation/driver-api/driver-model/porting.rst @@ -0,0 +1,448 @@ +======================================= +Porting Drivers to the New Driver Model +======================================= + +Patrick Mochel + +7 January 2003 + + +Overview + +Please refer to `Documentation/driver-api/driver-model/*.rst` for definitions of +various driver types and concepts. + +Most of the work of porting devices drivers to the new model happens +at the bus driver layer. This was intentional, to minimize the +negative effect on kernel drivers, and to allow a gradual transition +of bus drivers. + +In a nutshell, the driver model consists of a set of objects that can +be embedded in larger, bus-specific objects. Fields in these generic +objects can replace fields in the bus-specific objects. + +The generic objects must be registered with the driver model core. By +doing so, they will exported via the sysfs filesystem. sysfs can be +mounted by doing:: + + # mount -t sysfs sysfs /sys + + + +The Process + +Step 0: Read include/linux/device.h for object and function definitions. + +Step 1: Registering the bus driver. + + +- Define a struct bus_type for the bus driver:: + + struct bus_type pci_bus_type = { + .name = "pci", + }; + + +- Register the bus type. + + This should be done in the initialization function for the bus type, + which is usually the module_init(), or equivalent, function:: + + static int __init pci_driver_init(void) + { + return bus_register(&pci_bus_type); + } + + subsys_initcall(pci_driver_init); + + + The bus type may be unregistered (if the bus driver may be compiled + as a module) by doing:: + + bus_unregister(&pci_bus_type); + + +- Export the bus type for others to use. + + Other code may wish to reference the bus type, so declare it in a + shared header file and export the symbol. + +From include/linux/pci.h:: + + extern struct bus_type pci_bus_type; + + +From file the above code appears in:: + + EXPORT_SYMBOL(pci_bus_type); + + + +- This will cause the bus to show up in /sys/bus/pci/ with two + subdirectories: 'devices' and 'drivers':: + + # tree -d /sys/bus/pci/ + /sys/bus/pci/ + |-- devices + `-- drivers + + + +Step 2: Registering Devices. + +struct device represents a single device. It mainly contains metadata +describing the relationship the device has to other entities. + + +- Embed a struct device in the bus-specific device type:: + + + struct pci_dev { + ... + struct device dev; /* Generic device interface */ + ... + }; + + It is recommended that the generic device not be the first item in + the struct to discourage programmers from doing mindless casts + between the object types. Instead macros, or inline functions, + should be created to convert from the generic object type:: + + + #define to_pci_dev(n) container_of(n, struct pci_dev, dev) + + or + + static inline struct pci_dev * to_pci_dev(struct kobject * kobj) + { + return container_of(n, struct pci_dev, dev); + } + + This allows the compiler to verify type-safety of the operations + that are performed (which is Good). + + +- Initialize the device on registration. + + When devices are discovered or registered with the bus type, the + bus driver should initialize the generic device. The most important + things to initialize are the bus_id, parent, and bus fields. + + The bus_id is an ASCII string that contains the device's address on + the bus. The format of this string is bus-specific. This is + necessary for representing devices in sysfs. + + parent is the physical parent of the device. It is important that + the bus driver sets this field correctly. + + The driver model maintains an ordered list of devices that it uses + for power management. This list must be in order to guarantee that + devices are shutdown before their physical parents, and vice versa. + The order of this list is determined by the parent of registered + devices. + + Also, the location of the device's sysfs directory depends on a + device's parent. sysfs exports a directory structure that mirrors + the device hierarchy. Accurately setting the parent guarantees that + sysfs will accurately represent the hierarchy. + + The device's bus field is a pointer to the bus type the device + belongs to. This should be set to the bus_type that was declared + and initialized before. + + Optionally, the bus driver may set the device's name and release + fields. + + The name field is an ASCII string describing the device, like + + "ATI Technologies Inc Radeon QD" + + The release field is a callback that the driver model core calls + when the device has been removed, and all references to it have + been released. More on this in a moment. + + +- Register the device. + + Once the generic device has been initialized, it can be registered + with the driver model core by doing:: + + device_register(&dev->dev); + + It can later be unregistered by doing:: + + device_unregister(&dev->dev); + + This should happen on buses that support hotpluggable devices. + If a bus driver unregisters a device, it should not immediately free + it. It should instead wait for the driver model core to call the + device's release method, then free the bus-specific object. + (There may be other code that is currently referencing the device + structure, and it would be rude to free the device while that is + happening). + + + When the device is registered, a directory in sysfs is created. + The PCI tree in sysfs looks like:: + + /sys/devices/pci0/ + |-- 00:00.0 + |-- 00:01.0 + | `-- 01:00.0 + |-- 00:02.0 + | `-- 02:1f.0 + | `-- 03:00.0 + |-- 00:1e.0 + | `-- 04:04.0 + |-- 00:1f.0 + |-- 00:1f.1 + | |-- ide0 + | | |-- 0.0 + | | `-- 0.1 + | `-- ide1 + | `-- 1.0 + |-- 00:1f.2 + |-- 00:1f.3 + `-- 00:1f.5 + + Also, symlinks are created in the bus's 'devices' directory + that point to the device's directory in the physical hierarchy:: + + /sys/bus/pci/devices/ + |-- 00:00.0 -> ../../../devices/pci0/00:00.0 + |-- 00:01.0 -> ../../../devices/pci0/00:01.0 + |-- 00:02.0 -> ../../../devices/pci0/00:02.0 + |-- 00:1e.0 -> ../../../devices/pci0/00:1e.0 + |-- 00:1f.0 -> ../../../devices/pci0/00:1f.0 + |-- 00:1f.1 -> ../../../devices/pci0/00:1f.1 + |-- 00:1f.2 -> ../../../devices/pci0/00:1f.2 + |-- 00:1f.3 -> ../../../devices/pci0/00:1f.3 + |-- 00:1f.5 -> ../../../devices/pci0/00:1f.5 + |-- 01:00.0 -> ../../../devices/pci0/00:01.0/01:00.0 + |-- 02:1f.0 -> ../../../devices/pci0/00:02.0/02:1f.0 + |-- 03:00.0 -> ../../../devices/pci0/00:02.0/02:1f.0/03:00.0 + `-- 04:04.0 -> ../../../devices/pci0/00:1e.0/04:04.0 + + + +Step 3: Registering Drivers. + +struct device_driver is a simple driver structure that contains a set +of operations that the driver model core may call. + + +- Embed a struct device_driver in the bus-specific driver. + + Just like with devices, do something like:: + + struct pci_driver { + ... + struct device_driver driver; + }; + + +- Initialize the generic driver structure. + + When the driver registers with the bus (e.g. doing pci_register_driver()), + initialize the necessary fields of the driver: the name and bus + fields. + + +- Register the driver. + + After the generic driver has been initialized, call:: + + driver_register(&drv->driver); + + to register the driver with the core. + + When the driver is unregistered from the bus, unregister it from the + core by doing:: + + driver_unregister(&drv->driver); + + Note that this will block until all references to the driver have + gone away. Normally, there will not be any. + + +- Sysfs representation. + + Drivers are exported via sysfs in their bus's 'driver's directory. + For example:: + + /sys/bus/pci/drivers/ + |-- 3c59x + |-- Ensoniq AudioPCI + |-- agpgart-amdk7 + |-- e100 + `-- serial + + +Step 4: Define Generic Methods for Drivers. + +struct device_driver defines a set of operations that the driver model +core calls. Most of these operations are probably similar to +operations the bus already defines for drivers, but taking different +parameters. + +It would be difficult and tedious to force every driver on a bus to +simultaneously convert their drivers to generic format. Instead, the +bus driver should define single instances of the generic methods that +forward call to the bus-specific drivers. For instance:: + + + static int pci_device_remove(struct device * dev) + { + struct pci_dev * pci_dev = to_pci_dev(dev); + struct pci_driver * drv = pci_dev->driver; + + if (drv) { + if (drv->remove) + drv->remove(pci_dev); + pci_dev->driver = NULL; + } + return 0; + } + + +The generic driver should be initialized with these methods before it +is registered:: + + /* initialize common driver fields */ + drv->driver.name = drv->name; + drv->driver.bus = &pci_bus_type; + drv->driver.probe = pci_device_probe; + drv->driver.resume = pci_device_resume; + drv->driver.suspend = pci_device_suspend; + drv->driver.remove = pci_device_remove; + + /* register with core */ + driver_register(&drv->driver); + + +Ideally, the bus should only initialize the fields if they are not +already set. This allows the drivers to implement their own generic +methods. + + +Step 5: Support generic driver binding. + +The model assumes that a device or driver can be dynamically +registered with the bus at any time. When registration happens, +devices must be bound to a driver, or drivers must be bound to all +devices that it supports. + +A driver typically contains a list of device IDs that it supports. The +bus driver compares these IDs to the IDs of devices registered with it. +The format of the device IDs, and the semantics for comparing them are +bus-specific, so the generic model does attempt to generalize them. + +Instead, a bus may supply a method in struct bus_type that does the +comparison:: + + int (*match)(struct device * dev, struct device_driver * drv); + +match should return positive value if the driver supports the device, +and zero otherwise. It may also return error code (for example +-EPROBE_DEFER) if determining that given driver supports the device is +not possible. + +When a device is registered, the bus's list of drivers is iterated +over. bus->match() is called for each one until a match is found. + +When a driver is registered, the bus's list of devices is iterated +over. bus->match() is called for each device that is not already +claimed by a driver. + +When a device is successfully bound to a driver, device->driver is +set, the device is added to a per-driver list of devices, and a +symlink is created in the driver's sysfs directory that points to the +device's physical directory:: + + /sys/bus/pci/drivers/ + |-- 3c59x + | `-- 00:0b.0 -> ../../../../devices/pci0/00:0b.0 + |-- Ensoniq AudioPCI + |-- agpgart-amdk7 + | `-- 00:00.0 -> ../../../../devices/pci0/00:00.0 + |-- e100 + | `-- 00:0c.0 -> ../../../../devices/pci0/00:0c.0 + `-- serial + + +This driver binding should replace the existing driver binding +mechanism the bus currently uses. + + +Step 6: Supply a hotplug callback. + +Whenever a device is registered with the driver model core, the +userspace program /sbin/hotplug is called to notify userspace. +Users can define actions to perform when a device is inserted or +removed. + +The driver model core passes several arguments to userspace via +environment variables, including + +- ACTION: set to 'add' or 'remove' +- DEVPATH: set to the device's physical path in sysfs. + +A bus driver may also supply additional parameters for userspace to +consume. To do this, a bus must implement the 'hotplug' method in +struct bus_type:: + + int (*hotplug) (struct device *dev, char **envp, + int num_envp, char *buffer, int buffer_size); + +This is called immediately before /sbin/hotplug is executed. + + +Step 7: Cleaning up the bus driver. + +The generic bus, device, and driver structures provide several fields +that can replace those defined privately to the bus driver. + +- Device list. + +struct bus_type contains a list of all devices registered with the bus +type. This includes all devices on all instances of that bus type. +An internal list that the bus uses may be removed, in favor of using +this one. + +The core provides an iterator to access these devices:: + + int bus_for_each_dev(struct bus_type * bus, struct device * start, + void * data, int (*fn)(struct device *, void *)); + + +- Driver list. + +struct bus_type also contains a list of all drivers registered with +it. An internal list of drivers that the bus driver maintains may +be removed in favor of using the generic one. + +The drivers may be iterated over, like devices:: + + int bus_for_each_drv(struct bus_type * bus, struct device_driver * start, + void * data, int (*fn)(struct device_driver *, void *)); + + +Please see drivers/base/bus.c for more information. + + +- rwsem + +struct bus_type contains an rwsem that protects all core accesses to +the device and driver lists. This can be used by the bus driver +internally, and should be used when accessing the device or driver +lists the bus maintains. + + +- Device and driver fields. + +Some of the fields in struct device and struct device_driver duplicate +fields in the bus-specific representations of these objects. Feel free +to remove the bus-specific ones and favor the generic ones. Note +though, that this will likely mean fixing up all the drivers that +reference the bus-specific fields (though those should all be 1-line +changes). diff --git a/Documentation/driver-api/gpio/driver.rst b/Documentation/driver-api/gpio/driver.rst index 349f2dc33029..921c71a3d683 100644 --- a/Documentation/driver-api/gpio/driver.rst +++ b/Documentation/driver-api/gpio/driver.rst @@ -399,7 +399,7 @@ symbol: will pass the struct gpio_chip* for the chip to all IRQ callbacks, so the callbacks need to embed the gpio_chip in its state container and obtain a pointer to the container using container_of(). - (See Documentation/driver-model/design-patterns.rst) + (See Documentation/driver-api/driver-model/design-patterns.rst) - gpiochip_irqchip_add_nested(): adds a nested cascaded irqchip to a gpiochip, as discussed above regarding different types of cascaded irqchips. The diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index b4c993ff7655..9fb03b7bdeb1 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -14,6 +14,7 @@ available subsections can be seen below. .. toctree:: :maxdepth: 2 + driver-model/index basics infrastructure early-userspace/index diff --git a/Documentation/driver-model/binding.rst b/Documentation/driver-model/binding.rst deleted file mode 100644 index 7ea1d7a41e1d..000000000000 --- a/Documentation/driver-model/binding.rst +++ /dev/null @@ -1,98 +0,0 @@ -============== -Driver Binding -============== - -Driver binding is the process of associating a device with a device -driver that can control it. Bus drivers have typically handled this -because there have been bus-specific structures to represent the -devices and the drivers. With generic device and device driver -structures, most of the binding can take place using common code. - - -Bus -~~~ - -The bus type structure contains a list of all devices that are on that bus -type in the system. When device_register is called for a device, it is -inserted into the end of this list. The bus object also contains a -list of all drivers of that bus type. When driver_register is called -for a driver, it is inserted at the end of this list. These are the -two events which trigger driver binding. - - -device_register -~~~~~~~~~~~~~~~ - -When a new device is added, the bus's list of drivers is iterated over -to find one that supports it. In order to determine that, the device -ID of the device must match one of the device IDs that the driver -supports. The format and semantics for comparing IDs is bus-specific. -Instead of trying to derive a complex state machine and matching -algorithm, it is up to the bus driver to provide a callback to compare -a device against the IDs of a driver. The bus returns 1 if a match was -found; 0 otherwise. - -int match(struct device * dev, struct device_driver * drv); - -If a match is found, the device's driver field is set to the driver -and the driver's probe callback is called. This gives the driver a -chance to verify that it really does support the hardware, and that -it's in a working state. - -Device Class -~~~~~~~~~~~~ - -Upon the successful completion of probe, the device is registered with -the class to which it belongs. Device drivers belong to one and only one -class, and that is set in the driver's devclass field. -devclass_add_device is called to enumerate the device within the class -and actually register it with the class, which happens with the -class's register_dev callback. - - -Driver -~~~~~~ - -When a driver is attached to a device, the device is inserted into the -driver's list of devices. - - -sysfs -~~~~~ - -A symlink is created in the bus's 'devices' directory that points to -the device's directory in the physical hierarchy. - -A symlink is created in the driver's 'devices' directory that points -to the device's directory in the physical hierarchy. - -A directory for the device is created in the class's directory. A -symlink is created in that directory that points to the device's -physical location in the sysfs tree. - -A symlink can be created (though this isn't done yet) in the device's -physical directory to either its class directory, or the class's -top-level directory. One can also be created to point to its driver's -directory also. - - -driver_register -~~~~~~~~~~~~~~~ - -The process is almost identical for when a new driver is added. -The bus's list of devices is iterated over to find a match. Devices -that already have a driver are skipped. All the devices are iterated -over, to bind as many devices as possible to the driver. - - -Removal -~~~~~~~ - -When a device is removed, the reference count for it will eventually -go to 0. When it does, the remove callback of the driver is called. It -is removed from the driver's list of devices and the reference count -of the driver is decremented. All symlinks between the two are removed. - -When a driver is removed, the list of devices that it supports is -iterated over, and the driver's remove callback is called for each -one. The device is removed from that list and the symlinks removed. diff --git a/Documentation/driver-model/bus.rst b/Documentation/driver-model/bus.rst deleted file mode 100644 index 016b15a6e8ea..000000000000 --- a/Documentation/driver-model/bus.rst +++ /dev/null @@ -1,146 +0,0 @@ -========= -Bus Types -========= - -Definition -~~~~~~~~~~ -See the kerneldoc for the struct bus_type. - -int bus_register(struct bus_type * bus); - - -Declaration -~~~~~~~~~~~ - -Each bus type in the kernel (PCI, USB, etc) should declare one static -object of this type. They must initialize the name field, and may -optionally initialize the match callback:: - - struct bus_type pci_bus_type = { - .name = "pci", - .match = pci_bus_match, - }; - -The structure should be exported to drivers in a header file: - -extern struct bus_type pci_bus_type; - - -Registration -~~~~~~~~~~~~ - -When a bus driver is initialized, it calls bus_register. This -initializes the rest of the fields in the bus object and inserts it -into a global list of bus types. Once the bus object is registered, -the fields in it are usable by the bus driver. - - -Callbacks -~~~~~~~~~ - -match(): Attaching Drivers to Devices -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The format of device ID structures and the semantics for comparing -them are inherently bus-specific. Drivers typically declare an array -of device IDs of devices they support that reside in a bus-specific -driver structure. - -The purpose of the match callback is to give the bus an opportunity to -determine if a particular driver supports a particular device by -comparing the device IDs the driver supports with the device ID of a -particular device, without sacrificing bus-specific functionality or -type-safety. - -When a driver is registered with the bus, the bus's list of devices is -iterated over, and the match callback is called for each device that -does not have a driver associated with it. - - - -Device and Driver Lists -~~~~~~~~~~~~~~~~~~~~~~~ - -The lists of devices and drivers are intended to replace the local -lists that many buses keep. They are lists of struct devices and -struct device_drivers, respectively. Bus drivers are free to use the -lists as they please, but conversion to the bus-specific type may be -necessary. - -The LDM core provides helper functions for iterating over each list:: - - int bus_for_each_dev(struct bus_type * bus, struct device * start, - void * data, - int (*fn)(struct device *, void *)); - - int bus_for_each_drv(struct bus_type * bus, struct device_driver * start, - void * data, int (*fn)(struct device_driver *, void *)); - -These helpers iterate over the respective list, and call the callback -for each device or driver in the list. All list accesses are -synchronized by taking the bus's lock (read currently). The reference -count on each object in the list is incremented before the callback is -called; it is decremented after the next object has been obtained. The -lock is not held when calling the callback. - - -sysfs -~~~~~~~~ -There is a top-level directory named 'bus'. - -Each bus gets a directory in the bus directory, along with two default -directories:: - - /sys/bus/pci/ - |-- devices - `-- drivers - -Drivers registered with the bus get a directory in the bus's drivers -directory:: - - /sys/bus/pci/ - |-- devices - `-- drivers - |-- Intel ICH - |-- Intel ICH Joystick - |-- agpgart - `-- e100 - -Each device that is discovered on a bus of that type gets a symlink in -the bus's devices directory to the device's directory in the physical -hierarchy:: - - /sys/bus/pci/ - |-- devices - | |-- 00:00.0 -> ../../../root/pci0/00:00.0 - | |-- 00:01.0 -> ../../../root/pci0/00:01.0 - | `-- 00:02.0 -> ../../../root/pci0/00:02.0 - `-- drivers - - -Exporting Attributes -~~~~~~~~~~~~~~~~~~~~ - -:: - - struct bus_attribute { - struct attribute attr; - ssize_t (*show)(struct bus_type *, char * buf); - ssize_t (*store)(struct bus_type *, const char * buf, size_t count); - }; - -Bus drivers can export attributes using the BUS_ATTR_RW macro that works -similarly to the DEVICE_ATTR_RW macro for devices. For example, a -definition like this:: - - static BUS_ATTR_RW(debug); - -is equivalent to declaring:: - - static bus_attribute bus_attr_debug; - -This can then be used to add and remove the attribute from the bus's -sysfs directory using:: - - int bus_create_file(struct bus_type *, struct bus_attribute *); - void bus_remove_file(struct bus_type *, struct bus_attribute *); diff --git a/Documentation/driver-model/class.rst b/Documentation/driver-model/class.rst deleted file mode 100644 index fff55b80e86a..000000000000 --- a/Documentation/driver-model/class.rst +++ /dev/null @@ -1,149 +0,0 @@ -============== -Device Classes -============== - -Introduction -~~~~~~~~~~~~ -A device class describes a type of device, like an audio or network -device. The following device classes have been identified: - - - - -Each device class defines a set of semantics and a programming interface -that devices of that class adhere to. Device drivers are the -implementation of that programming interface for a particular device on -a particular bus. - -Device classes are agnostic with respect to what bus a device resides -on. - - -Programming Interface -~~~~~~~~~~~~~~~~~~~~~ -The device class structure looks like:: - - - typedef int (*devclass_add)(struct device *); - typedef void (*devclass_remove)(struct device *); - -See the kerneldoc for the struct class. - -A typical device class definition would look like:: - - struct device_class input_devclass = { - .name = "input", - .add_device = input_add_device, - .remove_device = input_remove_device, - }; - -Each device class structure should be exported in a header file so it -can be used by drivers, extensions and interfaces. - -Device classes are registered and unregistered with the core using:: - - int devclass_register(struct device_class * cls); - void devclass_unregister(struct device_class * cls); - - -Devices -~~~~~~~ -As devices are bound to drivers, they are added to the device class -that the driver belongs to. Before the driver model core, this would -typically happen during the driver's probe() callback, once the device -has been initialized. It now happens after the probe() callback -finishes from the core. - -The device is enumerated in the class. Each time a device is added to -the class, the class's devnum field is incremented and assigned to the -device. The field is never decremented, so if the device is removed -from the class and re-added, it will receive a different enumerated -value. - -The class is allowed to create a class-specific structure for the -device and store it in the device's class_data pointer. - -There is no list of devices in the device class. Each driver has a -list of devices that it supports. The device class has a list of -drivers of that particular class. To access all of the devices in the -class, iterate over the device lists of each driver in the class. - - -Device Drivers -~~~~~~~~~~~~~~ -Device drivers are added to device classes when they are registered -with the core. A driver specifies the class it belongs to by setting -the struct device_driver::devclass field. - - -sysfs directory structure -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -There is a top-level sysfs directory named 'class'. - -Each class gets a directory in the class directory, along with two -default subdirectories:: - - class/ - `-- input - |-- devices - `-- drivers - - -Drivers registered with the class get a symlink in the drivers/ directory -that points to the driver's directory (under its bus directory):: - - class/ - `-- input - |-- devices - `-- drivers - `-- usb:usb_mouse -> ../../../bus/drivers/usb_mouse/ - - -Each device gets a symlink in the devices/ directory that points to the -device's directory in the physical hierarchy:: - - class/ - `-- input - |-- devices - | `-- 1 -> ../../../root/pci0/00:1f.0/usb_bus/00:1f.2-1:0/ - `-- drivers - - -Exporting Attributes -~~~~~~~~~~~~~~~~~~~~ - -:: - - struct devclass_attribute { - struct attribute attr; - ssize_t (*show)(struct device_class *, char * buf, size_t count, loff_t off); - ssize_t (*store)(struct device_class *, const char * buf, size_t count, loff_t off); - }; - -Class drivers can export attributes using the DEVCLASS_ATTR macro that works -similarly to the DEVICE_ATTR macro for devices. For example, a definition -like this:: - - static DEVCLASS_ATTR(debug,0644,show_debug,store_debug); - -is equivalent to declaring:: - - static devclass_attribute devclass_attr_debug; - -The bus driver can add and remove the attribute from the class's -sysfs directory using:: - - int devclass_create_file(struct device_class *, struct devclass_attribute *); - void devclass_remove_file(struct device_class *, struct devclass_attribute *); - -In the example above, the file will be named 'debug' in placed in the -class's directory in sysfs. - - -Interfaces -~~~~~~~~~~ -There may exist multiple mechanisms for accessing the same device of a -particular class type. Device interfaces describe these mechanisms. - -When a device is added to a device class, the core attempts to add it -to every interface that is registered with the device class. diff --git a/Documentation/driver-model/design-patterns.rst b/Documentation/driver-model/design-patterns.rst deleted file mode 100644 index 41eb8f41f7dd..000000000000 --- a/Documentation/driver-model/design-patterns.rst +++ /dev/null @@ -1,116 +0,0 @@ -============================= -Device Driver Design Patterns -============================= - -This document describes a few common design patterns found in device drivers. -It is likely that subsystem maintainers will ask driver developers to -conform to these design patterns. - -1. State Container -2. container_of() - - -1. State Container -~~~~~~~~~~~~~~~~~~ - -While the kernel contains a few device drivers that assume that they will -only be probed() once on a certain system (singletons), it is custom to assume -that the device the driver binds to will appear in several instances. This -means that the probe() function and all callbacks need to be reentrant. - -The most common way to achieve this is to use the state container design -pattern. It usually has this form:: - - struct foo { - spinlock_t lock; /* Example member */ - (...) - }; - - static int foo_probe(...) - { - struct foo *foo; - - foo = devm_kzalloc(dev, sizeof(*foo), GFP_KERNEL); - if (!foo) - return -ENOMEM; - spin_lock_init(&foo->lock); - (...) - } - -This will create an instance of struct foo in memory every time probe() is -called. This is our state container for this instance of the device driver. -Of course it is then necessary to always pass this instance of the -state around to all functions that need access to the state and its members. - -For example, if the driver is registering an interrupt handler, you would -pass around a pointer to struct foo like this:: - - static irqreturn_t foo_handler(int irq, void *arg) - { - struct foo *foo = arg; - (...) - } - - static int foo_probe(...) - { - struct foo *foo; - - (...) - ret = request_irq(irq, foo_handler, 0, "foo", foo); - } - -This way you always get a pointer back to the correct instance of foo in -your interrupt handler. - - -2. container_of() -~~~~~~~~~~~~~~~~~ - -Continuing on the above example we add an offloaded work:: - - struct foo { - spinlock_t lock; - struct workqueue_struct *wq; - struct work_struct offload; - (...) - }; - - static void foo_work(struct work_struct *work) - { - struct foo *foo = container_of(work, struct foo, offload); - - (...) - } - - static irqreturn_t foo_handler(int irq, void *arg) - { - struct foo *foo = arg; - - queue_work(foo->wq, &foo->offload); - (...) - } - - static int foo_probe(...) - { - struct foo *foo; - - foo->wq = create_singlethread_workqueue("foo-wq"); - INIT_WORK(&foo->offload, foo_work); - (...) - } - -The design pattern is the same for an hrtimer or something similar that will -return a single argument which is a pointer to a struct member in the -callback. - -container_of() is a macro defined in - -What container_of() does is to obtain a pointer to the containing struct from -a pointer to a member by a simple subtraction using the offsetof() macro from -standard C, which allows something similar to object oriented behaviours. -Notice that the contained member must not be a pointer, but an actual member -for this to work. - -We can see here that we avoid having global pointers to our struct foo * -instance this way, while still keeping the number of parameters passed to the -work function to a single pointer. diff --git a/Documentation/driver-model/device.rst b/Documentation/driver-model/device.rst deleted file mode 100644 index 2b868d49d349..000000000000 --- a/Documentation/driver-model/device.rst +++ /dev/null @@ -1,109 +0,0 @@ -========================== -The Basic Device Structure -========================== - -See the kerneldoc for the struct device. - - -Programming Interface -~~~~~~~~~~~~~~~~~~~~~ -The bus driver that discovers the device uses this to register the -device with the core:: - - int device_register(struct device * dev); - -The bus should initialize the following fields: - - - parent - - name - - bus_id - - bus - -A device is removed from the core when its reference count goes to -0. The reference count can be adjusted using:: - - struct device * get_device(struct device * dev); - void put_device(struct device * dev); - -get_device() will return a pointer to the struct device passed to it -if the reference is not already 0 (if it's in the process of being -removed already). - -A driver can access the lock in the device structure using:: - - void lock_device(struct device * dev); - void unlock_device(struct device * dev); - - -Attributes -~~~~~~~~~~ - -:: - - struct device_attribute { - struct attribute attr; - ssize_t (*show)(struct device *dev, struct device_attribute *attr, - char *buf); - ssize_t (*store)(struct device *dev, struct device_attribute *attr, - const char *buf, size_t count); - }; - -Attributes of devices can be exported by a device driver through sysfs. - -Please see Documentation/filesystems/sysfs.txt for more information -on how sysfs works. - -As explained in Documentation/kobject.txt, device attributes must be -created before the KOBJ_ADD uevent is generated. The only way to realize -that is by defining an attribute group. - -Attributes are declared using a macro called DEVICE_ATTR:: - - #define DEVICE_ATTR(name,mode,show,store) - -Example::: - - static DEVICE_ATTR(type, 0444, show_type, NULL); - static DEVICE_ATTR(power, 0644, show_power, store_power); - -This declares two structures of type struct device_attribute with respective -names 'dev_attr_type' and 'dev_attr_power'. These two attributes can be -organized as follows into a group:: - - static struct attribute *dev_attrs[] = { - &dev_attr_type.attr, - &dev_attr_power.attr, - NULL, - }; - - static struct attribute_group dev_attr_group = { - .attrs = dev_attrs, - }; - - static const struct attribute_group *dev_attr_groups[] = { - &dev_attr_group, - NULL, - }; - -This array of groups can then be associated with a device by setting the -group pointer in struct device before device_register() is invoked:: - - dev->groups = dev_attr_groups; - device_register(dev); - -The device_register() function will use the 'groups' pointer to create the -device attributes and the device_unregister() function will use this pointer -to remove the device attributes. - -Word of warning: While the kernel allows device_create_file() and -device_remove_file() to be called on a device at any time, userspace has -strict expectations on when attributes get created. When a new device is -registered in the kernel, a uevent is generated to notify userspace (like -udev) that a new device is available. If attributes are added after the -device is registered, then userspace won't get notified and userspace will -not know about the new attributes. - -This is important for device driver that need to publish additional -attributes for a device at driver probe time. If the device driver simply -calls device_create_file() on the device structure passed to it, then -userspace will never be notified of the new attributes. diff --git a/Documentation/driver-model/devres.rst b/Documentation/driver-model/devres.rst deleted file mode 100644 index 4ac99122b5f1..000000000000 --- a/Documentation/driver-model/devres.rst +++ /dev/null @@ -1,414 +0,0 @@ -================================ -Devres - Managed Device Resource -================================ - -Tejun Heo - -First draft 10 January 2007 - -.. contents - - 1. Intro : Huh? Devres? - 2. Devres : Devres in a nutshell - 3. Devres Group : Group devres'es and release them together - 4. Details : Life time rules, calling context, ... - 5. Overhead : How much do we have to pay for this? - 6. List of managed interfaces: Currently implemented managed interfaces - - -1. Intro --------- - -devres came up while trying to convert libata to use iomap. Each -iomapped address should be kept and unmapped on driver detach. For -example, a plain SFF ATA controller (that is, good old PCI IDE) in -native mode makes use of 5 PCI BARs and all of them should be -maintained. - -As with many other device drivers, libata low level drivers have -sufficient bugs in ->remove and ->probe failure path. Well, yes, -that's probably because libata low level driver developers are lazy -bunch, but aren't all low level driver developers? After spending a -day fiddling with braindamaged hardware with no document or -braindamaged document, if it's finally working, well, it's working. - -For one reason or another, low level drivers don't receive as much -attention or testing as core code, and bugs on driver detach or -initialization failure don't happen often enough to be noticeable. -Init failure path is worse because it's much less travelled while -needs to handle multiple entry points. - -So, many low level drivers end up leaking resources on driver detach -and having half broken failure path implementation in ->probe() which -would leak resources or even cause oops when failure occurs. iomap -adds more to this mix. So do msi and msix. - - -2. Devres ---------- - -devres is basically linked list of arbitrarily sized memory areas -associated with a struct device. Each devres entry is associated with -a release function. A devres can be released in several ways. No -matter what, all devres entries are released on driver detach. On -release, the associated release function is invoked and then the -devres entry is freed. - -Managed interface is created for resources commonly used by device -drivers using devres. For example, coherent DMA memory is acquired -using dma_alloc_coherent(). The managed version is called -dmam_alloc_coherent(). It is identical to dma_alloc_coherent() except -for the DMA memory allocated using it is managed and will be -automatically released on driver detach. Implementation looks like -the following:: - - struct dma_devres { - size_t size; - void *vaddr; - dma_addr_t dma_handle; - }; - - static void dmam_coherent_release(struct device *dev, void *res) - { - struct dma_devres *this = res; - - dma_free_coherent(dev, this->size, this->vaddr, this->dma_handle); - } - - dmam_alloc_coherent(dev, size, dma_handle, gfp) - { - struct dma_devres *dr; - void *vaddr; - - dr = devres_alloc(dmam_coherent_release, sizeof(*dr), gfp); - ... - - /* alloc DMA memory as usual */ - vaddr = dma_alloc_coherent(...); - ... - - /* record size, vaddr, dma_handle in dr */ - dr->vaddr = vaddr; - ... - - devres_add(dev, dr); - - return vaddr; - } - -If a driver uses dmam_alloc_coherent(), the area is guaranteed to be -freed whether initialization fails half-way or the device gets -detached. If most resources are acquired using managed interface, a -driver can have much simpler init and exit code. Init path basically -looks like the following:: - - my_init_one() - { - struct mydev *d; - - d = devm_kzalloc(dev, sizeof(*d), GFP_KERNEL); - if (!d) - return -ENOMEM; - - d->ring = dmam_alloc_coherent(...); - if (!d->ring) - return -ENOMEM; - - if (check something) - return -EINVAL; - ... - - return register_to_upper_layer(d); - } - -And exit path:: - - my_remove_one() - { - unregister_from_upper_layer(d); - shutdown_my_hardware(); - } - -As shown above, low level drivers can be simplified a lot by using -devres. Complexity is shifted from less maintained low level drivers -to better maintained higher layer. Also, as init failure path is -shared with exit path, both can get more testing. - -Note though that when converting current calls or assignments to -managed devm_* versions it is up to you to check if internal operations -like allocating memory, have failed. Managed resources pertains to the -freeing of these resources *only* - all other checks needed are still -on you. In some cases this may mean introducing checks that were not -necessary before moving to the managed devm_* calls. - - -3. Devres group ---------------- - -Devres entries can be grouped using devres group. When a group is -released, all contained normal devres entries and properly nested -groups are released. One usage is to rollback series of acquired -resources on failure. For example:: - - if (!devres_open_group(dev, NULL, GFP_KERNEL)) - return -ENOMEM; - - acquire A; - if (failed) - goto err; - - acquire B; - if (failed) - goto err; - ... - - devres_remove_group(dev, NULL); - return 0; - - err: - devres_release_group(dev, NULL); - return err_code; - -As resource acquisition failure usually means probe failure, constructs -like above are usually useful in midlayer driver (e.g. libata core -layer) where interface function shouldn't have side effect on failure. -For LLDs, just returning error code suffices in most cases. - -Each group is identified by `void *id`. It can either be explicitly -specified by @id argument to devres_open_group() or automatically -created by passing NULL as @id as in the above example. In both -cases, devres_open_group() returns the group's id. The returned id -can be passed to other devres functions to select the target group. -If NULL is given to those functions, the latest open group is -selected. - -For example, you can do something like the following:: - - int my_midlayer_create_something() - { - if (!devres_open_group(dev, my_midlayer_create_something, GFP_KERNEL)) - return -ENOMEM; - - ... - - devres_close_group(dev, my_midlayer_create_something); - return 0; - } - - void my_midlayer_destroy_something() - { - devres_release_group(dev, my_midlayer_create_something); - } - - -4. Details ----------- - -Lifetime of a devres entry begins on devres allocation and finishes -when it is released or destroyed (removed and freed) - no reference -counting. - -devres core guarantees atomicity to all basic devres operations and -has support for single-instance devres types (atomic -lookup-and-add-if-not-found). Other than that, synchronizing -concurrent accesses to allocated devres data is caller's -responsibility. This is usually non-issue because bus ops and -resource allocations already do the job. - -For an example of single-instance devres type, read pcim_iomap_table() -in lib/devres.c. - -All devres interface functions can be called without context if the -right gfp mask is given. - - -5. Overhead ------------ - -Each devres bookkeeping info is allocated together with requested data -area. With debug option turned off, bookkeeping info occupies 16 -bytes on 32bit machines and 24 bytes on 64bit (three pointers rounded -up to ull alignment). If singly linked list is used, it can be -reduced to two pointers (8 bytes on 32bit, 16 bytes on 64bit). - -Each devres group occupies 8 pointers. It can be reduced to 6 if -singly linked list is used. - -Memory space overhead on ahci controller with two ports is between 300 -and 400 bytes on 32bit machine after naive conversion (we can -certainly invest a bit more effort into libata core layer). - - -6. List of managed interfaces ------------------------------ - -CLOCK - devm_clk_get() - devm_clk_get_optional() - devm_clk_put() - devm_clk_hw_register() - devm_of_clk_add_hw_provider() - devm_clk_hw_register_clkdev() - -DMA - dmaenginem_async_device_register() - dmam_alloc_coherent() - dmam_alloc_attrs() - dmam_free_coherent() - dmam_pool_create() - dmam_pool_destroy() - -DRM - devm_drm_dev_init() - -GPIO - devm_gpiod_get() - devm_gpiod_get_index() - devm_gpiod_get_index_optional() - devm_gpiod_get_optional() - devm_gpiod_put() - devm_gpiod_unhinge() - devm_gpiochip_add_data() - devm_gpio_request() - devm_gpio_request_one() - devm_gpio_free() - -I2C - devm_i2c_new_dummy_device() - -IIO - devm_iio_device_alloc() - devm_iio_device_free() - devm_iio_device_register() - devm_iio_device_unregister() - devm_iio_kfifo_allocate() - devm_iio_kfifo_free() - devm_iio_triggered_buffer_setup() - devm_iio_triggered_buffer_cleanup() - devm_iio_trigger_alloc() - devm_iio_trigger_free() - devm_iio_trigger_register() - devm_iio_trigger_unregister() - devm_iio_channel_get() - devm_iio_channel_release() - devm_iio_channel_get_all() - devm_iio_channel_release_all() - -INPUT - devm_input_allocate_device() - -IO region - devm_release_mem_region() - devm_release_region() - devm_release_resource() - devm_request_mem_region() - devm_request_region() - devm_request_resource() - -IOMAP - devm_ioport_map() - devm_ioport_unmap() - devm_ioremap() - devm_ioremap_nocache() - devm_ioremap_wc() - devm_ioremap_resource() : checks resource, requests memory region, ioremaps - devm_iounmap() - pcim_iomap() - pcim_iomap_regions() : do request_region() and iomap() on multiple BARs - pcim_iomap_table() : array of mapped addresses indexed by BAR - pcim_iounmap() - -IRQ - devm_free_irq() - devm_request_any_context_irq() - devm_request_irq() - devm_request_threaded_irq() - devm_irq_alloc_descs() - devm_irq_alloc_desc() - devm_irq_alloc_desc_at() - devm_irq_alloc_desc_from() - devm_irq_alloc_descs_from() - devm_irq_alloc_generic_chip() - devm_irq_setup_generic_chip() - devm_irq_sim_init() - -LED - devm_led_classdev_register() - devm_led_classdev_unregister() - -MDIO - devm_mdiobus_alloc() - devm_mdiobus_alloc_size() - devm_mdiobus_free() - -MEM - devm_free_pages() - devm_get_free_pages() - devm_kasprintf() - devm_kcalloc() - devm_kfree() - devm_kmalloc() - devm_kmalloc_array() - devm_kmemdup() - devm_kstrdup() - devm_kvasprintf() - devm_kzalloc() - -MFD - devm_mfd_add_devices() - -MUX - devm_mux_chip_alloc() - devm_mux_chip_register() - devm_mux_control_get() - -PER-CPU MEM - devm_alloc_percpu() - devm_free_percpu() - -PCI - devm_pci_alloc_host_bridge() : managed PCI host bridge allocation - devm_pci_remap_cfgspace() : ioremap PCI configuration space - devm_pci_remap_cfg_resource() : ioremap PCI configuration space resource - pcim_enable_device() : after success, all PCI ops become managed - pcim_pin_device() : keep PCI device enabled after release - -PHY - devm_usb_get_phy() - devm_usb_put_phy() - -PINCTRL - devm_pinctrl_get() - devm_pinctrl_put() - devm_pinctrl_register() - devm_pinctrl_unregister() - -POWER - devm_reboot_mode_register() - devm_reboot_mode_unregister() - -PWM - devm_pwm_get() - devm_pwm_put() - -REGULATOR - devm_regulator_bulk_get() - devm_regulator_get() - devm_regulator_put() - devm_regulator_register() - -RESET - devm_reset_control_get() - devm_reset_controller_register() - -SERDEV - devm_serdev_device_open() - -SLAVE DMA ENGINE - devm_acpi_dma_controller_register() - -SPI - devm_spi_register_master() - -WATCHDOG - devm_watchdog_register_device() diff --git a/Documentation/driver-model/driver.rst b/Documentation/driver-model/driver.rst deleted file mode 100644 index 11d281506a04..000000000000 --- a/Documentation/driver-model/driver.rst +++ /dev/null @@ -1,223 +0,0 @@ -============== -Device Drivers -============== - -See the kerneldoc for the struct device_driver. - - -Allocation -~~~~~~~~~~ - -Device drivers are statically allocated structures. Though there may -be multiple devices in a system that a driver supports, struct -device_driver represents the driver as a whole (not a particular -device instance). - -Initialization -~~~~~~~~~~~~~~ - -The driver must initialize at least the name and bus fields. It should -also initialize the devclass field (when it arrives), so it may obtain -the proper linkage internally. It should also initialize as many of -the callbacks as possible, though each is optional. - -Declaration -~~~~~~~~~~~ - -As stated above, struct device_driver objects are statically -allocated. Below is an example declaration of the eepro100 -driver. This declaration is hypothetical only; it relies on the driver -being converted completely to the new model:: - - static struct device_driver eepro100_driver = { - .name = "eepro100", - .bus = &pci_bus_type, - - .probe = eepro100_probe, - .remove = eepro100_remove, - .suspend = eepro100_suspend, - .resume = eepro100_resume, - }; - -Most drivers will not be able to be converted completely to the new -model because the bus they belong to has a bus-specific structure with -bus-specific fields that cannot be generalized. - -The most common example of this are device ID structures. A driver -typically defines an array of device IDs that it supports. The format -of these structures and the semantics for comparing device IDs are -completely bus-specific. Defining them as bus-specific entities would -sacrifice type-safety, so we keep bus-specific structures around. - -Bus-specific drivers should include a generic struct device_driver in -the definition of the bus-specific driver. Like this:: - - struct pci_driver { - const struct pci_device_id *id_table; - struct device_driver driver; - }; - -A definition that included bus-specific fields would look like -(using the eepro100 driver again):: - - static struct pci_driver eepro100_driver = { - .id_table = eepro100_pci_tbl, - .driver = { - .name = "eepro100", - .bus = &pci_bus_type, - .probe = eepro100_probe, - .remove = eepro100_remove, - .suspend = eepro100_suspend, - .resume = eepro100_resume, - }, - }; - -Some may find the syntax of embedded struct initialization awkward or -even a bit ugly. So far, it's the best way we've found to do what we want... - -Registration -~~~~~~~~~~~~ - -:: - - int driver_register(struct device_driver *drv); - -The driver registers the structure on startup. For drivers that have -no bus-specific fields (i.e. don't have a bus-specific driver -structure), they would use driver_register and pass a pointer to their -struct device_driver object. - -Most drivers, however, will have a bus-specific structure and will -need to register with the bus using something like pci_driver_register. - -It is important that drivers register their driver structure as early as -possible. Registration with the core initializes several fields in the -struct device_driver object, including the reference count and the -lock. These fields are assumed to be valid at all times and may be -used by the device model core or the bus driver. - - -Transition Bus Drivers -~~~~~~~~~~~~~~~~~~~~~~ - -By defining wrapper functions, the transition to the new model can be -made easier. Drivers can ignore the generic structure altogether and -let the bus wrapper fill in the fields. For the callbacks, the bus can -define generic callbacks that forward the call to the bus-specific -callbacks of the drivers. - -This solution is intended to be only temporary. In order to get class -information in the driver, the drivers must be modified anyway. Since -converting drivers to the new model should reduce some infrastructural -complexity and code size, it is recommended that they are converted as -class information is added. - -Access -~~~~~~ - -Once the object has been registered, it may access the common fields of -the object, like the lock and the list of devices:: - - int driver_for_each_dev(struct device_driver *drv, void *data, - int (*callback)(struct device *dev, void *data)); - -The devices field is a list of all the devices that have been bound to -the driver. The LDM core provides a helper function to operate on all -the devices a driver controls. This helper locks the driver on each -node access, and does proper reference counting on each device as it -accesses it. - - -sysfs -~~~~~ - -When a driver is registered, a sysfs directory is created in its -bus's directory. In this directory, the driver can export an interface -to userspace to control operation of the driver on a global basis; -e.g. toggling debugging output in the driver. - -A future feature of this directory will be a 'devices' directory. This -directory will contain symlinks to the directories of devices it -supports. - - - -Callbacks -~~~~~~~~~ - -:: - - int (*probe) (struct device *dev); - -The probe() entry is called in task context, with the bus's rwsem locked -and the driver partially bound to the device. Drivers commonly use -container_of() to convert "dev" to a bus-specific type, both in probe() -and other routines. That type often provides device resource data, such -as pci_dev.resource[] or platform_device.resources, which is used in -addition to dev->platform_data to initialize the driver. - -This callback holds the driver-specific logic to bind the driver to a -given device. That includes verifying that the device is present, that -it's a version the driver can handle, that driver data structures can -be allocated and initialized, and that any hardware can be initialized. -Drivers often store a pointer to their state with dev_set_drvdata(). -When the driver has successfully bound itself to that device, then probe() -returns zero and the driver model code will finish its part of binding -the driver to that device. - -A driver's probe() may return a negative errno value to indicate that -the driver did not bind to this device, in which case it should have -released all resources it allocated:: - - int (*remove) (struct device *dev); - -remove is called to unbind a driver from a device. This may be -called if a device is physically removed from the system, if the -driver module is being unloaded, during a reboot sequence, or -in other cases. - -It is up to the driver to determine if the device is present or -not. It should free any resources allocated specifically for the -device; i.e. anything in the device's driver_data field. - -If the device is still present, it should quiesce the device and place -it into a supported low-power state:: - - int (*suspend) (struct device *dev, pm_message_t state); - -suspend is called to put the device in a low power state:: - - int (*resume) (struct device *dev); - -Resume is used to bring a device back from a low power state. - - -Attributes -~~~~~~~~~~ - -:: - - struct driver_attribute { - struct attribute attr; - ssize_t (*show)(struct device_driver *driver, char *buf); - ssize_t (*store)(struct device_driver *, const char *buf, size_t count); - }; - -Device drivers can export attributes via their sysfs directories. -Drivers can declare attributes using a DRIVER_ATTR_RW and DRIVER_ATTR_RO -macro that works identically to the DEVICE_ATTR_RW and DEVICE_ATTR_RO -macros. - -Example:: - - DRIVER_ATTR_RW(debug); - -This is equivalent to declaring:: - - struct driver_attribute driver_attr_debug; - -This can then be used to add and remove the attribute from the -driver's directory using:: - - int driver_create_file(struct device_driver *, const struct driver_attribute *); - void driver_remove_file(struct device_driver *, const struct driver_attribute *); diff --git a/Documentation/driver-model/index.rst b/Documentation/driver-model/index.rst deleted file mode 100644 index 9f85d579ce56..000000000000 --- a/Documentation/driver-model/index.rst +++ /dev/null @@ -1,26 +0,0 @@ -:orphan: - -============ -Driver Model -============ - -.. toctree:: - :maxdepth: 1 - - binding - bus - class - design-patterns - device - devres - driver - overview - platform - porting - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex` diff --git a/Documentation/driver-model/overview.rst b/Documentation/driver-model/overview.rst deleted file mode 100644 index d4d1e9b40e0c..000000000000 --- a/Documentation/driver-model/overview.rst +++ /dev/null @@ -1,124 +0,0 @@ -============================= -The Linux Kernel Device Model -============================= - -Patrick Mochel - -Drafted 26 August 2002 -Updated 31 January 2006 - - -Overview -~~~~~~~~ - -The Linux Kernel Driver Model is a unification of all the disparate driver -models that were previously used in the kernel. It is intended to augment the -bus-specific drivers for bridges and devices by consolidating a set of data -and operations into globally accessible data structures. - -Traditional driver models implemented some sort of tree-like structure -(sometimes just a list) for the devices they control. There wasn't any -uniformity across the different bus types. - -The current driver model provides a common, uniform data model for describing -a bus and the devices that can appear under the bus. The unified bus -model includes a set of common attributes which all busses carry, and a set -of common callbacks, such as device discovery during bus probing, bus -shutdown, bus power management, etc. - -The common device and bridge interface reflects the goals of the modern -computer: namely the ability to do seamless device "plug and play", power -management, and hot plug. In particular, the model dictated by Intel and -Microsoft (namely ACPI) ensures that almost every device on almost any bus -on an x86-compatible system can work within this paradigm. Of course, -not every bus is able to support all such operations, although most -buses support most of those operations. - - -Downstream Access -~~~~~~~~~~~~~~~~~ - -Common data fields have been moved out of individual bus layers into a common -data structure. These fields must still be accessed by the bus layers, -and sometimes by the device-specific drivers. - -Other bus layers are encouraged to do what has been done for the PCI layer. -struct pci_dev now looks like this:: - - struct pci_dev { - ... - - struct device dev; /* Generic device interface */ - ... - }; - -Note first that the struct device dev within the struct pci_dev is -statically allocated. This means only one allocation on device discovery. - -Note also that that struct device dev is not necessarily defined at the -front of the pci_dev structure. This is to make people think about what -they're doing when switching between the bus driver and the global driver, -and to discourage meaningless and incorrect casts between the two. - -The PCI bus layer freely accesses the fields of struct device. It knows about -the structure of struct pci_dev, and it should know the structure of struct -device. Individual PCI device drivers that have been converted to the current -driver model generally do not and should not touch the fields of struct device, -unless there is a compelling reason to do so. - -The above abstraction prevents unnecessary pain during transitional phases. -If it were not done this way, then when a field was renamed or removed, every -downstream driver would break. On the other hand, if only the bus layer -(and not the device layer) accesses the struct device, it is only the bus -layer that needs to change. - - -User Interface -~~~~~~~~~~~~~~ - -By virtue of having a complete hierarchical view of all the devices in the -system, exporting a complete hierarchical view to userspace becomes relatively -easy. This has been accomplished by implementing a special purpose virtual -file system named sysfs. - -Almost all mainstream Linux distros mount this filesystem automatically; you -can see some variation of the following in the output of the "mount" command:: - - $ mount - ... - none on /sys type sysfs (rw,noexec,nosuid,nodev) - ... - $ - -The auto-mounting of sysfs is typically accomplished by an entry similar to -the following in the /etc/fstab file:: - - none /sys sysfs defaults 0 0 - -or something similar in the /lib/init/fstab file on Debian-based systems:: - - none /sys sysfs nodev,noexec,nosuid 0 0 - -If sysfs is not automatically mounted, you can always do it manually with:: - - # mount -t sysfs sysfs /sys - -Whenever a device is inserted into the tree, a directory is created for it. -This directory may be populated at each layer of discovery - the global layer, -the bus layer, or the device layer. - -The global layer currently creates two files - 'name' and 'power'. The -former only reports the name of the device. The latter reports the -current power state of the device. It will also be used to set the current -power state. - -The bus layer may also create files for the devices it finds while probing the -bus. For example, the PCI layer currently creates 'irq' and 'resource' files -for each PCI device. - -A device-specific driver may also export files in its directory to expose -device-specific data or tunable interfaces. - -More information about the sysfs directory layout can be found in -the other documents in this directory and in the file -Documentation/filesystems/sysfs.txt. diff --git a/Documentation/driver-model/platform.rst b/Documentation/driver-model/platform.rst deleted file mode 100644 index 334dd4071ae4..000000000000 --- a/Documentation/driver-model/platform.rst +++ /dev/null @@ -1,246 +0,0 @@ -============================ -Platform Devices and Drivers -============================ - -See for the driver model interface to the -platform bus: platform_device, and platform_driver. This pseudo-bus -is used to connect devices on busses with minimal infrastructure, -like those used to integrate peripherals on many system-on-chip -processors, or some "legacy" PC interconnects; as opposed to large -formally specified ones like PCI or USB. - - -Platform devices -~~~~~~~~~~~~~~~~ -Platform devices are devices that typically appear as autonomous -entities in the system. This includes legacy port-based devices and -host bridges to peripheral buses, and most controllers integrated -into system-on-chip platforms. What they usually have in common -is direct addressing from a CPU bus. Rarely, a platform_device will -be connected through a segment of some other kind of bus; but its -registers will still be directly addressable. - -Platform devices are given a name, used in driver binding, and a -list of resources such as addresses and IRQs:: - - struct platform_device { - const char *name; - u32 id; - struct device dev; - u32 num_resources; - struct resource *resource; - }; - - -Platform drivers -~~~~~~~~~~~~~~~~ -Platform drivers follow the standard driver model convention, where -discovery/enumeration is handled outside the drivers, and drivers -provide probe() and remove() methods. They support power management -and shutdown notifications using the standard conventions:: - - struct platform_driver { - int (*probe)(struct platform_device *); - int (*remove)(struct platform_device *); - void (*shutdown)(struct platform_device *); - int (*suspend)(struct platform_device *, pm_message_t state); - int (*suspend_late)(struct platform_device *, pm_message_t state); - int (*resume_early)(struct platform_device *); - int (*resume)(struct platform_device *); - struct device_driver driver; - }; - -Note that probe() should in general verify that the specified device hardware -actually exists; sometimes platform setup code can't be sure. The probing -can use device resources, including clocks, and device platform_data. - -Platform drivers register themselves the normal way:: - - int platform_driver_register(struct platform_driver *drv); - -Or, in common situations where the device is known not to be hot-pluggable, -the probe() routine can live in an init section to reduce the driver's -runtime memory footprint:: - - int platform_driver_probe(struct platform_driver *drv, - int (*probe)(struct platform_device *)) - -Kernel modules can be composed of several platform drivers. The platform core -provides helpers to register and unregister an array of drivers:: - - int __platform_register_drivers(struct platform_driver * const *drivers, - unsigned int count, struct module *owner); - void platform_unregister_drivers(struct platform_driver * const *drivers, - unsigned int count); - -If one of the drivers fails to register, all drivers registered up to that -point will be unregistered in reverse order. Note that there is a convenience -macro that passes THIS_MODULE as owner parameter:: - - #define platform_register_drivers(drivers, count) - - -Device Enumeration -~~~~~~~~~~~~~~~~~~ -As a rule, platform specific (and often board-specific) setup code will -register platform devices:: - - int platform_device_register(struct platform_device *pdev); - - int platform_add_devices(struct platform_device **pdevs, int ndev); - -The general rule is to register only those devices that actually exist, -but in some cases extra devices might be registered. For example, a kernel -might be configured to work with an external network adapter that might not -be populated on all boards, or likewise to work with an integrated controller -that some boards might not hook up to any peripherals. - -In some cases, boot firmware will export tables describing the devices -that are populated on a given board. Without such tables, often the -only way for system setup code to set up the correct devices is to build -a kernel for a specific target board. Such board-specific kernels are -common with embedded and custom systems development. - -In many cases, the memory and IRQ resources associated with the platform -device are not enough to let the device's driver work. Board setup code -will often provide additional information using the device's platform_data -field to hold additional information. - -Embedded systems frequently need one or more clocks for platform devices, -which are normally kept off until they're actively needed (to save power). -System setup also associates those clocks with the device, so that that -calls to clk_get(&pdev->dev, clock_name) return them as needed. - - -Legacy Drivers: Device Probing -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Some drivers are not fully converted to the driver model, because they take -on a non-driver role: the driver registers its platform device, rather than -leaving that for system infrastructure. Such drivers can't be hotplugged -or coldplugged, since those mechanisms require device creation to be in a -different system component than the driver. - -The only "good" reason for this is to handle older system designs which, like -original IBM PCs, rely on error-prone "probe-the-hardware" models for hardware -configuration. Newer systems have largely abandoned that model, in favor of -bus-level support for dynamic configuration (PCI, USB), or device tables -provided by the boot firmware (e.g. PNPACPI on x86). There are too many -conflicting options about what might be where, and even educated guesses by -an operating system will be wrong often enough to make trouble. - -This style of driver is discouraged. If you're updating such a driver, -please try to move the device enumeration to a more appropriate location, -outside the driver. This will usually be cleanup, since such drivers -tend to already have "normal" modes, such as ones using device nodes that -were created by PNP or by platform device setup. - -None the less, there are some APIs to support such legacy drivers. Avoid -using these calls except with such hotplug-deficient drivers:: - - struct platform_device *platform_device_alloc( - const char *name, int id); - -You can use platform_device_alloc() to dynamically allocate a device, which -you will then initialize with resources and platform_device_register(). -A better solution is usually:: - - struct platform_device *platform_device_register_simple( - const char *name, int id, - struct resource *res, unsigned int nres); - -You can use platform_device_register_simple() as a one-step call to allocate -and register a device. - - -Device Naming and Driver Binding -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The platform_device.dev.bus_id is the canonical name for the devices. -It's built from two components: - - * platform_device.name ... which is also used to for driver matching. - - * platform_device.id ... the device instance number, or else "-1" - to indicate there's only one. - -These are concatenated, so name/id "serial"/0 indicates bus_id "serial.0", and -"serial/3" indicates bus_id "serial.3"; both would use the platform_driver -named "serial". While "my_rtc"/-1 would be bus_id "my_rtc" (no instance id) -and use the platform_driver called "my_rtc". - -Driver binding is performed automatically by the driver core, invoking -driver probe() after finding a match between device and driver. If the -probe() succeeds, the driver and device are bound as usual. There are -three different ways to find such a match: - - - Whenever a device is registered, the drivers for that bus are - checked for matches. Platform devices should be registered very - early during system boot. - - - When a driver is registered using platform_driver_register(), all - unbound devices on that bus are checked for matches. Drivers - usually register later during booting, or by module loading. - - - Registering a driver using platform_driver_probe() works just like - using platform_driver_register(), except that the driver won't - be probed later if another device registers. (Which is OK, since - this interface is only for use with non-hotpluggable devices.) - - -Early Platform Devices and Drivers -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The early platform interfaces provide platform data to platform device -drivers early on during the system boot. The code is built on top of the -early_param() command line parsing and can be executed very early on. - -Example: "earlyprintk" class early serial console in 6 steps - -1. Registering early platform device data -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The architecture code registers platform device data using the function -early_platform_add_devices(). In the case of early serial console this -should be hardware configuration for the serial port. Devices registered -at this point will later on be matched against early platform drivers. - -2. Parsing kernel command line -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The architecture code calls parse_early_param() to parse the kernel -command line. This will execute all matching early_param() callbacks. -User specified early platform devices will be registered at this point. -For the early serial console case the user can specify port on the -kernel command line as "earlyprintk=serial.0" where "earlyprintk" is -the class string, "serial" is the name of the platform driver and -0 is the platform device id. If the id is -1 then the dot and the -id can be omitted. - -3. Installing early platform drivers belonging to a certain class -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The architecture code may optionally force registration of all early -platform drivers belonging to a certain class using the function -early_platform_driver_register_all(). User specified devices from -step 2 have priority over these. This step is omitted by the serial -driver example since the early serial driver code should be disabled -unless the user has specified port on the kernel command line. - -4. Early platform driver registration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Compiled-in platform drivers making use of early_platform_init() are -automatically registered during step 2 or 3. The serial driver example -should use early_platform_init("earlyprintk", &platform_driver). - -5. Probing of early platform drivers belonging to a certain class -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The architecture code calls early_platform_driver_probe() to match -registered early platform devices associated with a certain class with -registered early platform drivers. Matched devices will get probed(). -This step can be executed at any point during the early boot. As soon -as possible may be good for the serial port case. - -6. Inside the early platform driver probe() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The driver code needs to take special care during early boot, especially -when it comes to memory allocation and interrupt registration. The code -in the probe() function can use is_early_platform_device() to check if -it is called at early platform device or at the regular platform device -time. The early serial driver performs register_console() at this point. - -For further information, see . diff --git a/Documentation/driver-model/porting.rst b/Documentation/driver-model/porting.rst deleted file mode 100644 index ae4bf843c1d6..000000000000 --- a/Documentation/driver-model/porting.rst +++ /dev/null @@ -1,448 +0,0 @@ -======================================= -Porting Drivers to the New Driver Model -======================================= - -Patrick Mochel - -7 January 2003 - - -Overview - -Please refer to `Documentation/driver-model/*.rst` for definitions of -various driver types and concepts. - -Most of the work of porting devices drivers to the new model happens -at the bus driver layer. This was intentional, to minimize the -negative effect on kernel drivers, and to allow a gradual transition -of bus drivers. - -In a nutshell, the driver model consists of a set of objects that can -be embedded in larger, bus-specific objects. Fields in these generic -objects can replace fields in the bus-specific objects. - -The generic objects must be registered with the driver model core. By -doing so, they will exported via the sysfs filesystem. sysfs can be -mounted by doing:: - - # mount -t sysfs sysfs /sys - - - -The Process - -Step 0: Read include/linux/device.h for object and function definitions. - -Step 1: Registering the bus driver. - - -- Define a struct bus_type for the bus driver:: - - struct bus_type pci_bus_type = { - .name = "pci", - }; - - -- Register the bus type. - - This should be done in the initialization function for the bus type, - which is usually the module_init(), or equivalent, function:: - - static int __init pci_driver_init(void) - { - return bus_register(&pci_bus_type); - } - - subsys_initcall(pci_driver_init); - - - The bus type may be unregistered (if the bus driver may be compiled - as a module) by doing:: - - bus_unregister(&pci_bus_type); - - -- Export the bus type for others to use. - - Other code may wish to reference the bus type, so declare it in a - shared header file and export the symbol. - -From include/linux/pci.h:: - - extern struct bus_type pci_bus_type; - - -From file the above code appears in:: - - EXPORT_SYMBOL(pci_bus_type); - - - -- This will cause the bus to show up in /sys/bus/pci/ with two - subdirectories: 'devices' and 'drivers':: - - # tree -d /sys/bus/pci/ - /sys/bus/pci/ - |-- devices - `-- drivers - - - -Step 2: Registering Devices. - -struct device represents a single device. It mainly contains metadata -describing the relationship the device has to other entities. - - -- Embed a struct device in the bus-specific device type:: - - - struct pci_dev { - ... - struct device dev; /* Generic device interface */ - ... - }; - - It is recommended that the generic device not be the first item in - the struct to discourage programmers from doing mindless casts - between the object types. Instead macros, or inline functions, - should be created to convert from the generic object type:: - - - #define to_pci_dev(n) container_of(n, struct pci_dev, dev) - - or - - static inline struct pci_dev * to_pci_dev(struct kobject * kobj) - { - return container_of(n, struct pci_dev, dev); - } - - This allows the compiler to verify type-safety of the operations - that are performed (which is Good). - - -- Initialize the device on registration. - - When devices are discovered or registered with the bus type, the - bus driver should initialize the generic device. The most important - things to initialize are the bus_id, parent, and bus fields. - - The bus_id is an ASCII string that contains the device's address on - the bus. The format of this string is bus-specific. This is - necessary for representing devices in sysfs. - - parent is the physical parent of the device. It is important that - the bus driver sets this field correctly. - - The driver model maintains an ordered list of devices that it uses - for power management. This list must be in order to guarantee that - devices are shutdown before their physical parents, and vice versa. - The order of this list is determined by the parent of registered - devices. - - Also, the location of the device's sysfs directory depends on a - device's parent. sysfs exports a directory structure that mirrors - the device hierarchy. Accurately setting the parent guarantees that - sysfs will accurately represent the hierarchy. - - The device's bus field is a pointer to the bus type the device - belongs to. This should be set to the bus_type that was declared - and initialized before. - - Optionally, the bus driver may set the device's name and release - fields. - - The name field is an ASCII string describing the device, like - - "ATI Technologies Inc Radeon QD" - - The release field is a callback that the driver model core calls - when the device has been removed, and all references to it have - been released. More on this in a moment. - - -- Register the device. - - Once the generic device has been initialized, it can be registered - with the driver model core by doing:: - - device_register(&dev->dev); - - It can later be unregistered by doing:: - - device_unregister(&dev->dev); - - This should happen on buses that support hotpluggable devices. - If a bus driver unregisters a device, it should not immediately free - it. It should instead wait for the driver model core to call the - device's release method, then free the bus-specific object. - (There may be other code that is currently referencing the device - structure, and it would be rude to free the device while that is - happening). - - - When the device is registered, a directory in sysfs is created. - The PCI tree in sysfs looks like:: - - /sys/devices/pci0/ - |-- 00:00.0 - |-- 00:01.0 - | `-- 01:00.0 - |-- 00:02.0 - | `-- 02:1f.0 - | `-- 03:00.0 - |-- 00:1e.0 - | `-- 04:04.0 - |-- 00:1f.0 - |-- 00:1f.1 - | |-- ide0 - | | |-- 0.0 - | | `-- 0.1 - | `-- ide1 - | `-- 1.0 - |-- 00:1f.2 - |-- 00:1f.3 - `-- 00:1f.5 - - Also, symlinks are created in the bus's 'devices' directory - that point to the device's directory in the physical hierarchy:: - - /sys/bus/pci/devices/ - |-- 00:00.0 -> ../../../devices/pci0/00:00.0 - |-- 00:01.0 -> ../../../devices/pci0/00:01.0 - |-- 00:02.0 -> ../../../devices/pci0/00:02.0 - |-- 00:1e.0 -> ../../../devices/pci0/00:1e.0 - |-- 00:1f.0 -> ../../../devices/pci0/00:1f.0 - |-- 00:1f.1 -> ../../../devices/pci0/00:1f.1 - |-- 00:1f.2 -> ../../../devices/pci0/00:1f.2 - |-- 00:1f.3 -> ../../../devices/pci0/00:1f.3 - |-- 00:1f.5 -> ../../../devices/pci0/00:1f.5 - |-- 01:00.0 -> ../../../devices/pci0/00:01.0/01:00.0 - |-- 02:1f.0 -> ../../../devices/pci0/00:02.0/02:1f.0 - |-- 03:00.0 -> ../../../devices/pci0/00:02.0/02:1f.0/03:00.0 - `-- 04:04.0 -> ../../../devices/pci0/00:1e.0/04:04.0 - - - -Step 3: Registering Drivers. - -struct device_driver is a simple driver structure that contains a set -of operations that the driver model core may call. - - -- Embed a struct device_driver in the bus-specific driver. - - Just like with devices, do something like:: - - struct pci_driver { - ... - struct device_driver driver; - }; - - -- Initialize the generic driver structure. - - When the driver registers with the bus (e.g. doing pci_register_driver()), - initialize the necessary fields of the driver: the name and bus - fields. - - -- Register the driver. - - After the generic driver has been initialized, call:: - - driver_register(&drv->driver); - - to register the driver with the core. - - When the driver is unregistered from the bus, unregister it from the - core by doing:: - - driver_unregister(&drv->driver); - - Note that this will block until all references to the driver have - gone away. Normally, there will not be any. - - -- Sysfs representation. - - Drivers are exported via sysfs in their bus's 'driver's directory. - For example:: - - /sys/bus/pci/drivers/ - |-- 3c59x - |-- Ensoniq AudioPCI - |-- agpgart-amdk7 - |-- e100 - `-- serial - - -Step 4: Define Generic Methods for Drivers. - -struct device_driver defines a set of operations that the driver model -core calls. Most of these operations are probably similar to -operations the bus already defines for drivers, but taking different -parameters. - -It would be difficult and tedious to force every driver on a bus to -simultaneously convert their drivers to generic format. Instead, the -bus driver should define single instances of the generic methods that -forward call to the bus-specific drivers. For instance:: - - - static int pci_device_remove(struct device * dev) - { - struct pci_dev * pci_dev = to_pci_dev(dev); - struct pci_driver * drv = pci_dev->driver; - - if (drv) { - if (drv->remove) - drv->remove(pci_dev); - pci_dev->driver = NULL; - } - return 0; - } - - -The generic driver should be initialized with these methods before it -is registered:: - - /* initialize common driver fields */ - drv->driver.name = drv->name; - drv->driver.bus = &pci_bus_type; - drv->driver.probe = pci_device_probe; - drv->driver.resume = pci_device_resume; - drv->driver.suspend = pci_device_suspend; - drv->driver.remove = pci_device_remove; - - /* register with core */ - driver_register(&drv->driver); - - -Ideally, the bus should only initialize the fields if they are not -already set. This allows the drivers to implement their own generic -methods. - - -Step 5: Support generic driver binding. - -The model assumes that a device or driver can be dynamically -registered with the bus at any time. When registration happens, -devices must be bound to a driver, or drivers must be bound to all -devices that it supports. - -A driver typically contains a list of device IDs that it supports. The -bus driver compares these IDs to the IDs of devices registered with it. -The format of the device IDs, and the semantics for comparing them are -bus-specific, so the generic model does attempt to generalize them. - -Instead, a bus may supply a method in struct bus_type that does the -comparison:: - - int (*match)(struct device * dev, struct device_driver * drv); - -match should return positive value if the driver supports the device, -and zero otherwise. It may also return error code (for example --EPROBE_DEFER) if determining that given driver supports the device is -not possible. - -When a device is registered, the bus's list of drivers is iterated -over. bus->match() is called for each one until a match is found. - -When a driver is registered, the bus's list of devices is iterated -over. bus->match() is called for each device that is not already -claimed by a driver. - -When a device is successfully bound to a driver, device->driver is -set, the device is added to a per-driver list of devices, and a -symlink is created in the driver's sysfs directory that points to the -device's physical directory:: - - /sys/bus/pci/drivers/ - |-- 3c59x - | `-- 00:0b.0 -> ../../../../devices/pci0/00:0b.0 - |-- Ensoniq AudioPCI - |-- agpgart-amdk7 - | `-- 00:00.0 -> ../../../../devices/pci0/00:00.0 - |-- e100 - | `-- 00:0c.0 -> ../../../../devices/pci0/00:0c.0 - `-- serial - - -This driver binding should replace the existing driver binding -mechanism the bus currently uses. - - -Step 6: Supply a hotplug callback. - -Whenever a device is registered with the driver model core, the -userspace program /sbin/hotplug is called to notify userspace. -Users can define actions to perform when a device is inserted or -removed. - -The driver model core passes several arguments to userspace via -environment variables, including - -- ACTION: set to 'add' or 'remove' -- DEVPATH: set to the device's physical path in sysfs. - -A bus driver may also supply additional parameters for userspace to -consume. To do this, a bus must implement the 'hotplug' method in -struct bus_type:: - - int (*hotplug) (struct device *dev, char **envp, - int num_envp, char *buffer, int buffer_size); - -This is called immediately before /sbin/hotplug is executed. - - -Step 7: Cleaning up the bus driver. - -The generic bus, device, and driver structures provide several fields -that can replace those defined privately to the bus driver. - -- Device list. - -struct bus_type contains a list of all devices registered with the bus -type. This includes all devices on all instances of that bus type. -An internal list that the bus uses may be removed, in favor of using -this one. - -The core provides an iterator to access these devices:: - - int bus_for_each_dev(struct bus_type * bus, struct device * start, - void * data, int (*fn)(struct device *, void *)); - - -- Driver list. - -struct bus_type also contains a list of all drivers registered with -it. An internal list of drivers that the bus driver maintains may -be removed in favor of using the generic one. - -The drivers may be iterated over, like devices:: - - int bus_for_each_drv(struct bus_type * bus, struct device_driver * start, - void * data, int (*fn)(struct device_driver *, void *)); - - -Please see drivers/base/bus.c for more information. - - -- rwsem - -struct bus_type contains an rwsem that protects all core accesses to -the device and driver lists. This can be used by the bus driver -internally, and should be used when accessing the device or driver -lists the bus maintains. - - -- Device and driver fields. - -Some of the fields in struct device and struct device_driver duplicate -fields in the bus-specific representations of these objects. Feel free -to remove the bus-specific ones and favor the generic ones. Note -though, that this will likely mean fixing up all the drivers that -reference the bus-specific fields (though those should all be 1-line -changes). diff --git a/Documentation/eisa.txt b/Documentation/eisa.txt index f388545a85a7..c07565ba57da 100644 --- a/Documentation/eisa.txt +++ b/Documentation/eisa.txt @@ -103,7 +103,7 @@ id_table an array of NULL terminated EISA id strings, (driver_data). driver a generic driver, such as described in - Documentation/driver-model/driver.rst. Only .name, + Documentation/driver-api/driver-model/driver.rst. Only .name, .probe and .remove members are mandatory. =============== ==================================================== @@ -152,7 +152,7 @@ state set of flags indicating the state of the device. Current flags are EISA_CONFIG_ENABLED and EISA_CONFIG_FORCED. res set of four 256 bytes I/O regions allocated to this device dma_mask DMA mask set from the parent device. -dev generic device (see Documentation/driver-model/device.rst) +dev generic device (see Documentation/driver-api/driver-model/device.rst) ======== ============================================================ You can get the 'struct eisa_device' from 'struct device' using the diff --git a/Documentation/filesystems/sysfs.txt b/Documentation/filesystems/sysfs.txt index 5b5311f9358d..ddf15b1b0d5a 100644 --- a/Documentation/filesystems/sysfs.txt +++ b/Documentation/filesystems/sysfs.txt @@ -319,7 +319,7 @@ quick way to lookup the sysfs interface for a device from the result of a stat(2) operation. More information can driver-model specific features can be found in -Documentation/driver-model/. +Documentation/driver-api/driver-model/. TODO: Finish this section. diff --git a/Documentation/hwmon/submitting-patches.rst b/Documentation/hwmon/submitting-patches.rst index d5b05d3e54ba..452fc28d8e0b 100644 --- a/Documentation/hwmon/submitting-patches.rst +++ b/Documentation/hwmon/submitting-patches.rst @@ -89,7 +89,7 @@ increase the chances of your change being accepted. console. Excessive logging can seriously affect system performance. * Use devres functions whenever possible to allocate resources. For rationale - and supported functions, please see Documentation/driver-model/devres.rst. + and supported functions, please see Documentation/driver-api/driver-model/devres.rst. If a function is not supported by devres, consider using devm_add_action(). * If the driver has a detect function, make sure it is silent. Debug messages diff --git a/Documentation/translations/zh_CN/filesystems/sysfs.txt b/Documentation/translations/zh_CN/filesystems/sysfs.txt index 452271dda141..ee1f37da5b23 100644 --- a/Documentation/translations/zh_CN/filesystems/sysfs.txt +++ b/Documentation/translations/zh_CN/filesystems/sysfs.txt @@ -288,7 +288,7 @@ dev/ 包含两个子目录： char/ 和 block/。在这两个子目录中，有 中相应的设备。/sys/dev 提供一个通过一个 stat(2) 操作结果，查找 设备 sysfs 接口快捷的方法。 -更多有关 driver-model 的特性信息可以在 Documentation/driver-model/ +更多有关 driver-model 的特性信息可以在 Documentation/driver-api/driver-model/ 中找到。 diff --git a/drivers/base/platform.c b/drivers/base/platform.c index 713903290385..506a0175a5a7 100644 --- a/drivers/base/platform.c +++ b/drivers/base/platform.c @@ -5,7 +5,7 @@ * Copyright (c) 2002-3 Patrick Mochel * Copyright (c) 2002-3 Open Source Development Labs * - * Please see Documentation/driver-model/platform.rst for more + * Please see Documentation/driver-api/driver-model/platform.rst for more * information. */ diff --git a/drivers/gpio/gpio-cs5535.c b/drivers/gpio/gpio-cs5535.c index 3611a0571667..53b24e3ae7de 100644 --- a/drivers/gpio/gpio-cs5535.c +++ b/drivers/gpio/gpio-cs5535.c @@ -41,7 +41,7 @@ MODULE_PARM_DESC(mask, "GPIO channel mask."); /* * FIXME: convert this singleton driver to use the state container - * design pattern, see Documentation/driver-model/design-patterns.rst + * design pattern, see Documentation/driver-api/driver-model/design-patterns.rst */ static struct cs5535_gpio_chip { struct gpio_chip chip; diff --git a/drivers/net/ethernet/intel/ice/ice_main.c b/drivers/net/ethernet/intel/ice/ice_main.c index 41c90f2ddb31..63db08d9bafa 100644 --- a/drivers/net/ethernet/intel/ice/ice_main.c +++ b/drivers/net/ethernet/intel/ice/ice_main.c @@ -2286,7 +2286,7 @@ ice_probe(struct pci_dev *pdev, const struct pci_device_id __always_unused *ent) struct ice_hw *hw; int err; - /* this driver uses devres, see Documentation/driver-model/devres.rst */ + /* this driver uses devres, see Documentation/driver-api/driver-model/devres.rst */ err = pcim_enable_device(pdev); if (err) return err; diff --git a/drivers/staging/unisys/Documentation/overview.txt b/drivers/staging/unisys/Documentation/overview.txt index 9ab30af265a5..f8a4144b239c 100644 --- a/drivers/staging/unisys/Documentation/overview.txt +++ b/drivers/staging/unisys/Documentation/overview.txt @@ -15,7 +15,7 @@ normally be unsharable, specifically: * visorinput - keyboard and mouse These drivers conform to the standard Linux bus/device model described -within Documentation/driver-model/, and utilize a driver named visorbus to +within Documentation/driver-api/driver-model/, and utilize a driver named visorbus to present the virtual busses involved. Drivers in the 'visor*' driver set are commonly referred to as "guest drivers" or "client drivers". All drivers except visorbus expose a device of a specific usable class to the Linux guest @@ -141,7 +141,7 @@ called automatically by the visorbus driver at appropriate times: ----------------------------------- Because visorbus is a standard Linux bus driver in the model described in -Documentation/driver-model/, the hierarchy of s-Par virtual devices is +Documentation/driver-api/driver-model/, the hierarchy of s-Par virtual devices is published in the sysfs tree beneath /bus/visorbus/, e.g., /sys/bus/visorbus/devices/ might look like: diff --git a/include/linux/device.h b/include/linux/device.h index 5eabfa0c4dee..c330b75c6c57 100644 --- a/include/linux/device.h +++ b/include/linux/device.h @@ -6,7 +6,7 @@ * Copyright (c) 2004-2009 Greg Kroah-Hartman * Copyright (c) 2008-2009 Novell Inc. * - * See Documentation/driver-model/ for more information. + * See Documentation/driver-api/driver-model/ for more information. */ #ifndef _DEVICE_H_ diff --git a/include/linux/platform_device.h b/include/linux/platform_device.h index beb25f277889..9bc36b589827 100644 --- a/include/linux/platform_device.h +++ b/include/linux/platform_device.h @@ -4,7 +4,7 @@ * * Copyright (c) 2001-2003 Patrick Mochel * - * See Documentation/driver-model/ for more information. + * See Documentation/driver-api/driver-model/ for more information. */ #ifndef _PLATFORM_DEVICE_H_ diff --git a/scripts/coccinelle/free/devm_free.cocci b/scripts/coccinelle/free/devm_free.cocci index fefd0331a2de..441799b5359b 100644 --- a/scripts/coccinelle/free/devm_free.cocci +++ b/scripts/coccinelle/free/devm_free.cocci @@ -3,7 +3,7 @@ /// functions. Values allocated using the devm_functions are freed when /// the device is detached, and thus the use of the standard freeing /// function would cause a double free. -/// See Documentation/driver-model/devres.rst for more information. +/// See Documentation/driver-api/driver-model/devres.rst for more information. /// /// A difficulty of detecting this problem is that the standard freeing /// function might be called from a different function than the one -- cgit v1.2.3 From 3266c806dc8692e079768ee2814498dcd6a91e61 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Wed, 5 Jun 2019 03:14:53 +0900 Subject: kconfig: run olddefconfig instead of oldconfig after merging fragments 'make olddefconfig' is non-interactive, so we can drop 'yes'. The behavior is equivalent. Signed-off-by: Masahiro Yamada --- scripts/kconfig/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/kconfig/Makefile b/scripts/kconfig/Makefile index ab30fe724c43..7656e1137b6b 100644 --- a/scripts/kconfig/Makefile +++ b/scripts/kconfig/Makefile @@ -94,7 +94,7 @@ configfiles=$(wildcard $(srctree)/kernel/configs/$@ $(srctree)/arch/$(SRCARCH)/c %.config: $(obj)/conf $(if $(call configfiles),, $(error No configuration exists for this target on this architecture)) $(Q)$(CONFIG_SHELL) $(srctree)/scripts/kconfig/merge_config.sh -m .config $(configfiles) - +$(Q)yes "" | $(MAKE) -f $(srctree)/Makefile oldconfig + $(Q)$(MAKE) -f $(srctree)/Makefile olddefconfig PHONY += kvmconfig kvmconfig: kvm_guest.config -- cgit v1.2.3 From 5a46421789f46165416d2b4834647b153c231c55 Mon Sep 17 00:00:00 2001 From: Cedric Hombourger Date: Tue, 9 Jul 2019 09:43:35 +0200 Subject: builddeb: generate multi-arch friendly linux-libc-dev package Debian-based distributions place libc header files in a machine specific directory (/usr/include/) instead of /usr/include/asm to support installation of the linux-libc-dev package from multiple architectures. Move headers installed by "make headers_install" accordingly using Debian's tuple from dpkg-architecture (stored in debian/arch). Signed-off-by: Cedric Hombourger Signed-off-by: Masahiro Yamada --- scripts/package/builddeb | 5 +++++ scripts/package/mkdebian | 1 + 2 files changed, 6 insertions(+) (limited to 'scripts') diff --git a/scripts/package/builddeb b/scripts/package/builddeb index e8ca6dc97e96..c4c580f547ef 100755 --- a/scripts/package/builddeb +++ b/scripts/package/builddeb @@ -132,6 +132,11 @@ fi if [ "$ARCH" != "um" ]; then $MAKE -f $srctree/Makefile headers $MAKE -f $srctree/Makefile headers_install INSTALL_HDR_PATH="$libc_headers_dir/usr" + # move asm headers to /usr/include//asm to match the structure + # used by Debian-based distros (to support multi-arch) + host_arch=$(dpkg-architecture -a$(cat debian/arch) -qDEB_HOST_MULTIARCH) + mkdir $libc_headers_dir/usr/include/$host_arch + mv $libc_headers_dir/usr/include/asm $libc_headers_dir/usr/include/$host_arch/ fi # Install the maintainer scripts diff --git a/scripts/package/mkdebian b/scripts/package/mkdebian index 8351584cb24e..e0750b70453f 100755 --- a/scripts/package/mkdebian +++ b/scripts/package/mkdebian @@ -197,6 +197,7 @@ Architecture: $debarch Description: Linux support headers for userspace development This package provides userspaces headers from the Linux kernel. These headers are used by the installed headers for GNU glibc and other system libraries. +Multi-Arch: same Package: $dbg_packagename Section: debug -- cgit v1.2.3 From 49662503e8e4df9db29bfc354112a9a6312d7a25 Mon Sep 17 00:00:00 2001 From: Joe Perches Date: Tue, 16 Jul 2019 16:27:09 -0700 Subject: get_maintainer: add ability to skip moderated mailing lists Add a command line switch --no-moderated to skip L: mailing lists marked with 'moderated'. Some people prefer not emailing moderated mailing lists as the moderation time can be indeterminate and some emails can be intentionally dropped by a moderator. This can cause fragmentation of email threads when some are subscribed to a moderated list but others are not and emails are dropped. Link: http://lkml.kernel.org/r/6f23c2918ad9fc744269feb8f909bdfb105c5afc.camel@perches.com Signed-off-by: Joe Perches Tested-by: Peter Zijlstra (Intel) Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- scripts/get_maintainer.pl | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) (limited to 'scripts') diff --git a/scripts/get_maintainer.pl b/scripts/get_maintainer.pl index c1c088ef1420..5ef59214c555 100755 --- a/scripts/get_maintainer.pl +++ b/scripts/get_maintainer.pl @@ -27,6 +27,7 @@ my $email_usename = 1; my $email_maintainer = 1; my $email_reviewer = 1; my $email_list = 1; +my $email_moderated_list = 1; my $email_subscriber_list = 0; my $email_git_penguin_chiefs = 0; my $email_git = 0; @@ -248,6 +249,7 @@ if (!GetOptions( 'r!' => \$email_reviewer, 'n!' => \$email_usename, 'l!' => \$email_list, + 'moderated!' => \$email_moderated_list, 's!' => \$email_subscriber_list, 'multiline!' => \$output_multiline, 'roles!' => \$output_roles, @@ -1023,7 +1025,8 @@ MAINTAINER field selection options: --r => include reviewer(s) if any --n => include name 'Full Name ' --l => include list(s) if any - --s => include subscriber only list(s) if any + --moderated => include moderated lists(s) if any (default: true) + --s => include subscriber only list(s) if any (default: false) --remove-duplicates => minimize duplicate email names/addresses --roles => show roles (status:subsystem, git-signer, list, etc...) --rolestats => show roles and statistics (commits/total_commits, %) @@ -1313,11 +1316,14 @@ sub add_categories { } else { if ($email_list) { if (!$hash_list_to{lc($list_address)}) { - $hash_list_to{lc($list_address)} = 1; if ($list_additional =~ m/moderated/) { - push(@list_to, [$list_address, - "moderated list${list_role}"]); + if ($email_moderated_list) { + $hash_list_to{lc($list_address)} = 1; + push(@list_to, [$list_address, + "moderated list${list_role}"]); + } } else { + $hash_list_to{lc($list_address)} = 1; push(@list_to, [$list_address, "open list${list_role}"]); } -- cgit v1.2.3 From 6a8d76cbd647d414248d314300106d1ce04daa4b Mon Sep 17 00:00:00 2001 From: Matteo Croce Date: Tue, 16 Jul 2019 16:27:48 -0700 Subject: checkpatch.pl: warn on duplicate sysctl local variable Commit d91bff3011cf ("proc/sysctl: add shared variables for range check") adds some shared const variables to be used instead of a local copy in each source file. Warn when a chunk duplicates one of these values in a ctl_table struct: $ scripts/checkpatch.pl 0001-test-commit.patch WARNING: duplicated sysctl range checking value 'zero', consider using the shared one in include/linux/sysctl.h #27: FILE: arch/arm/kernel/isa.c:48: + .extra1 = &zero, WARNING: duplicated sysctl range checking value 'int_max', consider using the shared one in include/linux/sysctl.h #28: FILE: arch/arm/kernel/isa.c:49: + .extra2 = &int_max, total: 0 errors, 2 warnings, 14 lines checked Link: http://lkml.kernel.org/r/20190531131422.14970-1-mcroce@redhat.com Signed-off-by: Matteo Croce Reviewed-by: Kees Cook Cc: Joe Perches Cc: Aaron Tomlin Cc: Matthew Wilcox Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- scripts/checkpatch.pl | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'scripts') diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl index a6d436809bf5..93a7edfe0f05 100755 --- a/scripts/checkpatch.pl +++ b/scripts/checkpatch.pl @@ -6639,6 +6639,12 @@ sub process { "unknown module license " . $extracted_string . "\n" . $herecurr); } } + +# check for sysctl duplicate constants + if ($line =~ /\.extra[12]\s*=\s*&(zero|one|int_max)\b/) { + WARN("DUPLICATED_SYSCTL_CONST", + "duplicated sysctl range checking value '$1', consider using the shared one in include/linux/sysctl.h\n" . $herecurr); + } } # If we have no input at all, then there is nothing to report on -- cgit v1.2.3 From 8207d4a88e1ef4ab54f05f2f18edd444a5099099 Mon Sep 17 00:00:00 2001 From: Leonard Crestez Date: Tue, 16 Jul 2019 16:30:12 -0700 Subject: scripts/gdb: add lx-genpd-summary command This is like /sys/kernel/debug/pm/pm_genpd_summary except it's accessible through a debugger. This can be useful if the target crashes or hangs because power domains were not properly enabled. Link: http://lkml.kernel.org/r/f9ee627a0d4f94b894aa202fee8a98444049bed8.1561492937.git.leonard.crestez@nxp.com Signed-off-by: Leonard Crestez Reviewed-by: Stephen Boyd Cc: Kieran Bingham Cc: Jan Kiszka Cc: "Rafael J. Wysocki" Cc: Greg Kroah-Hartman Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- scripts/gdb/linux/genpd.py | 83 ++++++++++++++++++++++++++++++++++++++++++++++ scripts/gdb/vmlinux-gdb.py | 1 + 2 files changed, 84 insertions(+) create mode 100644 scripts/gdb/linux/genpd.py (limited to 'scripts') diff --git a/scripts/gdb/linux/genpd.py b/scripts/gdb/linux/genpd.py new file mode 100644 index 000000000000..6ca93bd2949e --- /dev/null +++ b/scripts/gdb/linux/genpd.py @@ -0,0 +1,83 @@ +# SPDX-License-Identifier: GPL-2.0 +# +# Copyright (c) NXP 2019 + +import gdb +import sys + +from linux.utils import CachedType +from linux.lists import list_for_each_entry + +generic_pm_domain_type = CachedType('struct generic_pm_domain') +pm_domain_data_type = CachedType('struct pm_domain_data') +device_link_type = CachedType('struct device_link') + + +def kobject_get_path(kobj): + path = kobj['name'].string() + parent = kobj['parent'] + if parent: + path = kobject_get_path(parent) + '/' + path + return path + + +def rtpm_status_str(dev): + if dev['power']['runtime_error']: + return 'error' + if dev['power']['disable_depth']: + return 'unsupported' + _RPM_STATUS_LOOKUP = [ + "active", + "resuming", + "suspended", + "suspending" + ] + return _RPM_STATUS_LOOKUP[dev['power']['runtime_status']] + + +class LxGenPDSummary(gdb.Command): + '''Print genpd summary + +Output is similar to /sys/kernel/debug/pm_genpd/pm_genpd_summary''' + + def __init__(self): + super(LxGenPDSummary, self).__init__('lx-genpd-summary', gdb.COMMAND_DATA) + + def summary_one(self, genpd): + if genpd['status'] == 0: + status_string = 'on' + else: + status_string = 'off-{}'.format(genpd['state_idx']) + + slave_names = [] + for link in list_for_each_entry( + genpd['master_links'], + device_link_type.get_type().pointer(), + 'master_node'): + slave_names.apend(link['slave']['name']) + + gdb.write('%-30s %-15s %s\n' % ( + genpd['name'].string(), + status_string, + ', '.join(slave_names))) + + # Print devices in domain + for pm_data in list_for_each_entry(genpd['dev_list'], + pm_domain_data_type.get_type().pointer(), + 'list_node'): + dev = pm_data['dev'] + kobj_path = kobject_get_path(dev['kobj']) + gdb.write(' %-50s %s\n' % (kobj_path, rtpm_status_str(dev))) + + def invoke(self, arg, from_tty): + gdb.write('domain status slaves\n'); + gdb.write(' /device runtime status\n'); + gdb.write('----------------------------------------------------------------------\n'); + for genpd in list_for_each_entry( + gdb.parse_and_eval('&gpd_list'), + generic_pm_domain_type.get_type().pointer(), + 'gpd_list_node'): + self.summary_one(genpd) + + +LxGenPDSummary() diff --git a/scripts/gdb/vmlinux-gdb.py b/scripts/gdb/vmlinux-gdb.py index eff5a48ac026..a504f511e752 100644 --- a/scripts/gdb/vmlinux-gdb.py +++ b/scripts/gdb/vmlinux-gdb.py @@ -35,3 +35,4 @@ else: import linux.constants import linux.timerlist import linux.clk + import linux.genpd -- cgit v1.2.3 From 778c1f5ccbd95722cf84d2233c6acbf4d01a3ec7 Mon Sep 17 00:00:00 2001 From: Leonard Crestez Date: Tue, 16 Jul 2019 16:30:15 -0700 Subject: scripts/gdb: add helpers to find and list devices Add helper commands and functions for finding pointers to struct device by enumerating linux device bus/class infrastructure. This can be used to fetch subsystem and driver-specific structs: (gdb) p *$container_of($lx_device_find_by_class_name("net", "eth0"), "struct net_device", "dev") (gdb) p *$container_of($lx_device_find_by_bus_name("i2c", "0-004b"), "struct i2c_client", "dev") (gdb) p *(struct imx_port*)$lx_device_find_by_class_name("tty", "ttymxc1")->parent->driver_data Several generic "lx-device-list" functions are included to enumerate devices by bus and class: (gdb) lx-device-list-bus usb (gdb) lx-device-list-class (gdb) lx-device-list-tree &platform_bus Similar information is available in /sys but pointer values are deliberately hidden. Link: http://lkml.kernel.org/r/c948628041311cbf1b9b4cff3dda7d2073cb3eaa.1561492937.git.leonard.crestez@nxp.com Signed-off-by: Leonard Crestez Reviewed-by: Stephen Boyd Cc: Kieran Bingham Cc: Jan Kiszka Cc: "Rafael J. Wysocki" Cc: Greg Kroah-Hartman Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- scripts/gdb/linux/device.py | 182 ++++++++++++++++++++++++++++++++++++++++++++ scripts/gdb/vmlinux-gdb.py | 1 + 2 files changed, 183 insertions(+) create mode 100644 scripts/gdb/linux/device.py (limited to 'scripts') diff --git a/scripts/gdb/linux/device.py b/scripts/gdb/linux/device.py new file mode 100644 index 000000000000..16376c5cfec6 --- /dev/null +++ b/scripts/gdb/linux/device.py @@ -0,0 +1,182 @@ +# SPDX-License-Identifier: GPL-2.0 +# +# Copyright (c) NXP 2019 + +import gdb + +from linux.utils import CachedType +from linux.utils import container_of +from linux.lists import list_for_each_entry + + +device_private_type = CachedType('struct device_private') +device_type = CachedType('struct device') + +subsys_private_type = CachedType('struct subsys_private') +kobject_type = CachedType('struct kobject') +kset_type = CachedType('struct kset') + +bus_type = CachedType('struct bus_type') +class_type = CachedType('struct class') + + +def dev_name(dev): + dev_init_name = dev['init_name'] + if dev_init_name: + return dev_init_name.string() + return dev['kobj']['name'].string() + + +def kset_for_each_object(kset): + return list_for_each_entry(kset['list'], + kobject_type.get_type().pointer(), "entry") + + +def for_each_bus(): + for kobj in kset_for_each_object(gdb.parse_and_eval('bus_kset')): + subsys = container_of(kobj, kset_type.get_type().pointer(), 'kobj') + subsys_priv = container_of(subsys, subsys_private_type.get_type().pointer(), 'subsys') + yield subsys_priv['bus'] + + +def for_each_class(): + for kobj in kset_for_each_object(gdb.parse_and_eval('class_kset')): + subsys = container_of(kobj, kset_type.get_type().pointer(), 'kobj') + subsys_priv = container_of(subsys, subsys_private_type.get_type().pointer(), 'subsys') + yield subsys_priv['class'] + + +def get_bus_by_name(name): + for item in for_each_bus(): + if item['name'].string() == name: + return item + raise gdb.GdbError("Can't find bus type {!r}".format(name)) + + +def get_class_by_name(name): + for item in for_each_class(): + if item['name'].string() == name: + return item + raise gdb.GdbError("Can't find device class {!r}".format(name)) + + +klist_type = CachedType('struct klist') +klist_node_type = CachedType('struct klist_node') + + +def klist_for_each(klist): + return list_for_each_entry(klist['k_list'], + klist_node_type.get_type().pointer(), 'n_node') + + +def bus_for_each_device(bus): + for kn in klist_for_each(bus['p']['klist_devices']): + dp = container_of(kn, device_private_type.get_type().pointer(), 'knode_bus') + yield dp['device'] + + +def class_for_each_device(cls): + for kn in klist_for_each(cls['p']['klist_devices']): + dp = container_of(kn, device_private_type.get_type().pointer(), 'knode_class') + yield dp['device'] + + +def device_for_each_child(dev): + for kn in klist_for_each(dev['p']['klist_children']): + dp = container_of(kn, device_private_type.get_type().pointer(), 'knode_parent') + yield dp['device'] + + +def _show_device(dev, level=0, recursive=False): + gdb.write('{}dev {}:\t{}\n'.format('\t' * level, dev_name(dev), dev)) + if recursive: + for child in device_for_each_child(dev): + _show_device(child, level + 1, recursive) + + +class LxDeviceListBus(gdb.Command): + '''Print devices on a bus (or all buses if not specified)''' + + def __init__(self): + super(LxDeviceListBus, self).__init__('lx-device-list-bus', gdb.COMMAND_DATA) + + def invoke(self, arg, from_tty): + if not arg: + for bus in for_each_bus(): + gdb.write('bus {}:\t{}\n'.format(bus['name'].string(), bus)) + for dev in bus_for_each_device(bus): + _show_device(dev, level=1) + else: + bus = get_bus_by_name(arg) + if not bus: + raise gdb.GdbError("Can't find bus {!r}".format(arg)) + for dev in bus_for_each_device(bus): + _show_device(dev) + + +class LxDeviceListClass(gdb.Command): + '''Print devices in a class (or all classes if not specified)''' + + def __init__(self): + super(LxDeviceListClass, self).__init__('lx-device-list-class', gdb.COMMAND_DATA) + + def invoke(self, arg, from_tty): + if not arg: + for cls in for_each_class(): + gdb.write("class {}:\t{}\n".format(cls['name'].string(), cls)) + for dev in class_for_each_device(cls): + _show_device(dev, level=1) + else: + cls = get_class_by_name(arg) + for dev in class_for_each_device(cls): + _show_device(dev) + + +class LxDeviceListTree(gdb.Command): + '''Print a device and its children recursively''' + + def __init__(self): + super(LxDeviceListTree, self).__init__('lx-device-list-tree', gdb.COMMAND_DATA) + + def invoke(self, arg, from_tty): + if not arg: + raise gdb.GdbError('Please provide pointer to struct device') + dev = gdb.parse_and_eval(arg) + if dev.type != device_type.get_type().pointer(): + raise gdb.GdbError('Please provide pointer to struct device') + _show_device(dev, level=0, recursive=True) + + +class LxDeviceFindByBusName(gdb.Function): + '''Find struct device by bus and name (both strings)''' + + def __init__(self): + super(LxDeviceFindByBusName, self).__init__('lx_device_find_by_bus_name') + + def invoke(self, bus, name): + name = name.string() + bus = get_bus_by_name(bus.string()) + for dev in bus_for_each_device(bus): + if dev_name(dev) == name: + return dev + + +class LxDeviceFindByClassName(gdb.Function): + '''Find struct device by class and name (both strings)''' + + def __init__(self): + super(LxDeviceFindByClassName, self).__init__('lx_device_find_by_class_name') + + def invoke(self, cls, name): + name = name.string() + cls = get_class_by_name(cls.string()) + for dev in class_for_each_device(cls): + if dev_name(dev) == name: + return dev + + +LxDeviceListBus() +LxDeviceListClass() +LxDeviceListTree() +LxDeviceFindByBusName() +LxDeviceFindByClassName() diff --git a/scripts/gdb/vmlinux-gdb.py b/scripts/gdb/vmlinux-gdb.py index a504f511e752..4136dc2c59df 100644 --- a/scripts/gdb/vmlinux-gdb.py +++ b/scripts/gdb/vmlinux-gdb.py @@ -36,3 +36,4 @@ else: import linux.timerlist import linux.clk import linux.genpd + import linux.device -- cgit v1.2.3 From b308467c916aa7acc5069802ab76a9f657434701 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 13 Jul 2019 08:50:24 -0300 Subject: scripts/sphinx-pre-install: fix script for RHEL/CentOS There's a missing parenthesis at the script, with causes it to fail to detect non-Fedora releases (e. g. RHEL/CentOS). Tested with Centos 7.6.1810. Signed-off-by: Mauro Carvalho Chehab --- scripts/sphinx-pre-install | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index f230e65329a2..101ddd00bf02 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -371,7 +371,7 @@ sub give_redhat_hints() # # Checks valid for RHEL/CentOS version 7.x. # - if (! $system_release =~ /Fedora/) { + if (!($system_release =~ /Fedora/)) { $map{"virtualenv"} = "python-virtualenv"; } -- cgit v1.2.3 From 56e5a633923793b31515795ad30156a307572c1e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 13 Jul 2019 09:37:16 -0300 Subject: scripts/sphinx-pre-install: don't use LaTeX with CentOS 7 There aren't enough texlive packages for LaTeX-based builds to work on CentOS/RHEL <= 7. Signed-off-by: Mauro Carvalho Chehab --- scripts/sphinx-pre-install | 68 ++++++++++++++++++++++++++++++++++------------ 1 file changed, 50 insertions(+), 18 deletions(-) (limited to 'scripts') diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index 101ddd00bf02..33efadd6c0b6 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -83,6 +83,17 @@ sub check_missing(%) foreach my $prog (sort keys %missing) { my $is_optional = $missing{$prog}; + # At least on some LTS distros like CentOS 7, texlive doesn't + # provide all packages we need. When such distros are + # detected, we have to disable PDF output. + # + # So, we need to ignore the packages that distros would + # need for LaTeX to work + if ($is_optional == 2 && !$pdf) { + $optional--; + next; + } + if ($is_optional) { print "Warning: better to also install \"$prog\".\n"; } else { @@ -333,10 +344,10 @@ sub give_debian_hints() if ($pdf) { check_missing_file("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf", - "fonts-dejavu", 1); + "fonts-dejavu", 2); } - check_program("dvipng", 1) if ($pdf); + check_program("dvipng", 2) if ($pdf); check_missing(\%map); return if (!$need && !$optional); @@ -371,22 +382,40 @@ sub give_redhat_hints() # # Checks valid for RHEL/CentOS version 7.x. # + my $old = 0; + my $rel; + $rel = $1 if ($system_release =~ /release\s+(\d+)/); + if (!($system_release =~ /Fedora/)) { $map{"virtualenv"} = "python-virtualenv"; - } - my $release; + if ($rel && $rel < 8) { + $old = 1; + $pdf = 0; - $release = $1 if ($system_release =~ /Fedora\s+release\s+(\d+)/); + printf("Note: texlive packages on RHEL/CENTOS <= 7 are incomplete. Can't support PDF output\n"); + printf("If you want to build PDF, please read:\n"); + printf("\thttps://www.systutorials.com/241660/how-to-install-tex-live-on-centos-7-linux/\n"); + } + } else { + if ($rel && $rel < 26) { + $old = 1; + } + } + if (!$rel) { + printf("Couldn't identify release number\n"); + $old = 1; + $pdf = 0; + } - check_rpm_missing(\@fedora26_opt_pkgs, 1) if ($pdf && $release >= 26); - check_rpm_missing(\@fedora_tex_pkgs, 1) if ($pdf); - check_missing_tex(1) if ($pdf); + check_rpm_missing(\@fedora26_opt_pkgs, 2) if ($pdf && !$old); + check_rpm_missing(\@fedora_tex_pkgs, 2) if ($pdf); + check_missing_tex(2) if ($pdf); check_missing(\%map); return if (!$need && !$optional); - if ($release >= 18) { + if (!$old) { # dnf, for Fedora 18+ printf("You should run:\n\n\tsudo dnf install -y $install\n"); } else { @@ -425,8 +454,8 @@ sub give_opensuse_hints() "texlive-zapfding", ); - check_rpm_missing(\@suse_tex_pkgs, 1) if ($pdf); - check_missing_tex(1) if ($pdf); + check_rpm_missing(\@suse_tex_pkgs, 2) if ($pdf); + check_missing_tex(2) if ($pdf); check_missing(\%map); return if (!$need && !$optional); @@ -450,7 +479,7 @@ sub give_mageia_hints() "texlive-fontsextra", ); - check_rpm_missing(\@tex_pkgs, 1) if ($pdf); + check_rpm_missing(\@tex_pkgs, 2) if ($pdf); check_missing(\%map); return if (!$need && !$optional); @@ -473,7 +502,8 @@ sub give_arch_linux_hints() "texlive-latexextra", "ttf-dejavu", ); - check_pacman_missing(\@archlinux_tex_pkgs, 1) if ($pdf); + check_pacman_missing(\@archlinux_tex_pkgs, 2) if ($pdf); + check_missing(\%map); return if (!$need && !$optional); @@ -492,7 +522,7 @@ sub give_gentoo_hints() ); check_missing_file("/usr/share/fonts/dejavu/DejaVuSans.ttf", - "media-fonts/dejavu", 1) if ($pdf); + "media-fonts/dejavu", 2) if ($pdf); check_missing(\%map); @@ -560,7 +590,7 @@ sub check_distros() my %map = ( "sphinx-build" => "sphinx" ); - check_missing_tex(1) if ($pdf); + check_missing_tex(2) if ($pdf); check_missing(\%map); print "I don't know distro $system_release.\n"; print "So, I can't provide you a hint with the install procedure.\n"; @@ -589,11 +619,13 @@ sub check_needs() check_program("make", 0); check_program("gcc", 0); check_python_module("sphinx_rtd_theme", 1) if (!$virtualenv); - check_program("xelatex", 1) if ($pdf); check_program("dot", 1); check_program("convert", 1); - check_program("rsvg-convert", 1) if ($pdf); - check_program("latexmk", 1) if ($pdf); + + # Extra PDF files - should use 2 for is_optional + check_program("xelatex", 2) if ($pdf); + check_program("rsvg-convert", 2) if ($pdf); + check_program("latexmk", 2) if ($pdf); check_distros(); -- cgit v1.2.3 From 353290a9eb5362a80bc8e52fcd7eb77a30f48afc Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 13 Jul 2019 08:19:44 -0300 Subject: scripts/sphinx-pre-install: fix latexmk dependencies The name of the package with carries latexmk is different on two distros: - On OpenSUSE, latexmk is packaged as "texlive-latexmk-bin" - On Mageia, latexmk is packaged at "texlive-collection-basic" Signed-off-by: Mauro Carvalho Chehab --- scripts/sphinx-pre-install | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'scripts') diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index 33efadd6c0b6..8dc13fe95ffe 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -454,6 +454,8 @@ sub give_opensuse_hints() "texlive-zapfding", ); + $map{"latexmk"} = "texlive-latexmk-bin"; + check_rpm_missing(\@suse_tex_pkgs, 2) if ($pdf); check_missing_tex(2) if ($pdf); check_missing(\%map); @@ -479,6 +481,8 @@ sub give_mageia_hints() "texlive-fontsextra", ); + $map{"latexmk"} = "texlive-collection-basic"; + check_rpm_missing(\@tex_pkgs, 2) if ($pdf); check_missing(\%map); -- cgit v1.2.3 From 4ea96d57bbfda93ae6cfdc8e565a3c419a78f328 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 13 Jul 2019 08:19:44 -0300 Subject: scripts/sphinx-pre-install: cleanup Gentoo checks On Gentoo, the portage changes for ImageMagick to work are always suggested, even if already applied. While the two extra commands should be harmless, add a check to avoid reporting it without need. Signed-off-by: Mauro Carvalho Chehab --- scripts/sphinx-pre-install | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index 8dc13fe95ffe..0a5c83aa5f44 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -533,8 +533,19 @@ sub give_gentoo_hints() return if (!$need && !$optional); printf("You should run:\n\n"); - printf("\tsudo su -c 'echo \"media-gfx/imagemagick svg png\" > /etc/portage/package.use/imagemagick'\n"); - printf("\tsudo su -c 'echo \"media-gfx/graphviz cairo pdf\" > /etc/portage/package.use/graphviz'\n"); + + my $imagemagick = "media-gfx/imagemagick svg png"; + my $cairo = "media-gfx/graphviz cairo pdf"; + my $portage_imagemagick = "/etc/portage/package.use/imagemagick"; + my $portage_cairo = "/etc/portage/package.use/graphviz"; + + if (qx(cat $portage_imagemagick) ne "$imagemagick\n") { + printf("\tsudo su -c 'echo \"$imagemagick\" > $portage_imagemagick'\n") + } + if (qx(cat $portage_cairo) ne "$cairo\n") { + printf("\tsudo su -c 'echo \"$cairo\" > $portage_cairo'\n"); + } + printf("\tsudo emerge --ask $install\n"); } -- cgit v1.2.3 From 27eed923f715f6269b98e089ad2164f9b016eace Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 13 Jul 2019 08:19:44 -0300 Subject: scripts/sphinx-pre-install: seek for Noto CJK fonts for pdf output The translations guide need Noto CJK fonts. So, add a logic that would suggest its install for distros. It also fix a few other issues while testing the script with several distributions. Signed-off-by: Mauro Carvalho Chehab --- scripts/sphinx-pre-install | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) (limited to 'scripts') diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index 0a5c83aa5f44..3b638c0e1a4f 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -345,6 +345,9 @@ sub give_debian_hints() if ($pdf) { check_missing_file("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf", "fonts-dejavu", 2); + + check_missing_file("/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc", + "fonts-noto-cjk", 2); } check_program("dvipng", 2) if ($pdf); @@ -374,6 +377,7 @@ sub give_redhat_hints() my @fedora_tex_pkgs = ( "texlive-collection-fontsrecommended", "texlive-collection-latex", + "texlive-xecjk", "dejavu-sans-fonts", "dejavu-serif-fonts", "dejavu-sans-mono-fonts", @@ -408,6 +412,11 @@ sub give_redhat_hints() $pdf = 0; } + if ($pdf) { + check_missing_file("/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc", + "google-noto-sans-cjk-ttc-fonts", 2); + } + check_rpm_missing(\@fedora26_opt_pkgs, 2) if ($pdf && !$old); check_rpm_missing(\@fedora_tex_pkgs, 2) if ($pdf); check_missing_tex(2) if ($pdf); @@ -456,6 +465,11 @@ sub give_opensuse_hints() $map{"latexmk"} = "texlive-latexmk-bin"; + # FIXME: add support for installing CJK fonts + # + # I tried hard, but was unable to find a way to install + # "Noto Sans CJK SC" on openSUSE + check_rpm_missing(\@suse_tex_pkgs, 2) if ($pdf); check_missing_tex(2) if ($pdf); check_missing(\%map); @@ -483,6 +497,11 @@ sub give_mageia_hints() $map{"latexmk"} = "texlive-collection-basic"; + if ($pdf) { + check_missing_file("/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc", + "google-noto-sans-cjk-ttc-fonts", 2); + } + check_rpm_missing(\@tex_pkgs, 2) if ($pdf); check_missing(\%map); @@ -508,6 +527,11 @@ 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", + "noto-fonts-cjk", 2); + } + check_missing(\%map); return if (!$need && !$optional); @@ -528,6 +552,11 @@ sub give_gentoo_hints() 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", + "media-fonts/noto-cjk", 2); + } + check_missing(\%map); return if (!$need && !$optional); -- cgit v1.2.3 From 8e2442a5f86e1f77b86401fce274a7f622740bc4 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Fri, 12 Jul 2019 15:07:09 +0900 Subject: kconfig: fix missing choice values in auto.conf MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Since commit 00c864f8903d ("kconfig: allow all config targets to write auto.conf if missing"), Kconfig creates include/config/auto.conf in the defconfig stage when it is missing. Joonas Kylmälä reported incorrect auto.conf generation under some circumstances. To reproduce it, apply the following diff: | --- a/arch/arm/configs/imx_v6_v7_defconfig | +++ b/arch/arm/configs/imx_v6_v7_defconfig | @@ -345,14 +345,7 @@ CONFIG_USB_CONFIGFS_F_MIDI=y | CONFIG_USB_CONFIGFS_F_HID=y | CONFIG_USB_CONFIGFS_F_UVC=y | CONFIG_USB_CONFIGFS_F_PRINTER=y | -CONFIG_USB_ZERO=m | -CONFIG_USB_AUDIO=m | -CONFIG_USB_ETH=m | -CONFIG_USB_G_NCM=m | -CONFIG_USB_GADGETFS=m | -CONFIG_USB_FUNCTIONFS=m | -CONFIG_USB_MASS_STORAGE=m | -CONFIG_USB_G_SERIAL=m | +CONFIG_USB_FUNCTIONFS=y | CONFIG_MMC=y | CONFIG_MMC_SDHCI=y | CONFIG_MMC_SDHCI_PLTFM=y And then, run: $ make ARCH=arm mrproper imx_v6_v7_defconfig You will see CONFIG_USB_FUNCTIONFS=y is correctly contained in the .config, but not in the auto.conf. Please note drivers/usb/gadget/legacy/Kconfig is included from a choice block in drivers/usb/gadget/Kconfig. So USB_FUNCTIONFS is a choice value. This is probably a similar situation described in commit beaaddb62540 ("kconfig: tests: test defconfig when two choices interact"). When sym_calc_choice() is called, the choice symbol forgets the SYMBOL_DEF_USER unless all of its choice values are explicitly set by the user. The choice symbol is given just one chance to recall it because set_all_choice_values() is called if SYMBOL_NEED_SET_CHOICE_VALUES is set. When sym_calc_choice() is called again, the choice symbol forgets it forever, since SYMBOL_NEED_SET_CHOICE_VALUES is a one-time aid. Hence, we cannot call sym_clear_all_valid() again and again. It is crazy to repeat set and unset of internal flags. However, we cannot simply get rid of "sym->flags &= flags | ~SYMBOL_DEF_USER;" Doing so would re-introduce the problem solved by commit 5d09598d488f ("kconfig: fix new choices being skipped upon config update"). To work around the issue, conf_write_autoconf() stopped calling sym_clear_all_valid(). conf_write() must be changed accordingly. Currently, it clears SYMBOL_WRITE after the symbol is written into the .config file. This is needed to prevent it from writing the same symbol multiple times in case the symbol is declared in two or more locations. I added the new flag SYMBOL_WRITTEN, to track the symbols that have been written. Anyway, this is a cheesy workaround in order to suppress the issue as far as defconfig is concerned. Handling of choices is totally broken. sym_clear_all_valid() is called every time a user touches a symbol from the GUI interface. To reproduce it, just add a new symbol drivers/usb/gadget/legacy/Kconfig, then touch around unrelated symbols from menuconfig. USB_FUNCTIONFS will disappear from the .config file. I added the Fixes tag since it is more fatal than before. But, this has been broken since long long time before, and still it is. We should take a closer look to fix this correctly somehow. Fixes: 00c864f8903d ("kconfig: allow all config targets to write auto.conf if missing") Cc: linux-stable # 4.19+ Reported-by: Joonas Kylmälä Signed-off-by: Masahiro Yamada Tested-by: Joonas Kylmälä --- scripts/kconfig/confdata.c | 7 +++---- scripts/kconfig/expr.h | 1 + 2 files changed, 4 insertions(+), 4 deletions(-) (limited to 'scripts') diff --git a/scripts/kconfig/confdata.c b/scripts/kconfig/confdata.c index 501fdcc5e999..1134892599da 100644 --- a/scripts/kconfig/confdata.c +++ b/scripts/kconfig/confdata.c @@ -895,7 +895,8 @@ int conf_write(const char *name) "# %s\n" "#\n", str); need_newline = false; - } else if (!(sym->flags & SYMBOL_CHOICE)) { + } else if (!(sym->flags & SYMBOL_CHOICE) && + !(sym->flags & SYMBOL_WRITTEN)) { sym_calc_value(sym); if (!(sym->flags & SYMBOL_WRITE)) goto next; @@ -903,7 +904,7 @@ int conf_write(const char *name) fprintf(out, "\n"); need_newline = false; } - sym->flags &= ~SYMBOL_WRITE; + sym->flags |= SYMBOL_WRITTEN; conf_write_symbol(out, sym, &kconfig_printer_cb, NULL); } @@ -1063,8 +1064,6 @@ int conf_write_autoconf(int overwrite) if (!overwrite && is_present(autoconf_name)) return 0; - sym_clear_all_valid(); - conf_write_dep("include/config/auto.conf.cmd"); if (conf_touch_deps()) diff --git a/scripts/kconfig/expr.h b/scripts/kconfig/expr.h index 8dde65bc3165..017843c9a4f4 100644 --- a/scripts/kconfig/expr.h +++ b/scripts/kconfig/expr.h @@ -141,6 +141,7 @@ struct symbol { #define SYMBOL_OPTIONAL 0x0100 /* choice is optional - values can be 'n' */ #define SYMBOL_WRITE 0x0200 /* write symbol to file (KCONFIG_CONFIG) */ #define SYMBOL_CHANGED 0x0400 /* ? */ +#define SYMBOL_WRITTEN 0x0800 /* track info to avoid double-write to .config */ #define SYMBOL_NO_WRITE 0x1000 /* Symbol for internal use only; it will not be written */ #define SYMBOL_CHECKED 0x2000 /* used during dependency checking */ #define SYMBOL_WARNED 0x8000 /* warning has been issued */ -- cgit v1.2.3 From c04d1e46fcd6090f2ae04e285e9d3adcf376f5b1 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Mon, 15 Jul 2019 23:11:03 +0900 Subject: kbuild: remove unused hostcc-option We can re-add this whenever it is needed. At this moment, it is unused. Signed-off-by: Masahiro Yamada --- scripts/Kbuild.include | 5 ----- 1 file changed, 5 deletions(-) (limited to 'scripts') diff --git a/scripts/Kbuild.include b/scripts/Kbuild.include index 73e80b917f12..77c742fa4fb1 100644 --- a/scripts/Kbuild.include +++ b/scripts/Kbuild.include @@ -125,11 +125,6 @@ CC_OPTION_CFLAGS = $(filter-out $(GCC_PLUGINS_CFLAGS),$(KBUILD_CFLAGS)) cc-option = $(call __cc-option, $(CC),\ $(KBUILD_CPPFLAGS) $(CC_OPTION_CFLAGS),$(1),$(2)) -# hostcc-option -# Usage: cflags-y += $(call hostcc-option,-march=winchip-c6,-march=i586) -hostcc-option = $(call __cc-option, $(HOSTCC),\ - $(KBUILD_HOSTCFLAGS) $(HOST_EXTRACFLAGS),$(1),$(2)) - # cc-option-yn # Usage: flag := $(call cc-option-yn,-march=winchip-c6) cc-option-yn = $(call try-run,\ -- cgit v1.2.3 From 4bd01de8f201abb704ae9bda3af4ea9ba3a10b0a Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Tue, 16 Jul 2019 22:29:45 +0900 Subject: kbuild: compile-test headers listed in header-test-m as well It will be useful to control the header-test by a tristate option. If CONFIG_FOO is a tristate option, you can write like this: header-test-$(CONFIG_FOO) += foo.h Signed-off-by: Masahiro Yamada --- scripts/Makefile.build | 2 +- scripts/Makefile.lib | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/Makefile.build b/scripts/Makefile.build index be38198d98b2..5829ccbc7dd0 100644 --- a/scripts/Makefile.build +++ b/scripts/Makefile.build @@ -294,7 +294,7 @@ quiet_cmd_cc_lst_c = MKLST $@ $(obj)/%.lst: $(src)/%.c FORCE $(call if_changed_dep,cc_lst_c) -# header test (header-test-y target) +# header test (header-test-y, header-test-m target) # --------------------------------------------------------------------------- quiet_cmd_cc_s_h = CC $@ diff --git a/scripts/Makefile.lib b/scripts/Makefile.lib index 6cb3aa5cbc79..5241d0751eb0 100644 --- a/scripts/Makefile.lib +++ b/scripts/Makefile.lib @@ -78,7 +78,7 @@ header-test-y += $(filter-out $(header-test-), \ $(wildcard $(addprefix $(srctree)/$(src)/, \ $(header-test-pattern-y))))) -extra-$(CONFIG_HEADER_TEST) += $(addsuffix .s, $(header-test-y)) +extra-$(CONFIG_HEADER_TEST) += $(addsuffix .s, $(header-test-y) $(header-test-m)) # Add subdir path -- cgit v1.2.3 From d09778d16e20bc4f1f4971cc9a9fd7ff6ba898ff Mon Sep 17 00:00:00 2001 From: Himanshu Jha Date: Tue, 16 Jul 2019 11:22:22 +0530 Subject: coccinelle: api: add devm_platform_ioremap_resource script Use recently introduced devm_platform_ioremap_resource helper which wraps platform_get_resource() and devm_ioremap_resource() together. This helps produce much cleaner code and remove local `struct resource` declaration. Signed-off-by: Himanshu Jha Signed-off-by: Julia Lawall Signed-off-by: Masahiro Yamada --- .../api/devm_platform_ioremap_resource.cocci | 60 ++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 scripts/coccinelle/api/devm_platform_ioremap_resource.cocci (limited to 'scripts') diff --git a/scripts/coccinelle/api/devm_platform_ioremap_resource.cocci b/scripts/coccinelle/api/devm_platform_ioremap_resource.cocci new file mode 100644 index 000000000000..56a2e261d61d --- /dev/null +++ b/scripts/coccinelle/api/devm_platform_ioremap_resource.cocci @@ -0,0 +1,60 @@ +// SPDX-License-Identifier: GPL-2.0 +/// Use devm_platform_ioremap_resource helper which wraps +/// platform_get_resource() and devm_ioremap_resource() together. +/// +// Confidence: High +// Copyright: (C) 2019 Himanshu Jha GPLv2. +// Copyright: (C) 2019 Julia Lawall, Inria/LIP6. GPLv2. +// Keywords: platform_get_resource, devm_ioremap_resource, +// Keywords: devm_platform_ioremap_resource + +virtual patch +virtual report + +@r depends on patch && !report@ +expression e1, e2, arg1, arg2, arg3; +identifier id; +@@ + +( +- id = platform_get_resource(arg1, IORESOURCE_MEM, arg2); +| +- struct resource *id = platform_get_resource(arg1, IORESOURCE_MEM, arg2); +) + ... when != id +- e1 = devm_ioremap_resource(arg3, id); ++ e1 = devm_platform_ioremap_resource(arg1, arg2); + ... when != id +? id = e2 + +@r1 depends on patch && !report@ +identifier r.id; +type T; +@@ + +- T *id; + ...when != id + +@r2 depends on report && !patch@ +identifier id; +expression e1, e2, arg1, arg2, arg3; +position j0; +@@ + +( + id = platform_get_resource(arg1, IORESOURCE_MEM, arg2); +| + struct resource *id = platform_get_resource(arg1, IORESOURCE_MEM, arg2); +) + ... when != id + e1@j0 = devm_ioremap_resource(arg3, id); + ... when != id +? id = e2 + +@script:python depends on report && !patch@ +e1 << r2.e1; +j0 << r2.j0; +@@ + +msg = "WARNING: Use devm_platform_ioremap_resource for %s" % (e1) +coccilib.report.print_report(j0[0], msg) -- cgit v1.2.3 From 7e13191879d6d589cd987a8db3a70019251fc757 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Wed, 17 Jul 2019 15:17:49 +0900 Subject: kbuild: do not create empty modules.order in the prepare stage Currently, $(objtree)/modules.order is touched in two places. In the 'prepare0' rule, scripts/Makefile.build creates an empty modules.order while processing 'obj=.' In the 'modules' rule, the top-level Makefile overwrites it with the correct list of modules. While this might be a good side-effect that modules.order is made empty every time (probably this is not intended functionality), I personally do not like this behavior. Create modules.order only when it is sensible to do so. This avoids creating the following pointless files: scripts/basic/modules.order scripts/dtc/modules.order scripts/gcc-plugins/modules.order scripts/genksyms/modules.order scripts/mod/modules.order scripts/modules.order scripts/selinux/genheaders/modules.order scripts/selinux/mdp/modules.order scripts/selinux/modules.order Going forward, $(objtree)/modules.order lists the modules that was built in the last successful build. Signed-off-by: Masahiro Yamada --- Makefile | 4 ++-- scripts/Makefile.build | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) (limited to 'scripts') diff --git a/Makefile b/Makefile index e43285786102..b74a6e9cefc8 100644 --- a/Makefile +++ b/Makefile @@ -1072,7 +1072,7 @@ $(sort $(vmlinux-deps)): $(vmlinux-dirs) ; PHONY += $(vmlinux-dirs) $(vmlinux-dirs): prepare - $(Q)$(MAKE) $(build)=$@ need-builtin=1 + $(Q)$(MAKE) $(build)=$@ need-builtin=1 need-modorder=1 filechk_kernel.release = \ echo "$(KERNELVERSION)$$($(CONFIG_SHELL) $(srctree)/scripts/setlocalversion $(srctree))" @@ -1616,7 +1616,7 @@ $(objtree)/Module.symvers: module-dirs := $(addprefix _module_,$(KBUILD_EXTMOD)) PHONY += $(module-dirs) modules $(module-dirs): prepare $(objtree)/Module.symvers - $(Q)$(MAKE) $(build)=$(patsubst _module_%,%,$@) + $(Q)$(MAKE) $(build)=$(patsubst _module_%,%,$@) need-modorder=1 modules: $(module-dirs) @$(kecho) ' Building modules, stage 2.'; diff --git a/scripts/Makefile.build b/scripts/Makefile.build index 5829ccbc7dd0..631bb89524de 100644 --- a/scripts/Makefile.build +++ b/scripts/Makefile.build @@ -63,7 +63,7 @@ ifneq ($(strip $(real-obj-y) $(need-builtin)),) builtin-target := $(obj)/built-in.a endif -ifdef CONFIG_MODULES +ifeq ($(CONFIG_MODULES)$(need-modorder),y1) modorder-target := $(obj)/modules.order endif -- cgit v1.2.3 From 1bd9a468018dd318283c7c620729ddf1923f2024 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Wed, 17 Jul 2019 15:17:50 +0900 Subject: kbuild: get rid of kernel/ prefix from in-tree modules.{order,builtin} Removing the 'kernel/' prefix will make our life easier because we can simply do 'cat modules.order' to get all built modules with full paths. Currently, we parse the first line of '*.mod' files in $(MODVERDIR). Since we have duplicated functionality here, I plan to remove MODVERDIR entirely. In fact, modules.order is generated also for external modules in a broken format. It adds the 'kernel/' prefix to the absolute path of the module, like this: kernel//path/to/your/external/module/foo.ko This is fine for now since modules.order is not used for external modules. However, I want to sanitize the format everywhere towards the goal of removing MODVERDIR. We cannot change the format of installed module.{order,builtin}. So, 'make modules_install' will add the 'kernel/' prefix while copying them to $(MODLIB)/. Signed-off-by: Masahiro Yamada --- Makefile | 4 ++-- scripts/Makefile.build | 2 +- scripts/Makefile.modbuiltin | 2 +- scripts/modules-check.sh | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) (limited to 'scripts') diff --git a/Makefile b/Makefile index b74a6e9cefc8..396cd5e525d1 100644 --- a/Makefile +++ b/Makefile @@ -1329,8 +1329,8 @@ _modinst_: rm -f $(MODLIB)/build ; \ ln -s $(CURDIR) $(MODLIB)/build ; \ fi - @cp -f $(objtree)/modules.order $(MODLIB)/ - @cp -f $(objtree)/modules.builtin $(MODLIB)/ + @sed 's:^:kernel/:' modules.order > $(MODLIB)/modules.order + @sed 's:^:kernel/:' modules.builtin > $(MODLIB)/modules.builtin @cp -f $(objtree)/modules.builtin.modinfo $(MODLIB)/ $(Q)$(MAKE) -f $(srctree)/scripts/Makefile.modinst diff --git a/scripts/Makefile.build b/scripts/Makefile.build index 631bb89524de..10e92a27ec20 100644 --- a/scripts/Makefile.build +++ b/scripts/Makefile.build @@ -426,7 +426,7 @@ endif # builtin-target modorder-cmds = \ $(foreach m, $(modorder), \ $(if $(filter %/modules.order, $m), \ - cat $m;, echo kernel/$m;)) + cat $m;, echo $m;)) $(modorder-target): $(subdir-ym) FORCE $(Q)(cat /dev/null; $(modorder-cmds)) > $@ diff --git a/scripts/Makefile.modbuiltin b/scripts/Makefile.modbuiltin index 50a9990760f3..7d4711b88656 100644 --- a/scripts/Makefile.modbuiltin +++ b/scripts/Makefile.modbuiltin @@ -40,7 +40,7 @@ __modbuiltin: $(modbuiltin-target) $(subdir-ym) @: $(modbuiltin-target): $(subdir-ym) FORCE - $(Q)(for m in $(modbuiltin-mods); do echo kernel/$$m; done; \ + $(Q)(for m in $(modbuiltin-mods); do echo $$m; done; \ cat /dev/null $(modbuiltin-subdirs)) > $@ PHONY += FORCE diff --git a/scripts/modules-check.sh b/scripts/modules-check.sh index 39e8cb36ba19..f51f446707b8 100755 --- a/scripts/modules-check.sh +++ b/scripts/modules-check.sh @@ -9,7 +9,7 @@ check_same_name_modules() for m in $(sed 's:.*/::' modules.order | sort | uniq -d) do echo "warning: same module names found:" >&2 - sed -n "/\/$m/s:^kernel/: :p" modules.order >&2 + sed -n "/\/$m/s:^: :p" modules.order >&2 done } -- cgit v1.2.3 From e0e1b1ec397e153da10f90355545607d2fd13293 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Wed, 17 Jul 2019 15:17:51 +0900 Subject: kbuild: remove duplication from modules.order in sub-directories Currently, only the top-level modules.order drops duplicated entries. The modules.order files in sub-directories potentially contain duplication. To list out the paths of all modules, I want to use modules.order instead of parsing *.mod files in $(MODVERDIR). To achieve this, I want to rip off duplication from modules.order of external modules too. Signed-off-by: Masahiro Yamada --- scripts/Makefile.build | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) (limited to 'scripts') diff --git a/scripts/Makefile.build b/scripts/Makefile.build index 10e92a27ec20..be32a3752de4 100644 --- a/scripts/Makefile.build +++ b/scripts/Makefile.build @@ -423,13 +423,10 @@ endif # builtin-target # # Create commands to either record .ko file or cat modules.order from # a subdirectory -modorder-cmds = \ - $(foreach m, $(modorder), \ - $(if $(filter %/modules.order, $m), \ - cat $m;, echo $m;)) - $(modorder-target): $(subdir-ym) FORCE - $(Q)(cat /dev/null; $(modorder-cmds)) > $@ + $(Q){ $(foreach m, $(modorder), \ + $(if $(filter %/modules.order, $m), cat $m, echo $m);) :; } \ + | $(AWK) '!x[$$0]++' - > $@ # # Rule to compile a set of .o files into one .a file (with symbol table) -- cgit v1.2.3 From d56aec102c0c462b94513421726e33938695cef4 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Wed, 17 Jul 2019 15:17:53 +0900 Subject: kbuild: modinst: read modules.order instead of $(MODVERDIR)/*.mod Towards the goal of removing MODVERDIR, read out modules.order to get the list of modules to be installed. This is simpler than parsing *.mod files in $(MODVERDIR). For external modules, $(KBUILD_EXTMOD)/modules.order should be read. Signed-off-by: Masahiro Yamada --- scripts/Makefile.modinst | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) (limited to 'scripts') diff --git a/scripts/Makefile.modinst b/scripts/Makefile.modinst index 0dae402661f3..5a4579e76485 100644 --- a/scripts/Makefile.modinst +++ b/scripts/Makefile.modinst @@ -8,10 +8,7 @@ __modinst: include scripts/Kbuild.include -# - -__modules := $(sort $(shell grep -h '\.ko$$' /dev/null $(wildcard $(MODVERDIR)/*.mod))) -modules := $(patsubst %.o,%.ko,$(wildcard $(__modules:.ko=.o))) +modules := $(sort $(shell cat $(if $(KBUILD_EXTMOD),$(KBUILD_EXTMOD)/)modules.order)) PHONY += $(modules) __modinst: $(modules) -- cgit v1.2.3 From c35c87d6f258ad943d0fb350ed45fa9302c36b52 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Wed, 17 Jul 2019 15:17:54 +0900 Subject: kbuild: modsign: read modules.order instead of $(MODVERDIR)/*.mod Towards the goal of removing MODVERDIR, read out modules.order to get the list of modules to be signed. This is simpler than parsing *.mod files in $(MODVERDIR). The modules_sign target is only supported for in-kernel modules. So, this commit does not take care of external modules. Signed-off-by: Masahiro Yamada --- scripts/Makefile.modsign | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/Makefile.modsign b/scripts/Makefile.modsign index da56aa78d245..d7325cefe709 100644 --- a/scripts/Makefile.modsign +++ b/scripts/Makefile.modsign @@ -8,8 +8,7 @@ __modsign: include scripts/Kbuild.include -__modules := $(sort $(shell grep -h '\.ko$$' /dev/null $(wildcard $(MODVERDIR)/*.mod))) -modules := $(patsubst %.o,%.ko,$(wildcard $(__modules:.ko=.o))) +modules := $(sort $(shell cat modules.order)) PHONY += $(modules) __modsign: $(modules) -- cgit v1.2.3 From ff9b45c55b2659d14420424da0ce4e8aa3dbce28 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Wed, 17 Jul 2019 15:17:55 +0900 Subject: kbuild: modpost: read modules.order instead of $(MODVERDIR)/*.mod Towards the goal of removing MODVERDIR, read out modules.order to get the list of modules to be processed. This is simpler than parsing *.mod files in $(MODVERDIR). For external modules, $(KBUILD_EXTMOD)/modules.order should be read. I removed the single target %.ko from the top Makefile. To make sure modpost works correctly, vmlinux and the other modules must be built. You cannot build a particular .ko file alone. Signed-off-by: Masahiro Yamada --- Makefile | 2 -- scripts/Makefile.modpost | 15 +++++++++------ 2 files changed, 9 insertions(+), 8 deletions(-) (limited to 'scripts') diff --git a/Makefile b/Makefile index 396cd5e525d1..d9103e731187 100644 --- a/Makefile +++ b/Makefile @@ -1772,8 +1772,6 @@ build-dir = $(patsubst %/,%,$(dir $(build-target))) $(Q)$(MAKE) $(build)=$(build-dir) $(build-target) %.symtypes: prepare FORCE $(Q)$(MAKE) $(build)=$(build-dir) $(build-target) -%.ko: %.o - $(Q)$(MAKE) -f $(srctree)/scripts/Makefile.modpost # Modules PHONY += / diff --git a/scripts/Makefile.modpost b/scripts/Makefile.modpost index fec6ec2ffa47..5841508ffca9 100644 --- a/scripts/Makefile.modpost +++ b/scripts/Makefile.modpost @@ -8,9 +8,10 @@ # b) A .o file which is the .o files above linked together # c) A .mod file in $(MODVERDIR)/, listing the name of the # the preliminary .o file, plus all .o files +# d) modules.order, which lists all the modules # Stage 2 is handled by this file and does the following -# 1) Find all modules from the files listed in $(MODVERDIR)/ +# 1) Find all modules listed in modules.order # 2) modpost is then used to # 3) create one .mod.c file pr. module # 4) create one Module.symvers file with CRC for all exported symbols @@ -60,10 +61,12 @@ include scripts/Makefile.lib kernelsymfile := $(objtree)/Module.symvers modulesymfile := $(firstword $(KBUILD_EXTMOD))/Module.symvers -# Step 1), find all modules listed in $(MODVERDIR)/ -MODLISTCMD := find $(MODVERDIR) -name '*.mod' | xargs -r grep -h '\.ko$$' | sort -u -__modules := $(shell $(MODLISTCMD)) -modules := $(patsubst %.o,%.ko, $(wildcard $(__modules:.ko=.o))) +modorder := $(if $(KBUILD_EXTMOD),$(KBUILD_EXTMOD)/)modules.order + +# Step 1), find all modules listed in modules.order +ifdef CONFIG_MODULES +modules := $(sort $(shell cat $(modorder))) +endif # Stop after building .o files if NOFINAL is set. Makes compile tests quicker _modpost: $(if $(KBUILD_MODPOST_NOFINAL), $(modules:.ko:.o),$(modules)) @@ -84,7 +87,7 @@ MODPOST_OPT=$(subst -i,-n,$(filter -i,$(MAKEFLAGS))) # We can go over command line length here, so be careful. quiet_cmd_modpost = MODPOST $(words $(filter-out vmlinux FORCE, $^)) modules - cmd_modpost = $(MODLISTCMD) | sed 's/\.ko$$/.o/' | $(modpost) $(MODPOST_OPT) -s -T - + cmd_modpost = sed 's/ko$$/o/' $(modorder) | $(modpost) $(MODPOST_OPT) -s -T - PHONY += __modpost __modpost: $(modules:.ko=.o) FORCE -- cgit v1.2.3 From 7deb55f57159f9de696ef8d5e93b201a6aba871c Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Wed, 17 Jul 2019 15:17:56 +0900 Subject: kbuild: export_report: read modules.order instead of .tmp_versions/*.mod Towards the goal of removing MODVERDIR aka .tmp_versions, read out modules.order to get the list of modules to be processed. This is simpler than parsing *.mod files in .tmp_versions. Signed-off-by: Masahiro Yamada --- scripts/export_report.pl | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) (limited to 'scripts') diff --git a/scripts/export_report.pl b/scripts/export_report.pl index 0f604f62f067..7d3030d03a25 100755 --- a/scripts/export_report.pl +++ b/scripts/export_report.pl @@ -52,13 +52,12 @@ sub usage { sub collectcfiles { my @file; - while (<.tmp_versions/*.mod>) { - open my $fh, '<', $_ or die "cannot open $_: $!\n"; - push (@file, - grep s/\.ko/.mod.c/, # change the suffix - grep m/.+\.ko/, # find the .ko path - <$fh>); # lines in opened file + open my $fh, '< modules.order' or die "cannot open modules.order: $!\n"; + while (<$fh>) { + s/\.ko$/.mod.c/; + push (@file, $_) } + close($fh); chomp @file; return @file; } -- cgit v1.2.3 From b7dca6dd1e591ad19a9aae716f3898be8063f880 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Wed, 17 Jul 2019 15:17:57 +0900 Subject: kbuild: create *.mod with full directory path and remove MODVERDIR While descending directories, Kbuild produces objects for modules, but do not link final *.ko files; it is done in the modpost. To keep track of modules, Kbuild creates a *.mod file in $(MODVERDIR) for every module it is building. Some post-processing steps read the necessary information from *.mod files. This avoids descending into directories again. This mechanism was introduced in 2003 or so. Later, commit 551559e13af1 ("kbuild: implement modules.order") added modules.order. So, we can simply read it out to know all the modules with directory paths. This is easier than parsing the first line of *.mod files. $(MODVERDIR) has a flat directory structure, that is, *.mod files are named only with base names. This is based on the assumption that the module name is unique across the tree. This assumption is really fragile. Stephen Rothwell reported a race condition caused by a module name conflict: https://lkml.org/lkml/2019/5/13/991 In parallel building, two different threads could write to the same $(MODVERDIR)/*.mod simultaneously. Non-unique module names are the source of all kind of troubles, hence commit 3a48a91901c5 ("kbuild: check uniqueness of module names") introduced a new checker script. However, it is still fragile in the build system point of view because this race happens before scripts/modules-check.sh is invoked. If it happens again, the modpost will emit unclear error messages. To fix this issue completely, create *.mod with full directory path so that two threads never attempt to write to the same file. $(MODVERDIR) is no longer needed. Since modules with directory paths are listed in modules.order, Kbuild is still able to find *.mod files without additional descending. I also killed cmd_secanalysis; scripts/mod/sumversion.c computes MD4 hash for modules with MODULE_VERSION(). When CONFIG_DEBUG_SECTION_MISMATCH=y, it occurs not only in the modpost stage, but also during directory descending, where sumversion.c may parse stale *.mod files. It would emit 'No such file or directory' warning when an object consisting a module is renamed, or when a single-obj module is turned into a multi-obj module or vice versa. Signed-off-by: Masahiro Yamada Acked-by: Nicolas Pitre --- .gitignore | 1 + Documentation/dontdiff | 1 + Makefile | 20 +++----------------- lib/Kconfig.debug | 12 +----------- scripts/Makefile.build | 15 +++------------ scripts/Makefile.modpost | 4 ++-- scripts/adjust_autoksyms.sh | 14 +++++--------- scripts/mod/sumversion.c | 16 +++------------- scripts/package/mkspec | 2 +- tools/power/cpupower/debug/kernel/Makefile | 4 ++-- 10 files changed, 22 insertions(+), 67 deletions(-) (limited to 'scripts') diff --git a/.gitignore b/.gitignore index 7587ef56b92d..8f5422cba6e2 100644 --- a/.gitignore +++ b/.gitignore @@ -30,6 +30,7 @@ *.lz4 *.lzma *.lzo +*.mod *.mod.c *.o *.o.* diff --git a/Documentation/dontdiff b/Documentation/dontdiff index 5eba889ea84d..9f4392876099 100644 --- a/Documentation/dontdiff +++ b/Documentation/dontdiff @@ -30,6 +30,7 @@ *.lzo *.mo *.moc +*.mod *.mod.c *.o *.o.* diff --git a/Makefile b/Makefile index d9103e731187..6308c8cea121 100644 --- a/Makefile +++ b/Makefile @@ -486,11 +486,6 @@ export KBUILD_AFLAGS_MODULE KBUILD_CFLAGS_MODULE KBUILD_LDFLAGS_MODULE export KBUILD_AFLAGS_KERNEL KBUILD_CFLAGS_KERNEL export KBUILD_ARFLAGS -# When compiling out-of-tree modules, put MODVERDIR in the module -# tree rather than in the kernel tree. The kernel tree might -# even be read-only. -export MODVERDIR := $(if $(KBUILD_EXTMOD),$(firstword $(KBUILD_EXTMOD))/).tmp_versions - # Files to ignore in find ... statements export RCS_FIND_IGNORE := \( -name SCCS -o -name BitKeeper -o -name .svn -o \ @@ -1029,8 +1024,8 @@ vmlinux-deps := $(KBUILD_LDS) $(KBUILD_VMLINUX_OBJS) $(KBUILD_VMLINUX_LIBS) # Recurse until adjust_autoksyms.sh is satisfied PHONY += autoksyms_recursive -autoksyms_recursive: $(vmlinux-deps) ifdef CONFIG_TRIM_UNUSED_KSYMS +autoksyms_recursive: $(vmlinux-deps) modules.order $(Q)$(CONFIG_SHELL) $(srctree)/scripts/adjust_autoksyms.sh \ "$(MAKE) -f $(srctree)/Makefile vmlinux" endif @@ -1113,7 +1108,6 @@ endif prepare1: prepare3 outputmakefile asm-generic $(version_h) $(autoksyms_h) \ include/generated/utsrelease.h - $(cmd_crmodverdir) archprepare: archheaders archscripts prepare1 scripts @@ -1371,7 +1365,7 @@ endif # CONFIG_MODULES # make distclean Remove editor backup files, patch leftover files and the like # Directories & files removed with 'make clean' -CLEAN_DIRS += $(MODVERDIR) include/ksym +CLEAN_DIRS += include/ksym CLEAN_FILES += modules.builtin.modinfo # Directories & files removed with 'make mrproper' @@ -1641,7 +1635,6 @@ PHONY += $(clean-dirs) clean $(clean-dirs): $(Q)$(MAKE) $(clean)=$(patsubst _clean_%,%,$@) -clean: rm-dirs := $(MODVERDIR) clean: rm-files := $(KBUILD_EXTMOD)/Module.symvers PHONY += help @@ -1655,8 +1648,6 @@ help: @echo '' PHONY += prepare -prepare: - $(cmd_crmodverdir) endif # KBUILD_EXTMOD clean: $(clean-dirs) @@ -1667,7 +1658,7 @@ clean: $(clean-dirs) -o -name '*.ko.*' \ -o -name '*.dtb' -o -name '*.dtb.S' -o -name '*.dt.yaml' \ -o -name '*.dwo' -o -name '*.lst' \ - -o -name '*.su' \ + -o -name '*.su' -o -name '*.mod' \ -o -name '.*.d' -o -name '.*.tmp' -o -name '*.mod.c' \ -o -name '*.lex.c' -o -name '*.tab.[ch]' \ -o -name '*.asn1.[ch]' \ @@ -1794,11 +1785,6 @@ quiet_cmd_depmod = DEPMOD $(KERNELRELEASE) cmd_depmod = $(CONFIG_SHELL) $(srctree)/scripts/depmod.sh $(DEPMOD) \ $(KERNELRELEASE) -# Create temporary dir for module support files -# clean it up only when building all modules -cmd_crmodverdir = $(Q)mkdir -p $(MODVERDIR) \ - $(if $(KBUILD_MODULES),; rm -f $(MODVERDIR)/*) - # read saved command lines for existing targets existing-targets := $(wildcard $(sort $(targets))) diff --git a/lib/Kconfig.debug b/lib/Kconfig.debug index 4ac4ca21a30a..cde5675340ba 100644 --- a/lib/Kconfig.debug +++ b/lib/Kconfig.debug @@ -353,23 +353,13 @@ config DEBUG_SECTION_MISMATCH which results in the code/data being placed in specific sections. The section mismatch analysis is always performed after a full kernel build, and enabling this option causes the following - additional steps to occur: + additional step to occur: - Add the option -fno-inline-functions-called-once to gcc commands. When inlining a function annotated with __init in a non-init function, we would lose the section information and thus the analysis would not catch the illegal reference. This option tells gcc to inline less (but it does result in a larger kernel). - - Run the section mismatch analysis for each module/built-in.a file. - When we run the section mismatch analysis on vmlinux.o, we - lose valuable information about where the mismatch was - introduced. - Running the analysis for each module/built-in.a file - tells where the mismatch happens much closer to the - source. The drawback is that the same mismatch is - reported at least twice. - - Enable verbose reporting from modpost in order to help resolve - the section mismatches that are reported. config SECTION_MISMATCH_WARN_ONLY bool "Make section mismatch errors non-fatal" diff --git a/scripts/Makefile.build b/scripts/Makefile.build index be32a3752de4..c6dfcc028f56 100644 --- a/scripts/Makefile.build +++ b/scripts/Makefile.build @@ -67,8 +67,6 @@ ifeq ($(CONFIG_MODULES)$(need-modorder),y1) modorder-target := $(obj)/modules.order endif -# We keep a list of all modules in $(MODVERDIR) - __build: $(if $(KBUILD_BUILTIN),$(builtin-target) $(lib-target) $(extra-y)) \ $(if $(KBUILD_MODULES),$(obj-m) $(modorder-target)) \ $(subdir-ym) $(always) @@ -87,11 +85,6 @@ ifneq ($(KBUILD_ENABLE_EXTRA_GCC_CHECKS),) cmd_checkdoc = $(srctree)/scripts/kernel-doc -none $< endif -# Do section mismatch analysis for each module/built-in.a -ifdef CONFIG_DEBUG_SECTION_MISMATCH - cmd_secanalysis = ; scripts/mod/modpost $@ -endif - # Compile C sources (.c) # --------------------------------------------------------------------------- @@ -278,13 +271,11 @@ $(obj)/%.o: $(src)/%.c $(recordmcount_source) $(objtool_dep) FORCE $(call cmd,force_checksrc) $(call if_changed_rule,cc_o_c) -# Single-part modules are special since we need to mark them in $(MODVERDIR) - $(single-used-m): $(obj)/%.o: $(src)/%.c $(recordmcount_source) $(objtool_dep) FORCE $(call cmd,force_checksrc) $(call if_changed_rule,cc_o_c) @{ echo $(@:.o=.ko); echo $@; \ - $(cmd_undef_syms); } > $(MODVERDIR)/$(@F:.o=.mod) + $(cmd_undef_syms); } > $(patsubst %.o,%.mod,$@) quiet_cmd_cc_lst_c = MKLST $@ cmd_cc_lst_c = $(CC) $(c_flags) -g -c -o $*.o $< && \ @@ -461,12 +452,12 @@ endif # module is turned into a multi object module, $^ will contain header file # dependencies recorded in the .*.cmd file. quiet_cmd_link_multi-m = LD [M] $@ -cmd_link_multi-m = $(LD) $(ld_flags) -r -o $@ $(filter %.o,$^) $(cmd_secanalysis) + cmd_link_multi-m = $(LD) $(ld_flags) -r -o $@ $(filter %.o,$^) $(multi-used-m): FORCE $(call if_changed,link_multi-m) @{ echo $(@:.o=.ko); echo $(filter %.o,$^); \ - $(cmd_undef_syms); } > $(MODVERDIR)/$(@F:.o=.mod) + $(cmd_undef_syms); } > $(patsubst %.o,%.mod,$@) $(call multi_depend, $(multi-used-m), .o, -objs -y -m) targets += $(multi-used-m) diff --git a/scripts/Makefile.modpost b/scripts/Makefile.modpost index 5841508ffca9..6b19c1a4eae5 100644 --- a/scripts/Makefile.modpost +++ b/scripts/Makefile.modpost @@ -6,8 +6,8 @@ # Stage one of module building created the following: # a) The individual .o files used for the module # b) A .o file which is the .o files above linked together -# c) A .mod file in $(MODVERDIR)/, listing the name of the -# the preliminary .o file, plus all .o files +# c) A .mod file, listing the name of the preliminary .o file, +# plus all .o files # d) modules.order, which lists all the modules # Stage 2 is handled by this file and does the following diff --git a/scripts/adjust_autoksyms.sh b/scripts/adjust_autoksyms.sh index aab4e299d7a2..2e4a7320bfb4 100755 --- a/scripts/adjust_autoksyms.sh +++ b/scripts/adjust_autoksyms.sh @@ -8,8 +8,7 @@ # # Create/update the include/generated/autoksyms.h file from the list -# of all module's needed symbols as recorded on the third line of -# .tmp_versions/*.mod files. +# of all module's needed symbols as recorded on the third line of *.mod files. # # For each symbol being added or removed, the corresponding dependency # file's timestamp is updated to force a rebuild of the affected source @@ -47,13 +46,10 @@ cat > "$new_ksyms_file" << EOT */ EOT -[ "$(ls -A "$MODVERDIR")" ] && -for mod in "$MODVERDIR"/*.mod; do - sed -n -e '3{s/ /\n/g;/^$/!p;}' "$mod" -done | sort -u | -while read sym; do - echo "#define __KSYM_${sym} 1" -done >> "$new_ksyms_file" +sed 's/ko$/mod/' modules.order | +xargs -n1 sed -n -e '3{s/ /\n/g;/^$/!p;}' -- | +sort -u | +sed -e 's/\(.*\)/#define __KSYM_\1 1/' >> "$new_ksyms_file" # Special case for modversions (see modpost.c) if [ -n "$CONFIG_MODVERSIONS" ]; then diff --git a/scripts/mod/sumversion.c b/scripts/mod/sumversion.c index 0f6dcb4011a8..166f3fa247a9 100644 --- a/scripts/mod/sumversion.c +++ b/scripts/mod/sumversion.c @@ -396,21 +396,11 @@ void get_src_version(const char *modname, char sum[], unsigned sumlen) unsigned long len; struct md4_ctx md; char *sources, *end, *fname; - const char *basename; char filelist[PATH_MAX + 1]; - char *modverdir = getenv("MODVERDIR"); - if (!modverdir) - modverdir = "."; - - /* Source files for module are in .tmp_versions/modname.mod, - after the first line. */ - if (strrchr(modname, '/')) - basename = strrchr(modname, '/') + 1; - else - basename = modname; - snprintf(filelist, sizeof(filelist), "%s/%.*s.mod", modverdir, - (int) strlen(basename) - 2, basename); + /* objects for a module are listed in the second line of *.mod file. */ + snprintf(filelist, sizeof(filelist), "%.*smod", + (int)strlen(modname) - 1, modname); file = grab_file(filelist, &len); if (!file) diff --git a/scripts/package/mkspec b/scripts/package/mkspec index 2d29df4a0a53..8640c278f1aa 100755 --- a/scripts/package/mkspec +++ b/scripts/package/mkspec @@ -29,7 +29,7 @@ fi PROVIDES="$PROVIDES kernel-$KERNELRELEASE" __KERNELRELEASE=$(echo $KERNELRELEASE | sed -e "s/-/_/g") -EXCLUDES="$RCS_TAR_IGNORE --exclude=.tmp_versions --exclude=*vmlinux* \ +EXCLUDES="$RCS_TAR_IGNORE --exclude=*vmlinux* --exclude=*.mod \ --exclude=*.o --exclude=*.ko --exclude=*.cmd --exclude=Documentation \ --exclude=.config.old --exclude=.missing-syscalls.d --exclude=*.s" diff --git a/tools/power/cpupower/debug/kernel/Makefile b/tools/power/cpupower/debug/kernel/Makefile index c23e5a6ceb7e..7b5c43684be1 100644 --- a/tools/power/cpupower/debug/kernel/Makefile +++ b/tools/power/cpupower/debug/kernel/Makefile @@ -12,8 +12,8 @@ default: $(MAKE) -C $(KDIR) M=$(CURDIR) clean: - - rm -rf *.o *.ko .tmp-versions .*.cmd .*.mod.* *.mod.c - - rm -rf .tmp_versions* Module.symvers modules.order + - rm -rf *.o *.ko .*.cmd .*.mod.* *.mod.c + - rm -rf Module.symvers modules.order install: default install -d $(KMISC) -- cgit v1.2.3 From 60ae1b194b4548102fea0f5091af83b478f2352b Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Wed, 17 Jul 2019 15:17:58 +0900 Subject: kbuild: remove the first line of *.mod files The current format of *.mod is like this: line 1: directory path to the .ko file line 2: a list of objects linked into this module line 3: unresolved symbols (only when CONFIG_TRIM_UNUSED_KSYMS=y) Now that *.mod and *.ko are created in the same directory, the line 1 provides no valuable information. It can be derived by replacing the extension .mod with .ko. In fact, nobody uses the first line any more. Cut down the first line. Signed-off-by: Masahiro Yamada --- scripts/Makefile.build | 4 ++-- scripts/adjust_autoksyms.sh | 4 ++-- scripts/mod/sumversion.c | 9 ++------- 3 files changed, 6 insertions(+), 11 deletions(-) (limited to 'scripts') diff --git a/scripts/Makefile.build b/scripts/Makefile.build index c6dfcc028f56..9f37f203882f 100644 --- a/scripts/Makefile.build +++ b/scripts/Makefile.build @@ -274,7 +274,7 @@ $(obj)/%.o: $(src)/%.c $(recordmcount_source) $(objtool_dep) FORCE $(single-used-m): $(obj)/%.o: $(src)/%.c $(recordmcount_source) $(objtool_dep) FORCE $(call cmd,force_checksrc) $(call if_changed_rule,cc_o_c) - @{ echo $(@:.o=.ko); echo $@; \ + @{ echo $@; \ $(cmd_undef_syms); } > $(patsubst %.o,%.mod,$@) quiet_cmd_cc_lst_c = MKLST $@ @@ -456,7 +456,7 @@ quiet_cmd_link_multi-m = LD [M] $@ $(multi-used-m): FORCE $(call if_changed,link_multi-m) - @{ echo $(@:.o=.ko); echo $(filter %.o,$^); \ + @{ echo $(filter %.o,$^); \ $(cmd_undef_syms); } > $(patsubst %.o,%.mod,$@) $(call multi_depend, $(multi-used-m), .o, -objs -y -m) diff --git a/scripts/adjust_autoksyms.sh b/scripts/adjust_autoksyms.sh index 2e4a7320bfb4..a904bf1f5e67 100755 --- a/scripts/adjust_autoksyms.sh +++ b/scripts/adjust_autoksyms.sh @@ -8,7 +8,7 @@ # # Create/update the include/generated/autoksyms.h file from the list -# of all module's needed symbols as recorded on the third line of *.mod files. +# of all module's needed symbols as recorded on the second line of *.mod files. # # For each symbol being added or removed, the corresponding dependency # file's timestamp is updated to force a rebuild of the affected source @@ -47,7 +47,7 @@ cat > "$new_ksyms_file" << EOT EOT sed 's/ko$/mod/' modules.order | -xargs -n1 sed -n -e '3{s/ /\n/g;/^$/!p;}' -- | +xargs -n1 sed -n -e '2{s/ /\n/g;/^$/!p;}' -- | sort -u | sed -e 's/\(.*\)/#define __KSYM_\1 1/' >> "$new_ksyms_file" diff --git a/scripts/mod/sumversion.c b/scripts/mod/sumversion.c index 166f3fa247a9..63062024ce0e 100644 --- a/scripts/mod/sumversion.c +++ b/scripts/mod/sumversion.c @@ -398,7 +398,7 @@ void get_src_version(const char *modname, char sum[], unsigned sumlen) char *sources, *end, *fname; char filelist[PATH_MAX + 1]; - /* objects for a module are listed in the second line of *.mod file. */ + /* objects for a module are listed in the first line of *.mod file. */ snprintf(filelist, sizeof(filelist), "%.*smod", (int)strlen(modname) - 1, modname); @@ -407,13 +407,8 @@ void get_src_version(const char *modname, char sum[], unsigned sumlen) /* not a module or .mod file missing - ignore */ return; - sources = strchr(file, '\n'); - if (!sources) { - warn("malformed versions file for %s\n", modname); - goto release; - } + sources = file; - sources++; end = strchr(sources, '\n'); if (!end) { warn("bad ending versions file for %s\n", modname); -- cgit v1.2.3 From 9f69a496f1001bd27c484da43da30b2cdc8e06ed Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Wed, 17 Jul 2019 15:18:00 +0900 Subject: kbuild: split out *.mod out of {single,multi}-used-m rules Currently, *.mod is created as a side-effect of obj-m. Split out *.mod as a dedicated build rule, which allows to unify the %.c -> %.o rule, and remove the single-used-m rule. This also makes the incremental build of allmodconfig faster because it saves $(NM) invocation when there is no change in the module. Signed-off-by: Masahiro Yamada --- scripts/Makefile.build | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) (limited to 'scripts') diff --git a/scripts/Makefile.build b/scripts/Makefile.build index 9f37f203882f..0d434d0afc0b 100644 --- a/scripts/Makefile.build +++ b/scripts/Makefile.build @@ -67,8 +67,10 @@ ifeq ($(CONFIG_MODULES)$(need-modorder),y1) modorder-target := $(obj)/modules.order endif +mod-targets := $(patsubst %.o, %.mod, $(obj-m)) + __build: $(if $(KBUILD_BUILTIN),$(builtin-target) $(lib-target) $(extra-y)) \ - $(if $(KBUILD_MODULES),$(obj-m) $(modorder-target)) \ + $(if $(KBUILD_MODULES),$(obj-m) $(mod-targets) $(modorder-target)) \ $(subdir-ym) $(always) @: @@ -261,7 +263,7 @@ endef # List module undefined symbols (or empty line if not enabled) ifdef CONFIG_TRIM_UNUSED_KSYMS -cmd_undef_syms = $(NM) $@ | sed -n 's/^ *U //p' | xargs echo +cmd_undef_syms = $(NM) $< | sed -n 's/^ *U //p' | xargs echo else cmd_undef_syms = echo endif @@ -271,11 +273,15 @@ $(obj)/%.o: $(src)/%.c $(recordmcount_source) $(objtool_dep) FORCE $(call cmd,force_checksrc) $(call if_changed_rule,cc_o_c) -$(single-used-m): $(obj)/%.o: $(src)/%.c $(recordmcount_source) $(objtool_dep) FORCE - $(call cmd,force_checksrc) - $(call if_changed_rule,cc_o_c) - @{ echo $@; \ - $(cmd_undef_syms); } > $(patsubst %.o,%.mod,$@) +cmd_mod = { \ + echo $(if $($*-objs)$($*-y)$($*-m), $(addprefix $(obj)/, $($*-objs) $($*-y) $($*-m)), $(@:.mod=.o)); \ + $(cmd_undef_syms); \ + } > $@ + +$(obj)/%.mod: $(obj)/%.o FORCE + $(call if_changed,mod) + +targets += $(mod-targets) quiet_cmd_cc_lst_c = MKLST $@ cmd_cc_lst_c = $(CC) $(c_flags) -g -c -o $*.o $< && \ @@ -456,8 +462,6 @@ quiet_cmd_link_multi-m = LD [M] $@ $(multi-used-m): FORCE $(call if_changed,link_multi-m) - @{ echo $(filter %.o,$^); \ - $(cmd_undef_syms); } > $(patsubst %.o,%.mod,$@) $(call multi_depend, $(multi-used-m), .o, -objs -y -m) targets += $(multi-used-m) -- cgit v1.2.3 From b2eff0921805935132bc308d3c769ef2efb321ad Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Tue, 23 Jul 2019 13:11:26 +0900 Subject: kbuild: remove unused objectify macro Commit 415008af3219 ("docs-rst: convert lsm from DocBook to ReST") removed the last users of this macro. Signed-off-by: Masahiro Yamada --- scripts/Kbuild.include | 3 --- 1 file changed, 3 deletions(-) (limited to 'scripts') diff --git a/scripts/Kbuild.include b/scripts/Kbuild.include index 77c742fa4fb1..4b0432e095ae 100644 --- a/scripts/Kbuild.include +++ b/scripts/Kbuild.include @@ -190,9 +190,6 @@ echo-cmd = $(if $($(quiet)cmd_$(1)),\ # printing commands cmd = @set -e; $(echo-cmd) $(cmd_$(1)) -# Add $(obj)/ for paths that are not absolute -objectify = $(foreach o,$(1),$(if $(filter /%,$(o)),$(o),$(obj)/$(o))) - ### # if_changed - execute command if any prerequisite is newer than # target, or command line has changed -- cgit v1.2.3 From cb36955a5569f1ff17a42ae93264ef391c013a97 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Sat, 27 Jul 2019 12:01:10 +0900 Subject: gen_compile_commands: lower the entry count threshold Running gen_compile_commands.py after building the kernel with allnoconfig gave this: $ ./scripts/gen_compile_commands.py WARNING: Found 449 entries. Have you compiled the kernel? Signed-off-by: Masahiro Yamada --- scripts/gen_compile_commands.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/gen_compile_commands.py b/scripts/gen_compile_commands.py index 7915823b92a5..c458696ef3a7 100755 --- a/scripts/gen_compile_commands.py +++ b/scripts/gen_compile_commands.py @@ -21,9 +21,9 @@ _LINE_PATTERN = r'^cmd_[^ ]*\.o := (.* )([^ ]*\.c)$' _VALID_LOG_LEVELS = ['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'] # A kernel build generally has over 2000 entries in its compile_commands.json -# database. If this code finds 500 or fewer, then warn the user that they might +# database. If this code finds 300 or fewer, then warn the user that they might # not have all the .cmd files, and they might need to compile the kernel. -_LOW_COUNT_THRESHOLD = 500 +_LOW_COUNT_THRESHOLD = 300 def parse_arguments(): -- cgit v1.2.3 From b25e8a23d4ea7e8ade2c349c22efe88da88c0988 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Fri, 26 Jul 2019 11:17:38 +0900 Subject: kbuild: remove unused single-used-m This is unused since commit 9f69a496f100 ("kbuild: split out *.mod out of {single,multi}-used-m rules"). Signed-off-by: Masahiro Yamada --- scripts/Makefile.lib | 2 -- 1 file changed, 2 deletions(-) (limited to 'scripts') diff --git a/scripts/Makefile.lib b/scripts/Makefile.lib index 5241d0751eb0..41c50f9461e5 100644 --- a/scripts/Makefile.lib +++ b/scripts/Makefile.lib @@ -45,7 +45,6 @@ subdir-ym := $(sort $(subdir-y) $(subdir-m)) multi-used-y := $(sort $(foreach m,$(obj-y), $(if $(strip $($(m:.o=-objs)) $($(m:.o=-y))), $(m)))) multi-used-m := $(sort $(foreach m,$(obj-m), $(if $(strip $($(m:.o=-objs)) $($(m:.o=-y)) $($(m:.o=-m))), $(m)))) multi-used := $(multi-used-y) $(multi-used-m) -single-used-m := $(sort $(filter-out $(multi-used-m),$(obj-m))) # $(subdir-obj-y) is the list of objects in $(obj-y) which uses dir/ to # tell kbuild to descend @@ -91,7 +90,6 @@ lib-y := $(addprefix $(obj)/,$(lib-y)) subdir-obj-y := $(addprefix $(obj)/,$(subdir-obj-y)) real-obj-y := $(addprefix $(obj)/,$(real-obj-y)) real-obj-m := $(addprefix $(obj)/,$(real-obj-m)) -single-used-m := $(addprefix $(obj)/,$(single-used-m)) multi-used-m := $(addprefix $(obj)/,$(multi-used-m)) subdir-ym := $(addprefix $(obj)/,$(subdir-ym)) -- cgit v1.2.3