In preparation for moving the range check macros to include/linux/overflow.h, document them properly.
Cc: Kees Cook <[email protected]> Signed-off-by: Jani Nikula <[email protected]> --- 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
