From 92ca318e11d76562bb9448295a4fd96b6580954f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 2 Nov 2020 11:32:12 +0100 Subject: [PATCH 1/6] docs: ABI: sysfs-driver-dma-ioatdma: what starts with /sys This is the only file where the /sys doesn't start with a /. So, rename them to: sys -> /sys Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/f4c53fff9696a61ff0e144fee237a9527982626d.1604312590.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman --- Documentation/ABI/stable/sysfs-driver-dma-ioatdma | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Documentation/ABI/stable/sysfs-driver-dma-ioatdma b/Documentation/ABI/stable/sysfs-driver-dma-ioatdma index 420c1d09e42f..3a4e2cd0ddcc 100644 --- a/Documentation/ABI/stable/sysfs-driver-dma-ioatdma +++ b/Documentation/ABI/stable/sysfs-driver-dma-ioatdma @@ -1,29 +1,29 @@ -What: sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dmachan/quickdata/cap +What: /sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dmachan/quickdata/cap Date: December 3, 2009 KernelVersion: 2.6.32 Contact: dmaengine@vger.kernel.org Description: Capabilities the DMA supports.Currently there are DMA_PQ, DMA_PQ_VAL, DMA_XOR,DMA_XOR_VAL,DMA_INTERRUPT. -What: sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dmachan/quickdata/ring_active +What: /sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dmachan/quickdata/ring_active Date: December 3, 2009 KernelVersion: 2.6.32 Contact: dmaengine@vger.kernel.org Description: The number of descriptors active in the ring. -What: sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dmachan/quickdata/ring_size +What: /sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dmachan/quickdata/ring_size Date: December 3, 2009 KernelVersion: 2.6.32 Contact: dmaengine@vger.kernel.org Description: Descriptor ring size, total number of descriptors available. -What: sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dmachan/quickdata/version +What: /sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dmachan/quickdata/version Date: December 3, 2009 KernelVersion: 2.6.32 Contact: dmaengine@vger.kernel.org Description: Version of ioatdma device. -What: sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dmachan/quickdata/intr_coalesce +What: /sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dmachan/quickdata/intr_coalesce Date: August 8, 2017 KernelVersion: 4.14 Contact: dmaengine@vger.kernel.org From 1088ee2230ac5e1c889d5ba020f37c09000ee3af Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 2 Nov 2020 11:32:13 +0100 Subject: [PATCH 2/6] docs: ABI: sysfs-class-net: fix a typo clas->class Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/4bba2a1592df5a9435c8d4757a9abf20246e2a99.1604312590.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman --- Documentation/ABI/testing/sysfs-class-net | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/ABI/testing/sysfs-class-net b/Documentation/ABI/testing/sysfs-class-net index 7670012ae9b6..1f2002df5ba2 100644 --- a/Documentation/ABI/testing/sysfs-class-net +++ b/Documentation/ABI/testing/sysfs-class-net @@ -152,7 +152,7 @@ Description: When an interface is under test, it cannot be expected to pass packets as normal. -What: /sys/clas/net//duplex +What: /sys/class/net//duplex Date: October 2009 KernelVersion: 2.6.33 Contact: netdev@vger.kernel.org From e186d80e2b85ab3e69de941d069ab9e11018ddf4 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 2 Nov 2020 11:32:14 +0100 Subject: [PATCH 3/6] docs: leds: index.rst: add a missing file Changeset 26a07553041e ("docs: ABI: sysfs-class-led-trigger-pattern: remove hw_pattern duplication") didn't include the needed changes at index.rst. Fixes: 26a07553041e ("docs: ABI: sysfs-class-led-trigger-pattern: remove hw_pattern duplication") Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/36a6e3aef6e57ea349f1b47c7731d4cd1e03ca77.1604312590.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman --- Documentation/leds/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/Documentation/leds/index.rst b/Documentation/leds/index.rst index 53e6090454af..e5d63b940045 100644 --- a/Documentation/leds/index.rst +++ b/Documentation/leds/index.rst @@ -25,3 +25,4 @@ LEDs leds-lp5562 leds-lp55xx leds-mlxcpld + leds-sc27xx From daaaf58a2b7fd59951bd090eddee131f26422e20 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 2 Nov 2020 11:32:15 +0100 Subject: [PATCH 4/6] scripts: get_abi.pl: Don't let ABI files to create subtitles The ReST output should only contain documentation titles automatically created by the script. There are two reasons for that: 1) Consistency. just a handful ABI docs define titles 2) To avoid critical errors. Docutils (which is the basis for Sphinx) allows a free assign of documentation title markups. So, one document could be doing things like: Level 1 ======= Level 2 ------- While another one could do the reverse: Level 1 ------- Level 2 ======= But the same document can't mix. As the output of get_abi.pl will join contents from multiple files, if they don't define the levels on a consistent errors, errors like this can happen: Sphinx parallel build error: docutils.utils.SystemMessage: /home/rdunlap/lnx/lnx-510-rc2/Documentation/ABI/testing/sysfs-bus-rapidio:2: (SEVERE/4) Title level inconsistent: Attributes Common for All RapidIO Devices ----------------------------------------- Which cause some versions of Sphinx to go into an endless loop. It should be noticed that an alternative to that would be to replace all title occurrences by a single markup, but that will make the parser more complex, and, due to (1) it would generate an inconsistent output. So, better to just remove the titles defined at the ABI files from the output. Reported-by: Randy Dunlap Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/6c62ef5c01d39dee8d891f8390c816d2a889670a.1604312590.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index 2cb592f8eba4..459f169f834c 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -352,6 +352,12 @@ sub output_rest { if (!($desc =~ /^\s*$/)) { if ($description_is_rst) { + # Remove title markups from the description + # Having titles inside ABI files will only work if extra + # care would be taken in order to strictly follow the same + # level order for each markup. + $desc =~ s/\n[\-\*\=\^\~]+\n/\n\n/g; + # Enrich text by creating cross-references $desc =~ s,Documentation/(?!devicetree)(\S+)\.rst,:doc:`/$1`,g; From 9d4fdda3344611ec53ededccc0c13cb149ba4375 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 2 Nov 2020 11:32:16 +0100 Subject: [PATCH 5/6] scripts: get_api.pl: Add sub-titles to ABI output Instead of adding titles just for the files, add titles for each part of the ABI output, in order to make easier to search for a symbol there. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/64752a5de06ab8263c296e3ed01414b25861e1eb.1604312590.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index 459f169f834c..68dab828a722 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -287,6 +287,8 @@ my $bondary = qr { (?{type} eq "File") cmp ($data{$b}->{type} eq "File") || $a cmp $b @@ -306,6 +308,21 @@ sub output_rest { $w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g; if ($type ne "File") { + my $cur_part = $what; + if ($what =~ '/') { + if ($what =~ m#^(\/?(?:[\w\-]+\/?){1,2})#) { + $cur_part = "Symbols under $1"; + $cur_part =~ s,/$,,; + } + } + + if ($cur_part ne "" && $part ne $cur_part) { + $part = $cur_part; + my $bar = $part; + $bar =~ s/./-/g; + print "$part\n$bar\n\n"; + } + printf ".. _%s:\n\n", $data{$what}->{label}; my @names = split /, /,$w; From d181bfe36715a1834958cf2d62253b624adfae51 Mon Sep 17 00:00:00 2001 From: Greg Kroah-Hartman Date: Tue, 3 Nov 2020 09:34:08 +0100 Subject: [PATCH 6/6] Documentation: remove mic/index from misc-devices/index.rst With the recent removal of the misc/mic/ directory, the documentation build now warns because we forgot about this index file. Fix that up so that there are no more warnings here. Reported-by: Stephen Rothwell Cc: Sudeep Dutt Link: https://lore.kernel.org/r/20201103083408.GA2511903@kroah.com Signed-off-by: Greg Kroah-Hartman --- Documentation/misc-devices/index.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/Documentation/misc-devices/index.rst b/Documentation/misc-devices/index.rst index 46072ce3d7ef..64420b3314fe 100644 --- a/Documentation/misc-devices/index.rst +++ b/Documentation/misc-devices/index.rst @@ -24,7 +24,6 @@ fit into other categories. isl29003 lis3lv02d max6875 - mic/index pci-endpoint-test spear-pcie-gadget uacce