Re: [PATCH 8/8] docs: kernel-doc: Don't mangle literal code blocks in comments

2018-02-14 Thread Jani Nikula 
On Wed, 14 Feb 2018, Jonathan Corbet  wrote:
> It can be useful to put code snippets into kerneldoc comments; that can be
> done with the "::" operator at the end of a line like this::
>
>if (desperate)
>run_in_circles();
>
> The ".. code-block::" directive can also be used to this end.  kernel-doc
> currently fails to understand these literal blocks and applies its normal
> markup to them, which is then treated as literal by sphinx.  The result is
> unsightly markup instead of a useful code snippet.
>
> Apply a hack to the output code to recognize literal blocks and avoid
> performing any special markup on them.  It's ugly, but that means it fits
> in well with the rest of the script.

With emphasis on part (d) of the reviewer's statement of oversight,

Reviewed-by: Jani Nikula 

>
> Signed-off-by: Jonathan Corbet 
> ---
>  scripts/kernel-doc | 69 
> ++
>  1 file changed, 64 insertions(+), 5 deletions(-)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index fb8fbdb25036..cbe864e72a2f 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -748,14 +748,73 @@ sub output_blockhead_rst(%) {
>  }
>  }
>  
> -sub output_highlight_rst {
> -my $contents = join "\n",@_;
> -my $line;
> -
> +#
> +# Apply the RST highlights to a sub-block of text.
> +#   
> +sub highlight_block($) {
> +# The dohighlight kludge requires the text be called $contents
> +my $contents = shift;
>  eval $dohighlight;
>  die $@ if $@;
> +return $contents;
> +}
>  
> -foreach $line (split "\n", $contents) {
> +#
> +# Regexes used only here.
> +#
> +my $sphinx_literal = '^[^.].*::$';
> +my $sphinx_cblock = '^\.\.\ +code-block::';
> +
> +sub output_highlight_rst {
> +my $input = join "\n",@_;
> +my $output = "";
> +my $line;
> +my $in_literal = 0;
> +my $litprefix;
> +my $block = "";
> +
> +foreach $line (split "\n",$input) {
> + #
> + # If we're in a literal block, see if we should drop out
> + # of it.  Otherwise pass the line straight through unmunged.
> + #
> + if ($in_literal) {
> + if (! ($line =~ /^\s*$/)) {
> + #
> + # If this is the first non-blank line in a literal
> + # block we need to figure out what the proper indent is.
> + #
> + if ($litprefix eq "") {
> + $line =~ /^(\s*)/;
> + $litprefix = '^' . $1;
> + $output .= $line . "\n";
> + } elsif (! ($line =~ /$litprefix/)) {
> + $in_literal = 0;
> + } else {
> + $output .= $line . "\n";
> + }
> + } else {
> + $output .= $line . "\n";
> + }
> + }
> + #
> + # Not in a literal block (or just dropped out)
> + #
> + if (! $in_literal) {
> + $block .= $line . "\n";
> + if (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) {
> + $in_literal = 1;
> + $litprefix = "";
> + $output .= highlight_block($block);
> + $block = ""
> + }
> + }
> +}
> +
> +if ($block) {
> + $output .= highlight_block($block);
> +}
> +foreach $line (split "\n", $output) {
>   print $lineprefix . $line . "\n";
>  }
>  }

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/8] docs: kernel-doc: Get rid of xml_escape() and friends

2018-02-14 Thread Jani Nikula 
On Wed, 14 Feb 2018, Jonathan Corbet  wrote:
> XML escaping is a worry that came with DocBook, which we no longer have any
> dealings with.  So get rid of the useless xml_escape()/xml_unescape()
> functions.  No change to the generated output.
>
> Signed-off-by: Jonathan Corbet 

Reviewed-by: Jani Nikula 

> ---
>  scripts/kernel-doc | 65 
> --
>  1 file changed, 9 insertions(+), 56 deletions(-)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index fee8952037b1..5aa4ce211fc6 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -553,10 +553,9 @@ sub output_highlight {
>   }
>   if ($line eq ""){
>   if (! $output_preformatted) {
> - print $lineprefix, local_unescape($blankline);
> + print $lineprefix, $blankline;
>   }
>   } else {
> - $line =~ s/\\/\&/g;
>   if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
>   print "\\&$line";
>   } else {
> @@ -751,9 +750,6 @@ sub output_highlight_rst {
>  my $contents = join "\n",@_;
>  my $line;
>  
> -# undo the evil effects of xml_escape() earlier
> -$contents = xml_unescape($contents);
> -
>  eval $dohighlight;
>  die $@ if $@;
>  
> @@ -1422,8 +1418,6 @@ sub push_parameter() {
>   }
>   }
>  
> - $param = xml_escape($param);
> -
>   # strip spaces from $param so that it is one continuous string
>   # on @parameterlist;
>   # this fixes a problem where check_sections() cannot find
> @@ -1748,47 +1742,6 @@ sub process_proto_type($$) {
>  }
>  }
>  
> -# xml_escape: replace <, >, and & in the text stream;
> -#
> -# however, formatting controls that are generated internally/locally in the
> -# kernel-doc script are not escaped here; instead, they begin life like
> -# $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings
> -# are converted to their mnemonic-expected output, without the 4 * '\' & ':',
> -# just before actual output; (this is done by local_unescape())
> -sub xml_escape($) {
> - my $text = shift;
> - if ($output_mode eq "man") {
> - return $text;
> - }
> - $text =~ s/\&/\\amp;/g;
> - $text =~ s/\ - $text =~ s/\>/\\gt;/g;
> - return $text;
> -}
> -
> -# xml_unescape: reverse the effects of xml_escape
> -sub xml_unescape($) {
> - my $text = shift;
> - if ($output_mode eq "man") {
> - return $text;
> - }
> - $text =~ s/\\amp;/\&/g;
> - $text =~ s/\\lt;/ - $text =~ s/\\gt;/>/g;
> - return $text;
> -}
> -
> -# convert local escape strings to html
> -# local escape strings look like:  'menmonic:' (that's 4 backslashes)
> -sub local_unescape($) {
> - my $text = shift;
> - if ($output_mode eq "man") {
> - return $text;
> - }
> - $text =~ s/lt:/ - $text =~ s/gt:/>/g;
> - return $text;
> -}
>  
>  sub map_filename($) {
>  my $file;
> @@ -1889,7 +1842,7 @@ sub process_file($) {
>   $descr =~ s/^\s*//;
>   $descr =~ s/\s*$//;
>   $descr =~ s/\s+/ /g;
> - $declaration_purpose = xml_escape($descr);
> + $declaration_purpose = $descr;
>   $in_purpose = 1;
>   } else {
>   $declaration_purpose = "";
> @@ -1944,7 +1897,7 @@ sub process_file($) {
>   print STDERR "${file}:$.: warning: contents before 
> sections\n";
>   ++$warnings;
>   }
> - dump_section($file, $section, xml_escape($contents));
> + dump_section($file, $section, $contents);
>   $section = $section_default;
>   }
>  
> @@ -1962,7 +1915,7 @@ sub process_file($) {
>   $leading_space = undef;
>   } elsif (/$doc_end/) {
>   if (($contents ne "") && ($contents ne "\n")) {
> - dump_section($file, $section, xml_escape($contents));
> + dump_section($file, $section, $contents);
>   $section = $section_default;
>   $contents = "";
>   }
> @@ -1981,7 +1934,7 @@ sub process_file($) {
>   # @parameter line to signify start of description
>   if ($1 eq "") {
>   if ($section =~ m/^@/ || $section eq $section_context) {
> - dump_section($file, $section, xml_escape($contents));
> + dump_section($file, $section, $contents);
>   $section = $section_default;
>   $contents = "";
>  $new_start_line = $.;
> @@ -1992,7 +1945,7 @@ sub process_file($) {
>   } elsif ($in_purpose == 1) {
>   # Continued declaration purpose
>

[PATCH 3/8] docs: kernel-doc: Move STATE_NORMAL processing into its own function

2018-02-14 Thread Jonathan Corbet 
Begin the process of splitting up the nearly 500-line process_file()
function by moving STATE_NORMAL processing to a separate function.

Reviewed-by: Jani Nikula 
Signed-off-by: Jonathan Corbet 
---
 scripts/kernel-doc | 21 -
 1 file changed, 16 insertions(+), 5 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index ad30c52f91ef..65150b7c8472 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1780,6 +1780,21 @@ sub process_export_file($) {
 close(IN);
 }
 
+#
+# Parsers for the various processing states.
+#
+# STATE_NORMAL: looking for the /** to begin everything.
+#
+sub process_normal() {
+if (/$doc_start/o) {
+   $state = STATE_NAME;# next line is always the function name
+   $in_doc_sect = 0;
+   $declaration_start_line = $. + 1;
+}
+}
+
+
+
 sub process_file($) {
 my $file;
 my $identifier;
@@ -1807,11 +1822,7 @@ sub process_file($) {
# Replace tabs by spaces
 while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
if ($state == STATE_NORMAL) {
-   if (/$doc_start/o) {
-   $state = STATE_NAME;# next line is always the function name
-   $in_doc_sect = 0;
-   $declaration_start_line = $. + 1;
-   }
+   process_normal();
} elsif ($state == STATE_NAME) {# this line is the function name 
(always)
if (/$doc_block/o) {
$state = STATE_DOCBLOCK;
-- 
2.14.3

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 1/8] docs: kernel-doc: Get rid of xml_escape() and friends

2018-02-14 Thread Jonathan Corbet 
XML escaping is a worry that came with DocBook, which we no longer have any
dealings with.  So get rid of the useless xml_escape()/xml_unescape()
functions.  No change to the generated output.

Signed-off-by: Jonathan Corbet 
---
 scripts/kernel-doc | 65 --
 1 file changed, 9 insertions(+), 56 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index fee8952037b1..5aa4ce211fc6 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -553,10 +553,9 @@ sub output_highlight {
}
if ($line eq ""){
if (! $output_preformatted) {
-   print $lineprefix, local_unescape($blankline);
+   print $lineprefix, $blankline;
}
} else {
-   $line =~ s/\\/\&/g;
if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
print "\\&$line";
} else {
@@ -751,9 +750,6 @@ sub output_highlight_rst {
 my $contents = join "\n",@_;
 my $line;
 
-# undo the evil effects of xml_escape() earlier
-$contents = xml_unescape($contents);
-
 eval $dohighlight;
 die $@ if $@;
 
@@ -1422,8 +1418,6 @@ sub push_parameter() {
}
}
 
-   $param = xml_escape($param);
-
# strip spaces from $param so that it is one continuous string
# on @parameterlist;
# this fixes a problem where check_sections() cannot find
@@ -1748,47 +1742,6 @@ sub process_proto_type($$) {
 }
 }
 
-# xml_escape: replace <, >, and & in the text stream;
-#
-# however, formatting controls that are generated internally/locally in the
-# kernel-doc script are not escaped here; instead, they begin life like
-# $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings
-# are converted to their mnemonic-expected output, without the 4 * '\' & ':',
-# just before actual output; (this is done by local_unescape())
-sub xml_escape($) {
-   my $text = shift;
-   if ($output_mode eq "man") {
-   return $text;
-   }
-   $text =~ s/\&/\\amp;/g;
-   $text =~ s/\/\\gt;/g;
-   return $text;
-}
-
-# xml_unescape: reverse the effects of xml_escape
-sub xml_unescape($) {
-   my $text = shift;
-   if ($output_mode eq "man") {
-   return $text;
-   }
-   $text =~ s/\\amp;/\&/g;
-   $text =~ s/\\lt;//g;
-   return $text;
-}
-
-# convert local escape strings to html
-# local escape strings look like:  'menmonic:' (that's 4 backslashes)
-sub local_unescape($) {
-   my $text = shift;
-   if ($output_mode eq "man") {
-   return $text;
-   }
-   $text =~ s/lt://g;
-   return $text;
-}
 
 sub map_filename($) {
 my $file;
@@ -1889,7 +1842,7 @@ sub process_file($) {
$descr =~ s/^\s*//;
$descr =~ s/\s*$//;
$descr =~ s/\s+/ /g;
-   $declaration_purpose = xml_escape($descr);
+   $declaration_purpose = $descr;
$in_purpose = 1;
} else {
$declaration_purpose = "";
@@ -1944,7 +1897,7 @@ sub process_file($) {
print STDERR "${file}:$.: warning: contents before 
sections\n";
++$warnings;
}
-   dump_section($file, $section, xml_escape($contents));
+   dump_section($file, $section, $contents);
$section = $section_default;
}
 
@@ -1962,7 +1915,7 @@ sub process_file($) {
$leading_space = undef;
} elsif (/$doc_end/) {
if (($contents ne "") && ($contents ne "\n")) {
-   dump_section($file, $section, xml_escape($contents));
+   dump_section($file, $section, $contents);
$section = $section_default;
$contents = "";
}
@@ -1981,7 +1934,7 @@ sub process_file($) {
# @parameter line to signify start of description
if ($1 eq "") {
if ($section =~ m/^@/ || $section eq $section_context) {
-   dump_section($file, $section, xml_escape($contents));
+   dump_section($file, $section, $contents);
$section = $section_default;
$contents = "";
 $new_start_line = $.;
@@ -1992,7 +1945,7 @@ sub process_file($) {
} elsif ($in_purpose == 1) {
# Continued declaration purpose
chomp($declaration_purpose);
-   $declaration_purpose .= " " . xml_escape($1);
+   $declaration_purpose .= " " . $1;
$declaration_purpose =~ s/\s+/ /g;
} else {
my $cont = $1;
@@ -2030,7 +1983,7 @@ sub process_file($) {
#

[PATCH 2/8] docs: kernel-doc: Rename and split STATE_FIELD

2018-02-14 Thread Jonathan Corbet 
STATE_FIELD describes a parser state that can handle any part of a
kerneldoc comment body; rename it to STATE_BODY to reflect that.

The $in_purpose variable was a hidden substate of STATE_FIELD; get rid of
it and make a proper state (STATE_BODY_MAYBE) instead.  This will make the
subsequent process_file() splitup easier.

Reviewed-by: Jani Nikula 
Signed-off-by: Jonathan Corbet 
---
 scripts/kernel-doc | 22 +++---
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 5aa4ce211fc6..ad30c52f91ef 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -328,10 +328,11 @@ my $lineprefix="";
 use constant {
 STATE_NORMAL=> 0, # normal code
 STATE_NAME  => 1, # looking for function name
-STATE_FIELD => 2, # scanning field start
-STATE_PROTO => 3, # scanning prototype
-STATE_DOCBLOCK  => 4, # documentation block
-STATE_INLINE=> 5, # gathering documentation outside main block
+STATE_BODY_MAYBE=> 2, # body - or maybe more description
+STATE_BODY  => 3, # the body of the comment
+STATE_PROTO => 4, # scanning prototype
+STATE_DOCBLOCK  => 5, # documentation block
+STATE_INLINE=> 6, # gathering documentation outside main block
 };
 my $state;
 my $in_doc_sect;
@@ -1784,7 +1785,6 @@ sub process_file($) {
 my $identifier;
 my $func;
 my $descr;
-my $in_purpose = 0;
 my $initial_section_counter = $section_counter;
 my ($orig_file) = @_;
 my $leading_space;
@@ -1830,7 +1830,7 @@ sub process_file($) {
$identifier = $1;
}
 
-   $state = STATE_FIELD;
+   $state = STATE_BODY;
# if there's no @param blocks need to set up default section
# here
$contents = "";
@@ -1843,7 +1843,7 @@ sub process_file($) {
$descr =~ s/\s*$//;
$descr =~ s/\s+/ /g;
$declaration_purpose = $descr;
-   $in_purpose = 1;
+   $state = STATE_BODY_MAYBE;
} else {
$declaration_purpose = "";
}
@@ -1875,7 +1875,7 @@ sub process_file($) {
++$warnings;
$state = STATE_NORMAL;
}
-   } elsif ($state == STATE_FIELD) {   # look for head: lines, and 
include content
+   } elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE) {
if (/$doc_sect/i) { # case insensitive for supported section names
$newsection = $1;
$newcontents = $2;
@@ -1902,7 +1902,7 @@ sub process_file($) {
}
 
$in_doc_sect = 1;
-   $in_purpose = 0;
+   $state = STATE_BODY;
$contents = $newcontents;
 $new_start_line = $.;
while (substr($contents, 0, 1) eq " ") {
@@ -1941,8 +1941,8 @@ sub process_file($) {
} else {
$contents .= "\n";
}
-   $in_purpose = 0;
-   } elsif ($in_purpose == 1) {
+   $state = STATE_BODY;
+   } elsif ($state == STATE_BODY_MAYBE) {
# Continued declaration purpose
chomp($declaration_purpose);
$declaration_purpose .= " " . $1;
-- 
2.14.3

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 4/8] docs: kernel-doc: Move STATE_NAME processing into its own function

2018-02-14 Thread Jonathan Corbet 
Move this code out of process_file() in the name of readability and
maintainability.

Reviewed-by: Jani Nikula 
Signed-off-by: Jonathan Corbet 
---
 scripts/kernel-doc | 137 -
 1 file changed, 72 insertions(+), 65 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 65150b7c8472..a27c7016f72d 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1793,13 +1793,81 @@ sub process_normal() {
 }
 }
 
+#
+# STATE_NAME: Looking for the "name - description" line
+#
+sub process_name($$) {
+my $file = shift;
+my $identifier;
+my $descr;
+
+if (/$doc_block/o) {
+   $state = STATE_DOCBLOCK;
+   $contents = "";
+   $new_start_line = $. + 1;
+
+   if ( $1 eq "" ) {
+   $section = $section_intro;
+   } else {
+   $section = $1;
+   }
+}
+elsif (/$doc_decl/o) {
+   $identifier = $1;
+   if (/\s*([\w\s]+?)\s*-/) {
+   $identifier = $1;
+   }
 
+   $state = STATE_BODY;
+   # if there's no @param blocks need to set up default section
+   # here
+   $contents = "";
+   $section = $section_default;
+   $new_start_line = $. + 1;
+   if (/-(.*)/) {
+   # strip leading/trailing/multiple spaces
+   $descr= $1;
+   $descr =~ s/^\s*//;
+   $descr =~ s/\s*$//;
+   $descr =~ s/\s+/ /g;
+   $declaration_purpose = $descr;
+   $state = STATE_BODY_MAYBE;
+   } else {
+   $declaration_purpose = "";
+   }
+
+   if (($declaration_purpose eq "") && $verbose) {
+   print STDERR "${file}:$.: warning: missing initial short 
description on line:\n";
+   print STDERR $_;
+   ++$warnings;
+   }
+
+   if ($identifier =~ m/^struct/) {
+   $decl_type = 'struct';
+   } elsif ($identifier =~ m/^union/) {
+   $decl_type = 'union';
+   } elsif ($identifier =~ m/^enum/) {
+   $decl_type = 'enum';
+   } elsif ($identifier =~ m/^typedef/) {
+   $decl_type = 'typedef';
+   } else {
+   $decl_type = 'function';
+   }
+
+   if ($verbose) {
+   print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
+   }
+} else {
+   print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
+   " - I thought it was a doc line\n";
+   ++$warnings;
+   $state = STATE_NORMAL;
+}
+}
 
 sub process_file($) {
 my $file;
-my $identifier;
 my $func;
-my $descr;
 my $initial_section_counter = $section_counter;
 my ($orig_file) = @_;
 my $leading_space;
@@ -1823,69 +1891,8 @@ sub process_file($) {
 while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
if ($state == STATE_NORMAL) {
process_normal();
-   } elsif ($state == STATE_NAME) {# this line is the function name 
(always)
-   if (/$doc_block/o) {
-   $state = STATE_DOCBLOCK;
-   $contents = "";
-$new_start_line = $. + 1;
-
-   if ( $1 eq "" ) {
-   $section = $section_intro;
-   } else {
-   $section = $1;
-   }
-   }
-   elsif (/$doc_decl/o) {
-   $identifier = $1;
-   if (/\s*([\w\s]+?)\s*-/) {
-   $identifier = $1;
-   }
-
-   $state = STATE_BODY;
-   # if there's no @param blocks need to set up default section
-   # here
-   $contents = "";
-   $section = $section_default;
-   $new_start_line = $. + 1;
-   if (/-(.*)/) {
-   # strip leading/trailing/multiple spaces
-   $descr= $1;
-   $descr =~ s/^\s*//;
-   $descr =~ s/\s*$//;
-   $descr =~ s/\s+/ /g;
-   $declaration_purpose = $descr;
-   $state = STATE_BODY_MAYBE;
-   } else {
-   $declaration_purpose = "";
-   }
-
-   if (($declaration_purpose eq "") && $verbose) {
-   print STDERR "${file}:$.: warning: missing initial 
short description on line:\n";
-   print STDERR $_;
-   ++$warnings;
-   }
-
-   if ($identifier =~ m/^struct/) {
-   $decl_type = 'struct';
-   } elsif ($identifier =~ m/^union/) {
-   $decl_type = 'union';
-   } elsif ($identifier =~ m/^enum/) {
-   $decl_type = 'enum';
-   } elsif ($identifier =~ m/^typedef/) {
-   $decl_type = 'typedef';
-   } else {
-   $decl_type = 'function';
-   }
-
-   if ($verbose) {
-   print STDERR "${file}:$.: info:

[PATCH 5/8] docs: kernel-doc: Move STATE_BODY processing to a separate function

2018-02-14 Thread Jonathan Corbet 
Also group the pseudo-global $leading_space variable with its peers.

Reviewed-by: Jani Nikula 
Signed-off-by: Jonathan Corbet 
---
 scripts/kernel-doc | 193 -
 1 file changed, 101 insertions(+), 92 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index a27c7016f72d..a6a7bb46ea29 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -336,6 +336,7 @@ use constant {
 };
 my $state;
 my $in_doc_sect;
+my $leading_space;
 
 # Inline documentation state
 use constant {
@@ -1865,12 +1866,110 @@ sub process_name($$) {
 }
 }
 
+
+#
+# STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment.
+#
+sub process_body($$) {
+my $file = shift;
+
+if (/$doc_sect/i) { # case insensitive for supported section names
+   $newsection = $1;
+   $newcontents = $2;
+
+   # map the supported section names to the canonical names
+   if ($newsection =~ m/^description$/i) {
+   $newsection = $section_default;
+   } elsif ($newsection =~ m/^context$/i) {
+   $newsection = $section_context;
+   } elsif ($newsection =~ m/^returns?$/i) {
+   $newsection = $section_return;
+   } elsif ($newsection =~ m/^\@return$/) {
+   # special: @return is a section, not a param description
+   $newsection = $section_return;
+   }
+
+   if (($contents ne "") && ($contents ne "\n")) {
+   if (!$in_doc_sect && $verbose) {
+   print STDERR "${file}:$.: warning: contents before sections\n";
+   ++$warnings;
+   }
+   dump_section($file, $section, $contents);
+   $section = $section_default;
+   }
+
+   $in_doc_sect = 1;
+   $state = STATE_BODY;
+   $contents = $newcontents;
+   $new_start_line = $.;
+   while (substr($contents, 0, 1) eq " ") {
+   $contents = substr($contents, 1);
+   }
+   if ($contents ne "") {
+   $contents .= "\n";
+   }
+   $section = $newsection;
+   $leading_space = undef;
+} elsif (/$doc_end/) {
+   if (($contents ne "") && ($contents ne "\n")) {
+   dump_section($file, $section, $contents);
+   $section = $section_default;
+   $contents = "";
+   }
+   # look for doc_com +  + doc_end:
+   if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
+   print STDERR "${file}:$.: warning: suspicious ending line: $_";
+   ++$warnings;
+   }
+
+   $prototype = "";
+   $state = STATE_PROTO;
+   $brcount = 0;
+} elsif (/$doc_content/) {
+   # miguel-style comment kludge, look for blank lines after
+   # @parameter line to signify start of description
+   if ($1 eq "") {
+   if ($section =~ m/^@/ || $section eq $section_context) {
+   dump_section($file, $section, $contents);
+   $section = $section_default;
+   $contents = "";
+   $new_start_line = $.;
+   } else {
+   $contents .= "\n";
+   }
+   $state = STATE_BODY;
+   } elsif ($state == STATE_BODY_MAYBE) {
+   # Continued declaration purpose
+   chomp($declaration_purpose);
+   $declaration_purpose .= " " . $1;
+   $declaration_purpose =~ s/\s+/ /g;
+   } else {
+   my $cont = $1;
+   if ($section =~ m/^@/ || $section eq $section_context) {
+   if (!defined $leading_space) {
+   if ($cont =~ m/^(\s+)/) {
+   $leading_space = $1;
+   } else {
+   $leading_space = "";
+   }
+   }
+   $cont =~ s/^$leading_space//;
+   }
+   $contents .= $cont . "\n";
+   }
+} else {
+   # i dont know - bad line?  ignore.
+   print STDERR "${file}:$.: warning: bad line: $_";
+   ++$warnings;
+}
+}
+
+
 sub process_file($) {
 my $file;
 my $func;
 my $initial_section_counter = $section_counter;
 my ($orig_file) = @_;
-my $leading_space;
 
 $file = map_filename($orig_file);
 
@@ -1894,97 +1993,7 @@ sub process_file($) {
} elsif ($state == STATE_NAME) {
process_name($file, $_);
} elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE) {
-   if (/$doc_sect/i) { # case insensitive for supported section names
-   $newsection = $1;
-   $newcontents = $2;
-
-   # map the supported section names to the canonical names
-   if ($newsection =~ m/^description$/i) {
-   $newsection = $section_default;
-   } elsif ($newsection =~ m/^context$/i) {
-   $newsection = $section_context;
-   } elsif ($newsection =~ m/^returns?$/i) {
-   $newsection = $section_return;
-   } elsif ($newsection =~ m/^\@return$/) {
-

[PATCH 6/8] docs: kernel-doc: Move STATE_PROTO processing into its own function

2018-02-14 Thread Jonathan Corbet 
Move the top-level prototype-processing code out of process_file().

Reviewed-by: Jani Nikula 
Signed-off-by: Jonathan Corbet 
---
 scripts/kernel-doc | 46 --
 1 file changed, 28 insertions(+), 18 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index a6a7bb46ea29..2deddb876156 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1965,6 +1965,32 @@ sub process_body($$) {
 }
 
 
+#
+# STATE_PROTO: reading a function/whatever prototype.
+#
+sub process_proto($$) {
+my $file = shift;
+
+if (/$doc_inline_oneline/) {
+   $section = $1;
+   $contents = $2;
+   if ($contents ne "") {
+   $contents .= "\n";
+   dump_section($file, $section, $contents);
+   $section = $section_default;
+   $contents = "";
+   }
+} elsif (/$doc_inline_start/) {
+   $state = STATE_INLINE;
+   $inline_doc_state = STATE_INLINE_NAME;
+} elsif ($decl_type eq 'function') {
+   process_proto_function($_, $file);
+} else {
+   process_proto_type($_, $file);
+}
+}
+
+
 sub process_file($) {
 my $file;
 my $func;
@@ -2031,24 +2057,8 @@ sub process_file($) {
++$warnings;
}
}
-   } elsif ($state == STATE_PROTO) {   # scanning for function '{' 
(end of prototype)
-   if (/$doc_inline_oneline/) {
-   $section = $1;
-   $contents = $2;
-   if ($contents ne "") {
-   $contents .= "\n";
-   dump_section($file, $section, $contents);
-   $section = $section_default;
-   $contents = "";
-   }
-   } elsif (/$doc_inline_start/) {
-   $state = STATE_INLINE;
-   $inline_doc_state = STATE_INLINE_NAME;
-   } elsif ($decl_type eq 'function') {
-   process_proto_function($_, $file);
-   } else {
-   process_proto_type($_, $file);
-   }
+   } elsif ($state == STATE_PROTO) {
+   process_proto($file, $_);
} elsif ($state == STATE_DOCBLOCK) {
if (/$doc_end/)
{
-- 
2.14.3

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 8/8] docs: kernel-doc: Don't mangle literal code blocks in comments

2018-02-14 Thread Jonathan Corbet 
It can be useful to put code snippets into kerneldoc comments; that can be
done with the "::" operator at the end of a line like this::

   if (desperate)
   run_in_circles();

The ".. code-block::" directive can also be used to this end.  kernel-doc
currently fails to understand these literal blocks and applies its normal
markup to them, which is then treated as literal by sphinx.  The result is
unsightly markup instead of a useful code snippet.

Apply a hack to the output code to recognize literal blocks and avoid
performing any special markup on them.  It's ugly, but that means it fits
in well with the rest of the script.

Signed-off-by: Jonathan Corbet 
---
 scripts/kernel-doc | 69 ++
 1 file changed, 64 insertions(+), 5 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index fb8fbdb25036..cbe864e72a2f 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -748,14 +748,73 @@ sub output_blockhead_rst(%) {
 }
 }
 
-sub output_highlight_rst {
-my $contents = join "\n",@_;
-my $line;
-
+#
+# Apply the RST highlights to a sub-block of text.
+#   
+sub highlight_block($) {
+# The dohighlight kludge requires the text be called $contents
+my $contents = shift;
 eval $dohighlight;
 die $@ if $@;
+return $contents;
+}
 
-foreach $line (split "\n", $contents) {
+#
+# Regexes used only here.
+#
+my $sphinx_literal = '^[^.].*::$';
+my $sphinx_cblock = '^\.\.\ +code-block::';
+
+sub output_highlight_rst {
+my $input = join "\n",@_;
+my $output = "";
+my $line;
+my $in_literal = 0;
+my $litprefix;
+my $block = "";
+
+foreach $line (split "\n",$input) {
+   #
+   # If we're in a literal block, see if we should drop out
+   # of it.  Otherwise pass the line straight through unmunged.
+   #
+   if ($in_literal) {
+   if (! ($line =~ /^\s*$/)) {
+   #
+   # If this is the first non-blank line in a literal
+   # block we need to figure out what the proper indent is.
+   #
+   if ($litprefix eq "") {
+   $line =~ /^(\s*)/;
+   $litprefix = '^' . $1;
+   $output .= $line . "\n";
+   } elsif (! ($line =~ /$litprefix/)) {
+   $in_literal = 0;
+   } else {
+   $output .= $line . "\n";
+   }
+   } else {
+   $output .= $line . "\n";
+   }
+   }
+   #
+   # Not in a literal block (or just dropped out)
+   #
+   if (! $in_literal) {
+   $block .= $line . "\n";
+   if (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) {
+   $in_literal = 1;
+   $litprefix = "";
+   $output .= highlight_block($block);
+   $block = ""
+   }
+   }
+}
+
+if ($block) {
+   $output .= highlight_block($block);
+}
+foreach $line (split "\n", $output) {
print $lineprefix . $line . "\n";
 }
 }
-- 
2.14.3

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 7/8] docs: kernel-doc: Finish moving STATE_* code out of process_file()

2018-02-14 Thread Jonathan Corbet 
Move STATE_INLINE and STATE_DOCBLOCK code out of process_file(), which now
actually fits on a single screen.  Delete an unused variable and add a
couple of comments while I'm at it.

Reviewed-by: Jani Nikula 
Signed-off-by: Jonathan Corbet 
---
 scripts/kernel-doc | 139 +
 1 file changed, 77 insertions(+), 62 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 2deddb876156..fb8fbdb25036 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1990,10 +1990,80 @@ sub process_proto($$) {
 }
 }
 
+#
+# STATE_DOCBLOCK: within a DOC: block.
+#
+sub process_docblock($$) {
+my $file = shift;
+
+if (/$doc_end/) {
+   dump_doc_section($file, $section, $contents);
+   $section = $section_default;
+   $contents = "";
+   $function = "";
+   %parameterdescs = ();
+   %parametertypes = ();
+   @parameterlist = ();
+   %sections = ();
+   @sectionlist = ();
+   $prototype = "";
+   $state = STATE_NORMAL;
+} elsif (/$doc_content/) {
+   if ( $1 eq "" ) {
+   $contents .= $blankline;
+   } else {
+   $contents .= $1 . "\n";
+   }
+}
+}
+
+#
+# STATE_INLINE: docbook comments within a prototype.
+#
+sub process_inline($$) {
+my $file = shift;
+
+# First line (state 1) needs to be a @parameter
+if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
+   $section = $1;
+   $contents = $2;
+   $new_start_line = $.;
+   if ($contents ne "") {
+   while (substr($contents, 0, 1) eq " ") {
+   $contents = substr($contents, 1);
+   }
+   $contents .= "\n";
+   }
+   $inline_doc_state = STATE_INLINE_TEXT;
+   # Documentation block end */
+} elsif (/$doc_inline_end/) {
+   if (($contents ne "") && ($contents ne "\n")) {
+   dump_section($file, $section, $contents);
+   $section = $section_default;
+   $contents = "";
+   }
+   $state = STATE_PROTO;
+   $inline_doc_state = STATE_INLINE_NA;
+   # Regular text
+} elsif (/$doc_content/) {
+   if ($inline_doc_state == STATE_INLINE_TEXT) {
+   $contents .= $1 . "\n";
+   # nuke leading blank lines
+   if ($contents =~ /^\s*$/) {
+   $contents = "";
+   }
+   } elsif ($inline_doc_state == STATE_INLINE_NAME) {
+   $inline_doc_state = STATE_INLINE_ERROR;
+   print STDERR "${file}:$.: warning: ";
+   print STDERR "Incorrect use of kernel-doc format: $_";
+   ++$warnings;
+   }
+}
+}
+
 
 sub process_file($) {
 my $file;
-my $func;
 my $initial_section_counter = $section_counter;
 my ($orig_file) = @_;
 
@@ -2014,6 +2084,8 @@ sub process_file($) {
}
# Replace tabs by spaces
 while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
+
+   # Hand this line to the appropriate state handler
if ($state == STATE_NORMAL) {
process_normal();
} elsif ($state == STATE_NAME) {
@@ -2021,72 +2093,15 @@ sub process_file($) {
} elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE) {
process_body($file, $_);
} elsif ($state == STATE_INLINE) { # scanning for inline parameters
-   # First line (state 1) needs to be a @parameter
-   if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
-   $section = $1;
-   $contents = $2;
-$new_start_line = $.;
-   if ($contents ne "") {
-   while (substr($contents, 0, 1) eq " ") {
-   $contents = substr($contents, 1);
-   }
-   $contents .= "\n";
-   }
-   $inline_doc_state = STATE_INLINE_TEXT;
-   # Documentation block end */
-   } elsif (/$doc_inline_end/) {
-   if (($contents ne "") && ($contents ne "\n")) {
-   dump_section($file, $section, $contents);
-   $section = $section_default;
-   $contents = "";
-   }
-   $state = STATE_PROTO;
-   $inline_doc_state = STATE_INLINE_NA;
-   # Regular text
-   } elsif (/$doc_content/) {
-   if ($inline_doc_state == STATE_INLINE_TEXT) {
-   $contents .= $1 . "\n";
-   # nuke leading blank lines
-   if ($contents =~ /^\s*$/) {
-   $contents = "";
-   }
-   } elsif ($inline_doc_state == STATE_INLINE_NAME) {
-   $inline_doc_state = STATE_INLINE_ERROR;
-   print STDERR "${file}:$.: warning: ";
-   print STDERR "Incorrect use of kernel-doc format: $_";
-   ++$warnings;
-   }
-   }
+

[PATCH v2 0/8] docs: Cleanup kernel-doc and fix literal block handling

2018-02-14 Thread Jonathan Corbet 
So once upon a time I set out to fix the problem reported by Tobin wherein
a literal block within a kerneldoc comment would be corrupted in
processing.  On the way, though, I got annoyed at the way I have to learn
how kernel-doc works from the beginning every time I tear into it.

As a result, seven of the following eight patches just get rid of some dead
code and reorganize the rest - mostly turning the 500-line process_file()
function into something a bit more rational.  Sphinx output is unchanged
after these are applied.  Then, at the end, there's a tweak to stop messing
with literal blocks.

If anybody was unaware that I've not done any serious Perl since the
1990's, they will certainly understand that fact now.

Changes in v2:
  - Fix up old coding-style ugliness as I move the code
  - Handle ".. code-block::" literals as well.  This fixed
the formatting in dev-tools/kselftest.rst.

Jonathan Corbet (8):
  docs: kernel-doc: Get rid of xml_escape() and friends
  docs: kernel-doc: Rename and split STATE_FIELD
  docs: kernel-doc: Move STATE_NORMAL processing into its own function
  docs: kernel-doc: Move STATE_NAME processing into its own function
  docs: kernel-doc: Move STATE_BODY processing to a separate function
  docs: kernel-doc: Move STATE_PROTO processing into its own function
  docs: kernel-doc: Finish moving STATE_* code out of process_file()
  docs: kernel-doc: Don't mangle literal code blocks in comments

 scripts/kernel-doc | 666 +
 1 file changed, 365 insertions(+), 301 deletions(-)

-- 
2.14.3

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v4 16/18] scripts: kernel-doc: improve nested logic to handle multiple identifiers

2018-02-14 Thread Jani Nikula 
On Wed, 14 Feb 2018, Mauro Carvalho Chehab  wrote:
> There is a simple fix, though. Make inline comments to accept a dot:
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index fee8952037b1..06d7f3f2c094 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -363,7 +363,7 @@ my $doc_sect = $doc_com .
>  my $doc_content = $doc_com_body . '(.*)';
>  my $doc_block = $doc_com . 'DOC:\s*(.*)?';
>  my $doc_inline_start = '^\s*/\*\*\s*$';
> -my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
> +my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';
>  my $doc_inline_end = '^\s*\*/\s*$';
>  my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
>  my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
>
> That requires a small change at the inline parameters, though:
>
> diff --git a/drivers/gpu/drm/i915/intel_dpio_phy.c 
> b/drivers/gpu/drm/i915/intel_dpio_phy.c
> index 76473e9836c6..c8e9e44e5981 100644
> --- a/drivers/gpu/drm/i915/intel_dpio_phy.c
> +++ b/drivers/gpu/drm/i915/intel_dpio_phy.c
> @@ -147,7 +147,7 @@ struct bxt_ddi_phy_info {
>*/
>   struct {
>   /**
> -  * @port: which port maps to this channel.
> +  * @channel.port: which port maps to this channel.
>*/
>   enum port port;
>   } channel[2];

Perhaps it would be slightly more elegant to be able to leave out
"channel." here and deduce that from the context... but the above
matches what you'd write in the higher level struct comment, and
produces the same output. It works and it's really simple. I like it.

Please submit this as a proper patch, with

Tested-by: Jani Nikula 

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v4 16/18] scripts: kernel-doc: improve nested logic to handle multiple identifiers

2018-02-14 Thread Mauro Carvalho Chehab 
Em Wed, 14 Feb 2018 18:07:03 +0200
Jani Nikula  escreveu:

> On Mon, 18 Dec 2017, Mauro Carvalho Chehab  wrote:
> > It is possible to use nested structs like:
> >
> > struct {
> > struct {
> > void *arg1;
> > } st1, st2, *st3, st4;
> > };
> >
> > Handling it requires to split each parameter. Change the logic
> > to allow such definitions.
> >
> > In order to test the new nested logic, the following file
> > was used to test  
> 
> Hi Mauro, resurrecting an old thread...
> 
> So this was a great improvement to documenting nested structs. However,
> it looks like it only supports describing the nested structs at the top
> level comment, and fails for inline documentation comments.

True. I didn't consider inline comments when I wrote the patch.
We don't use inline doc tags at media. IMO, a single description block
on the top works better, but yeah, it would be very good if it would
support nested structs to also have inlined comments.

Yet, on a quick hack:

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index fee8952037b1..e2d5cadd8d0b 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1009,6 +1009,8 @@ sub dump_struct($$) {
$declaration_name = $2;
my $members = $3;
 
+print "members: $members\n";
+
# ignore members marked private:
$members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
$members =~ s/\/\*\s*private:.*//gosi;

produce:

$ scripts/kernel-doc -none drivers/gpu/drm/i915/intel_dpio_phy.c
members:  bool dual_channel; enum dpio_phy rcomp_phy; int reset_delay; 
u32 pwron_mask; struct { enum port port; }  channel[2]; 
drivers/gpu/drm/i915/intel_dpio_phy.c:154: warning: Function parameter 
or member 'channel.port' not described in 'bxt_ddi_phy_info'

So, dump_struct() already receives the struct sanitizes without any comments
inside.

There is a simple fix, though. Make inline comments to accept a dot:

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index fee8952037b1..06d7f3f2c094 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -363,7 +363,7 @@ my $doc_sect = $doc_com .
 my $doc_content = $doc_com_body . '(.*)';
 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
 my $doc_inline_start = '^\s*/\*\*\s*$';
-my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
+my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';
 my $doc_inline_end = '^\s*\*/\s*$';
 my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
 my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';

That requires a small change at the inline parameters, though:

diff --git a/drivers/gpu/drm/i915/intel_dpio_phy.c 
b/drivers/gpu/drm/i915/intel_dpio_phy.c
index 76473e9836c6..c8e9e44e5981 100644
--- a/drivers/gpu/drm/i915/intel_dpio_phy.c
+++ b/drivers/gpu/drm/i915/intel_dpio_phy.c
@@ -147,7 +147,7 @@ struct bxt_ddi_phy_info {
 */
struct {
/**
-* @port: which port maps to this channel.
+* @channel.port: which port maps to this channel.
 */
enum port port;
} channel[2];

The alternative would be a way more complex: to teach the code with
starts at:

If ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {

About how to handle with inlined structs/enums at inlined comments.

Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[RESEND PATCH] memory-barriers: Fix description of data dependency barriers

2018-02-14 Thread Nikolay Borisov 
In the description of data dependency barriers the words 'before' is
used erroneously. Since such barrier order dependent loads one after
the other. So substitute 'before' with 'after'.

Signed-off-by: Nikolay Borisov 
---

Resent due to missing out the various mailing lists doh ... 


 Documentation/memory-barriers.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/memory-barriers.txt 
b/Documentation/memory-barriers.txt
index a863009849a3..0d696c7fd97a 100644
--- a/Documentation/memory-barriers.txt
+++ b/Documentation/memory-barriers.txt
@@ -399,7 +399,7 @@ VARIETIES OF MEMORY BARRIER
  where two loads are performed such that the second depends on the result
  of the first (eg: the first load retrieves the address to which the second
  load will be directed), a data dependency barrier would be required to
- make sure that the target of the second load is updated before the address
+ make sure that the target of the second load is updated after the address
  obtained by the first load is accessed.
 
  A data dependency barrier is a partial ordering on interdependent loads
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 8/8] docs: kernel-doc: Don't mangle literal code blocks in comments

2018-02-14 Thread Markus Heiser 

> Am 07.02.2018 um 18:26 schrieb Jonathan Corbet :
> 
> It can be useful to put code snippets into kerneldoc comments; that can be
> done with the "::" operator at the end of a line like this::
> 
>  if (desperate)
>  run_in_circles();
> 
> kernel-doc currently fails to understand these literal blocks and applies
> its normal markup to them, which is then treated as literal by sphinx.  The
> result is unsightly markup instead of a useful code snippet.
> 
> Apply a hack to the output code to recognize literal blocks and avoid
> performing any special markup on them.  It's ugly, but that means it fits
> in well with the rest of the script.
> 
> Signed-off-by: Jonathan Corbet 


[...]

FYI; added similar patch to python version of kernel-doc:

 https://github.com/return42/linuxdoc/commit/3205b8a68

may you like to add regexpr for code-block directive to your patch (jani 
mentioned already).

-- Markus --


--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v4 16/18] scripts: kernel-doc: improve nested logic to handle multiple identifiers

2018-02-14 Thread Jani Nikula 
On Mon, 18 Dec 2017, Mauro Carvalho Chehab  wrote:
> It is possible to use nested structs like:
>
> struct {
>   struct {
>   void *arg1;
>   } st1, st2, *st3, st4;
> };
>
> Handling it requires to split each parameter. Change the logic
> to allow such definitions.
>
> In order to test the new nested logic, the following file
> was used to test

Hi Mauro, resurrecting an old thread...

So this was a great improvement to documenting nested structs. However,
it looks like it only supports describing the nested structs at the top
level comment, and fails for inline documentation comments.

For example, in v4.16-rc1:

$ scripts/kernel-doc -none drivers/gpu/drm/i915/intel_dpio_phy.c
drivers/gpu/drm/i915/intel_dpio_phy.c:154: warning: Function parameter or 
member 'channel.port' not described in 'bxt_ddi_phy_info'

The struct in question is:

/**
 * struct bxt_ddi_phy_info - Hold info for a broxton DDI phy
 */
struct bxt_ddi_phy_info {
/* [some members removed] */

/**
 * @channel: struct containing per channel information.
 */
struct {
/**
 * @port: which port maps to this channel.
 */
enum port port;
} channel[2];
};

Apparently the only way to currently do this is to add channel.port at
the top level:

/**
 * struct bxt_ddi_phy_info - Hold info for a broxton DDI phy
 * @channel.port: which port maps to this channel.
 */

Which is less than perfect if you have everything else described
inline. :(

BR,
Jani.


>
> 
> struct foo { int a; }; /* Just to avoid errors if compiled */
>
> /**
>  * struct my_struct - a struct with nested unions and structs
>  * @arg1: first argument of anonymous union/anonymous struct
>  * @arg2: second argument of anonymous union/anonymous struct
>  * @arg1b: first argument of anonymous union/anonymous struct
>  * @arg2b: second argument of anonymous union/anonymous struct
>  * @arg3: third argument of anonymous union/anonymous struct
>  * @arg4: fourth argument of anonymous union/anonymous struct
>  * @bar.st1.arg1: first argument of struct st1 on union bar
>  * @bar.st1.arg2: second argument of struct st1 on union bar
>  * @bar.st1.bar1: bar1 at st1
>  * @bar.st1.bar2: bar2 at st1
>  * @bar.st2.arg1: first argument of struct st2 on union bar
>  * @bar.st2.arg2: second argument of struct st2 on union bar
>  * @bar.st3.arg2: second argument of struct st3 on union bar
>  * @f1: nested function on anonimous union/struct
>  * @bar.st2.f2: nested function on named union/struct
>  */
> struct my_struct {
>/* Anonymous union/struct*/
>union {
>   struct {
>   char arg1 : 1;
>   char arg2 : 3;
>   };
>struct {
>int arg1b;
>int arg2b;
>};
>struct {
>void *arg3;
>int arg4;
>int (*f1)(char foo, int bar);
>};
>};
>union {
>struct {
>int arg1;
>int arg2;
>  struct foo bar1, *bar2;
>} st1;   /* bar.st1 is undocumented, cause a warning */
>struct {
>void *arg1;  /* bar.st3.arg1 is undocumented, cause a warning */
>   int arg2;
>   int (*f2)(char foo, int bar); /* bar.st3.fn2 is undocumented, cause 
> a warning */
>} st2, st3, *st4;
>int (*f3)(char foo, int bar); /* f3 is undocumented, cause a warning */
>} bar;   /* bar is undocumented, cause a warning */
>
>/* private: */
>int undoc_privat;/* is undocumented but private, no warning */
>
>/* public: */
>int undoc_public;/* is undocumented, cause a warning */
> };
> 
>
> It produces the following warnings, as expected:
>
> test2.h:57: warning: Function parameter or member 'bar' not described in 
> 'my_struct'
> test2.h:57: warning: Function parameter or member 'bar.st1' not described in 
> 'my_struct'
> test2.h:57: warning: Function parameter or member 'bar.st2' not described in 
> 'my_struct'
> test2.h:57: warning: Function parameter or member 'bar.st3' not described in 
> 'my_struct'
> test2.h:57: warning: Function parameter or member 'bar.st3.arg1' not 
> described in 'my_struct'
> test2.h:57: warning: Function parameter or member 'bar.st3.f2' not described 
> in 'my_struct'
> test2.h:57: warning: Function parameter or member 'bar.st4' not described in 
> 'my_struct'
> test2.h:57: warning: Function parameter or member 'bar.st4.arg1' not 
> described in 'my_struct'
> test2.h:57: warning: Function parameter or member 'bar.st4.arg2' not 
> described in 'my_struct'
> test2.h:57: warning: Function parameter or member 'bar.st4.f2' not described 
> in 'my_struct'
> test2.h:57: warning: Function parameter or member 'bar.f3' not described in 
> 'my_struct'
> test2.h:57: warning: Function parameter or member 'undoc_public' not 
> described in 'my_struct'
>
> Suggested-by: Markus Heiser 
>

Re: [PATCH v2 4/6] crypto: virtio: convert to new crypto engine API

2018-02-14 Thread Michael S. Tsirkin 
On Fri, Jan 26, 2018 at 08:15:32PM +0100, Corentin Labbe wrote:
> This patch convert the driver to the new crypto engine API.
> 
> Signed-off-by: Corentin Labbe 

Acked-by: Michael S. Tsirkin 

Pls queue when/if rest of changes go in.

> ---
>  drivers/crypto/virtio/virtio_crypto_algs.c   | 16 ++--
>  drivers/crypto/virtio/virtio_crypto_common.h |  3 +--
>  drivers/crypto/virtio/virtio_crypto_core.c   |  3 ---
>  3 files changed, 11 insertions(+), 11 deletions(-)
> 
> diff --git a/drivers/crypto/virtio/virtio_crypto_algs.c 
> b/drivers/crypto/virtio/virtio_crypto_algs.c
> index abe8c15450df..ba190cfa7aa1 100644
> --- a/drivers/crypto/virtio/virtio_crypto_algs.c
> +++ b/drivers/crypto/virtio/virtio_crypto_algs.c
> @@ -29,6 +29,7 @@
>  
>  
>  struct virtio_crypto_ablkcipher_ctx {
> + struct crypto_engine_ctx enginectx;
>   struct virtio_crypto *vcrypto;
>   struct crypto_tfm *tfm;
>  
> @@ -491,7 +492,7 @@ static int virtio_crypto_ablkcipher_encrypt(struct 
> ablkcipher_request *req)
>   vc_sym_req->ablkcipher_req = req;
>   vc_sym_req->encrypt = true;
>  
> - return crypto_transfer_cipher_request_to_engine(data_vq->engine, req);
> + return crypto_transfer_ablkcipher_request_to_engine(data_vq->engine, 
> req);
>  }
>  
>  static int virtio_crypto_ablkcipher_decrypt(struct ablkcipher_request *req)
> @@ -511,7 +512,7 @@ static int virtio_crypto_ablkcipher_decrypt(struct 
> ablkcipher_request *req)
>   vc_sym_req->ablkcipher_req = req;
>   vc_sym_req->encrypt = false;
>  
> - return crypto_transfer_cipher_request_to_engine(data_vq->engine, req);
> + return crypto_transfer_ablkcipher_request_to_engine(data_vq->engine, 
> req);
>  }
>  
>  static int virtio_crypto_ablkcipher_init(struct crypto_tfm *tfm)
> @@ -521,6 +522,9 @@ static int virtio_crypto_ablkcipher_init(struct 
> crypto_tfm *tfm)
>   tfm->crt_ablkcipher.reqsize = sizeof(struct virtio_crypto_sym_request);
>   ctx->tfm = tfm;
>  
> + ctx->enginectx.op.do_one_request = virtio_crypto_ablkcipher_crypt_req;
> + ctx->enginectx.op.prepare_request = NULL;
> + ctx->enginectx.op.unprepare_request = NULL;
>   return 0;
>  }
>  
> @@ -538,9 +542,9 @@ static void virtio_crypto_ablkcipher_exit(struct 
> crypto_tfm *tfm)
>  }
>  
>  int virtio_crypto_ablkcipher_crypt_req(
> - struct crypto_engine *engine,
> - struct ablkcipher_request *req)
> + struct crypto_engine *engine, void *vreq)
>  {
> + struct ablkcipher_request *req = container_of(vreq, struct 
> ablkcipher_request, base);
>   struct virtio_crypto_sym_request *vc_sym_req =
>   ablkcipher_request_ctx(req);
>   struct virtio_crypto_request *vc_req = _sym_req->base;
> @@ -561,8 +565,8 @@ static void virtio_crypto_ablkcipher_finalize_req(
>   struct ablkcipher_request *req,
>   int err)
>  {
> - crypto_finalize_cipher_request(vc_sym_req->base.dataq->engine,
> - req, err);
> + crypto_finalize_ablkcipher_request(vc_sym_req->base.dataq->engine,
> +req, err);
>   kzfree(vc_sym_req->iv);
>   virtcrypto_clear_request(_sym_req->base);
>  }
> diff --git a/drivers/crypto/virtio/virtio_crypto_common.h 
> b/drivers/crypto/virtio/virtio_crypto_common.h
> index e976539a05d9..72621bd67211 100644
> --- a/drivers/crypto/virtio/virtio_crypto_common.h
> +++ b/drivers/crypto/virtio/virtio_crypto_common.h
> @@ -107,8 +107,7 @@ struct virtio_crypto *virtcrypto_get_dev_node(int node);
>  int virtcrypto_dev_start(struct virtio_crypto *vcrypto);
>  void virtcrypto_dev_stop(struct virtio_crypto *vcrypto);
>  int virtio_crypto_ablkcipher_crypt_req(
> - struct crypto_engine *engine,
> - struct ablkcipher_request *req);
> + struct crypto_engine *engine, void *vreq);
>  
>  void
>  virtcrypto_clear_request(struct virtio_crypto_request *vc_req);
> diff --git a/drivers/crypto/virtio/virtio_crypto_core.c 
> b/drivers/crypto/virtio/virtio_crypto_core.c
> index ff1410a32c2b..83326986c113 100644
> --- a/drivers/crypto/virtio/virtio_crypto_core.c
> +++ b/drivers/crypto/virtio/virtio_crypto_core.c
> @@ -111,9 +111,6 @@ static int virtcrypto_find_vqs(struct virtio_crypto *vi)
>   ret = -ENOMEM;
>   goto err_engine;
>   }
> -
> - vi->data_vq[i].engine->cipher_one_request =
> - virtio_crypto_ablkcipher_crypt_req;
>   }
>  
>   kfree(names);
> -- 
> 2.13.6
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2 2/6] crypto: engine - Permit to enqueue all async requests

2018-02-14 Thread Fabien DESSENNE 
Adding my tested-by for the AEAD part which is new in v2


On 26/01/18 20:15, Corentin Labbe wrote:
> The crypto engine could actually only enqueue hash and ablkcipher request.
> This patch permit it to enqueue any type of crypto_async_request.
>
> Signed-off-by: Corentin Labbe 
> Tested-by: Fabien Dessenne 

Tested-by: Fabien Dessenne 


> ---
>   crypto/crypto_engine.c  | 301 
> ++--
>   include/crypto/engine.h |  68 ++-
>   2 files changed, 203 insertions(+), 166 deletions(-)
>
> diff --git a/crypto/crypto_engine.c b/crypto/crypto_engine.c
> index 61e7c4e02fd2..992e8d8dcdd9 100644
> --- a/crypto/crypto_engine.c
> +++ b/crypto/crypto_engine.c
> @@ -15,13 +15,50 @@
>   #include 
>   #include 
>   #include 
> -#include 
>   #include 
>   #include "internal.h"
>   
>   #define CRYPTO_ENGINE_MAX_QLEN 10
>   
>   /**
> + * crypto_finalize_request - finalize one request if the request is done
> + * @engine: the hardware engine
> + * @req: the request need to be finalized
> + * @err: error number
> + */
> +static void crypto_finalize_request(struct crypto_engine *engine,
> +  struct crypto_async_request *req, int err)
> +{
> + unsigned long flags;
> + bool finalize_cur_req = false;
> + int ret;
> + struct crypto_engine_ctx *enginectx;
> +
> + spin_lock_irqsave(>queue_lock, flags);
> + if (engine->cur_req == req)
> + finalize_cur_req = true;
> + spin_unlock_irqrestore(>queue_lock, flags);
> +
> + if (finalize_cur_req) {
> + enginectx = crypto_tfm_ctx(req->tfm);
> + if (engine->cur_req_prepared &&
> + enginectx->op.unprepare_request) {
> + ret = enginectx->op.unprepare_request(engine, req);
> + if (ret)
> + dev_err(engine->dev, "failed to unprepare 
> request\n");
> + }
> + spin_lock_irqsave(>queue_lock, flags);
> + engine->cur_req = NULL;
> + engine->cur_req_prepared = false;
> + spin_unlock_irqrestore(>queue_lock, flags);
> + }
> +
> + req->complete(req, err);
> +
> + kthread_queue_work(engine->kworker, >pump_requests);
> +}
> +
> +/**
>* crypto_pump_requests - dequeue one request from engine queue to process
>* @engine: the hardware engine
>* @in_kthread: true if we are in the context of the request pump thread
> @@ -34,11 +71,10 @@ static void crypto_pump_requests(struct crypto_engine 
> *engine,
>bool in_kthread)
>   {
>   struct crypto_async_request *async_req, *backlog;
> - struct ahash_request *hreq;
> - struct ablkcipher_request *breq;
>   unsigned long flags;
>   bool was_busy = false;
> - int ret, rtype;
> + int ret;
> + struct crypto_engine_ctx *enginectx;
>   
>   spin_lock_irqsave(>queue_lock, flags);
>   
> @@ -94,7 +130,6 @@ static void crypto_pump_requests(struct crypto_engine 
> *engine,
>   
>   spin_unlock_irqrestore(>queue_lock, flags);
>   
> - rtype = crypto_tfm_alg_type(engine->cur_req->tfm);
>   /* Until here we get the request need to be encrypted successfully */
>   if (!was_busy && engine->prepare_crypt_hardware) {
>   ret = engine->prepare_crypt_hardware(engine);
> @@ -104,57 +139,31 @@ static void crypto_pump_requests(struct crypto_engine 
> *engine,
>   }
>   }
>   
> - switch (rtype) {
> - case CRYPTO_ALG_TYPE_AHASH:
> - hreq = ahash_request_cast(engine->cur_req);
> - if (engine->prepare_hash_request) {
> - ret = engine->prepare_hash_request(engine, hreq);
> - if (ret) {
> - dev_err(engine->dev, "failed to prepare 
> request: %d\n",
> - ret);
> - goto req_err;
> - }
> - engine->cur_req_prepared = true;
> - }
> - ret = engine->hash_one_request(engine, hreq);
> - if (ret) {
> - dev_err(engine->dev, "failed to hash one request from 
> queue\n");
> - goto req_err;
> - }
> - return;
> - case CRYPTO_ALG_TYPE_ABLKCIPHER:
> - breq = ablkcipher_request_cast(engine->cur_req);
> - if (engine->prepare_cipher_request) {
> - ret = engine->prepare_cipher_request(engine, breq);
> - if (ret) {
> - dev_err(engine->dev, "failed to prepare 
> request: %d\n",
> - ret);
> - goto req_err;
> - }
> - engine->cur_req_prepared = true;
> - }
> - ret = engine->cipher_one_request(engine, breq);
> +

Re: [PATCH v2 3/7] soc: qcom: Add GENI based QUP Wrapper driver

2018-02-14 Thread Amit Kucheria 
On Sat, Jan 13, 2018 at 6:35 AM, Karthikeyan Ramasubramanian
 wrote:
> This driver manages the Generic Interface (GENI) firmware based Qualcomm
> Universal Peripheral (QUP) Wrapper. GENI based QUP is the next generation
> programmable module composed of multiple Serial Engines (SE) and supports
> a wide range of serial interfaces like UART, SPI, I2C, I3C, etc. This
> driver also enables managing the serial interface independent aspects of
> Serial Engines.
>
> Signed-off-by: Karthikeyan Ramasubramanian 
> Signed-off-by: Sagar Dharia 
> Signed-off-by: Girish Mahadevan 


> +int geni_se_resources_off(struct geni_se_rsc *rsc)
> +{
> +   int ret = 0;
> +   struct geni_se_device *geni_se_dev;
> +
> +   if (unlikely(!rsc || !rsc->wrapper_dev))
> +   return -EINVAL;
> +
> +   geni_se_dev = dev_get_drvdata(rsc->wrapper_dev);
> +   if (unlikely(!geni_se_dev))
> +   return -ENODEV;
> +
> +   ret = pinctrl_select_state(rsc->geni_pinctrl, rsc->geni_gpio_sleep);

You need to include linux/pinctrl/consumer.h for devm_pinctrl_get

I couldn't compile test it w/o it.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2 7/7] tty: serial: msm_geni_serial: Add serial driver support for GENI based QUP

2018-02-14 Thread Amit Kucheria 
On Sat, Jan 13, 2018 at 6:35 AM, Karthikeyan Ramasubramanian
 wrote:
> This driver supports GENI based UART Controller in the Qualcomm SOCs. The
> Qualcomm Generic Interface (GENI) is a programmable module supporting a
> wide range of serial interfaces including UART. This driver support console
> operations using FIFO mode of transfer.
>
> Signed-off-by: Girish Mahadevan 
> Signed-off-by: Karthikeyan Ramasubramanian 
> Signed-off-by: Sagar Dharia 
> ---
>  drivers/tty/serial/Kconfig|   10 +
>  drivers/tty/serial/Makefile   |1 +
>  drivers/tty/serial/qcom_geni_serial.c | 1414 
> +
>  3 files changed, 1425 insertions(+)
>  create mode 100644 drivers/tty/serial/qcom_geni_serial.c

> +   if (!uport->membase) {
> +   ret = -ENOMEM;
> +   dev_err(>dev, "Err IO mapping serial iomem");
> +   goto exit_geni_serial_probe;
> +   }
> +
> +   dev_port->serial_rsc.geni_pinctrl = devm_pinctrl_get(>dev);

You need to include linux/pinctrl/consumer.h for devm_pinctrl_get

I couldn't compile test it w/o it.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [patch 1/2] mm, page_alloc: extend kernelcore and movablecore for percent

2018-02-14 Thread David Rientjes 
On Wed, 14 Feb 2018, Michal Hocko wrote:

> I do not have any objections regarding the extension. What I am more
> interested in is _why_ people are still using this command line
> parameter at all these days. Why would anybody want to introduce lowmem
> issues from 32b days. I can see the CMA/Hotplug usecases for
> ZONE_MOVABLE but those have their own ways to define zone movable. I was
> tempted to simply remove the kernelcore already. Could you be more
> specific what is your usecase which triggered a need of an easier
> scaling of the size?

Fragmentation of non-__GFP_MOVABLE pages due to low on memory situations 
can pollute most pageblocks on the system, as much as 1GB of slab being 
fragmented over 128GB of memory, for example.  When the amount of kernel 
memory is well bounded for certain systems, it is better to aggressively 
reclaim from existing MIGRATE_UNMOVABLE pageblocks rather than eagerly 
fallback to others.

We have additional patches that help with this fragmentation if you're 
interested, specifically kcompactd compaction of MIGRATE_UNMOVABLE 
pageblocks triggered by fallback of non-__GFP_MOVABLE allocations and 
draining of pcp lists back to the zone free area to prevent stranding.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [patch 1/2] mm, page_alloc: extend kernelcore and movablecore for percent

2018-02-14 Thread Michal Hocko 
On Mon 12-02-18 16:24:25, David Rientjes wrote:
> Both kernelcore= and movablecore= can be used to define the amount of
> ZONE_NORMAL and ZONE_MOVABLE on a system, respectively.  This requires
> the system memory capacity to be known when specifying the command line,
> however.
> 
> This introduces the ability to define both kernelcore= and movablecore=
> as a percentage of total system memory.  This is convenient for systems
> software that wants to define the amount of ZONE_MOVABLE, for example, as
> a proportion of a system's memory rather than a hardcoded byte value.
> 
> To define the percentage, the final character of the parameter should be
> a '%'.

I do not have any objections regarding the extension. What I am more
interested in is _why_ people are still using this command line
parameter at all these days. Why would anybody want to introduce lowmem
issues from 32b days. I can see the CMA/Hotplug usecases for
ZONE_MOVABLE but those have their own ways to define zone movable. I was
tempted to simply remove the kernelcore already. Could you be more
specific what is your usecase which triggered a need of an easier
scaling of the size?
-- 
Michal Hocko
SUSE Labs
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation: kdump: describe jumping to dump-capture kernel

2018-02-14 Thread Gi-Oh Kim 
On Wed, Feb 14, 2018 at 10:17 AM, Bhupesh SHARMA
 wrote:
> On Wed, Feb 14, 2018 at 2:32 PM, Gi-Oh Kim  wrote:
>> On Wed, Feb 14, 2018 at 2:43 AM, Dave Young  wrote:
>>> Hi,
>>> On 02/13/18 at 04:22pm, Gioh Kim wrote:
 Jumping between the system kernel and the dump-capture kernel
 has been supported for long time but there is no description
 how to use it. This patch adds the description how to use kexec tool
 to jump to the dump-capture kernel and jump back to the system kernel.
>>>
>>> I do not think this should belong to kdump documentation.  There are a
>>> lot of choices after a vmcore saving, one can reboot, halt, even go
>>> ahead with real root filesystem init path.  We do not need to document
>>> all these in kdump.txt.
>>>
>>> Since it is a general use case not only for kdump, add more info in
>>> kexec man page would be better.
>>
>> Hi,
>>
>> Whenever I find a kernel option, I search Documentation files, and
>> next is google.
>> So I think it would be better to describe how to use a kernel option
>> or kernel feature in kernel document.
>
> But this is not the kernel documentation for kexec warm reboot.
> Instead this is the kdump documentation. The example you quoted above
> is the 'kexec -l' use case and not 'kexec -p'.


I thought enabling CONFIG_KEXEC_JUMP in kernel is the main topic
and describing 'kexec -l' is showing how to use the CONFIG_KEXEC_JUMP option.
Ok, I'll check the manual page of kexec.
I think it would be enough if I add a short note for -l and
--load-preserve-context about the kernel option.

Thank you ;-)


>
> Rather the man page for kexec-tools should be a good place to include
> this documentation.
>
> Regards,
> Bhupesh
>
>>>

 Signed-off-by: Gioh Kim 
 ---
  Documentation/kdump/kdump.txt | 38 ++
  1 file changed, 38 insertions(+)

 diff --git a/Documentation/kdump/kdump.txt b/Documentation/kdump/kdump.txt
 index 51814450a7f8..35b71fef5d88 100644
 --- a/Documentation/kdump/kdump.txt
 +++ b/Documentation/kdump/kdump.txt
 @@ -460,6 +460,44 @@ and the system will boot into the dump-capture kernel.
  For testing purposes, you can trigger a crash by using "ALT-SysRq-c",
  "echo c > /proc/sysrq-trigger" or write a module to force the panic.

 +Jump between the System kernel and the Dump-capture kernel
 +===
 +
 +Without system crash, the system can jump to the dump-capture kernel.
 +
 +1) Enable "jump between system kernel and dump-capture kernel" support 
 under
 +   "Processor type and features"
 +
 +   CONFIG_KEXEC_JUMP=y
 +
 +2) Load the dump-capture kernel with --load-preserve-context and mem-max
 +   options as following.
 +
 +   kexec -l  \
 +   --initrd= --args-linux \
 +   --append="root= " \
 +   --load-preserve-context \
 +   --mem-max=
 +
 +3) Jump to the loaded kernel
 +
 +   kexec -e
 +
 +Now the system is running with the dump-capture kernel. You can jump back
 +to the system kernel.
 +
 +1) Find kexec_jump_back_entry address in kernel booting parameters in
 +   /proc/cmdline. That is the address for kexec to jump to. For example:
 +   kexec_jump_back_entry=0x000810d2
 +
 +2) Following command sets the jump-back address for kexec.
 +
 +   kexec --load-jump-back-helper --entry=0x810d2
 +
 +3) Jump to the system kernel
 +
 +   kexec -e
 +
  Write Out the Dump File
  ===

 --
 2.11.0

>>>
>>> Thanks
>>> Dave
>>
>>
>>
>> --
>> GIOH KIM
>> Linux Kernel Entwickler
>>
>> ProfitBricks GmbH
>> Greifswalder Str. 207
>> D - 10405 Berlin
>>
>> Tel:   +49 176 2697 8962
>> Fax:  +49 30 577 008 299
>> Email:gi-oh@profitbricks.com
>> URL:  https://www.profitbricks.de
>>
>> Sitz der Gesellschaft: Berlin
>> Registergericht: Amtsgericht Charlottenburg, HRB 125506 B
>> Geschäftsführer: Achim Weiss, Matthias Steinberg



-- 
GIOH KIM
Linux Kernel Entwickler

ProfitBricks GmbH
Greifswalder Str. 207
D - 10405 Berlin

Tel:   +49 176 2697 8962
Fax:  +49 30 577 008 299
Email:gi-oh@profitbricks.com
URL:  https://www.profitbricks.de

Sitz der Gesellschaft: Berlin
Registergericht: Amtsgericht Charlottenburg, HRB 125506 B
Geschäftsführer: Achim Weiss, Matthias Steinberg
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 0/2] Update lockdep doc and add section about annotations

2018-02-14 Thread Peter Zijlstra 
On Tue, Feb 13, 2018 at 07:55:17PM +0100, Juri Lelli wrote:
> Hi,
> 
> a couple of patches to lockdep docs.
> 
> First one is a small fix for that fact that Peter made documentation
> stale (as usual :P).
> 
> Second one is an RFC. I thought that adding some info about lockdep
> asserts might help spread adoption even wider (mostly regarding
> lockdep_pin_lock stuff, which is pretty new and maybe got unnoticed
> outside of the scheduler?).

Thanks for writing that Juri!

Acked-by: Peter Zijlstra (Intel) 
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation: kdump: describe jumping to dump-capture kernel

2018-02-14 Thread Bhupesh SHARMA 
On Wed, Feb 14, 2018 at 2:32 PM, Gi-Oh Kim  wrote:
> On Wed, Feb 14, 2018 at 2:43 AM, Dave Young  wrote:
>> Hi,
>> On 02/13/18 at 04:22pm, Gioh Kim wrote:
>>> Jumping between the system kernel and the dump-capture kernel
>>> has been supported for long time but there is no description
>>> how to use it. This patch adds the description how to use kexec tool
>>> to jump to the dump-capture kernel and jump back to the system kernel.
>>
>> I do not think this should belong to kdump documentation.  There are a
>> lot of choices after a vmcore saving, one can reboot, halt, even go
>> ahead with real root filesystem init path.  We do not need to document
>> all these in kdump.txt.
>>
>> Since it is a general use case not only for kdump, add more info in
>> kexec man page would be better.
>
> Hi,
>
> Whenever I find a kernel option, I search Documentation files, and
> next is google.
> So I think it would be better to describe how to use a kernel option
> or kernel feature in kernel document.

But this is not the kernel documentation for kexec warm reboot.
Instead this is the kdump documentation. The example you quoted above
is the 'kexec -l' use case and not 'kexec -p'.

Rather the man page for kexec-tools should be a good place to include
this documentation.

Regards,
Bhupesh

>>
>>>
>>> Signed-off-by: Gioh Kim 
>>> ---
>>>  Documentation/kdump/kdump.txt | 38 ++
>>>  1 file changed, 38 insertions(+)
>>>
>>> diff --git a/Documentation/kdump/kdump.txt b/Documentation/kdump/kdump.txt
>>> index 51814450a7f8..35b71fef5d88 100644
>>> --- a/Documentation/kdump/kdump.txt
>>> +++ b/Documentation/kdump/kdump.txt
>>> @@ -460,6 +460,44 @@ and the system will boot into the dump-capture kernel.
>>>  For testing purposes, you can trigger a crash by using "ALT-SysRq-c",
>>>  "echo c > /proc/sysrq-trigger" or write a module to force the panic.
>>>
>>> +Jump between the System kernel and the Dump-capture kernel
>>> +===
>>> +
>>> +Without system crash, the system can jump to the dump-capture kernel.
>>> +
>>> +1) Enable "jump between system kernel and dump-capture kernel" support 
>>> under
>>> +   "Processor type and features"
>>> +
>>> +   CONFIG_KEXEC_JUMP=y
>>> +
>>> +2) Load the dump-capture kernel with --load-preserve-context and mem-max
>>> +   options as following.
>>> +
>>> +   kexec -l  \
>>> +   --initrd= --args-linux \
>>> +   --append="root= " \
>>> +   --load-preserve-context \
>>> +   --mem-max=
>>> +
>>> +3) Jump to the loaded kernel
>>> +
>>> +   kexec -e
>>> +
>>> +Now the system is running with the dump-capture kernel. You can jump back
>>> +to the system kernel.
>>> +
>>> +1) Find kexec_jump_back_entry address in kernel booting parameters in
>>> +   /proc/cmdline. That is the address for kexec to jump to. For example:
>>> +   kexec_jump_back_entry=0x000810d2
>>> +
>>> +2) Following command sets the jump-back address for kexec.
>>> +
>>> +   kexec --load-jump-back-helper --entry=0x810d2
>>> +
>>> +3) Jump to the system kernel
>>> +
>>> +   kexec -e
>>> +
>>>  Write Out the Dump File
>>>  ===
>>>
>>> --
>>> 2.11.0
>>>
>>
>> Thanks
>> Dave
>
>
>
> --
> GIOH KIM
> Linux Kernel Entwickler
>
> ProfitBricks GmbH
> Greifswalder Str. 207
> D - 10405 Berlin
>
> Tel:   +49 176 2697 8962
> Fax:  +49 30 577 008 299
> Email:gi-oh@profitbricks.com
> URL:  https://www.profitbricks.de
>
> Sitz der Gesellschaft: Berlin
> Registergericht: Amtsgericht Charlottenburg, HRB 125506 B
> Geschäftsführer: Achim Weiss, Matthias Steinberg
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation: kdump: describe jumping to dump-capture kernel

2018-02-14 Thread Gi-Oh Kim 
On Wed, Feb 14, 2018 at 2:43 AM, Dave Young  wrote:
> Hi,
> On 02/13/18 at 04:22pm, Gioh Kim wrote:
>> Jumping between the system kernel and the dump-capture kernel
>> has been supported for long time but there is no description
>> how to use it. This patch adds the description how to use kexec tool
>> to jump to the dump-capture kernel and jump back to the system kernel.
>
> I do not think this should belong to kdump documentation.  There are a
> lot of choices after a vmcore saving, one can reboot, halt, even go
> ahead with real root filesystem init path.  We do not need to document
> all these in kdump.txt.
>
> Since it is a general use case not only for kdump, add more info in
> kexec man page would be better.

Hi,

Whenever I find a kernel option, I search Documentation files, and
next is google.
So I think it would be better to describe how to use a kernel option
or kernel feature in kernel document.


>
>>
>> Signed-off-by: Gioh Kim 
>> ---
>>  Documentation/kdump/kdump.txt | 38 ++
>>  1 file changed, 38 insertions(+)
>>
>> diff --git a/Documentation/kdump/kdump.txt b/Documentation/kdump/kdump.txt
>> index 51814450a7f8..35b71fef5d88 100644
>> --- a/Documentation/kdump/kdump.txt
>> +++ b/Documentation/kdump/kdump.txt
>> @@ -460,6 +460,44 @@ and the system will boot into the dump-capture kernel.
>>  For testing purposes, you can trigger a crash by using "ALT-SysRq-c",
>>  "echo c > /proc/sysrq-trigger" or write a module to force the panic.
>>
>> +Jump between the System kernel and the Dump-capture kernel
>> +===
>> +
>> +Without system crash, the system can jump to the dump-capture kernel.
>> +
>> +1) Enable "jump between system kernel and dump-capture kernel" support under
>> +   "Processor type and features"
>> +
>> +   CONFIG_KEXEC_JUMP=y
>> +
>> +2) Load the dump-capture kernel with --load-preserve-context and mem-max
>> +   options as following.
>> +
>> +   kexec -l  \
>> +   --initrd= --args-linux \
>> +   --append="root= " \
>> +   --load-preserve-context \
>> +   --mem-max=
>> +
>> +3) Jump to the loaded kernel
>> +
>> +   kexec -e
>> +
>> +Now the system is running with the dump-capture kernel. You can jump back
>> +to the system kernel.
>> +
>> +1) Find kexec_jump_back_entry address in kernel booting parameters in
>> +   /proc/cmdline. That is the address for kexec to jump to. For example:
>> +   kexec_jump_back_entry=0x000810d2
>> +
>> +2) Following command sets the jump-back address for kexec.
>> +
>> +   kexec --load-jump-back-helper --entry=0x810d2
>> +
>> +3) Jump to the system kernel
>> +
>> +   kexec -e
>> +
>>  Write Out the Dump File
>>  ===
>>
>> --
>> 2.11.0
>>
>
> Thanks
> Dave



-- 
GIOH KIM
Linux Kernel Entwickler

ProfitBricks GmbH
Greifswalder Str. 207
D - 10405 Berlin

Tel:   +49 176 2697 8962
Fax:  +49 30 577 008 299
Email:gi-oh@profitbricks.com
URL:  https://www.profitbricks.de

Sitz der Gesellschaft: Berlin
Registergericht: Amtsgericht Charlottenburg, HRB 125506 B
Geschäftsführer: Achim Weiss, Matthias Steinberg
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html