[PATCH 00/24] Fix some issues at documentation

List overview All Threads
Download

newer

older

[PATCH v3] selftests: nci: replace...

[PATCH v2] selftests: nci: replace...

Mauro Carvalho Chehab

16 Sep 2021 16 Sep '21

9:13 a.m.

Hi John,

The first patch in this series fix a bad character used instead of a "(c)" UTF-8 symbol.

The remaining ones fix several broken references to files under Documentation/, several due to DT schema conversions from .txt to .yaml.

Mauro Carvalho Chehab (24): visorbus: fix a copyright symbol that was bad encoded dt-bindings: net: dsa: sja1105: update nxp,sja1105.yaml reference dt-bindings: arm: mediatek: mmsys: update mediatek,mmsys.yaml reference dt-bindings: w1: update w1-gpio.yaml reference dt-bindings: mmc: update mmc-card.yaml reference libbpf: update index.rst reference docs: accounting: update delay-accounting.rst reference tools: bpftool: update bpftool-prog.rst reference tools: bpftool: update bpftool-map.rst reference bpftool: update bpftool-cgroup.rst reference MAINTAINERS: update mtd-physmap.yaml reference MAINTAINERS: update arm,vic.yaml reference MAINTAINERS: update aspeed,i2c.yaml reference MAINTAINERS: update faraday,ftrtc010.yaml reference MAINTAINERS: update fsl,fec.yaml reference MAINTAINERS: update mtd-physmap.yaml reference MAINTAINERS: update ti,am654-hbmc.yaml reference MAINTAINERS: update ti,sci.yaml reference MAINTAINERS: update intel,ixp46x-rng.yaml reference MAINTAINERS: update nxp,imx8-jpeg.yaml reference MAINTAINERS: update gemini.yaml reference MAINTAINERS: update brcm,unimac-mdio.yaml reference MAINTAINERS: update chipone,icn8318.yaml reference MAINTAINERS: update silergy,sy8106a.yaml reference

Documentation/admin-guide/sysctl/kernel.rst | 2 +- Documentation/bpf/index.rst | 2 +- .../display/mediatek/mediatek,disp.txt | 2 +- Documentation/networking/dsa/sja1105.rst | 2 +- Documentation/w1/masters/w1-gpio.rst | 2 +- MAINTAINERS | 28 +++++++++---------- drivers/mmc/host/omap_hsmmc.c | 2 +- drivers/visorbus/visorbus_main.c | 2 +- .../selftests/bpf/test_bpftool_synctypes.py | 6 ++-- 9 files changed, 24 insertions(+), 24 deletions(-)

-- 2.31.1

Show replies by date

Mauro Carvalho Chehab

16 Sep 16 Sep

9:14 a.m.

New subject: [PATCH 08/24] tools: bpftool: update bpftool-prog.rst reference

The file name: Documentation/bpftool-prog.rst should be, instead: tools/bpf/bpftool/Documentation/bpftool-prog.rst.

Update its cross-reference accordingly.

Fixes: a2b5944fb4e0 ("selftests/bpf: Check consistency between bpftool source, doc, completion") Fixes: ff69c21a85a4 ("tools: bpftool: add documentation") Signed-off-by: Mauro Carvalho Chehab mchehab+huawei@kernel.org --- tools/testing/selftests/bpf/test_bpftool_synctypes.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/testing/selftests/bpf/test_bpftool_synctypes.py b/tools/testing/selftests/bpf/test_bpftool_synctypes.py index be54b7335a76..27a2c369a798 100755 --- a/tools/testing/selftests/bpf/test_bpftool_synctypes.py +++ b/tools/testing/selftests/bpf/test_bpftool_synctypes.py @@ -374,7 +374,7 @@ class ManProgExtractor(ManPageExtractor): """ An extractor for bpftool-prog.rst. """ - filename = os.path.join(BPFTOOL_DIR, 'Documentation/bpftool-prog.rst') + filename = os.path.join(BPFTOOL_DIR, 'tools/bpf/bpftool/Documentation/bpftool-prog.rst')

def get_attach_types(self): return self.get_rst_list('ATTACH_TYPE')

-- 2.31.1

Quentin Monnet

9:43 a.m.

New subject: [PATCH 08/24] tools: bpftool: update bpftool-prog.rst reference

2021-09-16 11:14 UTC+0200 ~ Mauro Carvalho Chehab mchehab+huawei@kernel.org

