ata: libata-scsi: fix ata_dsm_trim_pages() kernel-docgrafted

make htmldocs fails with:

  Documentation/driver-api/libata:604: ./drivers/ata/libata-scsi.c:2301:
  ERROR: Unexpected indentation. [docutils]

The Return: section of ata_dsm_trim_pages() ends its first sentence with
a colon and continues with an indented bullet list. reStructuredText
requires a blank line before an indented block, so docutils chokes on
the list.

Simply adding the missing blank line does not work either: Return: is a
kernel-doc "special section", which is terminated by the first blank
line, so the bullet list would end up in the Description section,
detached from the sentence introducing it.

Spell the two bounds out as prose instead, so that the Return: section
stays self-contained. Documentation-only change.

Fixes: e64e6b5dc867 ("ata: libata-scsi: scale DSM TRIM payload by MAX PAGES PER DSM COMMAND")
Reported-by: Thomas Huth <thuth@redhat.com>
Closes: https://lore.kernel.org/linux-ide/b0a0b8e8-cc4f-4c7b-8bc5-fee0712d405a@redhat.com/
Reviewed-by: Damien Le Moal <dlemoal@kernel.org>
Reviewed-by: Thomas Huth <thuth@redhat.com>
Link: https://lore.kernel.org/r/20260916130031.29990-2-cassel@kernel.org
Signed-off-by: Niklas Cassel <cassel@kernel.org>

1 files changed, 138 insertions, 0 deletions

diff --git a/scripts/extract-module-sig.pl b/scripts/extract-module-sig.pl
new file mode 100755
index 000000000..36a2f59c4
--- /dev/null
+++ b/scripts/extract-module-sig.pl
@@ -0,0 +1,138 @@
+#!/usr/bin/env perl
+# SPDX-License-Identifier: GPL-2.0
+#
+# extract-mod-sig <part> <module-file>
+#
+# Reads the module file and writes out some or all of the signature
+# section to stdout.  Part is the bit to be written and is one of:
+#
+#  -0: The unsigned module, no signature data at all
+#  -a: All of the signature data, including magic number
+#  -d: Just the descriptor values as a sequence of numbers
+#  -n: Just the signer's name
+#  -k: Just the key ID
+#  -s: Just the crypto signature or PKCS#7 message
+#
+use warnings;
+use strict;
+
+die "Format: $0 -[0adnks] module-file >out\n"
+    if ($#ARGV != 1);
+
+my $part = $ARGV[0];
+my $modfile = $ARGV[1];
+
+my $magic_number = "~Module signature appended~\n";
+
+#
+# Read the module contents
+#
+open FD, "<$modfile" || die $modfile;
+binmode(FD);
+my @st = stat(FD);
+die "$modfile" unless (@st);
+my $buf = "";
+my $len = sysread(FD, $buf, $st[7]);
+die "$modfile" unless (defined($len));
+die "Short read on $modfile\n" unless ($len == $st[7]);
+close(FD) || die $modfile;
+
+print STDERR "Read ", $len, " bytes from module file\n";
+
+die "The file is too short to have a sig magic number and descriptor\n"
+    if ($len < 12 + length($magic_number));
+
+#
+# Check for the magic number and extract the information block
+#
+my $p = $len - length($magic_number);
+my $raw_magic = substr($buf, $p);
+
+die "Magic number not found at $len\n"
+    if ($raw_magic ne $magic_number);
+print STDERR "Found magic number at $len\n";
+
+$p -= 12;
+my $raw_info = substr($buf, $p, 12);
+
+my @info = unpack("CCCCCxxxN", $raw_info);
+my ($algo, $hash, $id_type, $name_len, $kid_len, $sig_len) = @info;
+
+if ($id_type == 0) {
+    print STDERR "Found PGP key identifier\n";
+} elsif ($id_type == 1) {
+    print STDERR "Found X.509 cert identifier\n";
+} elsif ($id_type == 2) {
+    print STDERR "Found PKCS#7/CMS encapsulation\n";
+} else {
+    print STDERR "Found unsupported identifier type $id_type\n";
+}
+
+#
+# Extract the three pieces of info data
+#
+die "Insufficient name+kid+sig data in file\n"
+    unless ($p >= $name_len + $kid_len + $sig_len);
+
+$p -= $sig_len;
+my $raw_sig = substr($buf, $p, $sig_len);
+$p -= $kid_len;
+my $raw_kid = substr($buf, $p, $kid_len);
+$p -= $name_len;
+my $raw_name = substr($buf, $p, $name_len);
+
+my $module_len = $p;
+
+if ($sig_len > 0) {
+    print STDERR "Found $sig_len bytes of signature [";
+    my $n = $sig_len > 16 ? 16 : $sig_len;
+    foreach my $i (unpack("C" x $n, substr($raw_sig, 0, $n))) {
+	printf STDERR "%02x", $i;
+    }
+    print STDERR "]\n";
+}
+
+if ($kid_len > 0) {
+    print STDERR "Found $kid_len bytes of key identifier [";
+    my $n = $kid_len > 16 ? 16 : $kid_len;
+    foreach my $i (unpack("C" x $n, substr($raw_kid, 0, $n))) {
+	printf STDERR "%02x", $i;
+    }
+    print STDERR "]\n";
+}
+
+if ($name_len > 0) {
+    print STDERR "Found $name_len bytes of signer's name [$raw_name]\n";
+}
+
+#
+# Produce the requested output
+#
+if ($part eq "-0") {
+    # The unsigned module, no signature data at all
+    binmode(STDOUT);
+    print substr($buf, 0, $module_len);
+} elsif ($part eq "-a") {
+    # All of the signature data, including magic number
+    binmode(STDOUT);
+    print substr($buf, $module_len);
+} elsif ($part eq "-d") {
+    # Just the descriptor values as a sequence of numbers
+    print join(" ", @info), "\n";
+} elsif ($part eq "-n") {
+    # Just the signer's name
+    print STDERR "No signer's name for PKCS#7 message type sig\n"
+	if ($id_type == 2);
+    binmode(STDOUT);
+    print $raw_name;
+} elsif ($part eq "-k") {
+    # Just the key identifier
+    print STDERR "No key ID for PKCS#7 message type sig\n"
+	if ($id_type == 2);
+    binmode(STDOUT);
+    print $raw_kid;
+} elsif ($part eq "-s") {
+    # Just the crypto signature or PKCS#7 message
+    binmode(STDOUT);
+    print $raw_sig;
+}