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, 286 insertions, 0 deletions

diff --git a/scripts/Makefile.package b/scripts/Makefile.package
new file mode 100644
index 000000000..6d36786ba
--- /dev/null
+++ b/scripts/Makefile.package
@@ -0,0 +1,286 @@
+# SPDX-License-Identifier: GPL-2.0-only
+# Makefile for the different targets used to generate full packages of a kernel
+
+include $(srctree)/scripts/Kbuild.include
+include $(srctree)/scripts/Makefile.lib
+
+# Git
+# ---------------------------------------------------------------------------
+
+filechk_HEAD = git -C $(srctree) rev-parse --verify HEAD 2>/dev/null
+
+.tmp_HEAD: check-git FORCE
+	$(call filechk,HEAD)
+
+PHONY += check-git
+check-git:
+	@if ! $(srctree)/scripts/check-git; then \
+		echo >&2 "error: creating source package requires git repository"; \
+		false; \
+	fi
+
+git-config-tar.gz   = -c tar.tar.gz.command="$(KGZIP)"
+git-config-tar.bz2  = -c tar.tar.bz2.command="$(KBZIP2)"
+git-config-tar.lzma = -c tar.tar.lzma.command="$(LZMA)"
+git-config-tar.xz   = -c tar.tar.xz.command="$(XZ)"
+git-config-tar.zst  = -c tar.tar.zst.command="$(ZSTD)"
+
+quiet_cmd_archive = ARCHIVE $@
+      cmd_archive = git -C $(srctree) $(git-config-tar$(suffix $@)) archive \
+                    --output=$$(realpath $@) $(archive-args)
+
+suffix-gzip  := .gz
+suffix-bzip2 := .bz2
+suffix-lzma  := .lzma
+suffix-xz    := .xz
+
+# Linux source tarball
+# ---------------------------------------------------------------------------
+
+linux-tarballs := $(addprefix linux, .tar.gz .tar.bz2 .tar.lzma .tar.xz)
+
+targets += $(linux-tarballs)
+$(linux-tarballs): archive-args = --prefix=linux/ $$(cat $<)
+$(linux-tarballs): .tmp_HEAD FORCE
+	$(call if_changed,archive)
+
+# rpm-pkg srcrpm-pkg binrpm-pkg
+# ---------------------------------------------------------------------------
+
+quiet_cmd_mkspec = GEN     $@
+      cmd_mkspec = $(srctree)/scripts/package/mkspec $@
+
+rpmbuild/SPECS/kernel.spec: FORCE
+	$(call cmd,mkspec)
+
+PHONY += rpm-sources
+rpm-sources: linux.tar.gz
+	$(Q)mkdir -p rpmbuild/SOURCES
+	$(Q)ln -f linux.tar.gz rpmbuild/SOURCES/linux.tar.gz
+	$(Q)cp $(KCONFIG_CONFIG) rpmbuild/SOURCES/config
+	$(Q)$(srctree)/scripts/package/gen-diff-patch rpmbuild/SOURCES/diff.patch
+
+PHONY += rpm-pkg srcrpm-pkg binrpm-pkg
+
+ifneq ($(CC),$(HOSTCC))
+rpm-no-devel = --without=devel
+endif
+
+rpm-pkg:    private build-type := a
+srcrpm-pkg: private build-type := s
+binrpm-pkg: private build-type := b
+
+rpm-pkg srcrpm-pkg: rpm-sources
+rpm-pkg srcrpm-pkg binrpm-pkg: rpmbuild/SPECS/kernel.spec
+	+$(strip rpmbuild -b$(build-type) rpmbuild/SPECS/kernel.spec \
+	--define='_topdir $(abspath rpmbuild)' \
+	$(if $(filter a b, $(build-type)), \
+		--target $(UTS_MACHINE)-linux --build-in-place --noprep --define='_smp_mflags %{nil}' \
+		$$(rpm -q rpm >/dev/null 2>&1 || echo --nodeps) \
+		$(rpm-no-devel)) \
+	$(RPMOPTS))
+
+# deb-pkg srcdeb-pkg bindeb-pkg
+# ---------------------------------------------------------------------------
+
+KDEB_SOURCE_COMPRESS ?= gzip
+
+supported-deb-source-compress := gzip bzip2 lzma xz
+
+PHONY += linux.tar.unsupported-deb-src-compress
+linux.tar.unsupported-deb-src-compress:
+	@echo "error: KDEB_SOURCE_COMPRESS=$(KDEB_SOURCE_COMPRESS) is not supported. The supported values are: $(supported-deb-source-compress)" >&2
+	@false
+
+debian-orig-suffix := \
+    $(strip $(if $(filter $(supported-deb-source-compress), $(KDEB_SOURCE_COMPRESS)), \
+    $(suffix-$(KDEB_SOURCE_COMPRESS)),.unsupported-deb-src-compress))
+
+quiet_cmd_debianize = GEN     $@
+      cmd_debianize = $(srctree)/scripts/package/mkdebian $(mkdebian-opts)
+
+debian: FORCE
+	$(call cmd,debianize)
+
+PHONY += debian-orig
+debian-orig: private source = $(shell dpkg-parsechangelog -S Source)
+debian-orig: private version = $(shell dpkg-parsechangelog -S Version | sed 's/-[^-]*$$//')
+debian-orig: private orig-name = $(source)_$(version).orig.tar$(debian-orig-suffix)
+debian-orig: mkdebian-opts = --need-source
+debian-orig: linux.tar$(debian-orig-suffix) debian
+	$(Q)if [ "$$(df  --output=target .. 2>/dev/null)" = "$$(df --output=target $< 2>/dev/null)" ]; then \
+		ln -f $< ../$(orig-name); \
+	else \
+		cp $< ../$(orig-name); \
+	fi
+
+PHONY += deb-pkg srcdeb-pkg bindeb-pkg
+
+deb-pkg:    private build-type := source,binary
+srcdeb-pkg: private build-type := source
+bindeb-pkg: private build-type := binary
+
+deb-pkg srcdeb-pkg: debian-orig
+bindeb-pkg: debian
+deb-pkg srcdeb-pkg bindeb-pkg:
+	+$(strip dpkg-buildpackage \
+	--build=$(build-type) --no-pre-clean --unsigned-changes \
+	$(if $(findstring source, $(build-type)), \
+		--unsigned-source --compression=$(KDEB_SOURCE_COMPRESS)) \
+	$(if $(findstring binary, $(build-type)), \
+		-R'$(MAKE) -f debian/rules' -j1 -a$$(cat debian/arch), \
+		--no-check-builddeps) \
+	$(DPKG_FLAGS))
+
+# snap-pkg
+# ---------------------------------------------------------------------------
+PHONY += snap-pkg
+snap-pkg:
+	rm -rf $(objtree)/snap
+	mkdir $(objtree)/snap
+	$(MAKE) clean
+	sed "s@KERNELRELEASE@$(KERNELRELEASE)@; \
+		s@SRCTREE@$(realpath $(srctree))@" \
+		$(srctree)/scripts/package/snapcraft.template > \
+		$(objtree)/snap/snapcraft.yaml
+	cd $(objtree)/snap && \
+	snapcraft --target-arch=$(UTS_MACHINE)
+
+# pacman-pkg
+# ---------------------------------------------------------------------------
+
+PHONY += pacman-pkg
+pacman-pkg:
+	@ln -srf $(srctree)/scripts/package/PKGBUILD $(objtree)/PKGBUILD
+	+BUILDDIR="$(realpath $(objtree))/pacman" \
+		CARCH="$(UTS_MACHINE)" \
+		KBUILD_MAKEFLAGS="$(MAKEFLAGS)" \
+		KBUILD_REVISION="$(shell $(srctree)/scripts/build-version)" \
+		makepkg $(MAKEPKGOPTS)
+
+# dir-pkg tar*-pkg - tarball targets
+# ---------------------------------------------------------------------------
+
+tar-install: FORCE
+	$(Q)$(MAKE) -f $(srctree)/Makefile
+	+$(Q)$(srctree)/scripts/package/buildtar $@
+
+compress-tar.gz  = -I "$(KGZIP)"
+compress-tar.bz2 = -I "$(KBZIP2)"
+compress-tar.xz  = -I "$(XZ)"
+compress-tar.zst = -I "$(ZSTD)"
+
+quiet_cmd_tar = TAR     $@
+      cmd_tar = cd $<; tar cf ../$@ $(compress-tar$(suffix $@)) --owner=root --group=root --sort=name *
+
+dir-tarballs := $(addprefix linux-$(KERNELRELEASE)-$(ARCH), .tar .tar.gz .tar.bz2 .tar.xz .tar.zst)
+
+$(dir-tarballs): tar-install
+	$(call cmd,tar)
+
+PHONY += dir-pkg
+dir-pkg: tar-install
+	@echo "Kernel tree successfully created in $<"
+
+PHONY += tar-pkg
+tar-pkg: linux-$(KERNELRELEASE)-$(ARCH).tar
+	@:
+
+tar%-pkg: linux-$(KERNELRELEASE)-$(ARCH).tar.% FORCE
+	@:
+
+# modules-cpio-pkg - generate an initramfs with the modules
+# ---------------------------------------------------------------------------
+
+.tmp_modules_cpio: FORCE
+	$(Q)$(MAKE) -f $(srctree)/Makefile
+	$(Q)rm -rf $@
+	$(Q)$(MAKE) -f $(srctree)/Makefile INSTALL_MOD_PATH=$@/$(INSTALL_MOD_PATH) modules_install
+
+quiet_cmd_cpio = CPIO    $@
+      cmd_cpio = $(CONFIG_SHELL) $(srctree)/usr/gen_initramfs.sh -o $@ $<
+
+modules-$(KERNELRELEASE)-$(ARCH).cpio: .tmp_modules_cpio
+	$(call cmd,cpio)
+
+PHONY += modules-cpio-pkg
+modules-cpio-pkg: modules-$(KERNELRELEASE)-$(ARCH).cpio
+	@:
+
+# perf-tar*-src-pkg - generate a source tarball with perf source
+# ---------------------------------------------------------------------------
+
+.tmp_perf:
+	$(Q)mkdir .tmp_perf
+
+.tmp_perf/HEAD: .tmp_HEAD | .tmp_perf
+	$(call cmd,copy)
+
+quiet_cmd_perf_version_file = GEN     $@
+      cmd_perf_version_file = cd $(srctree)/tools/perf; util/PERF-VERSION-GEN $(dir $(abspath $@))
+
+# PERF-VERSION-FILE and .tmp_HEAD are independent, but this avoids updating the
+# timestamp of PERF-VERSION-FILE.
+# The best is to fix tools/perf/util/PERF-VERSION-GEN.
+.tmp_perf/PERF-VERSION-FILE: .tmp_HEAD $(srctree)/tools/perf/util/PERF-VERSION-GEN | .tmp_perf
+	$(call cmd,perf_version_file)
+
+perf-archive-args = --add-file=$$(realpath $(word 2, $^)) \
+	--add-file=$$(realpath $(word 3, $^)) \
+	$$(cat $(word 2, $^))^{tree} $$(cat $<)
+
+
+perf-tarballs := $(addprefix perf-$(KERNELVERSION), .tar .tar.gz .tar.bz2 .tar.xz .tar.zst)
+
+targets += $(perf-tarballs)
+$(perf-tarballs): archive-args = --prefix=perf-$(KERNELVERSION)/ $(perf-archive-args)
+$(perf-tarballs): tools/perf/MANIFEST .tmp_perf/HEAD .tmp_perf/PERF-VERSION-FILE FORCE
+	$(call if_changed,archive)
+
+PHONY += perf-tar-src-pkg
+perf-tar-src-pkg: perf-$(KERNELVERSION).tar
+	@:
+
+perf-tar%-src-pkg: perf-$(KERNELVERSION).tar.% FORCE
+	@:
+
+# Help text displayed when executing 'make help'
+# ---------------------------------------------------------------------------
+PHONY += help
+help:
+	@echo '  rpm-pkg             - Build both source and binary RPM kernel packages'
+	@echo '  srcrpm-pkg          - Build only the source kernel RPM package'
+	@echo '  binrpm-pkg          - Build only the binary kernel RPM package'
+	@echo '  deb-pkg             - Build both source and binary deb kernel packages'
+	@echo '  srcdeb-pkg          - Build only the source kernel deb package'
+	@echo '  bindeb-pkg          - Build only the binary kernel deb package'
+	@echo '  snap-pkg            - Build only the binary kernel snap package'
+	@echo '                        (will connect to external hosts)'
+	@echo '  pacman-pkg          - Build only the binary kernel pacman package'
+	@echo '  dir-pkg             - Build the kernel as a plain directory structure'
+	@echo '  tar-pkg             - Build the kernel as an uncompressed tarball'
+	@echo '  targz-pkg           - Build the kernel as a gzip compressed tarball'
+	@echo '  tarbz2-pkg          - Build the kernel as a bzip2 compressed tarball'
+	@echo '  tarxz-pkg           - Build the kernel as a xz compressed tarball'
+	@echo '  tarzst-pkg          - Build the kernel as a zstd compressed tarball'
+	@echo '  modules-cpio-pkg    - Build the kernel modules as cpio archive'
+	@echo '                        (uses INSTALL_MOD_PATH inside the archive)'
+	@echo '  perf-tar-src-pkg    - Build the perf source tarball with no compression'
+	@echo '  perf-targz-src-pkg  - Build the perf source tarball with gzip compression'
+	@echo '  perf-tarbz2-src-pkg - Build the perf source tarball with bz2 compression'
+	@echo '  perf-tarxz-src-pkg  - Build the perf source tarball with xz compression'
+	@echo '  perf-tarzst-src-pkg - Build the perf source tarball with zst compression'
+
+PHONY += FORCE
+FORCE:
+
+# Read all saved command lines and dependencies for the $(targets) we
+# may be building above, using $(if_changed{,_dep}). As an
+# optimization, we don't need to read them if the target does not
+# exist, we will rebuild anyway in that case.
+
+existing-targets := $(wildcard $(sort $(targets)))
+
+-include $(foreach f,$(existing-targets),$(dir $(f)).$(notdir $(f)).cmd)
+
+.PHONY: $(PHONY)