...

The file name: Documentation/bpftool-prog.rst should be, instead: tools/bpf/bpftool/Documentation/bpftool-prog.rst.

Update its cross-reference accordingly.

Fixes: a2b5944fb4e0 ("selftests/bpf: Check consistency between bpftool source, doc, completion") Fixes: ff69c21a85a4 ("tools: bpftool: add documentation")

Hi, How is this a fix for the commit that added the documentation in bpftool?

...

Signed-off-by: Mauro Carvalho Chehab mchehab+huawei@kernel.org

tools/testing/selftests/bpf/test_bpftool_synctypes.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/testing/selftests/bpf/test_bpftool_synctypes.py b/tools/testing/selftests/bpf/test_bpftool_synctypes.py index be54b7335a76..27a2c369a798 100755 --- a/tools/testing/selftests/bpf/test_bpftool_synctypes.py +++ b/tools/testing/selftests/bpf/test_bpftool_synctypes.py @@ -374,7 +374,7 @@ class ManProgExtractor(ManPageExtractor): """ An extractor for bpftool-prog.rst. """

filename = os.path.join(BPFTOOL_DIR, 'Documentation/bpftool-prog.rst')

filename = os.path.join(BPFTOOL_DIR, 'tools/bpf/bpftool/Documentation/bpftool-prog.rst')

def get_attach_types(self): return self.get_rst_list('ATTACH_TYPE')

No I don't believe it should. BPFTOOL_DIR already contains 'tools/bpf/bpftool' and the os.path.join() concatenates the two path fragments.

Where is this suggestion coming from? Did you face an issue with the script?

Same comment applies for the next two patches.

Quentin

Mauro Carvalho Chehab

10:49 a.m.

New subject: [PATCH 08/24] tools: bpftool: update bpftool-prog.rst reference

Hi Quentin,

Em Thu, 16 Sep 2021 10:43:45 +0100 Quentin Monnet quentin@isovalent.com escreveu:

...

2021-09-16 11:14 UTC+0200 ~ Mauro Carvalho Chehab mchehab+huawei@kernel.org

...
The file name: Documentation/bpftool-prog.rst should be, instead: tools/bpf/bpftool/Documentation/bpftool-prog.rst.

Update its cross-reference accordingly.

Fixes: a2b5944fb4e0 ("selftests/bpf: Check consistency between bpftool source, doc, completion") Fixes: ff69c21a85a4 ("tools: bpftool: add documentation")

Hi, How is this a fix for the commit that added the documentation in bpftool?

...
Signed-off-by: Mauro Carvalho Chehab mchehab+huawei@kernel.org

tools/testing/selftests/bpf/test_bpftool_synctypes.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/testing/selftests/bpf/test_bpftool_synctypes.py b/tools/testing/selftests/bpf/test_bpftool_synctypes.py index be54b7335a76..27a2c369a798 100755 --- a/tools/testing/selftests/bpf/test_bpftool_synctypes.py +++ b/tools/testing/selftests/bpf/test_bpftool_synctypes.py @@ -374,7 +374,7 @@ class ManProgExtractor(ManPageExtractor): """ An extractor for bpftool-prog.rst. """

filename = os.path.join(BPFTOOL_DIR, 'Documentation/bpftool-prog.rst')

filename = os.path.join(BPFTOOL_DIR, 'tools/bpf/bpftool/Documentation/bpftool-prog.rst')

def get_attach_types(self): return self.get_rst_list('ATTACH_TYPE')

No I don't believe it should. BPFTOOL_DIR already contains 'tools/bpf/bpftool' and the os.path.join() concatenates the two path fragments.

Where is this suggestion coming from? Did you face an issue with the script?

No, I didn't face any issues with this script.

The suggestion cames from the script at:

./scripts/documentation-file-ref-check

which is meant to discover broken doc references.

Such script has already a rule to handle stuff under tools/:

# Accept relative Documentation patches for tools/ if ($f =~ m/tools/) { my $path = $f; $path =~ s,(.*)/.*,$1,; next if (grep -e, glob("$path/$ref $path/../$ref $path/$fulref")); }

but it seems it needs a fixup in order for it to stop reporting issues at test_bpftool_synctypes.py:

