minmax.h: update some comments

#include <linux/types.h>

/*

 * min()/max()/clamp() macros must accomplish three things:

 * min()/max()/clamp() macros must accomplish several things:

 *

 * - Avoid multiple evaluations of the arguments (so side-effects like

 *   "x++" happen only once) when non-constant.

 * - Retain result as a constant expressions when called with only

 *   constant expressions (to avoid tripping VLA warnings in stack

 *   allocation usage).

 * - Perform signed v unsigned type-checking (to generate compile

 *   errors instead of nasty runtime surprises).

 * - Unsigned char/short are always promoted to signed int and can be

 *   bit #0 set if ok for unsigned comparisons

 *   bit #1 set if ok for signed comparisons

 *

 * In particular, statically non-negative signed integer

 * expressions are ok for both.

 * In particular, statically non-negative signed integer expressions

 * are ok for both.

 *

 * NOTE! Unsigned types smaller than 'int' are implicitly

 * converted to 'int' in expressions, and are accepted for

 * signed conversions for now. This is debatable.

 * NOTE! Unsigned types smaller than 'int' are implicitly converted to 'int'

 * in expressions, and are accepted for signed conversions for now.

 * This is debatable.

 *

 * Note that 'x' is the original expression, and 'ux' is

 * the unique variable that contains the value.

 * Note that 'x' is the original expression, and 'ux' is the unique variable

 * that contains the value.

 *

 * We use 'ux' for pure type checking, and 'x' for when

 * we need to look at the value (but without evaluating

 * it for side effects! Careful to only ever evaluate it

 * with sizeof() or __builtin_constant_p() etc).

 * We use 'ux' for pure type checking, and 'x' for when we need to look at the

 * value (but without evaluating it for side effects!

 * Careful to only ever evaluate it with sizeof() or __builtin_constant_p() etc).

 *

 * Pointers end up being checked by the normal C type

 * rules at the actual comparison, and these expressions

 * only need to be careful to not cause warnings for

 * pointer use.

 * Pointers end up being checked by the normal C type rules at the actual

 * comparison, and these expressions only need to be careful to not cause

 * warnings for pointer use.

 */

#define __signed_type_use(x, ux) (2 + __is_nonneg(x, ux))

#define __unsigned_type_use(x, ux) (1 + 2 * (sizeof(ux) < 4))

	__signed_type_use(x, ux) : __unsigned_type_use(x, ux))

/*

 * To avoid warnings about casting pointers to integers

 * of different sizes, we need that special sign type.

 * Check whether a signed value is always non-negative.

 *

 * On 64-bit we can just always use 'long', since any

 * integer or pointer type can just be cast to that.

 * A cast is needed to avoid any warnings from values that aren't signed

 * integer types (in which case the result doesn't matter).

 *

 * This does not work for 128-bit signed integers since

 * the cast would truncate them, but we do not use s128

 * types in the kernel (we do use 'u128', but they will

 * be handled by the !is_signed_type() case).

 * On 64-bit any integer or pointer type can safely be cast to 'long'.

 * But on 32-bit we need to avoid warnings about casting pointers to integers

 * of different sizes without truncating 64-bit values so 'long' or 'long long'

 * must be used depending on the size of the value.

 *

 * NOTE! The cast is there only to avoid any warnings

 * from when values that aren't signed integer types.

 * This does not work for 128-bit signed integers since the cast would truncate

 * them, but we do not use s128 types in the kernel (we do use 'u128',

 * but they are handled by the !is_signed_type() case).

 */

#ifdef CONFIG_64BIT

  #define __signed_type(ux) long