linux-hardening - [RFC] drm/i915/utils: document range

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-Id: <20250604085900.819259-1-jani.nikula@intel.com>
Date: Wed,  4 Jun 2025 11:59:00 +0300
From: Jani Nikula <jani.nikula@...el.com>
To: Kees Cook <kees@...nel.org>,
	Jani Nikula <jani.nikula@...el.com>
Cc: "Gustavo A. R. Silva" <gustavoars@...nel.org>,
	linux-hardening@...r.kernel.org,
	intel-gfx@...ts.freedesktop.org
Subject: [RFC] drm/i915/utils: document range_overflows*() macros

In preparation for moving the range check macros to
include/linux/overflow.h, document them properly.

Cc: Kees Cook <kees@...nel.org>
Signed-off-by: Jani Nikula <jani.nikula@...el.com>

---

I can squash this into actually moving the macros, I just want to
solicit feedback for the documentation first.
---
 drivers/gpu/drm/i915/i915_utils.h | 45 +++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/drivers/gpu/drm/i915/i915_utils.h b/drivers/gpu/drm/i915/i915_utils.h
index f7fb40cfdb70..79127f01f887 100644
--- a/drivers/gpu/drm/i915/i915_utils.h
+++ b/drivers/gpu/drm/i915/i915_utils.h
@@ -67,6 +67,19 @@ bool i915_error_injected(void);
 		drm_err(&(i915)->drm, fmt, ##__VA_ARGS__); \
 })
 
+
+/**
+ * range_overflows() - Check if @start + @size > @max
+ * @start: start offset
+ * @size: length of the range
+ * @max: valid upper limit
+ *
+ * Helper for the common @start + @size > @max range or buffer overflow
+ * check. Return true if the addition exceeds max or overflows. Also return true
+ * if @start == @max, even if @size == 0.
+ *
+ * Returns: %true if the range overflows.
+ */
 #define range_overflows(start, size, max) ({ \
 	typeof(start) start__ = (start); \
 	typeof(size) size__ = (size); \
@@ -76,9 +89,30 @@ bool i915_error_injected(void);
 	start__ >= max__ || size__ > max__ - start__; \
 })
 
+/**
+ * range_overflows_t() - Check if @start + @size > @max
+ * @type: data type to use
+ * @start: start offset
+ * @size: length of the range
+ * @max: valid upper limit
+ *
+ * Same as range_overflows(), but using the specified @type.
+ *
+ * Returns: %true if the range overflows.
+ */
 #define range_overflows_t(type, start, size, max) \
 	range_overflows((type)(start), (type)(size), (type)(max))
 
+/**
+ * range_overflows_end() - Check if @start + @size > @max
+ * @start: start offset
+ * @size: length of the range
+ * @max: valid upper limit
+ *
+ * Same as range_overflows(), but allow @start == @max when @size == 0.
+ *
+ * Returns: %true if the range overflows.
+ */
 #define range_overflows_end(start, size, max) ({ \
 	typeof(start) start__ = (start); \
 	typeof(size) size__ = (size); \
@@ -88,6 +122,17 @@ bool i915_error_injected(void);
 	start__ > max__ || size__ > max__ - start__; \
 })
 
+/**
+ * range_overflows_end_t() - Check if @start + @size > @max
+ * @type: data type to use
+ * @start: start offset
+ * @size: length of the range
+ * @max: valid upper limit
+ *
+ * Same as range_overflows_end(), but using the specified @type.
+ *
+ * Returns: %true if the range overflows.
+ */
 #define range_overflows_end_t(type, start, size, max) \
 	range_overflows_end((type)(start), (type)(size), (type)(max))
 
-- 
2.39.5