$ ./scripts/documentation-file-ref-check ... tools/testing/selftests/bpf/test_bpftool_synctypes.py: Documentation/bpftool-prog.rst tools/testing/selftests/bpf/test_bpftool_synctypes.py: Documentation/bpftool-map.rst tools/testing/selftests/bpf/test_bpftool_synctypes.py: Documentation/bpftool-cgroup.rst

I'll drop the patches touching it for a next version, probably adding a fix for such script.

Thanks, Mauro

Quentin Monnet

10:57 a.m.

New subject: [PATCH 08/24] tools: bpftool: update bpftool-prog.rst reference

2021-09-16 12:49 UTC+0200 ~ Mauro Carvalho Chehab mchehab+huawei@kernel.org

...

Hi Quentin,

Em Thu, 16 Sep 2021 10:43:45 +0100 Quentin Monnet quentin@isovalent.com escreveu:

...
2021-09-16 11:14 UTC+0200 ~ Mauro Carvalho Chehab mchehab+huawei@kernel.org

...
The file name: Documentation/bpftool-prog.rst should be, instead: tools/bpf/bpftool/Documentation/bpftool-prog.rst.

Update its cross-reference accordingly.

Fixes: a2b5944fb4e0 ("selftests/bpf: Check consistency between bpftool source, doc, completion") Fixes: ff69c21a85a4 ("tools: bpftool: add documentation")

Hi, How is this a fix for the commit that added the documentation in bpftool?

...
Signed-off-by: Mauro Carvalho Chehab mchehab+huawei@kernel.org

tools/testing/selftests/bpf/test_bpftool_synctypes.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/testing/selftests/bpf/test_bpftool_synctypes.py b/tools/testing/selftests/bpf/test_bpftool_synctypes.py index be54b7335a76..27a2c369a798 100755 --- a/tools/testing/selftests/bpf/test_bpftool_synctypes.py +++ b/tools/testing/selftests/bpf/test_bpftool_synctypes.py @@ -374,7 +374,7 @@ class ManProgExtractor(ManPageExtractor): """ An extractor for bpftool-prog.rst. """

filename = os.path.join(BPFTOOL_DIR, 'Documentation/bpftool-prog.rst')

filename = os.path.join(BPFTOOL_DIR, 'tools/bpf/bpftool/Documentation/bpftool-prog.rst')

def get_attach_types(self): return self.get_rst_list('ATTACH_TYPE')

No I don't believe it should. BPFTOOL_DIR already contains 'tools/bpf/bpftool' and the os.path.join() concatenates the two path fragments.

Where is this suggestion coming from? Did you face an issue with the script?

No, I didn't face any issues with this script.

The suggestion cames from the script at:

./scripts/documentation-file-ref-check

which is meant to discover broken doc references.

Such script has already a rule to handle stuff under tools/:
# Accept relative Documentation patches for tools/
if ($f =~ m/tools/) {
	my $path = $f;
	$path =~ s,(.*)/.*,$1,;
	next if (grep -e, glob("$path/$ref $path/../$ref $path/$fulref"));
}
but it seems it needs a fixup in order for it to stop reporting issues at test_bpftool_synctypes.py:

$ ./scripts/documentation-file-ref-check ... tools/testing/selftests/bpf/test_bpftool_synctypes.py: Documentation/bpftool-prog.rst tools/testing/selftests/bpf/test_bpftool_synctypes.py: Documentation/bpftool-map.rst tools/testing/selftests/bpf/test_bpftool_synctypes.py: Documentation/bpftool-cgroup.rst

Oh, I see, thanks for explaining. I didn't know this script would catch the paths in bpftool's test file.

...

I'll drop the patches touching it for a next version, probably adding a fix for such script.

Thanks, Mauro

Sounds good to me, thanks a lot! Quentin

Mauro Carvalho Chehab

11:30 a.m.

New subject: [PATCH 08/24] tools: bpftool: update bpftool-prog.rst reference

Em Thu, 16 Sep 2021 11:57:51 +0100 Quentin Monnet quentin@isovalent.com escreveu:

...

2021-09-16 12:49 UTC+0200 ~ Mauro Carvalho Chehab mchehab+huawei@kernel.org

...
Hi Quentin,

Em Thu, 16 Sep 2021 10:43:45 +0100 Quentin Monnet quentin@isovalent.com escreveu:

...
2021-09-16 11:14 UTC+0200 ~ Mauro Carvalho Chehab mchehab+huawei@kernel.org

