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

diff --git a/drivers/rtc/rtc-ep93xx.c b/drivers/rtc/rtc-ep93xx.c
new file mode 100644
index 000000000..507c9f220
--- /dev/null
+++ b/drivers/rtc/rtc-ep93xx.c
@@ -0,0 +1,170 @@
+// SPDX-License-Identifier: GPL-2.0
+/*
+ * A driver for the RTC embedded in the Cirrus Logic EP93XX processors
+ * Copyright (c) 2006 Tower Technologies
+ *
+ * Author: Alessandro Zummo <a.zummo@towertech.it>
+ */
+
+#include <linux/module.h>
+#include <linux/rtc.h>
+#include <linux/platform_device.h>
+#include <linux/io.h>
+#include <linux/gfp.h>
+
+#define EP93XX_RTC_DATA			0x000
+#define EP93XX_RTC_MATCH		0x004
+#define EP93XX_RTC_STATUS		0x008
+#define  EP93XX_RTC_STATUS_INTR		 BIT(0)
+#define EP93XX_RTC_LOAD			0x00C
+#define EP93XX_RTC_CONTROL		0x010
+#define  EP93XX_RTC_CONTROL_MIE		 BIT(0)
+#define EP93XX_RTC_SWCOMP		0x108
+#define  EP93XX_RTC_SWCOMP_DEL_MASK	 0x001f0000
+#define  EP93XX_RTC_SWCOMP_DEL_SHIFT	 16
+#define  EP93XX_RTC_SWCOMP_INT_MASK	 0x0000ffff
+#define  EP93XX_RTC_SWCOMP_INT_SHIFT	 0
+
+struct ep93xx_rtc {
+	void __iomem	*mmio_base;
+};
+
+static int ep93xx_rtc_get_swcomp(struct device *dev, unsigned short *preload,
+				 unsigned short *delete)
+{
+	struct ep93xx_rtc *ep93xx_rtc = dev_get_drvdata(dev);
+	unsigned long comp;
+
+	comp = readl(ep93xx_rtc->mmio_base + EP93XX_RTC_SWCOMP);
+
+	if (preload)
+		*preload = (comp & EP93XX_RTC_SWCOMP_INT_MASK)
+				>> EP93XX_RTC_SWCOMP_INT_SHIFT;
+
+	if (delete)
+		*delete = (comp & EP93XX_RTC_SWCOMP_DEL_MASK)
+				>> EP93XX_RTC_SWCOMP_DEL_SHIFT;
+
+	return 0;
+}
+
+static int ep93xx_rtc_read_time(struct device *dev, struct rtc_time *tm)
+{
+	struct ep93xx_rtc *ep93xx_rtc = dev_get_drvdata(dev);
+	unsigned long time;
+
+	time = readl(ep93xx_rtc->mmio_base + EP93XX_RTC_DATA);
+
+	rtc_time64_to_tm(time, tm);
+	return 0;
+}
+
+static int ep93xx_rtc_set_time(struct device *dev, struct rtc_time *tm)
+{
+	struct ep93xx_rtc *ep93xx_rtc = dev_get_drvdata(dev);
+	unsigned long secs = rtc_tm_to_time64(tm);
+
+	writel(secs + 1, ep93xx_rtc->mmio_base + EP93XX_RTC_LOAD);
+	return 0;
+}
+
+static int ep93xx_rtc_proc(struct device *dev, struct seq_file *seq)
+{
+	unsigned short preload, delete;
+
+	ep93xx_rtc_get_swcomp(dev, &preload, &delete);
+
+	seq_printf(seq, "preload\t\t: %d\n", preload);
+	seq_printf(seq, "delete\t\t: %d\n", delete);
+
+	return 0;
+}
+
+static const struct rtc_class_ops ep93xx_rtc_ops = {
+	.read_time	= ep93xx_rtc_read_time,
+	.set_time	= ep93xx_rtc_set_time,
+	.proc		= ep93xx_rtc_proc,
+};
+
+static ssize_t comp_preload_show(struct device *dev,
+				 struct device_attribute *attr, char *buf)
+{
+	unsigned short preload;
+
+	ep93xx_rtc_get_swcomp(dev->parent, &preload, NULL);
+
+	return sprintf(buf, "%d\n", preload);
+}
+static DEVICE_ATTR_RO(comp_preload);
+
+static ssize_t comp_delete_show(struct device *dev,
+				struct device_attribute *attr, char *buf)
+{
+	unsigned short delete;
+
+	ep93xx_rtc_get_swcomp(dev->parent, NULL, &delete);
+
+	return sprintf(buf, "%d\n", delete);
+}
+static DEVICE_ATTR_RO(comp_delete);
+
+static struct attribute *ep93xx_rtc_attrs[] = {
+	&dev_attr_comp_preload.attr,
+	&dev_attr_comp_delete.attr,
+	NULL
+};
+
+static const struct attribute_group ep93xx_rtc_sysfs_files = {
+	.attrs	= ep93xx_rtc_attrs,
+};
+
+static int ep93xx_rtc_probe(struct platform_device *pdev)
+{
+	struct ep93xx_rtc *ep93xx_rtc;
+	struct rtc_device *rtc;
+	int err;
+
+	ep93xx_rtc = devm_kzalloc(&pdev->dev, sizeof(*ep93xx_rtc), GFP_KERNEL);
+	if (!ep93xx_rtc)
+		return -ENOMEM;
+
+	ep93xx_rtc->mmio_base = devm_platform_ioremap_resource(pdev, 0);
+	if (IS_ERR(ep93xx_rtc->mmio_base))
+		return PTR_ERR(ep93xx_rtc->mmio_base);
+
+	platform_set_drvdata(pdev, ep93xx_rtc);
+
+	rtc = devm_rtc_allocate_device(&pdev->dev);
+	if (IS_ERR(rtc))
+		return PTR_ERR(rtc);
+
+	rtc->ops = &ep93xx_rtc_ops;
+	rtc->range_max = U32_MAX;
+
+	err = rtc_add_group(rtc, &ep93xx_rtc_sysfs_files);
+	if (err)
+		return err;
+
+	return devm_rtc_register_device(rtc);
+}
+
+static const struct of_device_id ep93xx_rtc_of_ids[] = {
+	{ .compatible = "cirrus,ep9301-rtc" },
+	{ /* sentinel */ }
+};
+MODULE_DEVICE_TABLE(of, ep93xx_rtc_of_ids);
+
+static struct platform_driver ep93xx_rtc_driver = {
+	.driver		= {
+		.name	= "ep93xx-rtc",
+		.of_match_table = ep93xx_rtc_of_ids,
+	},
+	.probe		= ep93xx_rtc_probe,
+};
+
+module_platform_driver(ep93xx_rtc_driver);
+
+MODULE_AUTHOR("Alessandro Zummo <a.zummo@towertech.it>");
+MODULE_DESCRIPTION("EP93XX RTC driver");
+MODULE_LICENSE("GPL");
+MODULE_ALIAS("platform:ep93xx-rtc");