gccint: Overview of poly_int

1 
1 10.1 Overview of 'poly_int'
1 ===========================
1 
1 We define indeterminates X1, ..., XN whose values are only known at
1 runtime and use polynomials of the form:
1 
1      C0 + C1 * X1 + ... + CN * XN
1 
1  to represent a size or offset whose value might depend on some of these
1 indeterminates.  The coefficients C0, ..., CN are always known at
1 compile time, with the C0 term being the "constant" part that does not
1 depend on any runtime value.
1 
1  GCC uses the 'poly_int' class to represent these coefficients.  The
1 class has two template parameters: the first specifies the number of
1 coefficients (N + 1) and the second specifies the type of the
1 coefficients.  For example, 'poly_int<2, unsigned short>' represents a
1 polynomial with two coefficients (and thus one indeterminate), with each
1 coefficient having type 'unsigned short'.  When N is 0, the class
1 degenerates to a single compile-time constant C0.
1 
1  The number of coefficients needed for compilation is a fixed property
1 of each target and is specified by the configuration macro
1 'NUM_POLY_INT_COEFFS'.  The default value is 1, since most targets do
1 not have such runtime invariants.  Targets that need a different value
11 should '#define' the macro in their 'CPU-modes.def' file.  ⇒Back
 End.
1 
1  'poly_int' makes the simplifying requirement that each indeterminate
1 must be a nonnegative integer.  An indeterminate value of 0 should
1 usually represent the minimum possible runtime value, with C0 specifying
1 the value in that case.
1 
1  For example, when targetting the Arm SVE ISA, the single indeterminate
1 represents the number of 128-bit blocks in a vector _beyond the minimum
1 length of 128 bits_.  Thus the number of 64-bit doublewords in a vector
1 is 2 + 2 * X1.  If an aggregate has a single SVE vector and 16
1 additional bytes, its total size is 32 + 16 * X1 bytes.
1 
1  The header file 'poly-int-types.h' provides typedefs for the most
1 common forms of 'poly_int', all having 'NUM_POLY_INT_COEFFS'
1 coefficients:
1 
1 'poly_uint16'
1      a 'poly_int' with 'unsigned short' coefficients.
1 
1 'poly_int64'
1      a 'poly_int' with 'HOST_WIDE_INT' coefficients.
1 
1 'poly_uint64'
1      a 'poly_int' with 'unsigned HOST_WIDE_INT' coefficients.
1 
1 'poly_offset_int'
1      a 'poly_int' with 'offset_int' coefficients.
1 
1 'poly_wide_int'
1      a 'poly_int' with 'wide_int' coefficients.
1 
1 'poly_widest_int'
1      a 'poly_int' with 'widest_int' coefficients.
1 
1  Since the main purpose of 'poly_int' is to represent sizes and offsets,
1 the last two typedefs are only rarely used.
1