...
The file name: Documentation/bpftool-prog.rst should be, instead: tools/bpf/bpftool/Documentation/bpftool-prog.rst.

Update its cross-reference accordingly.

Fixes: a2b5944fb4e0 ("selftests/bpf: Check consistency between bpftool source, doc, completion") Fixes: ff69c21a85a4 ("tools: bpftool: add documentation")

Hi, How is this a fix for the commit that added the documentation in bpftool?

...
Signed-off-by: Mauro Carvalho Chehab mchehab+huawei@kernel.org

tools/testing/selftests/bpf/test_bpftool_synctypes.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/testing/selftests/bpf/test_bpftool_synctypes.py b/tools/testing/selftests/bpf/test_bpftool_synctypes.py index be54b7335a76..27a2c369a798 100755 --- a/tools/testing/selftests/bpf/test_bpftool_synctypes.py +++ b/tools/testing/selftests/bpf/test_bpftool_synctypes.py @@ -374,7 +374,7 @@ class ManProgExtractor(ManPageExtractor): """ An extractor for bpftool-prog.rst. """

filename = os.path.join(BPFTOOL_DIR, 'Documentation/bpftool-prog.rst')

filename = os.path.join(BPFTOOL_DIR, 'tools/bpf/bpftool/Documentation/bpftool-prog.rst')

def get_attach_types(self): return self.get_rst_list('ATTACH_TYPE')

No I don't believe it should. BPFTOOL_DIR already contains 'tools/bpf/bpftool' and the os.path.join() concatenates the two path fragments.

Where is this suggestion coming from? Did you face an issue with the script?

No, I didn't face any issues with this script.

The suggestion cames from the script at:

./scripts/documentation-file-ref-check

which is meant to discover broken doc references.

Such script has already a rule to handle stuff under tools/:
# Accept relative Documentation patches for tools/
if ($f =~ m/tools/) {
	my $path = $f;
	$path =~ s,(.*)/.*,$1,;
	next if (grep -e, glob("$path/$ref $path/../$ref $path/$fulref"));
}
but it seems it needs a fixup in order for it to stop reporting issues at test_bpftool_synctypes.py:

$ ./scripts/documentation-file-ref-check ... tools/testing/selftests/bpf/test_bpftool_synctypes.py: Documentation/bpftool-prog.rst tools/testing/selftests/bpf/test_bpftool_synctypes.py: Documentation/bpftool-map.rst tools/testing/selftests/bpf/test_bpftool_synctypes.py: Documentation/bpftool-cgroup.rst
Oh, I see, thanks for explaining. I didn't know this script would catch the paths in bpftool's test file.

...
I'll drop the patches touching it for a next version, probably adding a fix for such script.

Thanks, Mauro

Sounds good to me, thanks a lot!

The enclosed patch should do the trick.

...

Quentin

Thanks, Mauro

[PATCH] scripts: documentation-file-ref-check: fix bpf selftests path

tools/testing/selftests/bpf/test_bpftool_synctypes.py use relative patches on the top of BPFTOOL_DIR:

BPFTOOL_DIR = os.path.join(LINUX_ROOT, 'tools/bpf/bpftool')

Change the script to automatically convert:

testing/selftests/bpf -> bpf/bpftool

In order to properly check the files used by such script.

Signed-off-by: Mauro Carvalho Chehab mchehab+huawei@kernel.org

