Re: [PATCH 1/2] scripts/kernel-doc: Add option to inject line numbers
On Fri, 03 Jun 2016, Daniel Vetter wrote:
> Opt-in since this wreaks the rst output and must be removed
> by consumers again. This is useful to adjust the linenumbers
> for included kernel-doc snippets in shinx. With that sphinx
> error message will be accurate when there's issues with the
> rst-ness of the kernel-doc comments.
>
> Especially when transitioning a new docbook .tmpl to .rst this
> is extremely useful, since you can just use your editors compilation
> quickfix list to accurately jump from error to error.
>
> v2:
> - Also make sure that we filter the LINENO for purpose/at declaration
> start so it only shows for selected blocks, not all of them (Jani).
> While at it make it a notch more accurate.
> - Avoid undefined $lineno issues. I tried filtering these out at the
> callsite, but Jani spotted more when linting the entire kernel.
> Unamed unions and similar things aren't stored consistently and end
> up with an undefined line number (but also no kernel-doc text, just
> the parameter type). Simplify things and filter undefined line
> numbers in print_lineno() to catch them all.
>
> v3: Fix LINENO 0 issue for kernel-doc comments without @param: lines
> or any other special sections that directly jump to the description
> after the "name - purpose" line. Only really possible for functions
> without parameters. Noticed by Jani.
Verified, with extra scripting on a bunch of files, and pushed both to
my sphinx-for-docs-next branch.
BR,
Jani.
>
> Cc: Jani Nikula
> Cc: linux-doc@vger.kernel.org
> Cc: Jonathan Corbet
> Signed-off-by: Daniel Vetter
> ---
> scripts/kernel-doc | 41 +
> 1 file changed, 41 insertions(+)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index 4da6f952d18b..5192213c5005 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -74,6 +74,8 @@ Output selection (mutually exclusive):
>
> Output selection modifiers:
>-no-doc-sections Do not output DOC: sections.
> + -enable-linenoEnable output of #define LINENO lines. Only works
> with
> +reStructuredText format.
>
> Other parameters:
>-v Verbose output, more warnings and other information.
> @@ -319,6 +321,7 @@ my $verbose = 0;
> my $output_mode = "man";
> my $output_preformatted = 0;
> my $no_doc_sections = 0;
> +my $enable_lineno = 0;
> my @highlights = @highlights_man;
> my $blankline = $blankline_man;
> my $modulename = "Kernel API";
> @@ -351,6 +354,7 @@ my $man_date = ('January', 'February', 'March', 'April',
> 'May', 'June',
> # CAVEAT EMPTOR! Some of the others I localised may not want to be, which
> # could cause "use of undefined value" or other bugs.
> my ($function, %function_table, %parametertypes, $declaration_purpose);
> +my $declaration_start_line;
> my ($type, $declaration_name, $return_type);
> my ($newsection, $newcontents, $prototype, $brcount, %source_map);
>
> @@ -411,13 +415,16 @@ my $doc_inline_end = '^\s*\*/\s*$';
> my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
>
> my %parameterdescs;
> +my %parameterdesc_start_lines;
> my @parameterlist;
> my %sections;
> my @sectionlist;
> +my %section_start_lines;
> my $sectcheck;
> my $struct_actual;
>
> my $contents = "";
> +my $new_start_line = 0;
>
> # the canonical section names. see also $doc_sect above.
> my $section_default = "Description"; # default section
> @@ -486,6 +493,8 @@ while ($ARGV[0] =~ m/^-(.*)/) {
> usage();
> } elsif ($cmd eq '-no-doc-sections') {
> $no_doc_sections = 1;
> +} elsif ($cmd eq '-enable-lineno') {
> + $enable_lineno = 1;
> } elsif ($cmd eq '-show-not-found') {
> $show_not_found = 1;
> }
> @@ -503,6 +512,13 @@ sub get_kernel_version() {
> return $version;
> }
>
> +#
> +sub print_lineno {
> +my $lineno = shift;
> +if ($enable_lineno && defined($lineno)) {
> +print "#define LINENO " . $lineno . "\n";
> +}
> +}
> ##
> # dumps section contents to arrays/hashes intended for that purpose.
> #
> @@ -516,11 +532,15 @@ sub dump_section {
> $name = $1;
> $parameterdescs{$name} = $contents;
> $sectcheck = $sectcheck . $name . " ";
> +$parameterdesc_start_lines{$name} = $new_start_line;
> +$new_start_line = 0;
> } elsif ($name eq "@\.\.\.") {
> #print STDERR "parameter def '...' = '$contents'\n";
> $name = "...";
> $parameterdescs{$name} = $contents;
> $sectcheck = $sectcheck . $name . " ";
> +$parameterdesc_start_lines{$name} = $new_start_line;
> +$new_start_line = 0;
> } else {
> #print STDERR "other section '$name' = '$contents'\n";
> if (defined($sections{$name}) && ($sections{$name} ne "")) {
> @@ -530,6 +550,8 @@ sub dump_section {
> } else {
> $sections{$name} = $contents;
> push @sectionlist, $name;
> +$section_start_lines{$name} =
Re: [PATCH 21/23] arm64: ilp32: introduce ilp32-specific handlers for sigframe and ucontext
Hi,
I found an issue of unwind with the following code. The correct backtrace
should be:
(gdb) where
#0 0x004004d0 in my_sig (sig=11) at test_force3.c:16
#1
#2 func2 (num=0) at test_force3.c:22
#3 0x00400540 in func1 (num=1) at test_force3.c:28
#4 0x00400574 in main (argc=1, argv=0xffd7bc04) at test_force3.c:33
Without my patch, the backtrace is:
(gdb) where
#0 0x00400490 in my_sig (sig=11) at test_force3.c:16
#1
#2 0x004004e4 in main (argc=1, argv=0xffe6f8f4) at test_force3.c:33
With my patch which fix the wrong frame pointer(setup_return calculate the
offset
of fp through ilp32_sigframe instead of sigfreame), the backtrace is:
(gdb) where
#0 0x00400490 in my_sig (sig=11) at test_force3.c:16
#1
#2 func1 () at test_force3.c:28
#3 0x004004e4 in main (argc=1, argv=0xffe6f8f4) at test_force3.c:33
I am not sure there is still some issue in kernel. But it seem that the gdb of
ilp32
does not work correctly when unwind without framepointer.
The test code is:
#include
#include
#include
#include
void my_sig(int sig)
{
printf("sig=%d\n", sig);
*(int *)0 = 0x0;
}
void func2()
{
*(int *)0 = 0x0;
}
void func1()
{
func2();
}
int main(int argc, char **argv)
{
signal(11, my_sig);
func1();
return 0;
}
The full patch is as follows:
From 7e364a765097f57aed2d73f94c1688c2e7343e79 Mon Sep 17 00:00:00 2001
From: Bamvor Jian Zhang
Date: Sat, 4 Jun 2016 14:30:05 +0800
Subject: [PATCH] arm64: ilp32: fix for wrong fp offset when calculate the
new fp
ILP32 define its own sigframe(ilp32_sigframe) because of the
difference uc_context. setup_return do not use ilp32 specific
sigframe to calculate the new offset of fp which lead to wrong
fp in signal handler. At this circumstance, gdb backtrace will miss
one item:
(gdb) where
It should be:
(gdb) where
The test code is as follows:
void my_sig(int sig)
{
printf("sig=%d\n", sig);
*(int *)0 = 0x0;
}
void func2(int num)
{
printf("%s: %d\n", __FUNCTION__, num);
*(int *)0 = 0x0;
func2(num-1);
}
void func1(int num)
{
printf("%s\n", __FUNCTION__);
func2(num - 1);
}
int main(int argc, char **argv)
{
signal(11, my_sig);
func1(argc);
return 0;
}
This patch fix this by passing the correct offset of fp to
setup_return.
Test pass on both ILP32 and LP64 in aarch64 EE.
Signed-off-by: Bamvor Jian Zhang
---
arch/arm64/include/asm/signal_common.h | 3 ++-
arch/arm64/kernel/signal.c | 9 +
arch/arm64/kernel/signal_ilp32.c | 4 ++--
3 files changed, 9 insertions(+), 7 deletions(-)
diff --git a/arch/arm64/include/asm/signal_common.h
b/arch/arm64/include/asm/signal_common.h
index de93c71..a5d7b63 100644
--- a/arch/arm64/include/asm/signal_common.h
+++ b/arch/arm64/include/asm/signal_common.h
@@ -29,6 +29,7 @@ int setup_sigcontex(struct sigcontext __user *uc_mcontext,
struct pt_regs *regs);
int restore_sigcontext(struct pt_regs *regs, struct sigcontext __user *sf);
void setup_return(struct pt_regs *regs, struct k_sigaction *ka,
- void __user *frame, off_t sigframe_off, int usig);
+ void __user *frame, off_t sigframe_off, off_t fp_off,
+ int usig);
#endif /* __ASM_SIGNAL_COMMON_H */
diff --git a/arch/arm64/kernel/signal.c b/arch/arm64/kernel/signal.c
index 038bebe..e66a6e9 100644
--- a/arch/arm64/kernel/signal.c
+++ b/arch/arm64/kernel/signal.c
@@ -256,14 +256,14 @@ static struct rt_sigframe __user *get_sigframe(struct
ksignal *ksig,
}
void setup_return(struct pt_regs *regs, struct k_sigaction *ka,
-void __user *frame, off_t sigframe_off, int usig)
+void __user *frame, off_t sigframe_off, off_t fp_off,
+int usig)
{
__sigrestore_t sigtramp;
regs->regs[0] = usig;
regs->sp = (unsigned long)frame;
- regs->regs[29] = regs->sp + sigframe_off +
- offsetof(struct sigframe, fp);
+ regs->regs[29] = regs->sp + sigframe_off + fp_off;
regs->pc = (unsigned long)ka->sa.sa_handler;
if (ka->sa.sa_flags & SA_RESTORER)
@@ -294,7 +294,8 @@ static int setup_rt_frame(int usig, struct ksignal *ksig,
sigset_t *set,
err |= setup_sigframe(&frame->sig, regs, set);
if (err == 0) {
setup_return(regs, &ksig->ka, frame,
- offsetof(struct rt_sigframe, sig), usig);
+ offsetof(struct rt_sigframe, sig),
+ offsetof(struct sigframe, fp), usig);
if (ksig->ka.sa.sa_flags & SA_SIGINFO) {
err |= copy_siginfo_to_user(&frame->info, &ksig->info);
regs->regs[1] = (unsigned long)&frame->info;
diff --git a/arch/arm64/kernel/signal_ilp32.c b/arch/arm64/kernel/signal_ilp32.c
index a8ea73e..9030f14 100644
--- a/arch/arm64/kernel/signal_ilp32.c
+++ b/arch/arm64/kernel/signal_i
[PATCH v2 00/38] Documentation/sphinx
Jon, this is v2 of [1] and [2], with a considerable amount of polish and fixes added. We started dogfooding this within drm-intel, and Daniel has reviewed the lot and contributed a number of fixes, most notably accurate file and line number references from Sphinx build errors/warnings to the kernel-doc comments in source code. We believe this is now in good shape for merging for v4.8. It's all in my sphinx-for-docs-next branch that you've already looked at; pull details below. When this lands in docs-next and we can backmerge to drm, we'll plunge ahead and convert gpu.tmpl to rst, and have that ready for v4.8. We think it's best to contribute that via the drm tree, as it'll involve splitting up the documentation and likely numerous updates to kernel-doc comments. I plan to update Documentation/kernel-doc-nano-HOWTO.txt for Sphinx and rst, obviously converting it to rst while at it. BR, Jani. [1] http://mid.gmane.org/cover.1463748027.git.jani.nik...@intel.com [2] http://mid.gmane.org/877fec7gfm@intel.com The following changes since commit 1a695a905c18548062509178b98bc91e67510864: Linux 4.7-rc1 (2016-05-29 09:29:24 -0700) are available in the git repository at: git://people.freedesktop.org/~jani/drm sphinx-for-docs-next for you to fetch changes up to d90368f2fa7ded7c56d214aef087e88bba5199e7: doc/sphinx: Track line-number of starting blocks (2016-06-04 11:35:59 +0300) Daniel Vetter (6): doc/sphinx: Pass right filename as source scripts/kernel-doc: Remove duplicated DOC: start handling doc/sphinx: Stop touching state_machine internals scripts/kernel-doc: Also give functions symbolic names scripts/kernel-doc: Add option to inject line numbers doc/sphinx: Track line-number of starting blocks Jani Nikula (31): kernel-doc/rst: fix use of uninitialized value kernel-doc: support printing exported and non-exported symbols Documentation/sphinx: add basic working Sphinx configuration and build Documentation: add .gitignore Documentation/sphinx: add Sphinx kernel-doc directive extension Documentation/sphinx: configure the kernel-doc extension Documentation/sphinx: set version and release properly sphinx: update docbook->rst conversion script match C domain spec Documentation/sphinx: nicer referencing of struct in docbook->rst conversion kernel-doc: add names for states and substates kernel-doc: add names for output selection kernel-doc/rst: do not output DOC: section titles for requested ones kernel-doc/rst: reference functions according to C domain spec kernel-doc/rst: &foo references are more universal than structs kernel-doc/rst: add support for &union foo and &typedef foo references kernel-doc/rst: add support for struct/union/enum member references kernel-doc/rst: drop redundant unescape in highlighting kernel-doc/rst: highlight function/struct/enum purpose lines too kernel-doc: do not regard $, %, or & prefixes as special in section names kernel-doc: fix wrong code indentation kernel-doc/rst: blank lines in output are not needed kernel-doc: strip leading blank lines from inline doc comments kernel-doc/rst: change the output layout kernel-doc: improve handling of whitespace on the first line param description kernel-doc: strip leading whitespace from continued param descs kernel-doc/rst: use *undescribed* instead of _undescribed_ kernel-doc/rst: remove fixme comment kernel-doc: limit the "section header:" detection to a select few kernel-doc: concatenate contents of colliding sections kernel-doc: reset contents and section harder Documentation/sphinx: fix kernel-doc extension on python3 Jonathan Corbet (1): sphinx: cheesy script to convert .tmpl files Documentation/.gitignore | 1 + Documentation/DocBook/Makefile| 7 +- Documentation/Makefile.sphinx | 63 + Documentation/conf.py | 414 ++ Documentation/index.rst | 23 ++ Documentation/sphinx/convert_template.sed | 18 ++ Documentation/sphinx/kernel-doc.py| 127 + Documentation/sphinx/post_convert.sed | 23 ++ Documentation/sphinx/tmplcvt | 19 ++ Makefile | 5 +- scripts/kernel-doc| 392 ++-- 11 files changed, 948 insertions(+), 144 deletions(-) create mode 100644 Documentation/.gitignore create mode 100644 Documentation/Makefile.sphinx create mode 100644 Documentation/conf.py create mode 100644 Documentation/index.rst create mode 100644 Documentation/sphinx/convert_template.sed create mode 100644 Documentation/sphinx/kernel-doc.py create mode 100644 Documentation/sphinx/post_convert.sed create mode 100755 Do
[PATCH v2 01/38] kernel-doc/rst: fix use of uninitialized value
I'm not quite sure why the errors below are happening, but this fixes
them.
Use of uninitialized value in string ne at ./scripts/kernel-doc line 1819,
line 6494.
Use of uninitialized value $_[0] in join or string at ./scripts/kernel-doc line
1759, line 6494.
Signed-off-by: Jani Nikula
---
scripts/kernel-doc | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 2fc8fad5195e..babb374c043d 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1803,7 +1803,8 @@ sub output_function_rst(%) {
} else {
print " ``$parameter``\n";
}
- if ($args{'parameterdescs'}{$parameter_name} ne $undescribed) {
+ if (defined($args{'parameterdescs'}{$parameter_name}) &&
+ $args{'parameterdescs'}{$parameter_name} ne $undescribed) {
my $oldprefix = $lineprefix;
$lineprefix = "";
output_highlight_rst($args{'parameterdescs'}{$parameter_name});
--
2.1.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
[PATCH v2 18/38] kernel-doc/rst: drop redundant unescape in highlighting
This bit is already done by xml_unescape() above.
Signed-off-by: Jani Nikula
---
scripts/kernel-doc | 1 -
1 file changed, 1 deletion(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index e0fd14f6d711..8f9eac509377 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1796,7 +1796,6 @@ sub output_highlight_rst {
if ($line eq "") {
print $lineprefix, $blankline;
} else {
- $line =~ s/\\/\&/g;
print $lineprefix, $line;
}
print "\n";
--
2.1.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
[PATCH v2 05/38] Documentation/sphinx: add Sphinx kernel-doc directive extension
Add an extension to handle kernel-doc directives, to call kernel-doc
according to the arguments and parameters given to the reStructuredText
directive.
The syntax for the kernel-doc directive is:
.. kernel-doc:: FILENAME
:export:
:internal:
:functions: FUNCTION [FUNCTION ...]
:doc: SECTION TITLE
Of the directive options export, internal, functions, and doc, currently
only one option may be given at a time.
The FILENAME is relative from the kernel source tree root.
The extension notifies Sphinx about the document dependency on FILENAME,
causing the document to be rebuilt when the file has been changed.
Signed-off-by: Jani Nikula
---
Documentation/sphinx/kernel-doc.py | 102 +
1 file changed, 102 insertions(+)
create mode 100644 Documentation/sphinx/kernel-doc.py
diff --git a/Documentation/sphinx/kernel-doc.py
b/Documentation/sphinx/kernel-doc.py
new file mode 100644
index ..87a1332fe934
--- /dev/null
+++ b/Documentation/sphinx/kernel-doc.py
@@ -0,0 +1,102 @@
+# coding=utf-8
+#
+# Copyright © 2016 Intel Corporation
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the "Software"),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice (including the next
+# paragraph) shall be included in all copies or substantial portions of the
+# Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+#
+# Authors:
+#Jani Nikula
+
+import os
+import subprocess
+import sys
+
+from docutils import nodes, statemachine
+from docutils.parsers.rst import directives
+from sphinx.util.compat import Directive
+
+class KernelDocDirective(Directive):
+"""Extract kernel-doc comments from the specified file"""
+required_argument = 1
+optional_arguments = 4
+option_spec = {
+'doc': directives.unchanged_required,
+'functions': directives.unchanged_required,
+'export': directives.flag,
+'internal': directives.flag,
+}
+has_content = False
+
+def run(self):
+env = self.state.document.settings.env
+cmd = [env.config.kerneldoc_bin, '-rst']
+
+filename = env.config.kerneldoc_srctree + '/' + self.arguments[0]
+
+# Tell sphinx of the dependency
+env.note_dependency(os.path.abspath(filename))
+
+tab_width = self.options.get('tab-width',
self.state.document.settings.tab_width)
+source = self.state_machine.input_lines.source(self.lineno -
self.state_machine.input_offset - 1)
+
+# FIXME: make this nicer and more robust against errors
+if 'export' in self.options:
+cmd += ['-export']
+elif 'internal' in self.options:
+cmd += ['-internal']
+elif 'doc' in self.options:
+cmd += ['-function', str(self.options.get('doc'))]
+elif 'functions' in self.options:
+for f in str(self.options.get('functions')).split(' '):
+cmd += ['-function', f]
+
+cmd += [filename]
+
+try:
+env.app.verbose('calling kernel-doc \'%s\'' % (" ".join(cmd)))
+
+p = subprocess.Popen(cmd, stdout=subprocess.PIPE,
stderr=subprocess.PIPE, universal_newlines=True)
+out, err = p.communicate()
+
+# assume the kernel sources are utf-8
+out, err = unicode(out, 'utf-8'), unicode(err, 'utf-8')
+
+if p.returncode != 0:
+sys.stderr.write(err)
+
+env.app.warn('kernel-doc \'%s\' failed with return code %d' %
(" ".join(cmd), p.returncode))
+return [nodes.error(None, nodes.paragraph(text = "kernel-doc
missing"))]
+elif env.config.kerneldoc_verbosity > 0:
+sys.stderr.write(err)
+
+lines = statemachine.string2lines(out, tab_width,
convert_whitespace=True)
+self.state_machine.insert_input(lines, source)
+return []
+except Exception as e:
+env.app.warn('kernel-doc \'%s\' processing failed with: %s' %
+ (" ".join(cmd), str(e)))
+return [nodes.error(None, nodes.paragraph(text = "kernel-doc
missing"))]
+
+def setup(app):
+app.add_config_v
[PATCH v2 34/38] scripts/kernel-doc: Remove duplicated DOC: start handling
From: Daniel Vetter
Further up in the state machinery we switch from STATE_NAME to
STATE_DOCBLOCK when we match /$doc_block/. Which means this block of
code here is entirely unreachable, unless there are multiple DOC:
sections within a single kernel-doc comment.
Getting a list of all the files with more than one DOC: section using
$ git grep -c " * DOC:" | grep -v ":1$"
and then doing a full audit of them reveals there are no such comment
blocks in the kernel.
Supporting multiple DOC: sections in a single kernel-doc comment does
not seem like a recommended way of doing things anyway, so nuke the code
for simplicity.
Cc: Jani Nikula
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet
Signed-off-by: Daniel Vetter
[Jani: amended the commit message]
Signed-off-by: Jani Nikula
---
scripts/kernel-doc | 19 +--
1 file changed, 1 insertion(+), 18 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 0eb2e7b5bf10..9fb26d142a56 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -2942,24 +2942,7 @@ sub process_file($) {
process_state3_type($_, $file);
}
} elsif ($state == STATE_DOCBLOCK) {
- # Documentation block
- if (/$doc_block/) {
- dump_doc_section($file, $section,
xml_escape($contents));
- $contents = "";
- $function = "";
- %parameterdescs = ();
- %parametertypes = ();
- @parameterlist = ();
- %sections = ();
- @sectionlist = ();
- $prototype = "";
- if ( $1 eq "" ) {
- $section = $section_intro;
- } else {
- $section = $1;
- }
- }
- elsif (/$doc_end/)
+ if (/$doc_end/)
{
dump_doc_section($file, $section,
xml_escape($contents));
$section = $section_default;
--
2.1.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
[PATCH v2 38/38] doc/sphinx: Track line-number of starting blocks
From: Daniel Vetter
Design is pretty simple: kernel-doc inserts breadcrumbs with line
numbers, and sphinx picks them up. At first I went with a sphinx
comment, but inserting those at random places seriously upsets the
parser, and must be filtered. Hence why this version now uses "#define
LINEO " since one of these ever escape into output it's pretty clear
there is a bug.
It seems to work well, and at least the 2-3 errors where sphinx
complained about something that was not correct in kernel-doc text the
line numbers matched up perfectly.
v2: Instead of noodling around in the parser state machine, create
a ViewList and parse it ourselves. This seems to be the recommended
way, per Jani's suggestion.
v3:
- Split out ViewList pach. Splitting the kernel-doc changes from the
sphinx ones isn't possible, since emitting the LINENO lines wreaks
havoc with the rst formatting. We must filter them.
- Improve the regex per Jani's suggestions, and compile it just once
for speed.
- Now that LINENO lines are eaten, also add them to function parameter
descriptions. Much less content and offset than for in-line struct
member descriptions, but still nice to know which exact continuation
line upsets sphinx.
- Simplify/clarify the line +/-1 business a bit.
v4: Split out the scripts/kernel-doc changes and make line-numbers
opt-in, as suggested by Jani.
Cc: Jani Nikula
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet
Signed-off-by: Daniel Vetter
Signed-off-by: Jani Nikula
---
Documentation/sphinx/kernel-doc.py | 17 +++--
1 file changed, 15 insertions(+), 2 deletions(-)
diff --git a/Documentation/sphinx/kernel-doc.py
b/Documentation/sphinx/kernel-doc.py
index bd422870101e..4adfb0e91ecc 100644
--- a/Documentation/sphinx/kernel-doc.py
+++ b/Documentation/sphinx/kernel-doc.py
@@ -30,6 +30,7 @@
import os
import subprocess
import sys
+import re
from docutils import nodes, statemachine
from docutils.statemachine import ViewList
@@ -50,7 +51,7 @@ class KernelDocDirective(Directive):
def run(self):
env = self.state.document.settings.env
-cmd = [env.config.kerneldoc_bin, '-rst']
+cmd = [env.config.kerneldoc_bin, '-rst', '-enable-lineno']
filename = env.config.kerneldoc_srctree + '/' + self.arguments[0]
@@ -93,7 +94,19 @@ class KernelDocDirective(Directive):
sys.stderr.write(err)
lines = statemachine.string2lines(out, tab_width,
convert_whitespace=True)
-result = ViewList(lines, source)
+result = ViewList()
+
+lineoffset = 0;
+line_regex = re.compile("^#define LINENO ([0-9]+)$")
+for line in lines:
+match = line_regex.search(line)
+if match:
+# sphinx counts lines from 0
+lineoffset = int(match.group(1)) - 1
+# we must eat our comments since the upset the markup
+else:
+result.append(line, source, lineoffset)
+lineoffset += 1
node = nodes.section()
node.document = self.state.document
--
2.1.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
[PATCH v2 35/38] doc/sphinx: Stop touching state_machine internals
From: Daniel Vetter
Instead of just forcefully inserting our kernel-doc input and letting
the state machine stumble over it the recommended way is to create
ViewList, parse that and then return the list of parsed nodes.
Suggested by Jani.
Cc: Jani Nikula
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet
Signed-off-by: Daniel Vetter
Signed-off-by: Jani Nikula
---
Documentation/sphinx/kernel-doc.py | 11 +--
1 file changed, 9 insertions(+), 2 deletions(-)
diff --git a/Documentation/sphinx/kernel-doc.py
b/Documentation/sphinx/kernel-doc.py
index 9fc2c27916a9..bd422870101e 100644
--- a/Documentation/sphinx/kernel-doc.py
+++ b/Documentation/sphinx/kernel-doc.py
@@ -32,6 +32,7 @@ import subprocess
import sys
from docutils import nodes, statemachine
+from docutils.statemachine import ViewList
from docutils.parsers.rst import directives
from sphinx.util.compat import Directive
@@ -92,8 +93,14 @@ class KernelDocDirective(Directive):
sys.stderr.write(err)
lines = statemachine.string2lines(out, tab_width,
convert_whitespace=True)
-self.state_machine.insert_input(lines, source)
-return []
+result = ViewList(lines, source)
+
+node = nodes.section()
+node.document = self.state.document
+self.state.nested_parse(result, self.content_offset, node)
+
+return node.children
+
except Exception as e:
env.app.warn('kernel-doc \'%s\' processing failed with: %s' %
(" ".join(cmd), str(e)))
--
2.1.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
[PATCH v2 37/38] scripts/kernel-doc: Add option to inject line numbers
From: Daniel Vetter
Opt-in since this wreaks the rst output and must be removed
by consumers again. This is useful to adjust the linenumbers
for included kernel-doc snippets in shinx. With that sphinx
error message will be accurate when there's issues with the
rst-ness of the kernel-doc comments.
Especially when transitioning a new docbook .tmpl to .rst this
is extremely useful, since you can just use your editors compilation
quickfix list to accurately jump from error to error.
v2:
- Also make sure that we filter the LINENO for purpose/at declaration
start so it only shows for selected blocks, not all of them (Jani).
While at it make it a notch more accurate.
- Avoid undefined $lineno issues. I tried filtering these out at the
callsite, but Jani spotted more when linting the entire kernel.
Unamed unions and similar things aren't stored consistently and end
up with an undefined line number (but also no kernel-doc text, just
the parameter type). Simplify things and filter undefined line
numbers in print_lineno() to catch them all.
v3: Fix LINENO 0 issue for kernel-doc comments without @param: lines
or any other special sections that directly jump to the description
after the "name - purpose" line. Only really possible for functions
without parameters. Noticed by Jani.
Cc: Jani Nikula
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet
Signed-off-by: Daniel Vetter
Signed-off-by: Jani Nikula
---
scripts/kernel-doc | 41 +
1 file changed, 41 insertions(+)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 4da6f952d18b..5192213c5005 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -74,6 +74,8 @@ Output selection (mutually exclusive):
Output selection modifiers:
-no-doc-sections Do not output DOC: sections.
+ -enable-linenoEnable output of #define LINENO lines. Only works with
+reStructuredText format.
Other parameters:
-v Verbose output, more warnings and other information.
@@ -319,6 +321,7 @@ my $verbose = 0;
my $output_mode = "man";
my $output_preformatted = 0;
my $no_doc_sections = 0;
+my $enable_lineno = 0;
my @highlights = @highlights_man;
my $blankline = $blankline_man;
my $modulename = "Kernel API";
@@ -351,6 +354,7 @@ my $man_date = ('January', 'February', 'March', 'April',
'May', 'June',
# CAVEAT EMPTOR! Some of the others I localised may not want to be, which
# could cause "use of undefined value" or other bugs.
my ($function, %function_table, %parametertypes, $declaration_purpose);
+my $declaration_start_line;
my ($type, $declaration_name, $return_type);
my ($newsection, $newcontents, $prototype, $brcount, %source_map);
@@ -411,13 +415,16 @@ my $doc_inline_end = '^\s*\*/\s*$';
my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
my %parameterdescs;
+my %parameterdesc_start_lines;
my @parameterlist;
my %sections;
my @sectionlist;
+my %section_start_lines;
my $sectcheck;
my $struct_actual;
my $contents = "";
+my $new_start_line = 0;
# the canonical section names. see also $doc_sect above.
my $section_default = "Description"; # default section
@@ -486,6 +493,8 @@ while ($ARGV[0] =~ m/^-(.*)/) {
usage();
} elsif ($cmd eq '-no-doc-sections') {
$no_doc_sections = 1;
+} elsif ($cmd eq '-enable-lineno') {
+ $enable_lineno = 1;
} elsif ($cmd eq '-show-not-found') {
$show_not_found = 1;
}
@@ -503,6 +512,13 @@ sub get_kernel_version() {
return $version;
}
+#
+sub print_lineno {
+my $lineno = shift;
+if ($enable_lineno && defined($lineno)) {
+print "#define LINENO " . $lineno . "\n";
+}
+}
##
# dumps section contents to arrays/hashes intended for that purpose.
#
@@ -516,11 +532,15 @@ sub dump_section {
$name = $1;
$parameterdescs{$name} = $contents;
$sectcheck = $sectcheck . $name . " ";
+$parameterdesc_start_lines{$name} = $new_start_line;
+$new_start_line = 0;
} elsif ($name eq "@\.\.\.") {
# print STDERR "parameter def '...' = '$contents'\n";
$name = "...";
$parameterdescs{$name} = $contents;
$sectcheck = $sectcheck . $name . " ";
+$parameterdesc_start_lines{$name} = $new_start_line;
+$new_start_line = 0;
} else {
# print STDERR "other section '$name' = '$contents'\n";
if (defined($sections{$name}) && ($sections{$name} ne "")) {
@@ -530,6 +550,8 @@ sub dump_section {
} else {
$sections{$name} = $contents;
push @sectionlist, $name;
+$section_start_lines{$name} = $new_start_line;
+$new_start_line = 0;
}
}
}
@@ -1775,6 +1797,7 @@ sub output_blockhead_rst(%) {
if ($output_selection != OUTPUT_INCLUDE) {
print "**$section**\n\n";
}
+print_lineno($section_start_lines{$section});
output_highlight_rst($args{'section
[PATCH v2 32/38] Documentation/sphinx: fix kernel-doc extension on python3
Reconcile differences between python2 and python3 on dealing with stdout, stderr from Popen. This fixes "name 'unicode' is not defined" errors on python3. We'll need to try to keep the extension working on both python-sphinx and python3-sphinx so we don't need two copies. Reported-and-tested-by: Marius Vlad Signed-off-by: Jani Nikula --- Documentation/sphinx/kernel-doc.py | 9 +++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/Documentation/sphinx/kernel-doc.py b/Documentation/sphinx/kernel-doc.py index 87a1332fe934..a6e170872c8a 100644 --- a/Documentation/sphinx/kernel-doc.py +++ b/Documentation/sphinx/kernel-doc.py @@ -23,6 +23,9 @@ # # Authors: #Jani Nikula +# +# Please make sure this works on both python2 and python3. +# import os import subprocess @@ -75,8 +78,10 @@ class KernelDocDirective(Directive): p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, universal_newlines=True) out, err = p.communicate() -# assume the kernel sources are utf-8 -out, err = unicode(out, 'utf-8'), unicode(err, 'utf-8') +# python2 needs conversion to unicode. +# python3 with universal_newlines=True returns strings. +if sys.version_info.major < 3: +out, err = unicode(out, 'utf-8'), unicode(err, 'utf-8') if p.returncode != 0: sys.stderr.write(err) -- 2.1.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
[PATCH v2 36/38] scripts/kernel-doc: Also give functions symbolic names
From: Daniel Vetter
state3 = prototype parsing, so name them accordingly.
Cc: Jani Nikula
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet
Signed-off-by: Daniel Vetter
Signed-off-by: Jani Nikula
---
scripts/kernel-doc | 8
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 9fb26d142a56..4da6f952d18b 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -2593,7 +2593,7 @@ sub syscall_munge() {
}
}
-sub process_state3_function($$) {
+sub process_proto_function($$) {
my $x = shift;
my $file = shift;
@@ -2623,7 +2623,7 @@ sub process_state3_function($$) {
}
}
-sub process_state3_type($$) {
+sub process_proto_type($$) {
my $x = shift;
my $file = shift;
@@ -2937,9 +2937,9 @@ sub process_file($) {
$state = STATE_INLINE;
$inline_doc_state = STATE_INLINE_NAME;
} elsif ($decl_type eq 'function') {
- process_state3_function($_, $file);
+ process_proto_function($_, $file);
} else {
- process_state3_type($_, $file);
+ process_proto_type($_, $file);
}
} elsif ($state == STATE_DOCBLOCK) {
if (/$doc_end/)
--
2.1.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
[PATCH v2 33/38] doc/sphinx: Pass right filename as source
From: Daniel Vetter
With this error output becomes almost readable. The line numbers are
still totally bonghits, but that's a lot harder to pull out of
kerneldoc. We'd essentially have to insert some special markers in the
kernel-doc output, split the output along these markers and then
insert each block separately using
state_machine.insert_input(block, source, first_line)
Cc: Jani Nikula
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet
Signed-off-by: Daniel Vetter
Signed-off-by: Jani Nikula
---
Documentation/sphinx/kernel-doc.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/sphinx/kernel-doc.py
b/Documentation/sphinx/kernel-doc.py
index a6e170872c8a..9fc2c27916a9 100644
--- a/Documentation/sphinx/kernel-doc.py
+++ b/Documentation/sphinx/kernel-doc.py
@@ -57,7 +57,7 @@ class KernelDocDirective(Directive):
env.note_dependency(os.path.abspath(filename))
tab_width = self.options.get('tab-width',
self.state.document.settings.tab_width)
-source = self.state_machine.input_lines.source(self.lineno -
self.state_machine.input_offset - 1)
+source = filename
# FIXME: make this nicer and more robust against errors
if 'export' in self.options:
--
2.1.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
[PATCH v2 28/38] kernel-doc/rst: remove fixme comment
Yes, for our purposes the type should contain typedef.
Signed-off-by: Jani Nikula
---
scripts/kernel-doc | 1 -
1 file changed, 1 deletion(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 19cee0cd53a3..425a94be04f6 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1897,7 +1897,6 @@ sub output_typedef_rst(%) {
my $oldprefix = $lineprefix;
my $name = "typedef " . $args{'typedef'};
-### FIXME: should the name below contain "typedef" or not?
print "\n\n.. c:type:: " . $name . "\n\n";
$lineprefix = " ";
output_highlight_rst($args{'purpose'});
--
2.1.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
[PATCH v2 20/38] kernel-doc: do not regard $, %, or & prefixes as special in section names
The use of these is confusing in the script, and per this grep, they're
not used anywhere anyway:
$ git grep " \* [%$&][a-zA-Z0-9_]*:" -- *.[ch] | grep -v
"\$\(Id\|Revision\|Date\)"
While at it, throw out the constants array, nothing is ever put there
again.
Signed-off-by: Jani Nikula
---
scripts/kernel-doc | 14 ++
1 file changed, 2 insertions(+), 12 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 76bad55c031e..f795660dfc7b 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -396,14 +396,12 @@ my $inline_doc_state;
# 'function', 'struct', 'union', 'enum', 'typedef'
my $decl_type;
-my $doc_special = "\@\%\$\&";
-
my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
my $doc_end = '\*/';
my $doc_com = '\s*\*\s*';
my $doc_com_body = '\s*\* ?';
my $doc_decl = $doc_com . '(\w+)';
-my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
+my $doc_sect = $doc_com . '(\@?[\w\s]+):(.*)';
my $doc_content = $doc_com_body . '(.*)';
my $doc_block = $doc_com . 'DOC:\s*(.*)?';
my $doc_inline_start = '^\s*/\*\*\s*$';
@@ -411,7 +409,6 @@ my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
my $doc_inline_end = '^\s*\*/\s*$';
my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
-my %constants;
my %parameterdescs;
my @parameterlist;
my %sections;
@@ -511,11 +508,7 @@ sub dump_section {
my $name = shift;
my $contents = join "\n", @_;
-if ($name =~ m/$type_constant/) {
- $name = $1;
-# print STDERR "constant section '$1' = '$contents'\n";
- $constants{$name} = $contents;
-} elsif ($name =~ m/$type_param/) {
+if ($name =~ m/$type_param/) {
# print STDERR "parameter def '$1' = '$contents'\n";
$name = $1;
$parameterdescs{$name} = $contents;
@@ -2528,7 +2521,6 @@ sub dump_function($$) {
sub reset_state {
$function = "";
-%constants = ();
%parameterdescs = ();
%parametertypes = ();
@parameterlist = ();
@@ -2924,7 +2916,6 @@ sub process_file($) {
dump_doc_section($file, $section,
xml_escape($contents));
$contents = "";
$function = "";
- %constants = ();
%parameterdescs = ();
%parametertypes = ();
@parameterlist = ();
@@ -2942,7 +2933,6 @@ sub process_file($) {
dump_doc_section($file, $section,
xml_escape($contents));
$contents = "";
$function = "";
- %constants = ();
%parameterdescs = ();
%parametertypes = ();
@parameterlist = ();
--
2.1.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
[PATCH v2 23/38] kernel-doc: strip leading blank lines from inline doc comments
The inline member markup allows whitespace lines before the actual
documentation starts. Strip the leading blank lines. This improves the
rst output.
Signed-off-by: Jani Nikula
---
scripts/kernel-doc | 4
1 file changed, 4 insertions(+)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index a89ff3ca366c..e8ea295567a3 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -2889,6 +2889,10 @@ sub process_file($) {
} 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 "Warning(${file}:$.): ";
--
2.1.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
[PATCH v2 27/38] kernel-doc/rst: use *undescribed* instead of _undescribed_
The latter isn't special to rst.
Signed-off-by: Jani Nikula
---
scripts/kernel-doc | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index f6f37e71dc08..19cee0cd53a3 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1839,7 +1839,7 @@ sub output_function_rst(%) {
$args{'parameterdescs'}{$parameter_name} ne $undescribed) {
output_highlight_rst($args{'parameterdescs'}{$parameter_name});
} else {
- print " _undescribed_\n";
+ print " *undescribed*\n";
}
print "\n";
}
@@ -1882,7 +1882,7 @@ sub output_enum_rst(%) {
if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
output_highlight_rst($args{'parameterdescs'}{$parameter});
} else {
- print " _undescribed_\n";
+ print " *undescribed*\n";
}
print "\n";
}
--
2.1.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
[PATCH v2 29/38] kernel-doc: limit the "section header:" detection to a select few
kernel-doc currently identifies anything matching "section header:"
(specifically a string of word characters and spaces followed by a
colon) as a new section in the documentation comment, and renders the
section header accordingly.
Unfortunately, this turns all uses of colon into sections, mostly
unintentionally. Considering the output, erroneously creating sections
when not intended is always worse than erroneously not creating sections
when intended. For example, a line with "http://example.com"; turns into
a "http" heading followed by "//example.com" in normal text style, which
is quite ugly. OTOH, "WARNING: Beware of the Leopard" is just fine even
if "WARNING" does not turn into a heading.
It is virtually impossible to change all the kernel-doc comments, either
way. The compromise is to pick the most commonly used and depended on
section headers (with variants) and accept them as section headers.
The accepted section headers are, case insensitive:
* description:
* context:
* return:
* returns:
Additionally, case sensitive:
* @return:
All of the above are commonly used in the kernel-doc comments, and will
result in worse output if not identified as section headers. Also,
kernel-doc already has some special handling for all of them, so there's
nothing particularly controversial in adding more special treatment for
them.
While at it, improve the whitespace handling surrounding section
names. Do not consider the whitespace as part of the name.
Signed-off-by: Jani Nikula
---
scripts/kernel-doc | 19 +--
1 file changed, 17 insertions(+), 2 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 425a94be04f6..20136564f264 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -401,7 +401,8 @@ my $doc_end = '\*/';
my $doc_com = '\s*\*\s*';
my $doc_com_body = '\s*\* ?';
my $doc_decl = $doc_com . '(\w+)';
-my $doc_sect = $doc_com . '(\@?[\w\s]+):(.*)';
+# @params and a strictly limited set of supported section names
+my $doc_sect = $doc_com . '\s*(\@\w+|description|context|returns?)\s*:(.*)';
my $doc_content = $doc_com_body . '(.*)';
my $doc_block = $doc_com . 'DOC:\s*(.*)?';
my $doc_inline_start = '^\s*/\*\*\s*$';
@@ -417,6 +418,8 @@ my $sectcheck;
my $struct_actual;
my $contents = "";
+
+# the canonical section names. see also $doc_sect above.
my $section_default = "Description"; # default section
my $section_intro = "Introduction";
my $section = $section_default;
@@ -2798,10 +2801,22 @@ sub process_file($) {
$state = STATE_NORMAL;
}
} elsif ($state == STATE_FIELD) { # look for head: lines, and
include content
- if (/$doc_sect/o) {
+ 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";
--
2.1.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
[PATCH v2 25/38] kernel-doc: improve handling of whitespace on the first line param description
Handle whitespace on the first line of param text as if it was the empty
string. There is no need to add the newline in this case. This improves
the rst output in particular, where blank lines may be problematic in
parameter lists.
Signed-off-by: Jani Nikula
---
scripts/kernel-doc | 8
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 4f559de8b173..e93e796b17ce 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -2814,11 +2814,11 @@ sub process_file($) {
$in_doc_sect = 1;
$in_purpose = 0;
$contents = $newcontents;
+ while ((substr($contents, 0, 1) eq " ") ||
+ substr($contents, 0, 1) eq "\t") {
+ $contents = substr($contents, 1);
+ }
if ($contents ne "") {
- while ((substr($contents, 0, 1) eq " ") ||
- substr($contents, 0, 1) eq "\t") {
- $contents = substr($contents, 1);
- }
$contents .= "\n";
}
$section = $newsection;
--
2.1.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
[PATCH v2 24/38] kernel-doc/rst: change the output layout
Move away from field lists, and simply use **strong emphasis** for
section headings on lines of their own. Do not use rst section headings,
because their nesting depth depends on the surrounding context, which
kernel-doc has no knowledge of. Also, they do not need to end up in any
table of contexts or indexes.
There are two related immediate benefits. Field lists are typically
rendered in two columns, while the new style uses the horizontal width
better. With no extra indent on the left, there's no need to be as fussy
about it. Field lists are more susceptible to indentation problems than
the new style.
Signed-off-by: Jani Nikula
---
scripts/kernel-doc | 34 +-
1 file changed, 17 insertions(+), 17 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index e8ea295567a3..4f559de8b173 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1823,23 +1823,23 @@ sub output_function_rst(%) {
output_highlight_rst($args{'purpose'});
print "\n";
-print ":Parameters:\n\n";
-$lineprefix = "";
+print "**Parameters**\n\n";
+$lineprefix = " ";
foreach $parameter (@{$args{'parameterlist'}}) {
my $parameter_name = $parameter;
#$parameter_name =~ s/\[.*//;
$type = $args{'parametertypes'}{$parameter};
if ($type ne "") {
- print " ``$type $parameter``\n";
+ print "``$type $parameter``\n";
} else {
- print " ``$parameter``\n";
+ print "``$parameter``\n";
}
if (defined($args{'parameterdescs'}{$parameter_name}) &&
$args{'parameterdescs'}{$parameter_name} ne $undescribed) {
output_highlight_rst($args{'parameterdescs'}{$parameter_name});
} else {
- print "\n_undescribed_\n";
+ print " _undescribed_\n";
}
print "\n";
}
@@ -1852,10 +1852,10 @@ sub output_section_rst(%) {
my %args = %{$_[0]};
my $section;
my $oldprefix = $lineprefix;
-$lineprefix = "";
+$lineprefix = "";
foreach $section (@{$args{'sectionlist'}}) {
- print ":$section:\n\n";
+ print "**$section**\n\n";
output_highlight_rst($args{'sections'}{$section});
print "\n";
}
@@ -1875,14 +1875,14 @@ sub output_enum_rst(%) {
output_highlight_rst($args{'purpose'});
print "\n";
-print "..\n\n:Constants:\n\n";
-$lineprefix = "";
+print "**Constants**\n\n";
+$lineprefix = " ";
foreach $parameter (@{$args{'parameterlist'}}) {
- print " `$parameter`\n";
+ print "``$parameter``\n";
if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
output_highlight_rst($args{'parameterdescs'}{$parameter});
} else {
- print "undescribed\n";
+ print " _undescribed_\n";
}
print "\n";
}
@@ -1918,12 +1918,12 @@ sub output_struct_rst(%) {
output_highlight_rst($args{'purpose'});
print "\n";
-print ":Definition:\n\n";
-print " ::\n\n";
+print "**Definition**\n\n";
+print "::\n\n";
print " " . $args{'type'} . " " . $args{'struct'} . " {\n";
foreach $parameter (@{$args{'parameterlist'}}) {
if ($parameter =~ /^#/) {
- print "" . "$parameter\n";
+ print " " . "$parameter\n";
next;
}
@@ -1944,8 +1944,8 @@ sub output_struct_rst(%) {
}
print " };\n\n";
-print ":Members:\n\n";
-$lineprefix = "";
+print "**Members**\n\n";
+$lineprefix = " ";
foreach $parameter (@{$args{'parameterlist'}}) {
($parameter =~ /^#/) && next;
@@ -1954,7 +1954,7 @@ sub output_struct_rst(%) {
($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
$type = $args{'parametertypes'}{$parameter};
- print " `$type $parameter`" . "\n";
+ print "``$type $parameter``\n";
output_highlight_rst($args{'parameterdescs'}{$parameter_name});
print "\n";
}
--
2.1.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
[PATCH v2 21/38] kernel-doc: fix wrong code indentation
No functional changes.
Signed-off-by: Jani Nikula
---
scripts/kernel-doc | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index f795660dfc7b..c154c3205df1 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -2878,7 +2878,7 @@ sub process_file($) {
substr($contents, 0, 1) eq "\t") {
$contents = substr($contents, 1);
}
- $contents .= "\n";
+ $contents .= "\n";
}
$inline_doc_state = STATE_INLINE_TEXT;
# Documentation block end */
--
2.1.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
[PATCH v2 22/38] kernel-doc/rst: blank lines in output are not needed
Current approach leads to two blank lines, while one is enough.
Signed-off-by: Jani Nikula
---
scripts/kernel-doc | 7 +--
1 file changed, 1 insertion(+), 6 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index c154c3205df1..a89ff3ca366c 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1786,12 +1786,7 @@ sub output_highlight_rst {
die $@ if $@;
foreach $line (split "\n", $contents) {
- if ($line eq "") {
- print $lineprefix, $blankline;
- } else {
- print $lineprefix, $line;
- }
- print "\n";
+ print $lineprefix . $line . "\n";
}
}
--
2.1.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
[PATCH v2 26/38] kernel-doc: strip leading whitespace from continued param descs
If a param description spans multiple lines, check any leading
whitespace in the first continuation line, and remove same amount of
whitespace from following lines.
This allows indentation in the multi-line parameter descriptions for
aesthetical reasons while not causing accidentally significant
indentation in the rst output.
Signed-off-by: Jani Nikula
---
scripts/kernel-doc | 16 +++-
1 file changed, 15 insertions(+), 1 deletion(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index e93e796b17ce..f6f37e71dc08 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -2701,6 +2701,7 @@ sub process_file($) {
my $in_purpose = 0;
my $initial_section_counter = $section_counter;
my ($orig_file) = @_;
+my $leading_space;
if (defined($ENV{'SRCTREE'})) {
$file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
@@ -2822,6 +2823,7 @@ sub process_file($) {
$contents .= "\n";
}
$section = $newsection;
+ $leading_space = undef;
} elsif (/$doc_end/) {
if (($contents ne "") && ($contents ne "\n")) {
dump_section($file, $section, xml_escape($contents));
@@ -2856,7 +2858,19 @@ sub process_file($) {
$declaration_purpose .= " " . xml_escape($1);
$declaration_purpose =~ s/\s+/ /g;
} else {
- $contents .= $1 . "\n";
+ 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.
--
2.1.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
[PATCH v2 31/38] kernel-doc: reset contents and section harder
If the documentation comment does not have params or sections, the
section heading may leak from the previous documentation comment.
Signed-off-by: Jani Nikula
---
scripts/kernel-doc | 3 +++
1 file changed, 3 insertions(+)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 3ac4b57ed76a..0eb2e7b5bf10 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -2763,6 +2763,8 @@ sub process_file($) {
}
$state = STATE_FIELD;
+ $contents = "";
+ $section = $section_default;
if (/-(.*)/) {
# strip leading/trailing/multiple spaces
$descr= $1;
@@ -2960,6 +2962,7 @@ sub process_file($) {
elsif (/$doc_end/)
{
dump_doc_section($file, $section,
xml_escape($contents));
+ $section = $section_default;
$contents = "";
$function = "";
%parameterdescs = ();
--
2.1.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
[PATCH v2 30/38] kernel-doc: concatenate contents of colliding sections
If there are multiple sections with the same section name, the current
implementation results in several sections by the same heading, with the
content duplicated from the last section to all. Even if there's the
error message, a more graceful approach is to combine all the
identically named sections into one, with concatenated contents.
With the supported sections already limited to select few, there are
massively fewer collisions than there used to be, but this is still
useful for e.g. when function parameters are documented in the middle of
a documentation comment, with description spread out above and
below. (This is not a recommended documentation style, but used in the
kernel nonetheless.)
We can now also demote the error to a warning.
Signed-off-by: Jani Nikula
---
scripts/kernel-doc | 10 ++
1 file changed, 6 insertions(+), 4 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 20136564f264..3ac4b57ed76a 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -524,11 +524,13 @@ sub dump_section {
} else {
# print STDERR "other section '$name' = '$contents'\n";
if (defined($sections{$name}) && ($sections{$name} ne "")) {
- print STDERR "${file}:$.: error: duplicate section name
'$name'\n";
- ++$errors;
+ print STDERR "${file}:$.: warning: duplicate section name
'$name'\n";
+ ++$warnings;
+ $sections{$name} .= $contents;
+ } else {
+ $sections{$name} = $contents;
+ push @sectionlist, $name;
}
- $sections{$name} = $contents;
- push @sectionlist, $name;
}
}
--
2.1.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
[PATCH v2 19/38] kernel-doc/rst: highlight function/struct/enum purpose lines too
Let the user use @foo, &bar, %baz, etc. in the first kernel-doc purpose
line too.
Signed-off-by: Jani Nikula
---
scripts/kernel-doc | 37 +
1 file changed, 25 insertions(+), 12 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 8f9eac509377..76bad55c031e 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1805,6 +1805,7 @@ sub output_highlight_rst {
sub output_function_rst(%) {
my %args = %{$_[0]};
my ($parameter, $section);
+my $oldprefix = $lineprefix;
my $start;
print ".. c:function:: ";
@@ -1829,9 +1830,13 @@ sub output_function_rst(%) {
print $type . " " . $parameter;
}
}
-print ")\n\n" . $args{'purpose'} . "\n\n";
+print ")\n\n";
+$lineprefix = " ";
+output_highlight_rst($args{'purpose'});
+print "\n";
print ":Parameters:\n\n";
+$lineprefix = "";
foreach $parameter (@{$args{'parameterlist'}}) {
my $parameter_name = $parameter;
#$parameter_name =~ s/\[.*//;
@@ -1844,15 +1849,14 @@ sub output_function_rst(%) {
}
if (defined($args{'parameterdescs'}{$parameter_name}) &&
$args{'parameterdescs'}{$parameter_name} ne $undescribed) {
- my $oldprefix = $lineprefix;
- $lineprefix = "";
output_highlight_rst($args{'parameterdescs'}{$parameter_name});
- $lineprefix = $oldprefix;
} else {
print "\n_undescribed_\n";
}
print "\n";
}
+
+$lineprefix = $oldprefix;
output_section_rst(@_);
}
@@ -1874,14 +1878,16 @@ sub output_section_rst(%) {
sub output_enum_rst(%) {
my %args = %{$_[0]};
my ($parameter);
+my $oldprefix = $lineprefix;
my $count;
my $name = "enum " . $args{'enum'};
print "\n\n.. c:type:: " . $name . "\n\n";
-print "" . $args{'purpose'} . "\n\n";
+$lineprefix = " ";
+output_highlight_rst($args{'purpose'});
+print "\n";
print "..\n\n:Constants:\n\n";
-my $oldprefix = $lineprefix;
$lineprefix = "";
foreach $parameter (@{$args{'parameterlist'}}) {
print " `$parameter`\n";
@@ -1892,6 +1898,7 @@ sub output_enum_rst(%) {
}
print "\n";
}
+
$lineprefix = $oldprefix;
output_section_rst(@_);
}
@@ -1899,23 +1906,29 @@ sub output_enum_rst(%) {
sub output_typedef_rst(%) {
my %args = %{$_[0]};
my ($parameter);
-my $count;
+my $oldprefix = $lineprefix;
my $name = "typedef " . $args{'typedef'};
### FIXME: should the name below contain "typedef" or not?
print "\n\n.. c:type:: " . $name . "\n\n";
-print "" . $args{'purpose'} . "\n\n";
+$lineprefix = " ";
+output_highlight_rst($args{'purpose'});
+print "\n";
+$lineprefix = $oldprefix;
output_section_rst(@_);
}
sub output_struct_rst(%) {
my %args = %{$_[0]};
my ($parameter);
+my $oldprefix = $lineprefix;
my $name = $args{'type'} . " " . $args{'struct'};
print "\n\n.. c:type:: " . $name . "\n\n";
-print "" . $args{'purpose'} . "\n\n";
+$lineprefix = " ";
+output_highlight_rst($args{'purpose'});
+print "\n";
print ":Definition:\n\n";
print " ::\n\n";
@@ -1944,6 +1957,7 @@ sub output_struct_rst(%) {
print " };\n\n";
print ":Members:\n\n";
+$lineprefix = "";
foreach $parameter (@{$args{'parameterlist'}}) {
($parameter =~ /^#/) && next;
@@ -1953,13 +1967,12 @@ sub output_struct_rst(%) {
($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
$type = $args{'parametertypes'}{$parameter};
print " `$type $parameter`" . "\n";
- my $oldprefix = $lineprefix;
- $lineprefix = "";
output_highlight_rst($args{'parameterdescs'}{$parameter_name});
- $lineprefix = $oldprefix;
print "\n";
}
print "\n";
+
+$lineprefix = $oldprefix;
output_section_rst(@_);
}
--
2.1.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 00/10] Documentation/Sphinx
On Sat, 04 Jun 2016, Jonathan Corbet wrote: > On Mon, 30 May 2016 23:05:34 +0300 > Jani Nikula wrote: > >> To be clear, the "sphinx-for-docs-next" branch of [1], [2] is what I >> propose to merge at this time. There's the Sphinx configuration, kernel >> build integration, Sphinx kernel-doc extension, tons of kernel-doc >> updates, etc. > > OK, I do believe that I am ready to do that. Many, many thanks for doing > this work! Please drop me a note when you think that the branch is ready > to go. In case you missed the patch bomb in your inbox, I think it's ready now. ;) >> There is no DocBook tmpl conversion; all of that is left >> to the authors (owners, maintainers) of the documents, but this enables >> them to focus on that part. > > I would like to have some actual documents in there in the near future, > so that interested folks have something to look at and start with. Maybe > I'll do that myself with some of the docbooks without active maintainers, > or even, maybe, some of the .txt files :) So we'll be working on gpu.tmpl next and I'll look at Documentation/kernel-doc-nano-HOWTO.txt too. 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
[PATCH v2 17/38] kernel-doc/rst: add support for struct/union/enum member references
Link "&foo->bar", "&foo->bar()", "&foo.bar", and "&foo.bar()" to the struct/union/enum foo definition. The members themselves do not currently have anchors to link to, but this is better than nothing, and promotes a universal notation. Signed-off-by: Jani Nikula --- scripts/kernel-doc | 5 + 1 file changed, 5 insertions(+) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 446c0912395e..e0fd14f6d711 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -214,6 +214,8 @@ my $type_enum_full = '\&(enum)\s*([_\w]+)'; my $type_struct_full = '\&(struct)\s*([_\w]+)'; my $type_typedef_full = '\&(typedef)\s*([_\w]+)'; my $type_union_full = '\&(union)\s*([_\w]+)'; +my $type_member = '\&([_\w]+)((\.|->)[_\w]+)'; +my $type_member_func = $type_member . '\(\)'; # Output conversion substitutions. # One for each output format @@ -282,6 +284,9 @@ my $blankline_text = ""; # rst-mode my @highlights_rst = ( [$type_constant, "``\$1``"], + # Note: need to escape () to avoid func matching later + [$type_member_func, "\\:c\\:type\\:`\$1\$2() <\$1>`"], + [$type_member, "\\:c\\:type\\:`\$1\$2 <\$1>`"], [$type_func, "\\:c\\:func\\:`\$1()`"], [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"], [$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"], -- 2.1.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
[PATCH v2 11/38] kernel-doc: add names for states and substates
Make the state machine a bit more readable by adding constants for
parser states and inline member documentation parser substates. While at
it, rename the "split" documentation to "inline" documentation.
No functional changes.
Signed-off-by: Jani Nikula
---
scripts/kernel-doc | 91 --
1 file changed, 48 insertions(+), 43 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 3ad54abe0989..cb5fd248ac57 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -350,24 +350,29 @@ my $section_counter = 0;
my $lineprefix="";
-# states
-# 0 - normal code
-# 1 - looking for function name
-# 2 - scanning field start.
-# 3 - scanning prototype.
-# 4 - documentation block
-# 5 - gathering documentation outside main block
+# Parser states
+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
+};
my $state;
my $in_doc_sect;
-# Split Doc State
-# 0 - Invalid (Before start or after finish)
-# 1 - Is started (the /** was found inside a struct)
-# 2 - The @parameter header was found, start accepting multi paragraph text.
-# 3 - Finished (the */ was found)
-# 4 - Error - Comment without header was found. Spit a warning as it's not
-# proper kernel-doc and ignore the rest.
-my $split_doc_state;
+# Inline documentation state
+use constant {
+STATE_INLINE_NA => 0, # not applicable ($state != STATE_INLINE)
+STATE_INLINE_NAME => 1, # looking for member name (@foo:)
+STATE_INLINE_TEXT => 2, # looking for member documentation
+STATE_INLINE_END=> 3, # done
+STATE_INLINE_ERROR => 4, # error - Comment without header was found.
+ # Spit a warning as it's not
+ # proper kernel-doc and ignore the rest.
+};
+my $inline_doc_state;
#declaration types: can be
# 'function', 'struct', 'union', 'enum', 'typedef'
@@ -383,9 +388,9 @@ my $doc_decl = $doc_com . '(\w+)';
my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
my $doc_content = $doc_com_body . '(.*)';
my $doc_block = $doc_com . 'DOC:\s*(.*)?';
-my $doc_split_start = '^\s*/\*\*\s*$';
-my $doc_split_sect = '\s*\*\s*(@[\w\s]+):(.*)';
-my $doc_split_end = '^\s*\*/\s*$';
+my $doc_inline_start = '^\s*/\*\*\s*$';
+my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
+my $doc_inline_end = '^\s*\*/\s*$';
my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
my %constants;
@@ -2497,8 +2502,8 @@ sub reset_state {
$struct_actual = "";
$prototype = "";
-$state = 0;
-$split_doc_state = 0;
+$state = STATE_NORMAL;
+$inline_doc_state = STATE_INLINE_NA;
}
sub tracepoint_munge($) {
@@ -2707,14 +2712,14 @@ sub process_file($) {
while (s/\\\s*$//) {
$_ .= ;
}
- if ($state == 0) {
+ if ($state == STATE_NORMAL) {
if (/$doc_start/o) {
- $state = 1; # next line is always the function name
+ $state = STATE_NAME;# next line is always the function name
$in_doc_sect = 0;
}
- } elsif ($state == 1) { # this line is the function name (always)
+ } elsif ($state == STATE_NAME) {# this line is the function name
(always)
if (/$doc_block/o) {
- $state = 4;
+ $state = STATE_DOCBLOCK;
$contents = "";
if ( $1 eq "" ) {
$section = $section_intro;
@@ -2728,7 +2733,7 @@ sub process_file($) {
$identifier = $1;
}
- $state = 2;
+ $state = STATE_FIELD;
if (/-(.*)/) {
# strip leading/trailing/multiple spaces
$descr= $1;
@@ -2766,9 +2771,9 @@ sub process_file($) {
print STDERR "${file}:$.: warning: Cannot understand $_ on line
$.",
" - I thought it was a doc line\n";
++$warnings;
- $state = 0;
+ $state = STATE_NORMAL;
}
- } elsif ($state == 2) { # look for head: lines, and include content
+ } elsif ($state == STATE_FIELD) { # look for head: lines, and
include content
if (/$doc_sect/o) {
$newsection = $1;
$newcontents = $2;
@@ -2806,7 +2811,7 @@ sub process_file($) {
}
$prototype = "";
- $state = 3;
+ $state = STATE_PROTO;
$brcount = 0;
# print STDERR "end of doc comment, looking for prototype\n";
} elsif (/$doc_content/) {
@@ -2834,9 +2839,9 @@ sub process_file($) {
print STDERR
[PATCH v2 12/38] kernel-doc: add names for output selection
Make the output selection a bit more readable by adding constants for
the various types of output selection. While at it, actually call the
variable for choosing what to output $output_selection.
No functional changes.
Signed-off-by: Jani Nikula
---
scripts/kernel-doc | 47 ++-
1 file changed, 30 insertions(+), 17 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index cb5fd248ac57..dd08944b0a6f 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -312,7 +312,15 @@ my $no_doc_sections = 0;
my @highlights = @highlights_man;
my $blankline = $blankline_man;
my $modulename = "Kernel API";
-my $function_only = 0;
+
+use constant {
+OUTPUT_ALL => 0, # output all symbols and doc sections
+OUTPUT_INCLUDE => 1, # output only specified symbols
+OUTPUT_EXCLUDE => 2, # output everything except specified symbols
+OUTPUT_EXPORTED => 3, # output exported symbols
+OUTPUT_INTERNAL => 4, # output non-exported symbols
+};
+my $output_selection = OUTPUT_ALL;
my $show_not_found = 0;
my @build_time;
@@ -449,18 +457,18 @@ while ($ARGV[0] =~ m/^-(.*)/) {
} elsif ($cmd eq "-module") { # not needed for XML, inherits from calling
document
$modulename = shift @ARGV;
} elsif ($cmd eq "-function") { # to only output specific functions
- $function_only = 1;
+ $output_selection = OUTPUT_INCLUDE;
$function = shift @ARGV;
$function_table{$function} = 1;
-} elsif ($cmd eq "-nofunction") { # to only output specific functions
- $function_only = 2;
+} elsif ($cmd eq "-nofunction") { # output all except specific functions
+ $output_selection = OUTPUT_EXCLUDE;
$function = shift @ARGV;
$function_table{$function} = 1;
} elsif ($cmd eq "-export") { # only exported symbols
- $function_only = 3;
+ $output_selection = OUTPUT_EXPORTED;
%function_table = ()
} elsif ($cmd eq "-internal") { # only non-exported symbols
- $function_only = 4;
+ $output_selection = OUTPUT_INTERNAL;
%function_table = ()
} elsif ($cmd eq "-v") {
$verbose = 1;
@@ -530,15 +538,17 @@ sub dump_doc_section {
return;
}
-if (($function_only == 0) ||
- ( $function_only == 1 && defined($function_table{$name})) ||
- ( $function_only == 2 && !defined($function_table{$name})))
+if (($output_selection == OUTPUT_ALL) ||
+ ($output_selection == OUTPUT_INCLUDE &&
+defined($function_table{$name})) ||
+ ($output_selection == OUTPUT_EXCLUDE &&
+!defined($function_table{$name})))
{
dump_section($file, $name, $contents);
output_blockhead({'sectionlist' => \@sectionlist,
'sections' => \%sections,
'module' => $modulename,
- 'content-only' => ($function_only != 0), });
+ 'content-only' => ($output_selection != OUTPUT_ALL),
});
}
}
@@ -1988,11 +1998,13 @@ sub output_declaration {
my $name = shift;
my $functype = shift;
my $func = "output_${functype}_$output_mode";
-if (($function_only==0) ||
- ( ($function_only == 1 || $function_only == 3) &&
- defined($function_table{$name})) ||
- ( ($function_only == 2 || $function_only == 4) &&
- !($functype eq "function" && defined($function_table{$name}
+if (($output_selection == OUTPUT_ALL) ||
+ (($output_selection == OUTPUT_INCLUDE ||
+ $output_selection == OUTPUT_EXPORTED) &&
+defined($function_table{$name})) ||
+ (($output_selection == OUTPUT_EXCLUDE ||
+ $output_selection == OUTPUT_INTERNAL) &&
+!($functype eq "function" && defined($function_table{$name}
{
&$func(@_);
$section_counter++;
@@ -2696,7 +2708,8 @@ sub process_file($) {
}
# two passes for -export and -internal
-if ($function_only == 3 || $function_only == 4) {
+if ($output_selection == OUTPUT_EXPORTED ||
+ $output_selection == OUTPUT_INTERNAL) {
while () {
if (/$export_symbol/o) {
$function_table{$2} = 1;
@@ -2929,7 +2942,7 @@ sub process_file($) {
}
if ($initial_section_counter == $section_counter) {
print STDERR "${file}:1: warning: no structured comments found\n";
- if (($function_only == 1) && ($show_not_found == 1)) {
+ if (($output_selection == OUTPUT_INCLUDE) && ($show_not_found == 1)) {
print STDERR "Was looking for '$_'.\n" for keys %function_table;
}
if ($output_mode eq "xml") {
--
2.1.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
[PATCH v2 16/38] kernel-doc/rst: add support for &union foo and &typedef foo references
Let the user use "&union foo" and "&typedef foo" to reference foo. The difference to using "union &foo", "typedef &foo", or just "&foo" (which are valid too) is that "union" and "typedef" become part of the link text. Signed-off-by: Jani Nikula --- scripts/kernel-doc | 4 1 file changed, 4 insertions(+) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index e7aa792e7f1b..446c0912395e 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -212,6 +212,8 @@ my $type_struct_xml = '\\&((struct\s*)*[_\w]+)'; my $type_env = '(\$\w+)'; my $type_enum_full = '\&(enum)\s*([_\w]+)'; my $type_struct_full = '\&(struct)\s*([_\w]+)'; +my $type_typedef_full = '\&(typedef)\s*([_\w]+)'; +my $type_union_full = '\&(union)\s*([_\w]+)'; # Output conversion substitutions. # One for each output format @@ -283,6 +285,8 @@ my @highlights_rst = ( [$type_func, "\\:c\\:func\\:`\$1()`"], [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"], [$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"], + [$type_typedef_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"], + [$type_union_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"], # in rst this can refer to any type [$type_struct, "\\:c\\:type\\:`\$1`"], [$type_param, "**\$1**"] -- 2.1.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
[PATCH v2 09/38] sphinx: update docbook->rst conversion script match C domain spec
Function references should include the parens (), struct references should not include "struct". Signed-off-by: Jani Nikula --- Documentation/sphinx/convert_template.sed | 8 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Documentation/sphinx/convert_template.sed b/Documentation/sphinx/convert_template.sed index d53bb8220a26..0553eabeac79 100644 --- a/Documentation/sphinx/convert_template.sed +++ b/Documentation/sphinx/convert_template.sed @@ -4,10 +4,10 @@ # # Use "$bq" instead of "`" so that pandoc won't mess with it. # -s%\([^<(]\+\)()%:c:func:$bq\1$bq%g -s%\([^<(]\+\)%:c:func:$bq\1$bq%g -s%struct *\([^<]\+\)%:ref:$bqstruct \1$bq%g -s%\([^<]\+\)%:ref:$bqstruct \1$bq%g +s%\([^<(]\+\)()%:c:func:$bq\1()$bq%g +s%\([^<(]\+\)%:c:func:$bq\1()$bq%g +s%struct *\([^<]\+\)%:c:type:$bq\1$bq%g +s%\([^<]\+\)%:c:type:$bq\1$bq%g # # Wrap docproc directives in para and code blocks. # -- 2.1.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
[PATCH v2 15/38] kernel-doc/rst: &foo references are more universal than structs
It's possible to use &foo to reference structs, enums, typedefs, etc. in the Sphinx C domain. Thus do not prefix the links with "struct". Signed-off-by: Jani Nikula --- scripts/kernel-doc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index e8651d7cf1cd..e7aa792e7f1b 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -283,7 +283,8 @@ my @highlights_rst = ( [$type_func, "\\:c\\:func\\:`\$1()`"], [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"], [$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"], - [$type_struct, "\\:c\\:type\\:`struct \$1 <\$1>`"], + # in rst this can refer to any type + [$type_struct, "\\:c\\:type\\:`\$1`"], [$type_param, "**\$1**"] ); my $blankline_rst = "\n"; -- 2.1.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
[PATCH v2 14/38] kernel-doc/rst: reference functions according to C domain spec
The Sphinx C domain spec says function references should include the parens (). Signed-off-by: Jani Nikula --- scripts/kernel-doc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 659d529b99d8..e8651d7cf1cd 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -280,7 +280,7 @@ my $blankline_text = ""; # rst-mode my @highlights_rst = ( [$type_constant, "``\$1``"], - [$type_func, "\\:c\\:func\\:`\$1`"], + [$type_func, "\\:c\\:func\\:`\$1()`"], [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"], [$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"], [$type_struct, "\\:c\\:type\\:`struct \$1 <\$1>`"], -- 2.1.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
[PATCH v2 08/38] sphinx: cheesy script to convert .tmpl files
From: Jonathan Corbet This script uses pandoc to convert existing DocBook template files to RST templates. A couple of sed scripts are need to massage things both before and after the conversion, but the result is then usable with no hand editing. [Jani: Change usage to tmplcvt . Fix escaping for docproc directives. Add support the new kernel-doc extension.] Signed-off-by: Jonathan Corbet Signed-off-by: Jani Nikula --- Documentation/sphinx/convert_template.sed | 14 ++ Documentation/sphinx/post_convert.sed | 19 +++ Documentation/sphinx/tmplcvt | 19 +++ 3 files changed, 52 insertions(+) create mode 100644 Documentation/sphinx/convert_template.sed create mode 100644 Documentation/sphinx/post_convert.sed create mode 100755 Documentation/sphinx/tmplcvt diff --git a/Documentation/sphinx/convert_template.sed b/Documentation/sphinx/convert_template.sed new file mode 100644 index ..d53bb8220a26 --- /dev/null +++ b/Documentation/sphinx/convert_template.sed @@ -0,0 +1,14 @@ +# +# Pandoc doesn't grok or , so convert them +# ahead of time. +# +# Use "$bq" instead of "`" so that pandoc won't mess with it. +# +s%\([^<(]\+\)()%:c:func:$bq\1$bq%g +s%\([^<(]\+\)%:c:func:$bq\1$bq%g +s%struct *\([^<]\+\)%:ref:$bqstruct \1$bq%g +s%\([^<]\+\)%:ref:$bqstruct \1$bq%g +# +# Wrap docproc directives in para and code blocks. +# +s%^\(!.*\)$%DOCPROC: \1% diff --git a/Documentation/sphinx/post_convert.sed b/Documentation/sphinx/post_convert.sed new file mode 100644 index ..ce17049f6a8e --- /dev/null +++ b/Documentation/sphinx/post_convert.sed @@ -0,0 +1,19 @@ +# +# pandoc thinks that both "_" needs to be escaped. Remove the extra +# backslashes. Also put in proper backquotes now that pandoc won't quote +# them. +# +s/$bq/`/g +s/\\_/_/g +# +# Unwrap docproc directives. +# +s/^``DOCPROC: !E\(.*\)``$/.. kernel-doc:: \1\n :export:/ +s/^``DOCPROC: !I\(.*\)``$/.. kernel-doc:: \1\n :internal:/ +s/^``DOCPROC: !F\([^ ]*\) \(.*\)``$/.. kernel-doc:: \1\n :functions: \2/ +s/^``DOCPROC: !P\([^ ]*\) \(.*\)``$/.. kernel-doc:: \1\n :doc: \2/ +s/^``DOCPROC: \(!.*\)``$/.. WARNING: DOCPROC directive not supported: \1/ +# +# Trim trailing whitespace. +# +s/[[:space:]]*$// diff --git a/Documentation/sphinx/tmplcvt b/Documentation/sphinx/tmplcvt new file mode 100755 index ..909a73065e0a --- /dev/null +++ b/Documentation/sphinx/tmplcvt @@ -0,0 +1,19 @@ +#!/bin/bash +# +# Convert a template file into something like RST +# +# fix +# feed to pandoc +# fix \_ +# title line? +# + +in=$1 +rst=$2 +tmp=$rst.tmp + +cp $in $tmp +sed --in-place -f convert_template.sed $tmp +pandoc -s -S -f docbook -t rst -o $rst $tmp +sed --in-place -f post_convert.sed $rst +rm $tmp -- 2.1.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
[PATCH v2 10/38] Documentation/sphinx: nicer referencing of struct in docbook->rst conversion
Add "struct" in the label of the reference. Signed-off-by: Jani Nikula --- Documentation/sphinx/convert_template.sed | 10 +++--- Documentation/sphinx/post_convert.sed | 10 +++--- 2 files changed, 14 insertions(+), 6 deletions(-) diff --git a/Documentation/sphinx/convert_template.sed b/Documentation/sphinx/convert_template.sed index 0553eabeac79..c1503fcca4ec 100644 --- a/Documentation/sphinx/convert_template.sed +++ b/Documentation/sphinx/convert_template.sed @@ -2,12 +2,16 @@ # Pandoc doesn't grok or , so convert them # ahead of time. # -# Use "$bq" instead of "`" so that pandoc won't mess with it. +# Use the following escapes to pass through pandoc: +# $bq = "`" +# $lt = "<" +# $gt = ">" # s%\([^<(]\+\)()%:c:func:$bq\1()$bq%g s%\([^<(]\+\)%:c:func:$bq\1()$bq%g -s%struct *\([^<]\+\)%:c:type:$bq\1$bq%g -s%\([^<]\+\)%:c:type:$bq\1$bq%g +s%struct *\([^<]\+\)%:c:type:$bqstruct \1 $lt\1$gt$bq%g +s%struct \([^<]\+\)%:c:type:$bqstruct \1 $lt\1$gt$bq%g +s%\([^<]\+\)%:c:type:$bqstruct \1 $lt\1$gt$bq%g # # Wrap docproc directives in para and code blocks. # diff --git a/Documentation/sphinx/post_convert.sed b/Documentation/sphinx/post_convert.sed index ce17049f6a8e..392770bac53b 100644 --- a/Documentation/sphinx/post_convert.sed +++ b/Documentation/sphinx/post_convert.sed @@ -1,9 +1,13 @@ # -# pandoc thinks that both "_" needs to be escaped. Remove the extra -# backslashes. Also put in proper backquotes now that pandoc won't quote -# them. +# Unescape. # s/$bq/`/g +s/$lt//g +# +# pandoc thinks that both "_" needs to be escaped. Remove the extra +# backslashes. +# s/\\_/_/g # # Unwrap docproc directives. -- 2.1.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
[PATCH v2 13/38] kernel-doc/rst: do not output DOC: section titles for requested ones
If the user requests a specific DOC: section by name, do not output its
section title. In these cases, the surrounding context already has a
heading, and the DOC: section title is only used as an identifier and a
heading for clarity in the source file.
Signed-off-by: Jani Nikula
---
scripts/kernel-doc | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index dd08944b0a6f..659d529b99d8 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1764,7 +1764,9 @@ sub output_blockhead_rst(%) {
my ($parameter, $section);
foreach $section (@{$args{'sectionlist'}}) {
- print "**$section**\n\n";
+ if ($output_selection != OUTPUT_INCLUDE) {
+ print "**$section**\n\n";
+ }
output_highlight_rst($args{'sections'}{$section});
print "\n";
}
--
2.1.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
[PATCH v2 04/38] Documentation: add .gitignore
The Sphinx output directory is generated. Signed-off-by: Jani Nikula --- Documentation/.gitignore | 1 + 1 file changed, 1 insertion(+) create mode 100644 Documentation/.gitignore diff --git a/Documentation/.gitignore b/Documentation/.gitignore new file mode 100644 index ..53752db253e3 --- /dev/null +++ b/Documentation/.gitignore @@ -0,0 +1 @@ +output -- 2.1.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
[PATCH v2 07/38] Documentation/sphinx: set version and release properly
Read the version and release from the top level Makefile (for use when
Sphinx is invoked directly, by e.g. Read the Docs), but override them
via Sphinx command line arguments in a normal documentation build.
Signed-off-by: Jani Nikula
---
Documentation/Makefile.sphinx | 2 +-
Documentation/conf.py | 29 +
2 files changed, 26 insertions(+), 5 deletions(-)
diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
index 8a662be9bd87..addf32309bc3 100644
--- a/Documentation/Makefile.sphinx
+++ b/Documentation/Makefile.sphinx
@@ -27,7 +27,7 @@ PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
KERNELDOC = $(srctree)/scripts/kernel-doc
KERNELDOC_CONF = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC)
-ALLSPHINXOPTS = -d $(BUILDDIR)/.doctrees $(KERNELDOC_CONF)
$(PAPEROPT_$(PAPER)) -c $(srctree)/$(src) $(SPHINXOPTS) $(srctree)/$(src)
+ALLSPHINXOPTS = -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) -d
$(BUILDDIR)/.doctrees $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) -c
$(srctree)/$(src) $(SPHINXOPTS) $(srctree)/$(src)
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 8b72577f38f5..6cc41a0555a3 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -60,10 +60,31 @@ author = 'The kernel development community'
# |version| and |release|, also used in various other places throughout the
# built documents.
#
-# The short X.Y version.
-version = '4.5'
-# The full version, including alpha/beta/rc tags.
-release = '4.5'
+# In a normal build, version and release are are set to KERNELVERSION and
+# KERNELRELEASE, respectively, from the Makefile via Sphinx command line
+# arguments.
+#
+# The following code tries to extract the information by reading the Makefile,
+# when Sphinx is run directly (e.g. by Read the Docs).
+try:
+makefile_version = None
+makefile_patchlevel = None
+for line in open('../Makefile'):
+key, val = [x.strip() for x in line.split('=', 2)]
+if key == 'VERSION':
+makefile_version = val
+elif key == 'PATCHLEVEL':
+makefile_patchlevel = val
+if makefile_version and makefile_patchlevel:
+break
+except:
+pass
+finally:
+if makefile_version and makefile_patchlevel:
+version = release = makefile_version + '.' + makefile_patchlevel
+else:
+sys.stderr.write('Warning: Could not extract kernel version\n')
+version = release = "unknown version"
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
--
2.1.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
[PATCH v2 06/38] Documentation/sphinx: configure the kernel-doc extension
Tell Sphinx where to find the extension, and pass on the kernel src tree
and kernel-doc paths to the extension.
With this, any .rst files under Documentation may contain the kernel-doc
rst directive to include kernel-doc documentation from any source file.
While building, it may be handy to pass kernel-doc extension
configuration on the command line. For example, 'make SPHINXOPTS="-D
kerneldoc_verbosity=0" htmldocs' silences all stderr output from
kernel-doc when the kernel-doc exit code is 0. (The stderr will be
logged unconditionally when the exit code is non-zero.)
Signed-off-by: Jani Nikula
---
Documentation/Makefile.sphinx | 4 +++-
Documentation/conf.py | 10 --
2 files changed, 11 insertions(+), 3 deletions(-)
diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
index 25a7970bfe5c..8a662be9bd87 100644
--- a/Documentation/Makefile.sphinx
+++ b/Documentation/Makefile.sphinx
@@ -25,7 +25,9 @@ HAVE_RST2PDF := $(shell if python -c "import rst2pdf"
>/dev/null 2>&1; then echo
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS = -d $(BUILDDIR)/.doctrees $(PAPEROPT_$(PAPER)) -c
$(srctree)/$(src) $(SPHINXOPTS) $(srctree)/$(src)
+KERNELDOC = $(srctree)/scripts/kernel-doc
+KERNELDOC_CONF = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC)
+ALLSPHINXOPTS = -d $(BUILDDIR)/.doctrees $(KERNELDOC_CONF)
$(PAPEROPT_$(PAPER)) -c $(srctree)/$(src) $(SPHINXOPTS) $(srctree)/$(src)
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 0f0e20757bb1..8b72577f38f5 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -18,7 +18,7 @@ import os
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('sphinx'))
# -- General configuration
@@ -28,7 +28,7 @@ import os
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
-extensions = []
+extensions = ['kernel-doc']
# Gracefully handle missing rst2pdf.
try:
@@ -385,3 +385,9 @@ epub_exclude_files = ['search.html']
pdf_documents = [
('index', u'Kernel', u'Kernel', u'J. Random Bozo'),
]
+
+# kernel-doc extension configuration for running Sphinx directly (e.g. by Read
+# the Docs). In a normal build, these are supplied from the Makefile via
command
+# line arguments.
+kerneldoc_bin = '../scripts/kernel-doc'
+kerneldoc_srctree = '..'
--
2.1.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
[PATCH v2 02/38] kernel-doc: support printing exported and non-exported symbols
Currently we use docproc to figure out which symbols are exported, and
then docproc calls kernel-doc on specific functions, to get
documentation on exported functions. According to git blame and docproc
comments, this is due to historical reasons, as functions and their
corresponding EXPORT_SYMBOL* may have been in different files. However
for more than ten years the recommendation in CodingStyle has been to
place the EXPORT_SYMBOL* immediately after the closing function brace
line.
Additionally, the kernel-doc comments for functions are generally placed
above the function definition in the .c files (i.e. where the
EXPORT_SYMBOL* is) rather than above the declaration in the .h
files. There are some exceptions to this, but AFAICT none of these are
included in DocBook documentation using the "!E" docproc directive.
Therefore, assuming the EXPORT_SYMBOL* and kernel-doc are with the
function definition, kernel-doc can extract the exported vs. not
information by making two passes on the input file. Add support for that
via the new -export and -internal parameters.
Signed-off-by: Jani Nikula
---
scripts/kernel-doc | 29 +++--
1 file changed, 27 insertions(+), 2 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index babb374c043d..3ad54abe0989 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -59,6 +59,12 @@ Output format selection (mutually exclusive):
-textOutput plain text format.
Output selection (mutually exclusive):
+ -export Only output documentation for symbols that have been
+ exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
+ in the same FILE.
+ -internalOnly output documentation for symbols that have NOT been
+ exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
+ in the same FILE.
-function NAME Only output documentation for the given function(s)
or DOC: section title(s). All other functions and DOC:
sections are ignored. May be specified multiple times.
@@ -380,6 +386,7 @@ my $doc_block = $doc_com . 'DOC:\s*(.*)?';
my $doc_split_start = '^\s*/\*\*\s*$';
my $doc_split_sect = '\s*\*\s*(@[\w\s]+):(.*)';
my $doc_split_end = '^\s*\*/\s*$';
+my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
my %constants;
my %parameterdescs;
@@ -444,6 +451,12 @@ while ($ARGV[0] =~ m/^-(.*)/) {
$function_only = 2;
$function = shift @ARGV;
$function_table{$function} = 1;
+} elsif ($cmd eq "-export") { # only exported symbols
+ $function_only = 3;
+ %function_table = ()
+} elsif ($cmd eq "-internal") { # only non-exported symbols
+ $function_only = 4;
+ %function_table = ()
} elsif ($cmd eq "-v") {
$verbose = 1;
} elsif (($cmd eq "-h") || ($cmd eq "--help")) {
@@ -1971,8 +1984,10 @@ sub output_declaration {
my $functype = shift;
my $func = "output_${functype}_$output_mode";
if (($function_only==0) ||
- ( $function_only == 1 && defined($function_table{$name})) ||
- ( $function_only == 2 && !($functype eq "function" &&
defined($function_table{$name}
+ ( ($function_only == 1 || $function_only == 3) &&
+ defined($function_table{$name})) ||
+ ( ($function_only == 2 || $function_only == 4) &&
+ !($functype eq "function" && defined($function_table{$name}
{
&$func(@_);
$section_counter++;
@@ -2675,6 +2690,16 @@ sub process_file($) {
return;
}
+# two passes for -export and -internal
+if ($function_only == 3 || $function_only == 4) {
+ while () {
+ if (/$export_symbol/o) {
+ $function_table{$2} = 1;
+ }
+ }
+ seek(IN, 0, 0);
+}
+
$. = 1;
$section_counter = 0;
--
2.1.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
[PATCH v2 03/38] Documentation/sphinx: add basic working Sphinx configuration and build
Add basic configuration and makefile to build documentation from any .rst files under Documentation using Sphinx. For starters, there's just the placeholder index.rst. At the top level Makefile, hook Sphinx documentation targets alongside (but independent of) the DocBook toolchain, having both be run on the various 'make *docs' targets. All Sphinx processing is placed into Documentation/Makefile.sphinx. Both that and the Documentation/DocBook/Makefile are now expected to handle all the documentation targets, explicitly ignoring them if they're not relevant for that particular toolchain. The changes to the existing DocBook Makefile are kept minimal. There is graceful handling of missing Sphinx and rst2pdf (which is needed for pdf output) by checking for the tool and python module, respectively, with informative messages to the user. If the Read the Docs theme (sphinx_rtd_theme) is available, use it, but otherwise gracefully fall back to the Sphinx default theme, with an informative message to the user, and slightly less pretty HTML output. Sphinx can now handle htmldocs, pdfdocs (if rst2pdf is available), epubdocs and xmldocs targets. The output documents are written into per output type subdirectories under Documentation/output. Finally, you can pass options to sphinx-build using the SPHINXBUILD make variable. For example, 'make SPHINXOPTS=-v htmldocs' for more verbose output from Sphinx. This is based on the original work by Jonathan Corbet, but he probably wouldn't recognize this as his own anymore. Signed-off-by: Jani Nikula --- Documentation/DocBook/Makefile | 7 +- Documentation/Makefile.sphinx | 61 +++ Documentation/conf.py | 387 + Documentation/index.rst| 23 +++ Makefile | 5 +- 5 files changed, 478 insertions(+), 5 deletions(-) create mode 100644 Documentation/Makefile.sphinx create mode 100644 Documentation/conf.py create mode 100644 Documentation/index.rst diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index d70f9b68174e..e0c7e1e0590b 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -33,10 +33,6 @@ PDF_METHOD = $(prefer-db2x) PS_METHOD = $(prefer-db2x) -### -# The targets that may be used. -PHONY += xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs cleandocs - targets += $(DOCBOOKS) BOOKS := $(addprefix $(obj)/,$(DOCBOOKS)) xmldocs: $(BOOKS) @@ -63,6 +59,9 @@ installmandocs: mandocs sort -k 2 -k 1 | uniq -f 1 | sed -e 's: :/:' | \ xargs install -m 644 -t /usr/local/man/man9/ +# no-op for the DocBook toolchain +epubdocs: + ### #External programs used KERNELDOCXMLREF = $(srctree)/scripts/kernel-doc-xml-ref diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx new file mode 100644 index ..25a7970bfe5c --- /dev/null +++ b/Documentation/Makefile.sphinx @@ -0,0 +1,61 @@ +# -*- makefile -*- +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXBUILD = sphinx-build +SPHINXOPTS= +PAPER = +BUILDDIR = $(obj)/output + +# User-friendly check for sphinx-build +HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi) + +ifeq ($(HAVE_SPHINX),0) + +.DEFAULT: + $(warning The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed and in PATH, or set the SPHINXBUILD make variable to point to the full path of the '$(SPHINXBUILD)' executable.) + @echo " SKIPSphinx $@ target." + +else # HAVE_SPHINX + +# User-friendly check for rst2pdf +HAVE_RST2PDF := $(shell if python -c "import rst2pdf" >/dev/null 2>&1; then echo 1; else echo 0; fi) + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/.doctrees $(PAPEROPT_$(PAPER)) -c $(srctree)/$(src) $(SPHINXOPTS) $(srctree)/$(src) +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +quiet_cmd_sphinx = SPHINX $@ + cmd_sphinx = $(SPHINXBUILD) -b $2 $(ALLSPHINXOPTS) $(BUILDDIR)/$2 + +htmldocs: + $(call cmd,sphinx,html) + +pdfdocs: +ifeq ($(HAVE_RST2PDF),0) + $(warning The Python 'rst2pdf' module was not found. Make sure you have the module installed to produce PDF output.) + @echo " SKIPSphinx $@ target." +else # HAVE_RST2PDF + $(call cmd,sphinx,pdf) +endif # HAVE_RST2PDF + +epubdocs: + $(call cmd,sphinx,epub) + +xmldocs: + $(call cmd,sphinx,xml) + +# no-ops for the Sphinx toolchain +sgmldocs: +psdocs: +mandocs: +installmandocs: + +cleandocs: + $(Q)rm -rf $(BUILDDIR) + +endif # HAVE_SPHINX diff --git a/Documentation/conf.py b/Documentation/conf.py new file mode 100644 index ..0f0e20757bb1 --- /dev/null +++ b/Documentation/conf.py @@
Re: [PATCH v2 00/38] Documentation/sphinx
On Sat, Jun 04, 2016 at 02:37:01PM +0300, Jani Nikula wrote: > Jon, this is v2 of [1] and [2], with a considerable amount of polish and > fixes added. We started dogfooding this within drm-intel, and Daniel has > reviewed the lot and contributed a number of fixes, most notably > accurate file and line number references from Sphinx build > errors/warnings to the kernel-doc comments in source code. dogfooding = our autobuilder also already eats it: https://01.org/linuxgraphics/gfx-docs/drm/ > We believe this is now in good shape for merging for v4.8. It's all in > my sphinx-for-docs-next branch that you've already looked at; pull > details below. I've read through all the patches and things look good. Now my python/perl/sphinx fu is by far not good enough for a full review, hence just: Acked-by: Daniel Vetter It also works really nicely, we already started to land some kernel-doc markup fixup patches for drm. Tested-by: Daniel Vetter I really think this is awesome, and it's a good foundation for more polish in the toolchain on top (like Markus' improved tables, or some of the ideas floating around about better linting for kernel-doc). But right now I think the next step is to convert a pile of docs and gain some real-world experience with the tool-chain. > When this lands in docs-next and we can backmerge to drm, we'll plunge > ahead and convert gpu.tmpl to rst, and have that ready for v4.8. We > think it's best to contribute that via the drm tree, as it'll involve > splitting up the documentation and likely numerous updates to kernel-doc > comments. Please send me a pull request with the tag to merge into drm-misc. > I plan to update Documentation/kernel-doc-nano-HOWTO.txt for Sphinx and > rst, obviously converting it to rst while at it. Cheers, Daniel > > BR, > Jani. > > > > [1] http://mid.gmane.org/cover.1463748027.git.jani.nik...@intel.com > [2] http://mid.gmane.org/877fec7gfm@intel.com > > The following changes since commit 1a695a905c18548062509178b98bc91e67510864: > > Linux 4.7-rc1 (2016-05-29 09:29:24 -0700) > > are available in the git repository at: > > git://people.freedesktop.org/~jani/drm sphinx-for-docs-next > > for you to fetch changes up to d90368f2fa7ded7c56d214aef087e88bba5199e7: > > doc/sphinx: Track line-number of starting blocks (2016-06-04 11:35:59 +0300) > > > Daniel Vetter (6): > doc/sphinx: Pass right filename as source > scripts/kernel-doc: Remove duplicated DOC: start handling > doc/sphinx: Stop touching state_machine internals > scripts/kernel-doc: Also give functions symbolic names > scripts/kernel-doc: Add option to inject line numbers > doc/sphinx: Track line-number of starting blocks > > Jani Nikula (31): > kernel-doc/rst: fix use of uninitialized value > kernel-doc: support printing exported and non-exported symbols > Documentation/sphinx: add basic working Sphinx configuration and build > Documentation: add .gitignore > Documentation/sphinx: add Sphinx kernel-doc directive extension > Documentation/sphinx: configure the kernel-doc extension > Documentation/sphinx: set version and release properly > sphinx: update docbook->rst conversion script match C domain spec > Documentation/sphinx: nicer referencing of struct in docbook->rst > conversion > kernel-doc: add names for states and substates > kernel-doc: add names for output selection > kernel-doc/rst: do not output DOC: section titles for requested ones > kernel-doc/rst: reference functions according to C domain spec > kernel-doc/rst: &foo references are more universal than structs > kernel-doc/rst: add support for &union foo and &typedef foo references > kernel-doc/rst: add support for struct/union/enum member references > kernel-doc/rst: drop redundant unescape in highlighting > kernel-doc/rst: highlight function/struct/enum purpose lines too > kernel-doc: do not regard $, %, or & prefixes as special in section > names > kernel-doc: fix wrong code indentation > kernel-doc/rst: blank lines in output are not needed > kernel-doc: strip leading blank lines from inline doc comments > kernel-doc/rst: change the output layout > kernel-doc: improve handling of whitespace on the first line param > description > kernel-doc: strip leading whitespace from continued param descs > kernel-doc/rst: use *undescribed* instead of _undescribed_ > kernel-doc/rst: remove fixme comment > kernel-doc: limit the "section header:" detection to a select few > kernel-doc: concatenate contents of colliding sections > kernel-doc: reset contents and section harder > Documentation/sphinx: fix kernel-doc extension on python3 > > Jonathan Corbet (1): > sphinx: cheesy script to convert .tmpl files > > Documentation/.gitignore
Re: [PATCH 00/10] Documentation/Sphinx
On Fri, 03 Jun 2016, Jonathan Corbet wrote: > [So I'm finally trying to get into this for real, hopefully I won't be > interrupted too many times...expect a few mails as I catch up.] > > On Fri, 20 May 2016 16:39:31 +0300 > Jani Nikula wrote: > >> There are a few tradeoffs, of course. First, this requires that the >> EXPORT_SYMBOL markers are placed immediately after the function being >> exported, as kernel-doc will only look at one file at a time. This is >> the recommendation anyway. > > As I understand it, the technical reasons that kept some markers in > separate files should no longer be relevant, so this is probably OK. It > would be nice to have a sense for how many sites need to be fixed. Actually, mostly this is not a problem due to EXPORT_SYMBOL placement, but rather due to kernel-doc comments being placed in header files above function declarations while EXPORT_SYMBOL is where it should be next to the function definition. I don't think we can force people to move the kernel-doc comments for exported functions from header files next to the function definitions. The straightforward fix to this is to add an optional filename parameter to the kernel-doc extension :export: argument, to pass additional files to kernel-doc where to look for the EXPORT_SYMBOLs. For example: .. kernel-doc:: include/drm/foo.h :export: drivers/gpu/drm/foo/foo.c drivers/gpu/drm/foo/bar.c This would instruct kernel-doc to extract documentation from include/drm/foo.h for all functions that have been exported using EXPORT_SYMBOL (or _GPL) in include/drm/foo.h, drivers/gpu/drm/foo/foo.c, or drivers/gpu/drm/foo/bar.c. We have something along these lines in docproc already with the !D directive, so nothing altogether surprising. If my quick grep-fu serves me right, there are about a thousand exported symbols with kernel-doc comments in the headers. It's a ballpark figure. They come in batches; a small fraction of that many filenames in a fraction of the :export: statements would cover most of them. Before this fix, the workaround is to name the functions with :functions: argument instead of using :export:. I'm hoping this is not a blocker for merging the series. If the proposed fix is acceptable, I'll get it done before v4.8. BR, Jani. The ugly greps: $ git grep "^EXPORT_SYMBOL" | sed 's/^[^(]*(\([a-zA-Z0-9_]*\)).*/\1/' | sort > exports $ git grep -h -A1 "^/\*\*$" -- *.h | grep -v "^\(/\*\*\|--\)" | sed 's/^ \*[ ]*\([a-zA-Z0-9_][a-zA-Z0-9_]*\).*/\1/;' | sort > comments $ comm -1 -2 comments exports | wc -l 952 -- 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 00/10] Documentation/Sphinx
On Fri, 03 Jun 2016, Jonathan Corbet wrote: > On Fri, 3 Jun 2016 22:24:03 +0200 > Daniel Vetter wrote: > >> > This is maybe a job for a separate tool. A related issue is the (fairly >> > frequent) "oh look, none of the comments in $FILE are being used" >> > realization that seems to happen fairly often. It would be nice to check >> > for that, but that's going to be hard to shoehorn into Sphinx. >> >> I think much more valuable would be a tool that checks whether >> comments are pulled in anywhere (for a given source file), over the >> entire tree. Very often entire subsystems carg-cult kernel-doc, but >> never use it in a .tmpl, which means 0-day won't notice, and neither >> anyone else. > > That is kind of what I was trying to get at, yes :) For the 0-day, I've already got a preliminary kernel-doc-rst-lint script, which can be used as a checker in the kernel build. This would catch all kernel-doc comments, whether they're included to documentation or not, and complain about kernel-doc and rst issues. It won't be as comprehensive as a full Sphinx build in terms of validation, but it'll cover more kernel-doc comments. It should catch the silly errors early. 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
[PATCH v3 00/30] Fixed issues raised by tglx, then move visorbus to drivers/virt
tglx: The following patchset fixes issues you raised during your
code review of visorbus on 5/18.
Converts visorbus to use a kernel timer for periodic device-specific
callbacks instead of a workqueue, making the implementation in
periodic_work.c and periodic_work.h no longer necessary. These files
are then deleted.
The visordriver_callback_lock has been switched to a mutex.
Several module parameters and structures were removed that were no
longer being used.
Changes since v2:
- Fixed comments raised by Neil Horman regarding return -1 changes
- Fixed kernel-doc style comments for visorbus driver, and added
kernel-doc documentation for many more functions
- Reworked visorbus so we did not need notifier_lock
Changes since v1:
- Added the patch staging: unisys: visorbus change -1 return values
- Added the patch staging: unisys: visorchipset change -1 return value
- Added the patch staging: unisys: iovmcall_gnuc.h change -1 return values
Bryan Thompson (4):
staging: unisys: visorbus: Make visordriver_callback_lock a mutex
staging: unisys: visorbus: Remove unnecessary EXPORT_SYMBOL statements
staging: unisys: visorbus: Remove unused functions
staging: unisys: Remove reference to unused STANDALONE_CLIENT
David Binder (13):
staging: unisys: visorbus: remove unused module parameters
staging: unisys: visorbus: remove unused struct
staging: unisys: visorbus: modify format string to match argument
staging: unisys: visornic: Correct comment spelling mistake
staging: unisys: include: Remove thread-related enum members
staging: unisys: visorbus: fix commenting in vbusdevinfo.h
staging: unisys: visorbus: fix commenting in visorbus_main.c
staging: unisys: visorbus: fix visorchannel.c comments
staging: unisys: visorbus: Rectify commenting in visorchipset.c
staging: unisys: visorbus: Move visorbus-unique functions to private
header
staging: unisys: visorbus: rectify kerneldoc comment for struct
staging: unisys: visorbus: Remove notifier-related code from visorbus
staging: unisys: visorbus: Rename function to follow existing
convention
David Kershner (4):
staging: unisys: Move vbushelper.h to visorbus directory
include: linux: visorbus: Add visorbus to include/linux directory
Documentation: Move visorbus documentation from staging to
Documentation/
drivers: Add visorbus to the drivers directory
Erik Arfvidson (3):
staging: unisys: visorbus change -1 return values
staging: unisys: visorchipset change -1 return value
staging: unisys: iovmcall_gnuc.h change -1 return values
Tim Sell (6):
staging: unisys: visorbus: removed unused periodic_test_workqueue
staging: unisys: visorinput: remove unnecessary locking
staging: unisys: visorbus: use kernel timer instead of workqueue
staging: unisys: visorbus: remove periodic_work.h/.c
staging: unisys: visorbus: remove unused parameter from function
staging: unisys: visorbus: fix visorbus_private.h comments
.../ABI/stable/sysfs-bus-visorbus |0
.../overview.txt => Documentation/visorbus.txt |0
drivers/staging/unisys/Kconfig |3 +-
drivers/staging/unisys/MAINTAINERS |2 +-
drivers/staging/unisys/Makefile|1 -
drivers/staging/unisys/include/periodic_work.h | 40 -
drivers/staging/unisys/include/visorbus.h | 234
drivers/staging/unisys/visorbus/Makefile | 12 -
drivers/staging/unisys/visorbus/periodic_work.c| 204 ---
drivers/staging/unisys/visorbus/vbusdeviceinfo.h | 213 ---
drivers/staging/unisys/visorbus/visorbus_main.c| 1344 ---
drivers/staging/unisys/visorbus/visorbus_private.h | 68 -
drivers/staging/unisys/visorbus/visorchannel.c | 635 -
drivers/staging/unisys/visorhba/Makefile |2 -
drivers/staging/unisys/visorhba/visorhba_main.c|5 +-
drivers/staging/unisys/visorinput/Makefile |2 -
drivers/staging/unisys/visorinput/visorinput.c | 63 +-
drivers/staging/unisys/visornic/Makefile |2 -
drivers/staging/unisys/visornic/visornic_main.c|7 +-
drivers/virt/Kconfig |2 +
drivers/virt/Makefile |1 +
drivers/{staging/unisys => virt}/visorbus/Kconfig |0
drivers/virt/visorbus/Makefile |9 +
.../unisys => virt}/visorbus/controlvmchannel.h|2 +-
.../visorbus/controlvmcompletionstatus.h |0
.../unisys => virt}/visorbus/iovmcall_gnuc.h |4 +-
.../unisys => virt}/visorbus/vbuschannel.h |3 +-
drivers/virt/visorbus/vbusdeviceinfo.h | 234
.../unisys/include => virt/visorbus}/vbushelper.h |0
drivers/virt/visorbus/visorbus_main.c | 1403
drivers/virt/visorbus/visorbus_private.h | 65 +
drivers/virt/visorbus/visorchannel.c | 516 +++
.../unisys => virt}
[PATCH v3 09/30] staging: unisys: visorbus: removed unused periodic_test_workqueue
From: Tim Sell
periodic_test_workqueue was an unused relic from the past, and was removed.
Signed-off-by: Tim Sell
Signed-off-by: David Kershner
---
drivers/staging/unisys/visorbus/visorbus_main.c | 15 ---
1 file changed, 15 deletions(-)
diff --git a/drivers/staging/unisys/visorbus/visorbus_main.c
b/drivers/staging/unisys/visorbus/visorbus_main.c
index 756df41..ebdd5de 100644
--- a/drivers/staging/unisys/visorbus/visorbus_main.c
+++ b/drivers/staging/unisys/visorbus/visorbus_main.c
@@ -116,14 +116,6 @@ struct bus_type visorbus_type = {
.bus_groups = visorbus_bus_groups,
};
-static struct delayed_work periodic_work;
-
-/* YES, we need 2 workqueues.
- * The reason is, workitems on the test queue may need to cancel
- * workitems on the other queue. You will be in for trouble if you try to
- * do this with workitems queued on the same workqueue.
- */
-static struct workqueue_struct *periodic_test_workqueue;
static struct workqueue_struct *periodic_dev_workqueue;
static long long bus_count;/** number of bus instances */
/** ever-increasing */
@@ -1309,13 +1301,6 @@ visorbus_exit(void)
destroy_workqueue(periodic_dev_workqueue);
periodic_dev_workqueue = NULL;
- if (periodic_test_workqueue) {
- cancel_delayed_work(&periodic_work);
- flush_workqueue(periodic_test_workqueue);
- destroy_workqueue(periodic_test_workqueue);
- periodic_test_workqueue = NULL;
- }
-
list_for_each_safe(listentry, listtmp, &list_all_bus_instances) {
struct visor_device *dev = list_entry(listentry,
struct visor_device,
--
1.9.1
--
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 v3 20/30] staging: unisys: visorbus: fix visorchannel.c comments
From: David Binder
This patch ONLY touches comment lines, i.e., NO executable code is
affected.
Comments were fixed in visorchannel.c:
* All functions worthy of documenting now use standard kerneldoc
formatting.
* Multi-line comments were tweaked so as to use appropriate conventions.
* Minor typos were corrected.
* Useless comments were removed.
Signed-off-by: Tim Sell
Signed-off-by: David Kershner
Signed-off-by: David Binder
---
drivers/staging/unisys/visorbus/visorchannel.c | 83 ++
1 file changed, 71 insertions(+), 12 deletions(-)
diff --git a/drivers/staging/unisys/visorbus/visorchannel.c
b/drivers/staging/unisys/visorbus/visorchannel.c
index 1bfbc06..0ddfe05 100644
--- a/drivers/staging/unisys/visorbus/visorchannel.c
+++ b/drivers/staging/unisys/visorbus/visorchannel.c
@@ -15,7 +15,7 @@
*/
/*
- * This provides Supervisor channel communication primitives, which are
+ * This provides s-Par channel communication primitives, which are
* independent of the mechanism used to access the channel data.
*/
@@ -55,8 +55,28 @@ struct visorchannel {
uuid_le inst;
};
-/* Creates the struct visorchannel abstraction for a data area in memory,
- * but does NOT modify this data area.
+/**
+ * visorchannel_create_guts() - creates the struct visorchannel abstraction
+ * for a data area in memory, but does NOT modify
+ * this data area
+ * @physaddr: physical address of start of channel
+ * @channel_bytes: size of the channel in bytes; this may 0 if the channel has
+ * already been initialized in memory (which is true for all
+ * channels provided to guest environments by the s-Par
+ * back-end), in which case the actual channel size will be
+ * read from the channel header in memory
+ * @gfp: gfp_t to use when allocating memory for the data struct
+ * @guid: uuid that identifies channel type; this may 0 if the channel
+ * has already been initialized in memory (which is true for
all
+ * channels provided to guest environments by the s-Par
+ * back-end), in which case the actual channel guid will be
+ * read from the channel header in memory
+ * @needs_lock:must specify true if you have multiple threads of execution
+ * that will be calling visorchannel methods of this
+ * visorchannel at the same time
+ *
+ * Return: pointer to visorchannel that was created if successful,
+ * otherwise NULL
*/
static struct visorchannel *
visorchannel_create_guts(u64 physaddr, unsigned long channel_bytes,
@@ -77,7 +97,8 @@ visorchannel_create_guts(u64 physaddr, unsigned long
channel_bytes,
spin_lock_init(&channel->insert_lock);
spin_lock_init(&channel->remove_lock);
- /* Video driver constains the efi framebuffer so it will get a
+ /*
+* Video driver constains the efi framebuffer so it will get a
* conflict resource when requesting its full mem region. Since
* we are only using the efi framebuffer for video we can ignore
* this. Remember that we haven't requested it so we don't try to
@@ -214,6 +235,12 @@ visorchannel_set_clientpartition(struct visorchannel
*channel,
return 0;
}
+/**
+ * visorchannel_get_uuid() - queries the UUID of the designated channel
+ * @channel: the channel to query
+ *
+ * Return: the UUID of the provided channel
+ */
uuid_le
visorchannel_get_uuid(struct visorchannel *channel)
{
@@ -260,22 +287,25 @@ visorchannel_get_header(struct visorchannel *channel)
return (void __iomem *)&channel->chan_hdr;
}
-/** Return offset of a specific SIGNAL_QUEUE_HEADER from the beginning of a
- * channel header
+/*
+ * Return offset of a specific SIGNAL_QUEUE_HEADER from the beginning of a
+ * channel header
*/
#define SIG_QUEUE_OFFSET(chan_hdr, q) \
((chan_hdr)->ch_space_offset + \
((q) * sizeof(struct signal_queue_header)))
-/** Return offset of a specific queue entry (data) from the beginning of a
- * channel header
+/*
+ * Return offset of a specific queue entry (data) from the beginning of a
+ * channel header
*/
#define SIG_DATA_OFFSET(chan_hdr, q, sig_hdr, slot) \
(SIG_QUEUE_OFFSET(chan_hdr, q) + (sig_hdr)->sig_base_offset + \
((slot) * (sig_hdr)->signal_size))
-/** Write the contents of a specific field within a SIGNAL_QUEUE_HEADER back
- * into host memory
+/*
+ * Write the contents of a specific field within a SIGNAL_QUEUE_HEADER back
+ * into host memory
*/
#define SIG_WRITE_FIELD(channel, queue, sig_hdr, FIELD)
\
(visorchannel_write(channel, \
@@ -350,7 +380,8 @@ signalremove_inner(struct visorchannel *channel, u32 queue,
void *msg)
return false;
sig_hdr.num_received++;
[PATCH v3 11/30] staging: unisys: visorbus: use kernel timer instead of workqueue
From: Tim Sell
A kernel timer is now used as the vehicle to periodically call the
channel_interrupt function of registered visor drivers, instead of a
workqueue.
This simplifies a lot of things by making periodic_work.c and
periodic_work.h no longer necessary. This change also means that the
channel_interrupt() callbacks registered by visor drivers (via
visorbus_register_visor_driver()) will now be called in atomic context
(i.e., canNOT sleep) rather than kernel thread context (CAN sleep).
Fortunately this did NOT necessitate any change to the existing
channel_interrupt() callbacks, because none of them ever perform any
operations that would be invalid in atomic context.
Signed-off-by: Tim Sell
Signed-off-by: David Kershner
---
drivers/staging/unisys/include/visorbus.h | 10 +++--
drivers/staging/unisys/visorbus/visorbus_main.c | 54 +++--
2 files changed, 21 insertions(+), 43 deletions(-)
diff --git a/drivers/staging/unisys/include/visorbus.h
b/drivers/staging/unisys/include/visorbus.h
index 9baf1ec..9bb88bb 100644
--- a/drivers/staging/unisys/include/visorbus.h
+++ b/drivers/staging/unisys/include/visorbus.h
@@ -34,8 +34,9 @@
#include
#include
#include
+#include
+#include
-#include "periodic_work.h"
#include "channel.h"
struct visor_driver;
@@ -126,8 +127,8 @@ struct visor_driver {
* device: Device struct meant for use by the bus driver
* only.
* list_all: Used by the bus driver to enumerate devices.
- * periodic_work: Device work queue. Private use by bus driver
- * only.
+ * timer: Timer fired periodically to do interrupt-type
+ * activity.
* being_removed: Indicates that the device is being removed from
* the bus. Private bus driver use only.
* visordriver_callback_lock: Used by the bus driver to lock when handling
@@ -157,7 +158,8 @@ struct visor_device {
/* These fields are for private use by the bus driver only. */
struct device device;
struct list_head list_all;
- struct periodic_work *periodic_work;
+ struct timer_list timer;
+ bool timer_active;
bool being_removed;
struct semaphore visordriver_callback_lock;
bool pausing;
diff --git a/drivers/staging/unisys/visorbus/visorbus_main.c
b/drivers/staging/unisys/visorbus/visorbus_main.c
index ebdd5de..e98e720 100644
--- a/drivers/staging/unisys/visorbus/visorbus_main.c
+++ b/drivers/staging/unisys/visorbus/visorbus_main.c
@@ -19,7 +19,6 @@
#include "visorbus.h"
#include "visorbus_private.h"
#include "version.h"
-#include "periodic_work.h"
#include "vbuschannel.h"
#include "guestlinuxdebug.h"
#include "vmcallinterface.h"
@@ -116,7 +115,6 @@ struct bus_type visorbus_type = {
.bus_groups = visorbus_bus_groups,
};
-static struct workqueue_struct *periodic_dev_workqueue;
static long long bus_count;/** number of bus instances */
/** ever-increasing */
@@ -222,10 +220,6 @@ visorbus_release_device(struct device *xdev)
{
struct visor_device *dev = to_visor_device(xdev);
- if (dev->periodic_work) {
- visor_periodic_work_destroy(dev->periodic_work);
- dev->periodic_work = NULL;
- }
if (dev->visorchannel) {
visorchannel_destroy(dev->visorchannel);
dev->visorchannel = NULL;
@@ -530,35 +524,36 @@ unregister_driver_attributes(struct visor_driver *drv)
}
static void
-dev_periodic_work(void *xdev)
+dev_periodic_work(unsigned long __opaque)
{
- struct visor_device *dev = xdev;
+ struct visor_device *dev = (struct visor_device *)__opaque;
struct visor_driver *drv = to_visor_driver(dev->device.driver);
- down(&dev->visordriver_callback_lock);
if (drv->channel_interrupt)
drv->channel_interrupt(dev);
- up(&dev->visordriver_callback_lock);
- if (!visor_periodic_work_nextperiod(dev->periodic_work))
- put_device(&dev->device);
+ mod_timer(&dev->timer, jiffies + POLLJIFFIES_NORMALCHANNEL);
}
static void
dev_start_periodic_work(struct visor_device *dev)
{
- if (dev->being_removed)
+ if (dev->being_removed || dev->timer_active)
return;
/* now up by at least 2 */
get_device(&dev->device);
- if (!visor_periodic_work_start(dev->periodic_work))
- put_device(&dev->device);
+ dev->timer.expires = jiffies + POLLJIFFIES_NORMALCHANNEL;
+ add_timer(&dev->timer);
+ dev->timer_active = true;
}
static void
dev_stop_periodic_work(struct visor_device *dev)
{
- if (visor_periodic_work_stop(dev->periodic_work))
- put_device(&dev->device);
+ if (!dev->timer_active)
+ return;
+ del_timer_sync(&dev->t
[PATCH v3 21/30] staging: unisys: visorbus: Rectify commenting in visorchipset.c
From: David Binder
Adds kerneldoc formatting to appropriate functions. Other multi-line
comments now use proper formatting.
Signed-off-by: David Binder
Signed-off-by: David Kershner
Reviewed-by: Tim Sell
---
drivers/staging/unisys/visorbus/visorchipset.c | 292 -
1 file changed, 190 insertions(+), 102 deletions(-)
diff --git a/drivers/staging/unisys/visorbus/visorchipset.c
b/drivers/staging/unisys/visorbus/visorchipset.c
index b5942c6..f8e1fa5 100644
--- a/drivers/staging/unisys/visorbus/visorchipset.c
+++ b/drivers/staging/unisys/visorbus/visorchipset.c
@@ -78,10 +78,11 @@ visorchipset_release(struct inode *inode, struct file *file)
return 0;
}
-/* When the controlvm channel is idle for at least MIN_IDLE_SECONDS,
-* we switch to slow polling mode. As soon as we get a controlvm
-* message, we switch back to fast polling mode.
-*/
+/*
+ * When the controlvm channel is idle for at least MIN_IDLE_SECONDS,
+ * we switch to slow polling mode. As soon as we get a controlvm
+ * message, we switch back to fast polling mode.
+ */
#define MIN_IDLE_SECONDS 10
static unsigned long poll_jiffies = POLLJIFFIES_CONTROLVMCHANNEL_FAST;
/* when we got our last controlvm message */
@@ -112,7 +113,8 @@ static struct visorchannel *controlvm_channel;
/* Manages the request payload in the controlvm channel */
struct visor_controlvm_payload_info {
u8 *ptr;/* pointer to base address of payload pool */
- u64 offset; /* offset from beginning of controlvm
+ u64 offset; /*
+* offset from beginning of controlvm
* channel to beginning of payload * pool
*/
u32 bytes; /* number of bytes in payload pool */
@@ -120,15 +122,17 @@ struct visor_controlvm_payload_info {
static struct visor_controlvm_payload_info controlvm_payload_info;
-/* The following globals are used to handle the scenario where we are unable to
- * offload the payload from a controlvm message due to memory requirements. In
+/*
+ * The following globals are used to handle the scenario where we are unable to
+ * offload the payload from a controlvm message due to memory requirements. In
* this scenario, we simply stash the controlvm message, then attempt to
* process it again the next time controlvm_periodic_work() runs.
*/
static struct controlvm_message controlvm_pending_msg;
static bool controlvm_pending_msg_valid;
-/* This identifies a data buffer that has been received via a controlvm
messages
+/*
+ * This identifies a data buffer that has been received via a controlvm
messages
* in a remote --> local CONTROLVM_TRANSMIT_FILE conversation.
*/
struct putfile_buffer_entry {
@@ -136,13 +140,15 @@ struct putfile_buffer_entry {
struct parser_context *parser_ctx; /* points to input data buffer */
};
-/* List of struct putfile_request *, via next_putfile_request member.
+/*
+ * List of struct putfile_request *, via next_putfile_request member.
* Each entry in this list identifies an outstanding TRANSMIT_FILE
* conversation.
*/
static LIST_HEAD(putfile_request_list);
-/* This describes a buffer and its current state of transfer (e.g., how many
+/*
+ * This describes a buffer and its current state of transfer (e.g., how many
* bytes have already been supplied as putfile data, and how many bytes are
* remaining) for a putfile_request.
*/
@@ -154,8 +160,9 @@ struct putfile_active_buffer {
};
#define PUTFILE_REQUEST_SIG 0x0906101302281211
-/* This identifies a single remote --> local CONTROLVM_TRANSMIT_FILE
- * conversation. Structs of this type are dynamically linked into
+/*
+ * This identifies a single remote --> local CONTROLVM_TRANSMIT_FILE
+ * conversation. Structs of this type are dynamically linked into
* .
*/
struct putfile_request {
@@ -167,7 +174,8 @@ struct putfile_request {
/* link to next struct putfile_request */
struct list_head next_putfile_request;
- /* head of putfile_buffer_entry list, which describes the data to be
+ /*
+* head of putfile_buffer_entry list, which describes the data to be
* supplied as putfile data;
* - this list is added to when controlvm messages come in that supply
* file data
@@ -183,11 +191,13 @@ struct putfile_request {
/* data not yet read within current putfile_buffer_entry */
struct putfile_active_buffer active_buf;
- /* <0 = failed, 0 = in-progress, >0 = successful; */
- /* note that this must be set with req_list_lock, and if you set <0, */
- /* it is your responsibility to also free up all of the other objects */
- /* in this struct (like input_buffer_list, active_buf.parser_ctx) */
- /* before releasing the lock */
+ /*
+* <0 = failed, 0 = in-progress, >0 = successful;
+* note that this must be set with req_list_lock, an
[PATCH v3 07/30] staging: unisys: visornic: Correct comment spelling mistake
From: David Binder Fixes a comment spelling mistake in visornic. Signed-off-by: David Binder Signed-off-by: David Kershner Reviewed-by: Tim Sell --- drivers/staging/unisys/visornic/visornic_main.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/drivers/staging/unisys/visornic/visornic_main.c b/drivers/staging/unisys/visornic/visornic_main.c index fd7c9a6..9e5b258 100644 --- a/drivers/staging/unisys/visornic/visornic_main.c +++ b/drivers/staging/unisys/visornic/visornic_main.c @@ -1587,7 +1587,7 @@ drain_resp_queue(struct uiscmdrsp *cmdrsp, struct visornic_devdata *devdata) * * Drain the respones queue of any responses from the IO partition. * Process the responses as we get them. - * Returns when response queue is empty or when the threadd stops. + * Returns when response queue is empty or when the thread stops. */ static void service_resp_queue(struct uiscmdrsp *cmdrsp, struct visornic_devdata *devdata, -- 1.9.1 -- 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 v3 26/30] staging: unisys: visorbus: fix visorbus_private.h comments
From: Tim Sell This patch ONLY touches comment lines, i.e., NO executable code is affected. Comments were fixed in visorbus_private.h: * Minor typos were corrected. * Useless comments were removed. Signed-off-by: Tim Sell Signed-off-by: David Kershner --- drivers/staging/unisys/visorbus/visorbus_private.h | 7 +-- 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/drivers/staging/unisys/visorbus/visorbus_private.h b/drivers/staging/unisys/visorbus/visorbus_private.h index a7b1d4f..3f6ad52 100644 --- a/drivers/staging/unisys/visorbus/visorbus_private.h +++ b/drivers/staging/unisys/visorbus/visorbus_private.h @@ -37,16 +37,11 @@ void device_destroy_response(struct visor_device *p, int response); void device_resume_response(struct visor_device *p, int response); void device_pause_response(struct visor_device *p, int response); -/* visorbus init and exit functions */ int visorbus_init(void); void visorbus_exit(void); -/* Visorchannel access functions */ +/* visorchannel access functions */ -/* Note that for visorchannel_create() - * and arguments may be 0 if we are a channel CLIENT. - * In this case, the values can simply be read from the channel header. - */ struct visorchannel *visorchannel_create(u64 physaddr, unsigned long channel_bytes, gfp_t gfp, uuid_le guid); -- 1.9.1 -- 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 v3 18/30] staging: unisys: visorbus: fix commenting in vbusdevinfo.h
From: David Binder
This patch ONLY touches comment lines, i.e., NO executable code is
affected.
* All functions worthy of documenting now use standard kerneldoc
formatting.
* Multi-line comments were tweaked so as to use appropriate conventions.
* Minor typos were corrected.
Signed-off-by: David Binder
Signed-off-by: Tim Sell
Signed-off-by: David Kershner
---
drivers/staging/unisys/visorbus/vbusdeviceinfo.h | 65
1 file changed, 43 insertions(+), 22 deletions(-)
diff --git a/drivers/staging/unisys/visorbus/vbusdeviceinfo.h
b/drivers/staging/unisys/visorbus/vbusdeviceinfo.h
index abdab4a..e6bfed1 100644
--- a/drivers/staging/unisys/visorbus/vbusdeviceinfo.h
+++ b/drivers/staging/unisys/visorbus/vbusdeviceinfo.h
@@ -19,7 +19,8 @@
#pragma pack(push, 1) /* both GCC and VC now allow this pragma */
-/* An array of this struct is present in the channel area for each vbus.
+/*
+ * An array of this struct is present in the channel area for each vbus.
* (See vbuschannel.h.)
* It is filled in by the client side to provide info about the device
* and driver from the client's perspective.
@@ -34,19 +35,28 @@ struct ultra_vbus_deviceinfo {
#pragma pack(pop)
-/* Reads chars from the buffer at for bytes, and writes to
- * the buffer at , which is bytes long, ensuring never to
- * overflow the buffer at , using the following rules:
- * - printable characters are simply copied from the buffer at to the
- * buffer at
- * - intervening streaks of non-printable characters in the buffer at
- * are replaced with a single space in the buffer at
+/**
+ * vbuschannel_sanitize_buffer() - remove non-printable chars from buffer
+ * @p: destination buffer where chars are written to
+ * @remain: number of bytes that can be written starting at #p
+ * @src: pointer to source buffer
+ * @srcmax: number of valid characters at #src
+ *
+ * Reads chars from the buffer at @src for @srcmax bytes, and writes to
+ * the buffer at @p, which is @remain bytes long, ensuring never to
+ * overflow the buffer at @p, using the following rules:
+ * - printable characters are simply copied from the buffer at @src to the
+ * buffer at @p
+ * - intervening streaks of non-printable characters in the buffer at @src
+ * are replaced with a single space in the buffer at @p
* Note that we pay no attention to '\0'-termination.
- * Returns the number of bytes written to .
*
- * Pass == NULL and == 0 for this special behavior. In this
+ * Pass @p == NULL and @remain == 0 for this special behavior -- In this
* case, we simply return the number of bytes that WOULD HAVE been written
- * to a buffer at , had it been infinitely big.
+ * to a buffer at @p, had it been infinitely big.
+ *
+ * Return: the number of bytes written to @p (or WOULD HAVE been written to
+ * @p, as described in the previous paragraph)
*/
static inline int
vbuschannel_sanitize_buffer(char *p, int remain, char *src, int srcmax)
@@ -92,14 +102,18 @@ vbuschannel_sanitize_buffer(char *p, int remain, char
*src, int srcmax)
p++; chars++; remain--; \
} while (0)
-/* Converts the non-negative value at to an ascii decimal string
- * at , writing at most bytes. Note there is NO '\0' termination
- * written to .
+/**
+ * vbuschannel_itoa() - convert non-negative int to string
+ * @p: destination string
+ * @remain: max number of bytes that can be written to @p
+ * @num: input int to convert
+ *
+ * Converts the non-negative value at @num to an ascii decimal string
+ * at @p, writing at most @remain bytes. Note there is NO '\0' termination
+ * written to @p.
*
- * Returns the number of bytes written to .
+ * Return: number of bytes written to @p
*
- * Note that we create this function because we need to do this operation in
- * an environment-independent way (since we are in a common header file).
*/
static inline int
vbuschannel_itoa(char *p, int remain, int num)
@@ -141,13 +155,20 @@ vbuschannel_itoa(char *p, int remain, int num)
return digits;
}
-/* Reads , and converts its contents to a printable string at ,
- * writing at most bytes. Note there is NO '\0' termination
- * written to .
+/**
+ * vbuschannel_devinfo_to_string() - format a struct ultra_vbus_deviceinfo
+ * to a printable string
+ * @devinfo: the struct ultra_vbus_deviceinfo to format
+ * @p: destination string area
+ * @remain: size of destination string area in bytes
+ * @devix: the device index to be included in the output data, or -1 if no
+ * device index is to be included
*
- * Pass >= 0 if you want a device index presented.
+ * Reads @devInfo, and converts its contents to a printable string at @p,
+ * writing at most @remain bytes. Note there is NO '\0' termination
+ * written to @p.
*
- * Returns the number of bytes written to .
+ * Return: number of bytes written to @p
*/
static inline int
vbuschannel_devinfo_to_string(struct
[PATCH v3 04/30] staging: unisys: visorbus: remove unused module parameters
From: David Binder Removes unused module parameters from visorbus_main.c, in response to findings by SonarQube. Signed-off-by: David Binder Signed-off-by: David Kershner Reviewed-by: Tim Sell --- drivers/staging/unisys/visorbus/visorbus_main.c | 9 + 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/drivers/staging/unisys/visorbus/visorbus_main.c b/drivers/staging/unisys/visorbus/visorbus_main.c index 2ed9628..71bff07 100644 --- a/drivers/staging/unisys/visorbus/visorbus_main.c +++ b/drivers/staging/unisys/visorbus/visorbus_main.c @@ -27,10 +27,9 @@ #define MYDRVNAME "visorbus" /* module parameters */ -static int visorbus_debug; static int visorbus_forcematch; static int visorbus_forcenomatch; -static int visorbus_debugref; + #define SERIALLOOPBACKCHANADDR (100 * 1024 * 1024) /* Display string that is guaranteed to be no longer the 99 characters*/ @@ -1332,9 +1331,6 @@ visorbus_exit(void) remove_bus_type(); } -module_param_named(debug, visorbus_debug, int, S_IRUGO); -MODULE_PARM_DESC(visorbus_debug, "1 to debug"); - module_param_named(forcematch, visorbus_forcematch, int, S_IRUGO); MODULE_PARM_DESC(visorbus_forcematch, "1 to force a successful dev <--> drv match"); @@ -1342,6 +1338,3 @@ MODULE_PARM_DESC(visorbus_forcematch, module_param_named(forcenomatch, visorbus_forcenomatch, int, S_IRUGO); MODULE_PARM_DESC(visorbus_forcenomatch, "1 to force an UNsuccessful dev <--> drv match"); - -module_param_named(debugref, visorbus_debugref, int, S_IRUGO); -MODULE_PARM_DESC(visorbus_debugref, "1 to debug reference counting"); -- 1.9.1 -- 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 v3 08/30] staging: unisys: include: Remove thread-related enum members
From: David Binder
Code relating to ktheads was previously removed from s-Par driver code.
This patch cleans up lingering remnants of kthreads by removing thread-
related enum types.
Signed-off-by: David Binder
Signed-off-by: David Kershner
Reviewed-by: Tim Sell
---
drivers/staging/unisys/include/guestlinuxdebug.h | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/drivers/staging/unisys/include/guestlinuxdebug.h
b/drivers/staging/unisys/include/guestlinuxdebug.h
index b81287f..5af3f77 100644
--- a/drivers/staging/unisys/include/guestlinuxdebug.h
+++ b/drivers/staging/unisys/include/guestlinuxdebug.h
@@ -56,7 +56,7 @@ enum driver_pc { /* POSTCODE driver identifier
tuples */
UISLIB_PC = 0xD0,
UISLIB_PC_uislib_c = 0xD1,
UISLIB_PC_uisqueue_c = 0xD2,
- UISLIB_PC_uisthread_c = 0xD3,
+ /* 0xD3 RESERVED */
UISLIB_PC_uisutils_c = 0xD4,
};
@@ -91,7 +91,7 @@ enum event_pc { /* POSTCODE event
identifier tuples */
DRIVER_EXIT_PC = 0x0AC,
MALLOC_FAILURE_PC = 0x0AD,
QUEUE_DELAYED_WORK_PC = 0x0AE,
- UISLIB_THREAD_FAILURE_PC = 0x0B7,
+ /* 0x0B7 RESERVED */
VBUS_CHANNEL_ENTRY_PC = 0x0B8,
VBUS_CHANNEL_FAILURE_PC = 0x0B9,
VBUS_CHANNEL_EXIT_PC = 0x0BA,
--
1.9.1
--
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 v3 15/30] staging: unisys: visorbus: Remove unused functions
From: Bryan Thompson
Remove visorbus_clear_channel, visorchannel_signalqueue_slots_avail,
visorchannel_signalqueue_max_slots, visorchannel_clear, and
visorchannel_debug which are no longer called by any driver.
Signed-off-by: Bryan Thompson
Signed-off-by: David Kershner
Reviewed-by: Tim Sell
---
drivers/staging/unisys/include/visorbus.h | 9 --
drivers/staging/unisys/visorbus/visorbus_main.c | 7 --
drivers/staging/unisys/visorbus/visorchannel.c | 161
3 files changed, 177 deletions(-)
diff --git a/drivers/staging/unisys/include/visorbus.h
b/drivers/staging/unisys/include/visorbus.h
index 3ba01cf..cbe240a 100644
--- a/drivers/staging/unisys/include/visorbus.h
+++ b/drivers/staging/unisys/include/visorbus.h
@@ -185,8 +185,6 @@ int visorbus_read_channel(struct visor_device *dev,
int visorbus_write_channel(struct visor_device *dev,
unsigned long offset, void *src,
unsigned long nbytes);
-int visorbus_clear_channel(struct visor_device *dev,
- unsigned long offset, u8 ch, unsigned long nbytes);
void visorbus_enable_channel_interrupts(struct visor_device *dev);
void visorbus_disable_channel_interrupts(struct visor_device *dev);
#endif
@@ -206,17 +204,12 @@ int visorchannel_read(struct visorchannel *channel, ulong
offset,
void *local, ulong nbytes);
int visorchannel_write(struct visorchannel *channel, ulong offset,
void *local, ulong nbytes);
-int visorchannel_clear(struct visorchannel *channel, ulong offset,
- u8 ch, ulong nbytes);
bool visorchannel_signalremove(struct visorchannel *channel, u32 queue,
void *msg);
bool visorchannel_signalinsert(struct visorchannel *channel, u32 queue,
void *msg);
bool visorchannel_signalempty(struct visorchannel *channel, u32 queue);
-int visorchannel_signalqueue_slots_avail(struct visorchannel *channel,
-u32 queue);
-int visorchannel_signalqueue_max_slots(struct visorchannel *channel, u32
queue);
u64 visorchannel_get_physaddr(struct visorchannel *channel);
ulong visorchannel_get_nbytes(struct visorchannel *channel);
char *visorchannel_id(struct visorchannel *channel, char *s);
@@ -226,8 +219,6 @@ int visorchannel_set_clientpartition(struct visorchannel
*channel,
u64 partition_handle);
uuid_le visorchannel_get_uuid(struct visorchannel *channel);
char *visorchannel_uuid_id(uuid_le *guid, char *s);
-void visorchannel_debug(struct visorchannel *channel, int num_queues,
- struct seq_file *seq, u32 off);
void __iomem *visorchannel_get_header(struct visorchannel *channel);
#define BUS_ROOT_DEVICEUINT_MAX
diff --git a/drivers/staging/unisys/visorbus/visorbus_main.c
b/drivers/staging/unisys/visorbus/visorbus_main.c
index f7f5986..8c1754f9 100644
--- a/drivers/staging/unisys/visorbus/visorbus_main.c
+++ b/drivers/staging/unisys/visorbus/visorbus_main.c
@@ -715,13 +715,6 @@ visorbus_write_channel(struct visor_device *dev, unsigned
long offset,
}
EXPORT_SYMBOL_GPL(visorbus_write_channel);
-int
-visorbus_clear_channel(struct visor_device *dev, unsigned long offset, u8 ch,
- unsigned long nbytes)
-{
- return visorchannel_clear(dev->visorchannel, offset, ch, nbytes);
-}
-
/** We don't really have a real interrupt, so for now we just call the
* interrupt function periodically...
*/
diff --git a/drivers/staging/unisys/visorbus/visorchannel.c
b/drivers/staging/unisys/visorbus/visorchannel.c
index 1f626c3..43315c2 100644
--- a/drivers/staging/unisys/visorbus/visorchannel.c
+++ b/drivers/staging/unisys/visorbus/visorchannel.c
@@ -255,41 +255,6 @@ visorchannel_write(struct visorchannel *channel, ulong
offset,
return 0;
}
-int
-visorchannel_clear(struct visorchannel *channel, ulong offset, u8 ch,
- ulong nbytes)
-{
- int err;
- int bufsize = PAGE_SIZE;
- int written = 0;
- u8 *buf;
-
- buf = (u8 *)__get_free_page(GFP_KERNEL);
- if (!buf)
- return -ENOMEM;
-
- memset(buf, ch, bufsize);
-
- while (nbytes > 0) {
- int thisbytes = bufsize;
-
- if (nbytes < thisbytes)
- thisbytes = nbytes;
- err = visorchannel_write(channel, offset + written,
-buf, thisbytes);
- if (err)
- goto out_free_page;
-
- written += thisbytes;
- nbytes -= thisbytes;
- }
- err = 0;
-
-out_free_page:
- free_page((unsigned long)buf);
- return err;
-}
-
void __iomem *
visorchannel_get_header(struct visorchannel *channel)
{
@@ -490,129 +455,3 @@ visorchannel_signalinsert(struct visorchannel *channel,
u32 queue, void *msg)
r
[PATCH v3 17/30] staging: unisys: visorbus: remove unused parameter from function
From: Tim Sell
The off parameter to visorchannel_create_guts() was never used, so it was
removed.
Signed-off-by: Tim Sell
Signed-off-by: David Kershner
---
drivers/staging/unisys/visorbus/visorchannel.c | 7 +++
1 file changed, 3 insertions(+), 4 deletions(-)
diff --git a/drivers/staging/unisys/visorbus/visorchannel.c
b/drivers/staging/unisys/visorbus/visorchannel.c
index 43315c2..1bfbc06 100644
--- a/drivers/staging/unisys/visorbus/visorchannel.c
+++ b/drivers/staging/unisys/visorbus/visorchannel.c
@@ -60,8 +60,7 @@ struct visorchannel {
*/
static struct visorchannel *
visorchannel_create_guts(u64 physaddr, unsigned long channel_bytes,
-gfp_t gfp, unsigned long off,
-uuid_le guid, bool needs_lock)
+gfp_t gfp, uuid_le guid, bool needs_lock)
{
struct visorchannel *channel;
int err;
@@ -145,7 +144,7 @@ struct visorchannel *
visorchannel_create(u64 physaddr, unsigned long channel_bytes,
gfp_t gfp, uuid_le guid)
{
- return visorchannel_create_guts(physaddr, channel_bytes, gfp, 0, guid,
+ return visorchannel_create_guts(physaddr, channel_bytes, gfp, guid,
false);
}
@@ -153,7 +152,7 @@ struct visorchannel *
visorchannel_create_with_lock(u64 physaddr, unsigned long channel_bytes,
gfp_t gfp, uuid_le guid)
{
- return visorchannel_create_guts(physaddr, channel_bytes, gfp, 0, guid,
+ return visorchannel_create_guts(physaddr, channel_bytes, gfp, guid,
true);
}
--
1.9.1
--
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 v3 03/30] staging: unisys: iovmcall_gnuc.h change -1 return values
From: Erik Arfvidson
This patch changes the vague -1 return values to -EPERM.
This operation is not supported is a good alternative
to -1 because the return is basically telling the caller
that the processor doesn't support vmcall operations.
Signed-off-by: Erik Arfvidson
Signed-off-by: David Kershner
Reviewed-by: Tim Sell
---
drivers/staging/unisys/visorbus/iovmcall_gnuc.h | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/drivers/staging/unisys/visorbus/iovmcall_gnuc.h
b/drivers/staging/unisys/visorbus/iovmcall_gnuc.h
index b08b6ec..98ea7f3 100644
--- a/drivers/staging/unisys/visorbus/iovmcall_gnuc.h
+++ b/drivers/staging/unisys/visorbus/iovmcall_gnuc.h
@@ -22,7 +22,7 @@ __unisys_vmcall_gnuc(unsigned long tuple, unsigned long
reg_ebx,
cpuid(0x0001, &cpuid_eax, &cpuid_ebx, &cpuid_ecx, &cpuid_edx);
if (!(cpuid_ecx & 0x8000))
- return -1;
+ return -EPERM;
__asm__ __volatile__(".byte 0x00f, 0x001, 0x0c1" : "=a"(result) :
"a"(tuple), "b"(reg_ebx), "c"(reg_ecx));
@@ -40,7 +40,7 @@ __unisys_extended_vmcall_gnuc(unsigned long long tuple,
cpuid(0x0001, &cpuid_eax, &cpuid_ebx, &cpuid_ecx, &cpuid_edx);
if (!(cpuid_ecx & 0x8000))
- return -1;
+ return -EPERM;
__asm__ __volatile__(".byte 0x00f, 0x001, 0x0c1" : "=a"(result) :
"a"(tuple), "b"(reg_ebx), "c"(reg_ecx), "d"(reg_edx));
--
1.9.1
--
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 v3 13/30] staging: unisys: visorbus: Make visordriver_callback_lock a mutex
From: Bryan Thompson
visordriver_callback_lock is just a binary semaphore that logically
makes more sense as a mutex.
Signed-off-by: Bryan Thompson
Signed-off-by: David Kershner
Reviewed-by: Tim Sell
---
drivers/staging/unisys/include/visorbus.h | 2 +-
drivers/staging/unisys/visorbus/visorbus_main.c | 10 +-
2 files changed, 6 insertions(+), 6 deletions(-)
diff --git a/drivers/staging/unisys/include/visorbus.h
b/drivers/staging/unisys/include/visorbus.h
index 9bb88bb..3ba01cf 100644
--- a/drivers/staging/unisys/include/visorbus.h
+++ b/drivers/staging/unisys/include/visorbus.h
@@ -161,7 +161,7 @@ struct visor_device {
struct timer_list timer;
bool timer_active;
bool being_removed;
- struct semaphore visordriver_callback_lock;
+ struct mutex visordriver_callback_lock;
bool pausing;
bool resuming;
u32 chipset_bus_no;
diff --git a/drivers/staging/unisys/visorbus/visorbus_main.c
b/drivers/staging/unisys/visorbus/visorbus_main.c
index e98e720..2e0eb03 100644
--- a/drivers/staging/unisys/visorbus/visorbus_main.c
+++ b/drivers/staging/unisys/visorbus/visorbus_main.c
@@ -574,7 +574,7 @@ visordriver_probe_device(struct device *xdev)
if (!drv->probe)
return -ENODEV;
- down(&dev->visordriver_callback_lock);
+ mutex_lock(&dev->visordriver_callback_lock);
dev->being_removed = false;
res = drv->probe(dev);
@@ -584,7 +584,7 @@ visordriver_probe_device(struct device *xdev)
fix_vbus_dev_info(dev);
}
- up(&dev->visordriver_callback_lock);
+ mutex_unlock(&dev->visordriver_callback_lock);
return res;
}
@@ -600,11 +600,11 @@ visordriver_remove_device(struct device *xdev)
dev = to_visor_device(xdev);
drv = to_visor_driver(xdev->driver);
- down(&dev->visordriver_callback_lock);
+ mutex_lock(&dev->visordriver_callback_lock);
dev->being_removed = true;
if (drv->remove)
drv->remove(dev);
- up(&dev->visordriver_callback_lock);
+ mutex_unlock(&dev->visordriver_callback_lock);
dev_stop_periodic_work(dev);
put_device(&dev->device);
@@ -764,7 +764,7 @@ create_visor_device(struct visor_device *dev)
POSTCODE_LINUX_4(DEVICE_CREATE_ENTRY_PC, chipset_dev_no, chipset_bus_no,
POSTCODE_SEVERITY_INFO);
- sema_init(&dev->visordriver_callback_lock, 1); /* unlocked */
+ mutex_init(&dev->visordriver_callback_lock);
dev->device.bus = &visorbus_type;
dev->device.groups = visorbus_channel_groups;
device_initialize(&dev->device);
--
1.9.1
--
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 v3 05/30] staging: unisys: visorbus: remove unused struct
From: David Binder
Removes unused struct definition, channel_size_info, in response to
findings by SonarQube.
Signed-off-by: David Binder
Signed-off-by: David Kershner
Reviewed-by: Tim Sell
---
drivers/staging/unisys/visorbus/visorbus_main.c | 6 --
1 file changed, 6 deletions(-)
diff --git a/drivers/staging/unisys/visorbus/visorbus_main.c
b/drivers/staging/unisys/visorbus/visorbus_main.c
index 71bff07..08d560c 100644
--- a/drivers/staging/unisys/visorbus/visorbus_main.c
+++ b/drivers/staging/unisys/visorbus/visorbus_main.c
@@ -1260,12 +1260,6 @@ chipset_device_resume(struct visor_device *dev_info)
initiate_chipset_device_pause_resume(dev_info, false);
}
-struct channel_size_info {
- uuid_le guid;
- unsigned long min_size;
- unsigned long max_size;
-};
-
int
visorbus_init(void)
{
--
1.9.1
--
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 v3 01/30] staging: unisys: visorbus change -1 return values
From: Erik Arfvidson This patch removes the vague -1 return values from the write_vbus channel functions. Nobody was checking the return values and the value stored into the vbus info is not critical to the functioning of the device. Signed-off-by: Erik Arfvidson Signed-off-by: David Kershner Reviewed-by: Tim Sell --- drivers/staging/unisys/visorbus/visorbus_main.c | 33 ++--- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/drivers/staging/unisys/visorbus/visorbus_main.c b/drivers/staging/unisys/visorbus/visorbus_main.c index 3a147db..2ed9628 100644 --- a/drivers/staging/unisys/visorbus/visorbus_main.c +++ b/drivers/staging/unisys/visorbus/visorbus_main.c @@ -866,9 +866,12 @@ get_vbus_header_info(struct visorchannel *chan, /* Write the contents of to the struct * spar_vbus_channel_protocol.chp_info. + * + * Returns void since this is debug information and not needed for + * device functionality. */ -static int +static void write_vbus_chp_info(struct visorchannel *chan, struct spar_vbus_headerinfo *hdr_info, struct ultra_vbus_deviceinfo *info) @@ -876,18 +879,19 @@ write_vbus_chp_info(struct visorchannel *chan, int off = sizeof(struct channel_header) + hdr_info->chp_info_offset; if (hdr_info->chp_info_offset == 0) - return -1; + return; - if (visorchannel_write(chan, off, info, sizeof(*info)) < 0) - return -1; - return 0; + visorchannel_write(chan, off, info, sizeof(*info)); } /* Write the contents of to the struct * spar_vbus_channel_protocol.bus_info. + * + * Returns void since this is debug information and not needed for + * device functionality. */ -static int +static void write_vbus_bus_info(struct visorchannel *chan, struct spar_vbus_headerinfo *hdr_info, struct ultra_vbus_deviceinfo *info) @@ -895,17 +899,18 @@ write_vbus_bus_info(struct visorchannel *chan, int off = sizeof(struct channel_header) + hdr_info->bus_info_offset; if (hdr_info->bus_info_offset == 0) - return -1; + return; - if (visorchannel_write(chan, off, info, sizeof(*info)) < 0) - return -1; - return 0; + visorchannel_write(chan, off, info, sizeof(*info)); } /* Write the contents of to the * struct spar_vbus_channel_protocol.dev_info[]. + * + * Returns void since this is debug information and not needed for + * device functionality. */ -static int +static void write_vbus_dev_info(struct visorchannel *chan, struct spar_vbus_headerinfo *hdr_info, struct ultra_vbus_deviceinfo *info, int devix) @@ -915,11 +920,9 @@ write_vbus_dev_info(struct visorchannel *chan, (hdr_info->device_info_struct_bytes * devix); if (hdr_info->dev_info_offset == 0) - return -1; + return; - if (visorchannel_write(chan, off, info, sizeof(*info)) < 0) - return -1; - return 0; + visorchannel_write(chan, off, info, sizeof(*info)); } /* For a child device just created on a client bus, fill in -- 1.9.1 -- 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 v3 29/30] Documentation: Move visorbus documentation from staging to Documentation/
This patch simple does a git mv of the drivers/staging/unisys/Documentation directory to Documentation. Renames overview.txt to visorbus.txt and renames sysfs-platform-visorchipset to the correct name sysfs-bus-visorbus. Signed-off-by: David Kershner Reviewed-by: Tim Sell --- .../ABI/stable/sysfs-bus-visorbus | 0 .../unisys/Documentation/overview.txt => Documentation/visorbus.txt | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename drivers/staging/unisys/Documentation/ABI/sysfs-platform-visorchipset => Documentation/ABI/stable/sysfs-bus-visorbus (100%) rename drivers/staging/unisys/Documentation/overview.txt => Documentation/visorbus.txt (100%) diff --git a/drivers/staging/unisys/Documentation/ABI/sysfs-platform-visorchipset b/Documentation/ABI/stable/sysfs-bus-visorbus similarity index 100% rename from drivers/staging/unisys/Documentation/ABI/sysfs-platform-visorchipset rename to Documentation/ABI/stable/sysfs-bus-visorbus diff --git a/drivers/staging/unisys/Documentation/overview.txt b/Documentation/visorbus.txt similarity index 100% rename from drivers/staging/unisys/Documentation/overview.txt rename to Documentation/visorbus.txt -- 1.9.1 -- 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 v3 23/30] staging: unisys: visorbus: rectify kerneldoc comment for struct
From: David Binder
Fixes the kerneldoc comment for struct visor_device - the struct members
were not listed with the appropriate @ prefix.
Signed-off-by: David Binder
Signed-off-by: David Kershner
---
drivers/staging/unisys/include/visorbus.h | 34 +++
1 file changed, 17 insertions(+), 17 deletions(-)
diff --git a/drivers/staging/unisys/include/visorbus.h
b/drivers/staging/unisys/include/visorbus.h
index 666a04e..c836c8d 100644
--- a/drivers/staging/unisys/include/visorbus.h
+++ b/drivers/staging/unisys/include/visorbus.h
@@ -121,33 +121,33 @@ struct visor_driver {
/**
* struct visor_device - A device type for things "plugged" into the visorbus
* bus
- * visorchannel: Points to the channel that the device is
+ * @visorchannel: Points to the channel that the device is
* associated with.
- * channel_type_guid: Identifies the channel type to the bus driver.
- * device: Device struct meant for use by the bus driver
+ * @channel_type_guid: Identifies the channel type to the bus driver.
+ * @device:Device struct meant for use by the bus driver
* only.
- * list_all: Used by the bus driver to enumerate devices.
- * timer: Timer fired periodically to do interrupt-type
+ * @list_all: Used by the bus driver to enumerate devices.
+ * @timer: Timer fired periodically to do interrupt-type
* activity.
- * being_removed: Indicates that the device is being removed from
+ * @being_removed: Indicates that the device is being removed from
* the bus. Private bus driver use only.
- * visordriver_callback_lock: Used by the bus driver to lock when handling
+ * @visordriver_callback_lock: Used by the bus driver to lock when handling
* channel events.
- * pausing:Indicates that a change towards a paused state.
+ * @pausing: Indicates that a change towards a paused state.
* is in progress. Only modified by the bus driver.
- * resuming: Indicates that a change towards a running state
+ * @resuming: Indicates that a change towards a running state
* is in progress. Only modified by the bus driver.
- * chipset_bus_no: Private field used by the bus driver.
- * chipset_dev_no: Private field used the bus driver.
- * state: Used to indicate the current state of the
+ * @chipset_bus_no:Private field used by the bus driver.
+ * @chipset_dev_no:Private field used the bus driver.
+ * @state: Used to indicate the current state of the
* device.
- * inst: Unique GUID for this instance of the device.
- * name: Name of the device.
- * pending_msg_hdr:For private use by bus driver to respond to
+ * @inst: Unique GUID for this instance of the device.
+ * @name: Name of the device.
+ * @pending_msg_hdr: For private use by bus driver to respond to
* hypervisor requests.
- * vbus_hdr_info: A pointer to header info. Private use by bus
+ * @vbus_hdr_info: A pointer to header info. Private use by bus
* driver.
- * partition_uuid: Indicates client partion id. This should be the
+ * @partition_uuid:Indicates client partion id. This should be the
* same across all visor_devices in the current
* guest. Private use by bus driver only.
*/
--
1.9.1
--
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 v3 16/30] staging: unisys: Remove reference to unused STANDALONE_CLIENT
From: Bryan Thompson
The STANDALONE_CLIENT define is no longer used by Unisys driver code.
Signed-off-by: Bryan Thompson
Signed-off-by: David Kershner
Reviewed-by: Tim Sell
---
drivers/staging/unisys/include/visorbus.h | 2 --
1 file changed, 2 deletions(-)
diff --git a/drivers/staging/unisys/include/visorbus.h
b/drivers/staging/unisys/include/visorbus.h
index cbe240a..fb53a65 100644
--- a/drivers/staging/unisys/include/visorbus.h
+++ b/drivers/staging/unisys/include/visorbus.h
@@ -176,7 +176,6 @@ struct visor_device {
#define to_visor_device(x) container_of(x, struct visor_device, device)
-#ifndef STANDALONE_CLIENT
int visorbus_register_visor_driver(struct visor_driver *);
void visorbus_unregister_visor_driver(struct visor_driver *);
int visorbus_read_channel(struct visor_device *dev,
@@ -187,7 +186,6 @@ int visorbus_write_channel(struct visor_device *dev,
unsigned long nbytes);
void visorbus_enable_channel_interrupts(struct visor_device *dev);
void visorbus_disable_channel_interrupts(struct visor_device *dev);
-#endif
/* Note that for visorchannel_create()
* and arguments may be 0 if we are a channel CLIENT.
--
1.9.1
--
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 v3 06/30] staging: unisys: visorbus: modify format string to match argument
From: David Binder Modifies the format string of snprintf to expect an unsigned int instead of a signed one, per the supplied argument. Signed-off-by: David Binder Signed-off-by: David Kershner Reviewed-by: Tim Sell --- drivers/staging/unisys/visorbus/visorbus_main.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/drivers/staging/unisys/visorbus/visorbus_main.c b/drivers/staging/unisys/visorbus/visorbus_main.c index 08d560c..756df41 100644 --- a/drivers/staging/unisys/visorbus/visorbus_main.c +++ b/drivers/staging/unisys/visorbus/visorbus_main.c @@ -433,7 +433,7 @@ static ssize_t client_bus_info_show(struct device *dev, if (vdev->name) partition_name = vdev->name; shift = snprintf(pos, remain, -"Client device / client driver info for %s eartition (vbus #%d):\n", +"Client device / client driver info for %s eartition (vbus #%u):\n", partition_name, vdev->chipset_dev_no); pos += shift; remain -= shift; -- 1.9.1 -- 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 v3 12/30] staging: unisys: visorbus: remove periodic_work.h/.c
From: Tim Sell
These files were made no-longer-necessary by recent commits.
Signed-off-by: Tim Sell
Signed-off-by: David Kershner
---
drivers/staging/unisys/include/periodic_work.h | 40 -
drivers/staging/unisys/visorbus/Makefile| 1 -
drivers/staging/unisys/visorbus/periodic_work.c | 204
drivers/staging/unisys/visorbus/visorchipset.c | 1 -
4 files changed, 246 deletions(-)
delete mode 100644 drivers/staging/unisys/include/periodic_work.h
delete mode 100644 drivers/staging/unisys/visorbus/periodic_work.c
diff --git a/drivers/staging/unisys/include/periodic_work.h
b/drivers/staging/unisys/include/periodic_work.h
deleted file mode 100644
index 0b3335a..000
--- a/drivers/staging/unisys/include/periodic_work.h
+++ /dev/null
@@ -1,40 +0,0 @@
-/* periodic_work.h
- *
- * Copyright (C) 2010 - 2013 UNISYS CORPORATION
- * All rights reserved.
- *
- * 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, GOOD TITLE or
- * NON INFRINGEMENT. See the GNU General Public License for more
- * details.
- */
-
-#ifndef __PERIODIC_WORK_H__
-#define __PERIODIC_WORK_H__
-
-#include
-#include
-
-/* PERIODIC_WORK an opaque structure to users.
- * Fields are declared only in the implementation .c files.
- */
-struct periodic_work;
-
-struct periodic_work *
-visor_periodic_work_create(ulong jiffy_interval,
- struct workqueue_struct *workqueue,
- void (*workfunc)(void *),
- void *workfuncarg,
- const char *devnam);
-void visor_periodic_work_destroy(struct periodic_work *pw);
-bool visor_periodic_work_nextperiod(struct periodic_work *pw);
-bool visor_periodic_work_start(struct periodic_work *pw);
-bool visor_periodic_work_stop(struct periodic_work *pw);
-
-#endif
diff --git a/drivers/staging/unisys/visorbus/Makefile
b/drivers/staging/unisys/visorbus/Makefile
index fc790e7..f3730d8 100644
--- a/drivers/staging/unisys/visorbus/Makefile
+++ b/drivers/staging/unisys/visorbus/Makefile
@@ -7,6 +7,5 @@ obj-$(CONFIG_UNISYS_VISORBUS) += visorbus.o
visorbus-y := visorbus_main.o
visorbus-y += visorchannel.o
visorbus-y += visorchipset.o
-visorbus-y += periodic_work.o
ccflags-y += -Idrivers/staging/unisys/include
diff --git a/drivers/staging/unisys/visorbus/periodic_work.c
b/drivers/staging/unisys/visorbus/periodic_work.c
deleted file mode 100644
index 00b1527..000
--- a/drivers/staging/unisys/visorbus/periodic_work.c
+++ /dev/null
@@ -1,204 +0,0 @@
-/* periodic_work.c
- *
- * Copyright (C) 2010 - 2015 UNISYS CORPORATION
- * All rights reserved.
- *
- * This program is free software; you can redistribute it and/or modify it
- * under the terms and conditions of the GNU General Public License,
- * version 2, as published by the Free Software Foundation.
- *
- * 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, GOOD TITLE or
- * NON INFRINGEMENT. See the GNU General Public License for more
- * details.
- */
-
-/*
- * Helper functions to schedule periodic work in Linux kernel mode.
- */
-#include
-
-#include "periodic_work.h"
-
-#define MYDRVNAME "periodic_work"
-
-struct periodic_work {
- rwlock_t lock;
- struct delayed_work work;
- void (*workfunc)(void *);
- void *workfuncarg;
- bool is_scheduled;
- bool want_to_stop;
- ulong jiffy_interval;
- struct workqueue_struct *workqueue;
- const char *devnam;
-};
-
-static void periodic_work_func(struct work_struct *work)
-{
- struct periodic_work *pw;
-
- pw = container_of(work, struct periodic_work, work.work);
- (*pw->workfunc)(pw->workfuncarg);
-}
-
-struct periodic_work
-*visor_periodic_work_create(ulong jiffy_interval,
- struct workqueue_struct *workqueue,
- void (*workfunc)(void *),
- void *workfuncarg,
- const char *devnam)
-{
- struct periodic_work *pw;
-
- pw = kzalloc(sizeof(*pw), GFP_KERNEL | __GFP_NORETRY);
- if (!pw)
- return NULL;
-
- rwlock_init(&pw->lock);
- pw->jiffy_interval = jiffy_interval;
- pw->workqueue = workqueue;
- pw->workfunc = workfunc;
- pw->workfuncarg = workfuncarg;
- pw->devnam = devnam;
- return pw;
-}
-EXPORT_SYMBOL_GPL(visor_periodic_work_create);
-
-void visor_periodic_work_destroy(struct periodic_work *pw)
-{
- kfree(
[PATCH v3 30/30] drivers: Add visorbus to the drivers directory
visorbus is currently located at drivers/staging/visorbus,
this patch moves it to drivers/virt.
Signed-off-by: David Kershner
Reviewed-by: Tim Sell
---
drivers/staging/unisys/Kconfig| 3 +--
drivers/staging/unisys/Makefile | 1 -
drivers/virt/Kconfig | 2 ++
drivers/virt/Makefile | 1 +
drivers/{staging/unisys => virt}/visorbus/Kconfig | 0
drivers/{staging/unisys => virt}/visorbus/Makefile| 0
drivers/{staging/unisys => virt}/visorbus/controlvmchannel.h | 0
drivers/{staging/unisys => virt}/visorbus/controlvmcompletionstatus.h | 0
drivers/{staging/unisys => virt}/visorbus/iovmcall_gnuc.h | 0
drivers/{staging/unisys => virt}/visorbus/vbuschannel.h | 0
drivers/{staging/unisys => virt}/visorbus/vbusdeviceinfo.h| 0
drivers/{staging/unisys => virt}/visorbus/vbushelper.h| 0
drivers/{staging/unisys => virt}/visorbus/visorbus_main.c | 0
drivers/{staging/unisys => virt}/visorbus/visorbus_private.h | 0
drivers/{staging/unisys => virt}/visorbus/visorchannel.c | 0
drivers/{staging/unisys => virt}/visorbus/visorchipset.c | 0
drivers/{staging/unisys => virt}/visorbus/vmcallinterface.h | 0
17 files changed, 4 insertions(+), 3 deletions(-)
rename drivers/{staging/unisys => virt}/visorbus/Kconfig (100%)
rename drivers/{staging/unisys => virt}/visorbus/Makefile (100%)
rename drivers/{staging/unisys => virt}/visorbus/controlvmchannel.h (100%)
rename drivers/{staging/unisys => virt}/visorbus/controlvmcompletionstatus.h
(100%)
rename drivers/{staging/unisys => virt}/visorbus/iovmcall_gnuc.h (100%)
rename drivers/{staging/unisys => virt}/visorbus/vbuschannel.h (100%)
rename drivers/{staging/unisys => virt}/visorbus/vbusdeviceinfo.h (100%)
rename drivers/{staging/unisys => virt}/visorbus/vbushelper.h (100%)
rename drivers/{staging/unisys => virt}/visorbus/visorbus_main.c (100%)
rename drivers/{staging/unisys => virt}/visorbus/visorbus_private.h (100%)
rename drivers/{staging/unisys => virt}/visorbus/visorchannel.c (100%)
rename drivers/{staging/unisys => virt}/visorbus/visorchipset.c (100%)
rename drivers/{staging/unisys => virt}/visorbus/vmcallinterface.h (100%)
diff --git a/drivers/staging/unisys/Kconfig b/drivers/staging/unisys/Kconfig
index 4f1f5e6..dab09a9 100644
--- a/drivers/staging/unisys/Kconfig
+++ b/drivers/staging/unisys/Kconfig
@@ -3,7 +3,7 @@
#
menuconfig UNISYSSPAR
bool "Unisys SPAR driver support"
- depends on X86_64 && !UML
+ depends on X86_64 && !UML && VIRT_DRIVERS
select PCI
select ACPI
---help---
@@ -11,7 +11,6 @@ menuconfig UNISYSSPAR
if UNISYSSPAR
-source "drivers/staging/unisys/visorbus/Kconfig"
source "drivers/staging/unisys/visornic/Kconfig"
source "drivers/staging/unisys/visorinput/Kconfig"
source "drivers/staging/unisys/visorhba/Kconfig"
diff --git a/drivers/staging/unisys/Makefile b/drivers/staging/unisys/Makefile
index 20eb098..e45f44b 100644
--- a/drivers/staging/unisys/Makefile
+++ b/drivers/staging/unisys/Makefile
@@ -1,7 +1,6 @@
#
# Makefile for Unisys SPAR drivers
#
-obj-$(CONFIG_UNISYS_VISORBUS) += visorbus/
obj-$(CONFIG_UNISYS_VISORNIC) += visornic/
obj-$(CONFIG_UNISYS_VISORINPUT)+= visorinput/
obj-$(CONFIG_UNISYS_VISORHBA) += visorhba/
diff --git a/drivers/virt/Kconfig b/drivers/virt/Kconfig
index 99ebdde..0c60896 100644
--- a/drivers/virt/Kconfig
+++ b/drivers/virt/Kconfig
@@ -30,4 +30,6 @@ config FSL_HV_MANAGER
4) A kernel interface for receiving callbacks when a managed
partition shuts down.
+source "drivers/virt/visorbus/Kconfig"
endif
+
diff --git a/drivers/virt/Makefile b/drivers/virt/Makefile
index c47f04d..44aebd2 100644
--- a/drivers/virt/Makefile
+++ b/drivers/virt/Makefile
@@ -3,3 +3,4 @@
#
obj-$(CONFIG_FSL_HV_MANAGER) += fsl_hypervisor.o
+obj-$(CONFIG_UNISYS_VISORBUS) += visorbus/
diff --git a/drivers/staging/unisys/visorbus/Kconfig
b/drivers/virt/visorbus/Kconfig
similarity index 100%
rename from drivers/staging/unisys/visorbus/Kconfig
rename to drivers/virt/visorbus/Kconfig
diff --git a/drivers/staging/unisys/visorbus/Makefile
b/drivers/virt/visorbus/Makefile
similarity index 100%
rename from drivers/staging/unisys/visorbus/Makefile
rename to drivers/virt/visorbus/Makefile
diff --git a/drivers/staging/unisys/visorbus/controlvmchannel.h
b/drivers/virt/visorbus/controlvmchannel.h
similarity index 100%
rename from drivers/staging/unisys/visorbus/controlvmchannel.h
rename to drivers/virt/visorbus/controlvmchannel.h
diff --git a/drivers/staging/unisys/visorbus/controlvmcompletionstatus.h
b/drivers/virt/visorbus/controlvmcompletionstatus.h
similarity index 100%
rename from drivers/stagin
[PATCH v3 28/30] include: linux: visorbus: Add visorbus to include/linux directory
Update include/linux to include the s-Par associated common include
header files needed for the s-Par visorbus.
Since we have now moved the include directories over to
include/linux/visorbus this patch makes all of the visor
drivers visorbus, visorinput, visornic, and visorhba use
the new include folders.
Signed-off-by: David Kershner
Reviewed-by: Tim Sell
---
drivers/staging/unisys/MAINTAINERS| 2 +-
drivers/staging/unisys/visorbus/Makefile | 2 --
drivers/staging/unisys/visorbus/controlvmchannel.h| 2 +-
drivers/staging/unisys/visorbus/vbuschannel.h | 3 ++-
drivers/staging/unisys/visorbus/visorbus_main.c | 6 +++---
drivers/staging/unisys/visorbus/visorchannel.c| 4 ++--
drivers/staging/unisys/visorbus/visorchipset.c| 8
drivers/staging/unisys/visorbus/vmcallinterface.h | 5 ++---
drivers/staging/unisys/visorhba/Makefile | 2 --
drivers/staging/unisys/visorhba/visorhba_main.c | 5 ++---
drivers/staging/unisys/visorinput/Makefile| 2 --
drivers/staging/unisys/visorinput/visorinput.c| 6 +++---
drivers/staging/unisys/visornic/Makefile | 2 --
drivers/staging/unisys/visornic/visornic_main.c | 5 ++---
.../staging/unisys/include => include/linux/visorbus}/channel.h | 0
.../unisys/include => include/linux/visorbus}/channel_guid.h | 0
.../unisys/include => include/linux/visorbus}/diagchannel.h | 0
.../unisys/include => include/linux/visorbus}/guestlinuxdebug.h | 0
.../staging/unisys/include => include/linux/visorbus}/iochannel.h | 0
.../staging/unisys/include => include/linux/visorbus}/version.h | 0
.../staging/unisys/include => include/linux/visorbus}/visorbus.h | 0
21 files changed, 22 insertions(+), 32 deletions(-)
rename {drivers/staging/unisys/include => include/linux/visorbus}/channel.h
(100%)
rename {drivers/staging/unisys/include =>
include/linux/visorbus}/channel_guid.h (100%)
rename {drivers/staging/unisys/include =>
include/linux/visorbus}/diagchannel.h (100%)
rename {drivers/staging/unisys/include =>
include/linux/visorbus}/guestlinuxdebug.h (100%)
rename {drivers/staging/unisys/include => include/linux/visorbus}/iochannel.h
(100%)
rename {drivers/staging/unisys/include => include/linux/visorbus}/version.h
(100%)
rename {drivers/staging/unisys/include => include/linux/visorbus}/visorbus.h
(100%)
diff --git a/drivers/staging/unisys/MAINTAINERS
b/drivers/staging/unisys/MAINTAINERS
index 1f0425b..146a8c3 100644
--- a/drivers/staging/unisys/MAINTAINERS
+++ b/drivers/staging/unisys/MAINTAINERS
@@ -1,5 +1,5 @@
Unisys s-Par drivers
M: David Kershner
S: Maintained
-F: Documentation/s-Par/overview.txt
+F: Documentation/visorbus.txt
F: drivers/staging/unisys/
diff --git a/drivers/staging/unisys/visorbus/Makefile
b/drivers/staging/unisys/visorbus/Makefile
index f3730d8..7f328cc 100644
--- a/drivers/staging/unisys/visorbus/Makefile
+++ b/drivers/staging/unisys/visorbus/Makefile
@@ -7,5 +7,3 @@ obj-$(CONFIG_UNISYS_VISORBUS) += visorbus.o
visorbus-y := visorbus_main.o
visorbus-y += visorchannel.o
visorbus-y += visorchipset.o
-
-ccflags-y += -Idrivers/staging/unisys/include
diff --git a/drivers/staging/unisys/visorbus/controlvmchannel.h
b/drivers/staging/unisys/visorbus/controlvmchannel.h
index 03e36fb..0a0e221 100644
--- a/drivers/staging/unisys/visorbus/controlvmchannel.h
+++ b/drivers/staging/unisys/visorbus/controlvmchannel.h
@@ -16,7 +16,7 @@
#define __CONTROLVMCHANNEL_H__
#include
-#include "channel.h"
+#include
/* {2B3C2D10-7EF5-4ad8-B966-3448B7386B3D} */
#define SPAR_CONTROLVM_CHANNEL_PROTOCOL_UUID \
diff --git a/drivers/staging/unisys/visorbus/vbuschannel.h
b/drivers/staging/unisys/visorbus/vbuschannel.h
index 90fa12e..3e0388d 100644
--- a/drivers/staging/unisys/visorbus/vbuschannel.h
+++ b/drivers/staging/unisys/visorbus/vbuschannel.h
@@ -23,8 +23,9 @@
* the client devices and client drivers for the server end to see.
*/
#include
+#include
+
#include "vbusdeviceinfo.h"
-#include "channel.h"
/* {193b331b-c58f-11da-95a9-00e08161165f} */
#define SPAR_VBUS_CHANNEL_PROTOCOL_UUID \
diff --git a/drivers/staging/unisys/visorbus/visorbus_main.c
b/drivers/staging/unisys/visorbus/visorbus_main.c
index 293532f..2af051c 100644
--- a/drivers/staging/unisys/visorbus/visorbus_main.c
+++ b/drivers/staging/unisys/visorbus/visorbus_main.c
@@ -16,11 +16,11 @@
#include
-#include "visorbus.h"
+#include
+#include
+#include
#include "visorbus_private.h"
-#include "version.h"
#include "vbuschannel.h"
-#include "guestlinuxdebug.h"
#include "vmcallinterface.h"
#define MYDRVNAME "visorbus"
diff --git a/drivers/staging/unisys/visorbus/visorchannel.c
b/drivers/staging/unisys/visorbus/visorchannel.c
index fbae66e.
[PATCH v3 24/30] staging: unisys: visorbus: Remove notifier-related code from visorbus
From: David Binder
When this functionality was first implemented, visorchipset and visorbus
were separate drivers, which necessitated a registration mechanism for
them to communicate. More-recently, visorchipset and visorbus were
combined into a single driver, and now exist as separate source files
within the same driver, known as 'visorbus'. This eliminated the need
for a registration mechanism, but it has remained nevertheless until now.
For the sake of simplification, this registration mechanism is now being
removed.
Signed-off-by: David Binder
Signed-off-by: David Kershner
Reviewed-by: Tim Sell
---
drivers/staging/unisys/visorbus/visorbus_main.c| 76 +++-
drivers/staging/unisys/visorbus/visorbus_private.h | 50 +++-
drivers/staging/unisys/visorbus/visorchipset.c | 130 -
3 files changed, 50 insertions(+), 206 deletions(-)
diff --git a/drivers/staging/unisys/visorbus/visorbus_main.c
b/drivers/staging/unisys/visorbus/visorbus_main.c
index 2468264..c361077 100644
--- a/drivers/staging/unisys/visorbus/visorbus_main.c
+++ b/drivers/staging/unisys/visorbus/visorbus_main.c
@@ -119,32 +119,6 @@ struct bus_type visorbus_type = {
static long long bus_count;/* number of bus instances */
/* ever-increasing */
-static void chipset_bus_create(struct visor_device *bus_info);
-static void chipset_bus_destroy(struct visor_device *bus_info);
-static void chipset_device_create(struct visor_device *dev_info);
-static void chipset_device_destroy(struct visor_device *dev_info);
-static void chipset_device_pause(struct visor_device *dev_info);
-static void chipset_device_resume(struct visor_device *dev_info);
-
-/*
- * These functions are implemented herein, and are called by the chipset
- * driver to notify us about specific events.
- */
-static struct visorchipset_busdev_notifiers chipset_notifiers = {
- .bus_create = chipset_bus_create,
- .bus_destroy = chipset_bus_destroy,
- .device_create = chipset_device_create,
- .device_destroy = chipset_device_destroy,
- .device_pause = chipset_device_pause,
- .device_resume = chipset_device_resume,
-};
-
-/*
- * These functions are implemented in the chipset driver, and we call them
- * herein when we want to acknowledge a specific event.
- */
-static struct visorchipset_busdev_responders chipset_responders;
-
/* filled in with info about parent chipset driver when we register with it */
static struct ultra_vbus_deviceinfo chipset_driverinfo;
/* filled in with info about this driver, wrt it servicing client busses */
@@ -1171,7 +1145,7 @@ remove_all_visor_devices(void)
}
}
-static void
+void
chipset_bus_create(struct visor_device *dev)
{
int rc;
@@ -1188,19 +1162,17 @@ chipset_bus_create(struct visor_device *dev)
POSTCODE_LINUX_3(CHIPSET_INIT_SUCCESS_PC, bus_no,
POSTCODE_SEVERITY_INFO);
- if (chipset_responders.bus_create)
- (*chipset_responders.bus_create) (dev, rc);
+ bus_create_response(dev, rc);
}
-static void
+void
chipset_bus_destroy(struct visor_device *dev)
{
remove_bus_instance(dev);
- if (chipset_responders.bus_destroy)
- (*chipset_responders.bus_destroy)(dev, 0);
+ bus_destroy_response(dev, 0);
}
-static void
+void
chipset_device_create(struct visor_device *dev_info)
{
int rc;
@@ -1211,8 +1183,7 @@ chipset_device_create(struct visor_device *dev_info)
POSTCODE_SEVERITY_INFO);
rc = create_visor_device(dev_info);
- if (chipset_responders.device_create)
- chipset_responders.device_create(dev_info, rc);
+ device_create_response(dev_info, rc);
if (rc < 0)
POSTCODE_LINUX_4(DEVICE_CREATE_FAILURE_PC, dev_no, bus_no,
@@ -1222,13 +1193,12 @@ chipset_device_create(struct visor_device *dev_info)
POSTCODE_SEVERITY_INFO);
}
-static void
+void
chipset_device_destroy(struct visor_device *dev_info)
{
remove_visor_device(dev_info);
- if (chipset_responders.device_destroy)
- (*chipset_responders.device_destroy) (dev_info, 0);
+ device_destroy_response(dev_info, 0);
}
/**
@@ -1247,14 +1217,8 @@ pause_state_change_complete(struct visor_device *dev,
int status)
return;
dev->pausing = false;
- if (!chipset_responders.device_pause) /* this can never happen! */
- return;
- /* Notify the chipset driver that the pause is complete, which
-* will presumably want to send some sort of response to the
-* initiator.
-*/
- (*chipset_responders.device_pause) (dev, status);
+ visorchipset_device_pause_response(dev, status);
}
/**
@@ -1273,15 +1237,13 @@ resume_state_change_complete(struct visor_device *dev,
int status)
return;
dev->resuming =
[PATCH v3 14/30] staging: unisys: visorbus: Remove unnecessary EXPORT_SYMBOL statements
From: Bryan Thompson
The driver that is now visorbus started out as multiple separate drivers,
and when they were merged the EXPORT_SYMBOL statements that were required
for separate drivers were left in the code. This patch removes those now
unnecessary exports.
Signed-off-by: Bryan Thompson
Signed-off-by: David Kershner
Reviewed-by: Tim Sell
---
drivers/staging/unisys/visorbus/visorbus_main.c | 1 -
drivers/staging/unisys/visorbus/visorchannel.c | 17 -
drivers/staging/unisys/visorbus/visorchipset.c | 2 --
3 files changed, 20 deletions(-)
diff --git a/drivers/staging/unisys/visorbus/visorbus_main.c
b/drivers/staging/unisys/visorbus/visorbus_main.c
index 2e0eb03..f7f5986 100644
--- a/drivers/staging/unisys/visorbus/visorbus_main.c
+++ b/drivers/staging/unisys/visorbus/visorbus_main.c
@@ -721,7 +721,6 @@ visorbus_clear_channel(struct visor_device *dev, unsigned
long offset, u8 ch,
{
return visorchannel_clear(dev->visorchannel, offset, ch, nbytes);
}
-EXPORT_SYMBOL_GPL(visorbus_clear_channel);
/** We don't really have a real interrupt, so for now we just call the
* interrupt function periodically...
diff --git a/drivers/staging/unisys/visorbus/visorchannel.c
b/drivers/staging/unisys/visorbus/visorchannel.c
index 4337358..1f626c3 100644
--- a/drivers/staging/unisys/visorbus/visorchannel.c
+++ b/drivers/staging/unisys/visorbus/visorchannel.c
@@ -148,7 +148,6 @@ visorchannel_create(u64 physaddr, unsigned long
channel_bytes,
return visorchannel_create_guts(physaddr, channel_bytes, gfp, 0, guid,
false);
}
-EXPORT_SYMBOL_GPL(visorchannel_create);
struct visorchannel *
visorchannel_create_with_lock(u64 physaddr, unsigned long channel_bytes,
@@ -157,7 +156,6 @@ visorchannel_create_with_lock(u64 physaddr, unsigned long
channel_bytes,
return visorchannel_create_guts(physaddr, channel_bytes, gfp, 0, guid,
true);
}
-EXPORT_SYMBOL_GPL(visorchannel_create_with_lock);
void
visorchannel_destroy(struct visorchannel *channel)
@@ -171,21 +169,18 @@ visorchannel_destroy(struct visorchannel *channel)
}
kfree(channel);
}
-EXPORT_SYMBOL_GPL(visorchannel_destroy);
u64
visorchannel_get_physaddr(struct visorchannel *channel)
{
return channel->physaddr;
}
-EXPORT_SYMBOL_GPL(visorchannel_get_physaddr);
ulong
visorchannel_get_nbytes(struct visorchannel *channel)
{
return channel->nbytes;
}
-EXPORT_SYMBOL_GPL(visorchannel_get_nbytes);
char *
visorchannel_uuid_id(uuid_le *guid, char *s)
@@ -193,28 +188,24 @@ visorchannel_uuid_id(uuid_le *guid, char *s)
sprintf(s, "%pUL", guid);
return s;
}
-EXPORT_SYMBOL_GPL(visorchannel_uuid_id);
char *
visorchannel_id(struct visorchannel *channel, char *s)
{
return visorchannel_uuid_id(&channel->guid, s);
}
-EXPORT_SYMBOL_GPL(visorchannel_id);
char *
visorchannel_zoneid(struct visorchannel *channel, char *s)
{
return visorchannel_uuid_id(&channel->chan_hdr.zone_uuid, s);
}
-EXPORT_SYMBOL_GPL(visorchannel_zoneid);
u64
visorchannel_get_clientpartition(struct visorchannel *channel)
{
return channel->chan_hdr.partition_handle;
}
-EXPORT_SYMBOL_GPL(visorchannel_get_clientpartition);
int
visorchannel_set_clientpartition(struct visorchannel *channel,
@@ -223,7 +214,6 @@ visorchannel_set_clientpartition(struct visorchannel
*channel,
channel->chan_hdr.partition_handle = partition_handle;
return 0;
}
-EXPORT_SYMBOL_GPL(visorchannel_set_clientpartition);
uuid_le
visorchannel_get_uuid(struct visorchannel *channel)
@@ -243,7 +233,6 @@ visorchannel_read(struct visorchannel *channel, ulong
offset,
return 0;
}
-EXPORT_SYMBOL_GPL(visorchannel_read);
int
visorchannel_write(struct visorchannel *channel, ulong offset,
@@ -265,7 +254,6 @@ visorchannel_write(struct visorchannel *channel, ulong
offset,
return 0;
}
-EXPORT_SYMBOL_GPL(visorchannel_write);
int
visorchannel_clear(struct visorchannel *channel, ulong offset, u8 ch,
@@ -301,14 +289,12 @@ out_free_page:
free_page((unsigned long)buf);
return err;
}
-EXPORT_SYMBOL_GPL(visorchannel_clear);
void __iomem *
visorchannel_get_header(struct visorchannel *channel)
{
return (void __iomem *)&channel->chan_hdr;
}
-EXPORT_SYMBOL_GPL(visorchannel_get_header);
/** Return offset of a specific SIGNAL_QUEUE_HEADER from the beginning of a
* channel header
@@ -522,7 +508,6 @@ visorchannel_signalqueue_slots_avail(struct visorchannel
*channel, u32 queue)
slots_avail = sig_hdr.max_signals - slots_used;
return (int)slots_avail;
}
-EXPORT_SYMBOL_GPL(visorchannel_signalqueue_slots_avail);
int
visorchannel_signalqueue_max_slots(struct visorchannel *channel, u32 queue)
@@ -533,7 +518,6 @@ visorchannel_signalqueue_max_slots(struct visorchannel
*channel, u32 queue)
return 0;
return (int)sig_hdr.max
[PATCH v3 02/30] staging: unisys: visorchipset change -1 return value
From: Erik Arfvidson
This patch changes the vague -1 return value to -EINVAL
It also modifies the caller of parahotplug_request_complete
to check the return value and return appropriate result.
Signed-off-by: Erik Arfvidson
Signed-off-by: David Kershner
Reviewed-by: Tim Sell
---
drivers/staging/unisys/visorbus/visorchipset.c | 7 +--
1 file changed, 5 insertions(+), 2 deletions(-)
diff --git a/drivers/staging/unisys/visorbus/visorchipset.c
b/drivers/staging/unisys/visorbus/visorchipset.c
index 5ba5936..7f44913 100644
--- a/drivers/staging/unisys/visorbus/visorchipset.c
+++ b/drivers/staging/unisys/visorbus/visorchipset.c
@@ -1613,7 +1613,7 @@ parahotplug_request_complete(int id, u16 active)
}
spin_unlock(¶hotplug_request_list_lock);
- return -1;
+ return -EINVAL;
}
/*
@@ -2036,11 +2036,14 @@ static ssize_t devicedisabled_store(struct device *dev,
const char *buf, size_t count)
{
unsigned int id;
+ int err;
if (kstrtouint(buf, 10, &id))
return -EINVAL;
- parahotplug_request_complete(id, 0);
+ err = parahotplug_request_complete(id, 0);
+ if (err < 0)
+ return err;
return count;
}
--
1.9.1
--
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 v3 10/30] staging: unisys: visorinput: remove unnecessary locking
From: Tim Sell
Locking in the _interrupt() function is NOT necessary so long as we ensure
that interrupts have been stopped whenever we need to pause or resume the
device, which we now do.
While a device is paused, we ensure that interrupts stay disabled, i.e.
that the _interrupt() function will NOT be called, yet remember the desired
state in devdata->interrupts_enabled if open() or close() are called are
called while the device is paused. Then when the device is resumed, we
restore the actual state of interrupts (i.e., whether _interrupt() is going
to be called or not) to the desired state in devdata->interrupts_enabled.
Signed-off-by: Tim Sell
Signed-off-by: David Kershner
---
drivers/staging/unisys/visorinput/visorinput.c | 57 +-
1 file changed, 47 insertions(+), 10 deletions(-)
diff --git a/drivers/staging/unisys/visorinput/visorinput.c
b/drivers/staging/unisys/visorinput/visorinput.c
index 12a3570..9c00710 100644
--- a/drivers/staging/unisys/visorinput/visorinput.c
+++ b/drivers/staging/unisys/visorinput/visorinput.c
@@ -66,6 +66,7 @@ struct visorinput_devdata {
struct rw_semaphore lock_visor_dev; /* lock for dev */
struct input_dev *visorinput_dev;
bool paused;
+ bool interrupts_enabled;
unsigned int keycode_table_bytes; /* size of following array */
/* for keyboard devices: visorkbd_keycode[] + visorkbd_ext_keycode[] */
unsigned char keycode_table[0];
@@ -228,7 +229,21 @@ static int visorinput_open(struct input_dev
*visorinput_dev)
return -EINVAL;
}
dev_dbg(&visorinput_dev->dev, "%s opened\n", __func__);
+
+ /*
+* If we're not paused, really enable interrupts.
+* Regardless of whether we are paused, set a flag indicating
+* interrupts should be enabled so when we resume, interrupts
+* will really be enabled.
+*/
+ down_write(&devdata->lock_visor_dev);
+ devdata->interrupts_enabled = true;
+ if (devdata->paused)
+ goto out_unlock;
visorbus_enable_channel_interrupts(devdata->dev);
+
+out_unlock:
+ up_write(&devdata->lock_visor_dev);
return 0;
}
@@ -243,7 +258,22 @@ static void visorinput_close(struct input_dev
*visorinput_dev)
return;
}
dev_dbg(&visorinput_dev->dev, "%s closed\n", __func__);
+
+ /*
+* If we're not paused, really disable interrupts.
+* Regardless of whether we are paused, set a flag indicating
+* interrupts should be disabled so when we resume we will
+* not re-enable them.
+*/
+
+ down_write(&devdata->lock_visor_dev);
+ devdata->interrupts_enabled = false;
+ if (devdata->paused)
+ goto out_unlock;
visorbus_disable_channel_interrupts(devdata->dev);
+
+out_unlock:
+ up_write(&devdata->lock_visor_dev);
}
/*
@@ -438,10 +468,8 @@ visorinput_remove(struct visor_device *dev)
* in visorinput_channel_interrupt()
*/
- down_write(&devdata->lock_visor_dev);
dev_set_drvdata(&dev->device, NULL);
unregister_client_input(devdata->visorinput_dev);
- up_write(&devdata->lock_visor_dev);
kfree(devdata);
}
@@ -529,13 +557,7 @@ visorinput_channel_interrupt(struct visor_device *dev)
if (!devdata)
return;
- down_write(&devdata->lock_visor_dev);
- if (devdata->paused) /* don't touch device/channel when paused */
- goto out_locked;
-
visorinput_dev = devdata->visorinput_dev;
- if (!visorinput_dev)
- goto out_locked;
while (visorchannel_signalremove(dev->visorchannel, 0, &r)) {
scancode = r.activity.arg1;
@@ -611,8 +633,6 @@ visorinput_channel_interrupt(struct visor_device *dev)
break;
}
}
-out_locked:
- up_write(&devdata->lock_visor_dev);
}
static int
@@ -632,6 +652,14 @@ visorinput_pause(struct visor_device *dev,
rc = -EBUSY;
goto out_locked;
}
+ if (devdata->interrupts_enabled)
+ visorbus_disable_channel_interrupts(dev);
+
+ /*
+* due to above, at this time no thread of execution will be
+* in visorinput_channel_interrupt()
+*/
+
devdata->paused = true;
complete_func(dev, 0);
rc = 0;
@@ -659,6 +687,15 @@ visorinput_resume(struct visor_device *dev,
}
devdata->paused = false;
complete_func(dev, 0);
+
+ /*
+* Re-establish calls to visorinput_channel_interrupt() if that is
+* the desired state that we've kept track of in interrupts_enabled
+* while the device was paused.
+*/
+ if (devdata->interrupts_enabled)
+ visorbus_enable_channel_interrupts(dev);
+
rc = 0;
out_locked:
up_write(&devdata->lock_visor_dev);
--
1.9.1
--
To unsubscribe
[PATCH v3 25/30] staging: unisys: visorbus: Rename function to follow existing convention
From: David Binder
Renames visorchipset_device_pause_response to device_pause_response,
thereby following the convention that other responder functions follow.
Signed-off-by: David Binder
Signed-off-by: David Kershner
---
drivers/staging/unisys/visorbus/visorbus_main.c| 4 ++--
drivers/staging/unisys/visorbus/visorbus_private.h | 3 +--
drivers/staging/unisys/visorbus/visorchipset.c | 4 ++--
3 files changed, 5 insertions(+), 6 deletions(-)
diff --git a/drivers/staging/unisys/visorbus/visorbus_main.c
b/drivers/staging/unisys/visorbus/visorbus_main.c
index c361077..293532f 100644
--- a/drivers/staging/unisys/visorbus/visorbus_main.c
+++ b/drivers/staging/unisys/visorbus/visorbus_main.c
@@ -1218,7 +1218,7 @@ pause_state_change_complete(struct visor_device *dev, int
status)
dev->pausing = false;
- visorchipset_device_pause_response(dev, status);
+ device_pause_response(dev, status);
}
/**
@@ -1265,7 +1265,7 @@ initiate_chipset_device_pause_resume(struct visor_device
*dev, bool is_pause)
void (*notify_func)(struct visor_device *dev, int response) = NULL;
if (is_pause)
- notify_func = visorchipset_device_pause_response;
+ notify_func = device_pause_response;
else
notify_func = device_resume_response;
if (!notify_func)
diff --git a/drivers/staging/unisys/visorbus/visorbus_private.h
b/drivers/staging/unisys/visorbus/visorbus_private.h
index 3b5a8f2..a7b1d4f 100644
--- a/drivers/staging/unisys/visorbus/visorbus_private.h
+++ b/drivers/staging/unisys/visorbus/visorbus_private.h
@@ -35,8 +35,7 @@ void bus_destroy_response(struct visor_device *p, int
response);
void device_create_response(struct visor_device *p, int response);
void device_destroy_response(struct visor_device *p, int response);
void device_resume_response(struct visor_device *p, int response);
-void visorchipset_device_pause_response(struct visor_device *p,
- int response);
+void device_pause_response(struct visor_device *p, int response);
/* visorbus init and exit functions */
int visorbus_init(void);
diff --git a/drivers/staging/unisys/visorbus/visorchipset.c
b/drivers/staging/unisys/visorbus/visorchipset.c
index ea548df..0b4a138 100644
--- a/drivers/staging/unisys/visorbus/visorchipset.c
+++ b/drivers/staging/unisys/visorbus/visorchipset.c
@@ -1983,8 +1983,8 @@ device_destroy_response(struct visor_device *dev_info,
int response)
}
void
-visorchipset_device_pause_response(struct visor_device *dev_info,
- int response)
+device_pause_response(struct visor_device *dev_info,
+ int response)
{
device_changestate_responder(CONTROLVM_DEVICE_CHANGESTATE,
dev_info, response,
--
1.9.1
--
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 v3 27/30] staging: unisys: Move vbushelper.h to visorbus directory
Only visorbus needs this header file so move it to visorbus
directory.
Signed-off-by: David Kershner
Reviewed-by: Tim Sell
---
drivers/staging/unisys/{include => visorbus}/vbushelper.h | 0
1 file changed, 0 insertions(+), 0 deletions(-)
rename drivers/staging/unisys/{include => visorbus}/vbushelper.h (100%)
diff --git a/drivers/staging/unisys/include/vbushelper.h
b/drivers/staging/unisys/visorbus/vbushelper.h
similarity index 100%
rename from drivers/staging/unisys/include/vbushelper.h
rename to drivers/staging/unisys/visorbus/vbushelper.h
--
1.9.1
--
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 v3 19/30] staging: unisys: visorbus: fix commenting in visorbus_main.c
From: David Binder
This patch ONLY touches comment lines, i.e., NO executable code is
affected.
* All functions worthy of documenting now use standard kerneldoc
formatting.
* Improper uses of kerneldoc formatting were converted to standard
multi-line comments.
* Multi-line comments were tweaked so as to use appropriate conventions.
Signed-off-by: David Binder
Signed-off-by: Tim Sell
Signed-off-by: David Kershner
---
drivers/staging/unisys/visorbus/visorbus_main.c | 420
1 file changed, 289 insertions(+), 131 deletions(-)
diff --git a/drivers/staging/unisys/visorbus/visorbus_main.c
b/drivers/staging/unisys/visorbus/visorbus_main.c
index 8c1754f9..2468264 100644
--- a/drivers/staging/unisys/visorbus/visorbus_main.c
+++ b/drivers/staging/unisys/visorbus/visorbus_main.c
@@ -44,11 +44,11 @@ static int visorbus_uevent(struct device *xdev, struct
kobj_uevent_env *env);
static int visorbus_match(struct device *xdev, struct device_driver *xdrv);
static void fix_vbus_dev_info(struct visor_device *visordev);
-/* BUS type attributes
- *
- * define & implement display of bus attributes under
- * /sys/bus/visorbus.
+/*
+ * BUS type attributes
*
+ * define & implement display of bus attributes under
+ * /sys/bus/visorbus.
*/
static ssize_t version_show(struct bus_type *bus, char *buf)
@@ -104,7 +104,8 @@ static const struct attribute_group *visorbus_dev_groups[]
= {
NULL,
};
-/** This describes the TYPE of bus.
+/*
+ * This describes the TYPE of bus.
* (Don't confuse this with an INSTANCE of the bus.)
*/
struct bus_type visorbus_type = {
@@ -115,8 +116,8 @@ struct bus_type visorbus_type = {
.bus_groups = visorbus_bus_groups,
};
-static long long bus_count;/** number of bus instances */
- /** ever-increasing */
+static long long bus_count;/* number of bus instances */
+ /* ever-increasing */
static void chipset_bus_create(struct visor_device *bus_info);
static void chipset_bus_destroy(struct visor_device *bus_info);
@@ -125,8 +126,9 @@ static void chipset_device_destroy(struct visor_device
*dev_info);
static void chipset_device_pause(struct visor_device *dev_info);
static void chipset_device_resume(struct visor_device *dev_info);
-/** These functions are implemented herein, and are called by the chipset
- * driver to notify us about specific events.
+/*
+ * These functions are implemented herein, and are called by the chipset
+ * driver to notify us about specific events.
*/
static struct visorchipset_busdev_notifiers chipset_notifiers = {
.bus_create = chipset_bus_create,
@@ -137,8 +139,9 @@ static struct visorchipset_busdev_notifiers
chipset_notifiers = {
.device_resume = chipset_device_resume,
};
-/** These functions are implemented in the chipset driver, and we call them
- * herein when we want to acknowledge a specific event.
+/*
+ * These functions are implemented in the chipset driver, and we call them
+ * herein when we want to acknowledge a specific event.
*/
static struct visorchipset_busdev_responders chipset_responders;
@@ -147,9 +150,9 @@ static struct ultra_vbus_deviceinfo chipset_driverinfo;
/* filled in with info about this driver, wrt it servicing client busses */
static struct ultra_vbus_deviceinfo clientbus_driverinfo;
-/** list of visor_device structs, linked via .list_all */
+/* list of visor_device structs, linked via .list_all */
static LIST_HEAD(list_all_bus_instances);
-/** list of visor_device structs, linked via .list_all */
+/* list of visor_device structs, linked via .list_all */
static LIST_HEAD(list_all_device_instances);
static int
@@ -166,9 +169,14 @@ visorbus_uevent(struct device *xdev, struct
kobj_uevent_env *env)
return 0;
}
-/* This is called automatically upon adding a visor_device (device_add), or
- * adding a visor_driver (visorbus_register_visor_driver), and returns 1 iff
the
- * provided driver can control the specified device.
+/**
+ * visorbus_match() - called automatically upon adding a visor_device
+ *(device_add), or adding a visor_driver
+ *(visorbus_register_visor_driver)
+ * @xdev: struct device for the device being matched
+ * @xdrv: struct device_driver for driver to match device against
+ *
+ * Return: 1 iff the provided driver can control the specified device
*/
static int
visorbus_match(struct device *xdev, struct device_driver *xdrv)
@@ -200,9 +208,11 @@ visorbus_match(struct device *xdev, struct device_driver
*xdrv)
return 0;
}
-/** This is called when device_unregister() is called for the bus device
- * instance, after all other tasks involved with destroying the device
- * are complete.
+/**
+ * visorbus_releae_busdevice() - called when device_unregister() is called for
+ * the bus device instance, after all other tasks
+ *
[PATCH v3 22/30] staging: unisys: visorbus: Move visorbus-unique functions to private header
From: David Binder Moves function prototypes that are unique to visorbus from include/visorbus.h to visorbus/visorbus_private.h. Signed-off-by: David Binder Signed-off-by: David Kershner Reviewed-by: Tim Sell --- drivers/staging/unisys/include/visorbus.h | 25 drivers/staging/unisys/visorbus/visorbus_private.h | 27 ++ drivers/staging/unisys/visorbus/visorchannel.c | 1 + 3 files changed, 28 insertions(+), 25 deletions(-) diff --git a/drivers/staging/unisys/include/visorbus.h b/drivers/staging/unisys/include/visorbus.h index fb53a65..666a04e 100644 --- a/drivers/staging/unisys/include/visorbus.h +++ b/drivers/staging/unisys/include/visorbus.h @@ -187,37 +187,12 @@ int visorbus_write_channel(struct visor_device *dev, void visorbus_enable_channel_interrupts(struct visor_device *dev); void visorbus_disable_channel_interrupts(struct visor_device *dev); -/* Note that for visorchannel_create() - * and arguments may be 0 if we are a channel CLIENT. - * In this case, the values can simply be read from the channel header. - */ -struct visorchannel *visorchannel_create(u64 physaddr, -unsigned long channel_bytes, -gfp_t gfp, uuid_le guid); -struct visorchannel *visorchannel_create_with_lock(u64 physaddr, - unsigned long channel_bytes, - gfp_t gfp, uuid_le guid); -void visorchannel_destroy(struct visorchannel *channel); -int visorchannel_read(struct visorchannel *channel, ulong offset, - void *local, ulong nbytes); -int visorchannel_write(struct visorchannel *channel, ulong offset, - void *local, ulong nbytes); bool visorchannel_signalremove(struct visorchannel *channel, u32 queue, void *msg); bool visorchannel_signalinsert(struct visorchannel *channel, u32 queue, void *msg); bool visorchannel_signalempty(struct visorchannel *channel, u32 queue); - -u64 visorchannel_get_physaddr(struct visorchannel *channel); -ulong visorchannel_get_nbytes(struct visorchannel *channel); -char *visorchannel_id(struct visorchannel *channel, char *s); -char *visorchannel_zoneid(struct visorchannel *channel, char *s); -u64 visorchannel_get_clientpartition(struct visorchannel *channel); -int visorchannel_set_clientpartition(struct visorchannel *channel, -u64 partition_handle); uuid_le visorchannel_get_uuid(struct visorchannel *channel); -char *visorchannel_uuid_id(uuid_le *guid, char *s); -void __iomem *visorchannel_get_header(struct visorchannel *channel); #define BUS_ROOT_DEVICEUINT_MAX struct visor_device *visorbus_get_device_by_id(u32 bus_no, u32 dev_no, diff --git a/drivers/staging/unisys/visorbus/visorbus_private.h b/drivers/staging/unisys/visorbus/visorbus_private.h index 39edd20..31b5ca9 100644 --- a/drivers/staging/unisys/visorbus/visorbus_private.h +++ b/drivers/staging/unisys/visorbus/visorbus_private.h @@ -65,4 +65,31 @@ visorchipset_register_busdev( /* visorbus init and exit functions */ int visorbus_init(void); void visorbus_exit(void); + +/* Visorchannel access functions */ + +/* Note that for visorchannel_create() + * and arguments may be 0 if we are a channel CLIENT. + * In this case, the values can simply be read from the channel header. + */ +struct visorchannel *visorchannel_create(u64 physaddr, +unsigned long channel_bytes, +gfp_t gfp, uuid_le guid); +struct visorchannel *visorchannel_create_with_lock(u64 physaddr, + unsigned long channel_bytes, + gfp_t gfp, uuid_le guid); +void visorchannel_destroy(struct visorchannel *channel); +int visorchannel_read(struct visorchannel *channel, ulong offset, + void *local, ulong nbytes); +int visorchannel_write(struct visorchannel *channel, ulong offset, + void *local, ulong nbytes); +u64 visorchannel_get_physaddr(struct visorchannel *channel); +ulong visorchannel_get_nbytes(struct visorchannel *channel); +char *visorchannel_id(struct visorchannel *channel, char *s); +char *visorchannel_zoneid(struct visorchannel *channel, char *s); +u64 visorchannel_get_clientpartition(struct visorchannel *channel); +int visorchannel_set_clientpartition(struct visorchannel *channel, +u64 partition_handle); +char *visorchannel_uuid_id(uuid_le *guid, char *s); +void __iomem *visorchannel_get_header(struct visorchannel *channel); #endif diff --git a/drivers/staging/unisys/visorbus/visorchannel.c b/drivers/staging/unisys/visorbus/visorchannel.c index 0ddfe05..fbae66e 100644 --- a/drivers/staging/unisys/visorbus/visorchannel.c +++ b/drivers/
[PATCH] documentation: ntb.txt correct grammar "however"
Correct the grammar around the word however. Signed-off-by: Justin Keller --- index 1d9bbab..5d43510 100644 --- a/Documentation/ntb.txt +++ b/Documentation/ntb.txt @@ -35,7 +35,7 @@ establishes a logical link to the peer, and creates queue pairs to exchange messages and data. The NTB Netdev then creates an ethernet device using a Transport queue pair. Network data is copied between socket buffers and the Transport queue pair buffer. The Transport client may be used for other things -besides Netdev, however no other applications have yet been written. +besides Netdev; however, no other applications have yet been written. ### NTB Ping Pong Test Client (ntb\_pingpong)-- 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] usb: configfs: allow UDC binding rule configured as binding to *any* UDC
On Tue 2016-05-03 11:04:24, changbin...@intel.com wrote: > From: "Du, Changbin" > > On most platforms, there is only one device controller available. > In this case, we desn't care the UDC's name. So let's ignore the > name by setting 'UDC' to 'any'. And also we can change UDC name > at any time if it is not binded (no need set to "" first). making "any" special does not look like a good idea. What if it really is "any"? Return nothing instead, not even \n? > Signed-off-by: Du, Changbin > Signed-off-by: Du, Changbin I don't think this is how you should sign it off. Best regards, Pavel -- (english) http://www.livejournal.com/~pavelmachek (cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html -- 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: [kernel-hardening] [PATCH 2/2] security,perf: Allow further restriction of perf_event_open
Acked-by: Jeff Vander Stoep
In addition to Debian, this patch has been merged into AOSP and is a
requirement for Android:
https://android-review.googlesource.com/#/q/topic:CONFIG_SECURITY_PERF_EVENTS_RESTRICT
On Wed, Apr 13, 2016 at 9:12 AM, Kees Cook wrote:
> On Mon, Jan 11, 2016 at 7:23 AM, Ben Hutchings wrote:
>> When kernel.perf_event_open is set to 3 (or greater), disallow all
>> access to performance events by users without CAP_SYS_ADMIN.
>> Add a Kconfig symbol CONFIG_SECURITY_PERF_EVENTS_RESTRICT that
>> makes this value the default.
>>
>> This is based on a similar feature in grsecurity
>> (CONFIG_GRKERNSEC_PERF_HARDEN). This version doesn't include making
>> the variable read-only. It also allows enabling further restriction
>> at run-time regardless of whether the default is changed.
>>
>> Signed-off-by: Ben Hutchings
>
> Whoops, I entirely missed this email! Just found it now.
>
> Ben, can you resend this with Perf maintainers in CC? This seems
> sensible enough to me.
>
> -Kees
>
>> ---
>> I made a similar change to Debian's kernel packages in August,
>> including the more restrictive default, and no-one has complained yet.
>>
>> Ben.
>>
>> Documentation/sysctl/kernel.txt | 4 +++-
>> include/linux/perf_event.h | 5 +
>> kernel/events/core.c| 8
>> security/Kconfig| 9 +
>> 4 files changed, 25 insertions(+), 1 deletion(-)
>>
>> diff --git a/Documentation/sysctl/kernel.txt
>> b/Documentation/sysctl/kernel.txt
>> index 88a2c8e..76e2ca8 100644
>> --- a/Documentation/sysctl/kernel.txt
>> +++ b/Documentation/sysctl/kernel.txt
>> @@ -629,12 +629,14 @@ allowed to execute.
>> perf_event_paranoid:
>>
>> Controls use of the performance events system by unprivileged
>> -users (without CAP_SYS_ADMIN). The default value is 1.
>> +users (without CAP_SYS_ADMIN). The default value is 3 if
>> +CONFIG_SECURITY_PERF_EVENTS_RESTRICT is set, or 1 otherwise.
>>
>> -1: Allow use of (almost) all events by all users
>> >=0: Disallow raw tracepoint access by users without CAP_IOC_LOCK
>> >=1: Disallow CPU event access by users without CAP_SYS_ADMIN
>> >=2: Disallow kernel profiling by users without CAP_SYS_ADMIN
>> +>=3: Disallow all event access by users without CAP_SYS_ADMIN
>>
>> ==
>>
>> diff --git a/include/linux/perf_event.h b/include/linux/perf_event.h
>> index f9828a4..aa72940 100644
>> --- a/include/linux/perf_event.h
>> +++ b/include/linux/perf_event.h
>> @@ -989,6 +989,11 @@ extern int perf_cpu_time_max_percent_handler(struct
>> ctl_table *table, int write,
>> loff_t *ppos);
>>
>>
>> +static inline bool perf_paranoid_any(void)
>> +{
>> + return sysctl_perf_event_paranoid > 2;
>> +}
>> +
>> static inline bool perf_paranoid_tracepoint_raw(void)
>> {
>> return sysctl_perf_event_paranoid > -1;
>> diff --git a/kernel/events/core.c b/kernel/events/core.c
>> index cfc227c..85bc810 100644
>> --- a/kernel/events/core.c
>> +++ b/kernel/events/core.c
>> @@ -175,8 +175,13 @@ static struct srcu_struct pmus_srcu;
>> * 0 - disallow raw tracepoint access for unpriv
>> * 1 - disallow cpu events for unpriv
>> * 2 - disallow kernel profiling for unpriv
>> + * 3 - disallow all unpriv perf event use
>> */
>> +#ifdef CONFIG_SECURITY_PERF_EVENTS_RESTRICT
>> +int sysctl_perf_event_paranoid __read_mostly = 3;
>> +#else
>> int sysctl_perf_event_paranoid __read_mostly = 1;
>> +#endif
>>
>> /* Minimum for 512 kiB + 1 user control page */
>> int sysctl_perf_event_mlock __read_mostly = 512 + (PAGE_SIZE / 1024); /*
>> 'free' kiB per user */
>> @@ -8265,6 +8270,9 @@ SYSCALL_DEFINE5(perf_event_open,
>> if (flags & ~PERF_FLAG_ALL)
>> return -EINVAL;
>>
>> + if (perf_paranoid_any() && !capable(CAP_SYS_ADMIN))
>> + return -EACCES;
>> +
>> err = perf_copy_attr(attr_uptr, &attr);
>> if (err)
>> return err;
>> diff --git a/security/Kconfig b/security/Kconfig
>> index e452378..30a2603 100644
>> --- a/security/Kconfig
>> +++ b/security/Kconfig
>> @@ -18,6 +18,15 @@ config SECURITY_DMESG_RESTRICT
>>
>> If you are unsure how to answer this question, answer N.
>>
>> +config SECURITY_PERF_EVENTS_RESTRICT
>> + bool "Restrict unprivileged use of performance events"
>> + depends on PERF_EVENTS
>> + help
>> + If you say Y here, the kernel.perf_event_paranoid sysctl
>> + will be set to 3 by default, and no unprivileged use of the
>> + perf_event_open syscall will be permitted unless it is
>> + changed.
>> +
>> config SECURITY
>> bool "Enable different security models"
>> depends on SYSFS
>
>
>
> --
> Kees Cook
> Chrome OS & Brillo Security
--
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
Re: [PATCH] documentation: ntb.txt correct grammar "however"
On Sat, Jun 04, 2016 at 03:34:01PM -0400, Justin Keller wrote: > Correct the grammar around the word however. > > Signed-off-by: Justin Keller > > --- > > index 1d9bbab..5d43510 100644 > --- a/Documentation/ntb.txt > +++ b/Documentation/ntb.txt > @@ -35,7 +35,7 @@ establishes a logical link to the peer, and creates queue > pairs to exchange > messages and data. The NTB Netdev then creates an ethernet device using a > Transport queue pair. Network data is copied between socket buffers and the > Transport queue pair buffer. The Transport client may be used for other > things > -besides Netdev, however no other applications have yet been written. > +besides Netdev; however, no other applications have yet been written. > > ### NTB Ping Pong Test Client (ntb\_pingpong) As a user of British English, the original looks fine. Your change, however, looks odd - a semi-colon seems out of place. If you replaced it by a full-stop it would look acceptable to me - but not in any sense better than what is there at the moment. ĸen -- I had to walk fifteen miles to school, barefoot in the snow. Uphill both ways. -- 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