diff --git a/scripts/documentation-file-ref-check b/scripts/documentation-file-ref-check index 7187ea5e5149..2d91cfe11cd2 100755 --- a/scripts/documentation-file-ref-check +++ b/scripts/documentation-file-ref-check @@ -144,6 +144,7 @@ while (<IN>) { if ($f =~ m/tools/) { my $path = $f; $path =~ s,(.*)/.*,$1,; + $path =~ s,testing/selftests/bpf,bpf/bpftool,; next if (grep -e, glob("$path/$ref $path/../$ref $path/$fulref")); }

Quentin Monnet

12:12 p.m.

New subject: [PATCH 08/24] tools: bpftool: update bpftool-prog.rst reference

2021-09-16 13:30 UTC+0200 ~ Mauro Carvalho Chehab mchehab+huawei@kernel.org

...

[PATCH] scripts: documentation-file-ref-check: fix bpf selftests path

tools/testing/selftests/bpf/test_bpftool_synctypes.py use relative patches on the top of BPFTOOL_DIR:

BPFTOOL_DIR = os.path.join(LINUX_ROOT, 'tools/bpf/bpftool')

Change the script to automatically convert:

testing/selftests/bpf -> bpf/bpftool

In order to properly check the files used by such script.

Signed-off-by: Mauro Carvalho Chehab mchehab+huawei@kernel.org

diff --git a/scripts/documentation-file-ref-check b/scripts/documentation-file-ref-check index 7187ea5e5149..2d91cfe11cd2 100755 --- a/scripts/documentation-file-ref-check +++ b/scripts/documentation-file-ref-check @@ -144,6 +144,7 @@ while (<IN>) { if ($f =~ m/tools/) { my $path = $f; $path =~ s,(.*)/.*,$1,;
	$path =~ s,testing/selftests/bpf,bpf/bpftool,;
next if (grep -e, glob("$path/$ref $path/../$ref $path/$fulref"));
}

I tested the patch and it works well on my side.

However, this looks a bit fragile to me. There is no particular reason to have testing/selftests/bpf point to bpf/bpftool other than to accommodate the current case, we could imagine other selftest files pointing to other parts of the documentation in the future. I would instead make an exception for test_bpftool_synctypes.py specifically (other selftest files don't usually parse documentation anyway). Alternatively, I would look at excluding lines where the path is used in code (tricky to detect), maybe at least when used with os.path.join():

next if ($ln =~ m,os.path.join([^,]*,\s*['"]$fulref,);

But I'm not familiar with documentation-file-ref-check in the first place, so these are just my two cents.

Thanks, Quentin

Mauro Carvalho Chehab

9:14 a.m.

New subject: [PATCH 09/24] tools: bpftool: update bpftool-map.rst reference

The file name: Documentation/bpftool-map.rst should be, instead: tools/bpf/bpftool/Documentation/bpftool-map.rst.

Update its cross-reference accordingly.

diff --git a/tools/testing/selftests/bpf/test_bpftool_synctypes.py b/tools/testing/selftests/bpf/test_bpftool_synctypes.py index 27a2c369a798..2d7eb683bd5a 100755 --- a/tools/testing/selftests/bpf/test_bpftool_synctypes.py +++ b/tools/testing/selftests/bpf/test_bpftool_synctypes.py @@ -383,7 +383,7 @@ class ManMapExtractor(ManPageExtractor): """ An extractor for bpftool-map.rst. """ - filename = os.path.join(BPFTOOL_DIR, 'Documentation/bpftool-map.rst') + filename = os.path.join(BPFTOOL_DIR, 'tools/bpf/bpftool/Documentation/bpftool-map.rst')

def get_map_types(self): return self.get_rst_list('TYPE')

-- 2.31.1

Mauro Carvalho Chehab

9:14 a.m.

New subject: [PATCH 10/24] bpftool: update bpftool-cgroup.rst reference

The file name: Documentation/bpftool-cgroup.rst should be, instead: tools/bpf/bpftool/Documentation/bpftool-cgroup.rst.

Update its cross-reference accordingly.

Fixes: a2b5944fb4e0 ("selftests/bpf: Check consistency between bpftool source, doc, completion") Fixes: 5ccda64d38cc ("bpftool: implement cgroup bpf operations") Signed-off-by: Mauro Carvalho Chehab mchehab+huawei@kernel.org --- tools/testing/selftests/bpf/test_bpftool_synctypes.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/testing/selftests/bpf/test_bpftool_synctypes.py b/tools/testing/selftests/bpf/test_bpftool_synctypes.py index 2d7eb683bd5a..c974abd4db13 100755 --- a/tools/testing/selftests/bpf/test_bpftool_synctypes.py +++ b/tools/testing/selftests/bpf/test_bpftool_synctypes.py @@ -392,7 +392,7 @@ class ManCgroupExtractor(ManPageExtractor): """ An extractor for bpftool-cgroup.rst. """ - filename = os.path.join(BPFTOOL_DIR, 'Documentation/bpftool-cgroup.rst') + filename = os.path.join(BPFTOOL_DIR, 'tools/bpf/bpftool/Documentation/bpftool-cgroup.rst')

def get_attach_types(self): return self.get_rst_list('ATTACH_TYPE')

-- 2.31.1

1416

days inactive

1416

days old

linux-kselftest-mirror@lists.linaro.org

8 comments

participants

tags (0)

participants (2)

Mauro Carvalho Chehab
Quentin Monnet