| 1 |
@node poly_int |
| 2 |
@chapter Sizes and offsets as runtime invariants |
| 3 |
@cindex polynomial integers |
| 4 |
@findex poly_int |
| 5 |
|
| 6 |
GCC allows the size of a hardware register to be a runtime invariant |
| 7 |
rather than a compile-time constant. This in turn means that various |
| 8 |
sizes and offsets must also be runtime invariants rather than |
| 9 |
compile-time constants, such as: |
| 10 |
|
| 11 |
@itemize @bullet |
| 12 |
@item |
| 13 |
the size of a general @code{machine_mode} (@pxref{Machine Modes}); |
| 14 |
|
| 15 |
@item |
| 16 |
the size of a spill slot; |
| 17 |
|
| 18 |
@item |
| 19 |
the offset of something within a stack frame; |
| 20 |
|
| 21 |
@item |
| 22 |
the number of elements in a vector; |
| 23 |
|
| 24 |
@item |
| 25 |
the size and offset of a @code{mem} rtx (@pxref{Regs and Memory}); and |
| 26 |
|
| 27 |
@item |
| 28 |
the byte offset in a @code{subreg} rtx (@pxref{Regs and Memory}). |
| 29 |
@end itemize |
| 30 |
|
| 31 |
The motivating example is the Arm SVE ISA, whose vector registers can be |
| 32 |
any multiple of 128 bits between 128 and 2048 inclusive. The compiler |
| 33 |
normally produces code that works for all SVE register sizes, with the |
| 34 |
actual size only being known at runtime. |
| 35 |
|
| 36 |
GCC's main representation of such runtime invariants is the |
| 37 |
@code{poly_int} class. This chapter describes what @code{poly_int} |
| 38 |
does, lists the available operations, and gives some general |
| 39 |
usage guidelines. |
| 40 |
|
| 41 |
@menu |
| 42 |
* Overview of @code{poly_int}:: |
| 43 |
* Consequences of using @code{poly_int}:: |
| 44 |
* Comparisons involving @code{poly_int}:: |
| 45 |
* Arithmetic on @code{poly_int}s:: |
| 46 |
* Alignment of @code{poly_int}s:: |
| 47 |
* Computing bounds on @code{poly_int}s:: |
| 48 |
* Converting @code{poly_int}s:: |
| 49 |
* Miscellaneous @code{poly_int} routines:: |
| 50 |
* Guidelines for using @code{poly_int}:: |
| 51 |
@end menu |
| 52 |
|
| 53 |
@node Overview of @code{poly_int} |
| 54 |
@section Overview of @code{poly_int} |
| 55 |
|
| 56 |
@cindex @code{poly_int}, runtime value |
| 57 |
We define indeterminates @var{x1}, @dots{}, @var{xn} whose values are |
| 58 |
only known at runtime and use polynomials of the form: |
| 59 |
|
| 60 |
@smallexample |
| 61 |
@var{c0} + @var{c1} * @var{x1} + @dots{} + @var{cn} * @var{xn} |
| 62 |
@end smallexample |
| 63 |
|
| 64 |
to represent a size or offset whose value might depend on some |
| 65 |
of these indeterminates. The coefficients @var{c0}, @dots{}, @var{cn} |
| 66 |
are always known at compile time, with the @var{c0} term being the |
| 67 |
``constant'' part that does not depend on any runtime value. |
| 68 |
|
| 69 |
GCC uses the @code{poly_int} class to represent these coefficients. |
| 70 |
The class has two template parameters: the first specifies the number of |
| 71 |
coefficients (@var{n} + 1) and the second specifies the type of the |
| 72 |
coefficients. For example, @samp{poly_int<2, unsigned short>} represents |
| 73 |
a polynomial with two coefficients (and thus one indeterminate), with each |
| 74 |
coefficient having type @code{unsigned short}. When @var{n} is 0, |
| 75 |
the class degenerates to a single compile-time constant @var{c0}. |
| 76 |
|
| 77 |
@cindex @code{poly_int}, template parameters |
| 78 |
@findex NUM_POLY_INT_COEFFS |
| 79 |
The number of coefficients needed for compilation is a fixed |
| 80 |
property of each target and is specified by the configuration macro |
| 81 |
@code{NUM_POLY_INT_COEFFS}. The default value is 1, since most targets |
| 82 |
do not have such runtime invariants. Targets that need a different |
| 83 |
value should @code{#define} the macro in their @file{@var{cpu}-modes.def} |
| 84 |
file. @xref{Back End}. |
| 85 |
|
| 86 |
@cindex @code{poly_int}, invariant range |
| 87 |
@code{poly_int} makes the simplifying requirement that each indeterminate |
| 88 |
must be a nonnegative integer. An indeterminate value of 0 should usually |
| 89 |
represent the minimum possible runtime value, with @var{c0} specifying |
| 90 |
the value in that case. |
| 91 |
|
| 92 |
For example, when targetting the Arm SVE ISA, the single indeterminate |
| 93 |
represents the number of 128-bit blocks in a vector @emph{beyond the minimum |
| 94 |
length of 128 bits}. Thus the number of 64-bit doublewords in a vector |
| 95 |
is 2 + 2 * @var{x1}. If an aggregate has a single SVE vector and 16 |
| 96 |
additional bytes, its total size is 32 + 16 * @var{x1} bytes. |
| 97 |
|
| 98 |
The header file @file{poly-int-types.h} provides typedefs for the |
| 99 |
most common forms of @code{poly_int}, all having |
| 100 |
@code{NUM_POLY_INT_COEFFS} coefficients: |
| 101 |
|
| 102 |
@cindex @code{poly_int}, main typedefs |
| 103 |
@table @code |
| 104 |
@item poly_uint16 |
| 105 |
a @samp{poly_int} with @code{unsigned short} coefficients. |
| 106 |
|
| 107 |
@item poly_int64 |
| 108 |
a @samp{poly_int} with @code{HOST_WIDE_INT} coefficients. |
| 109 |
|
| 110 |
@item poly_uint64 |
| 111 |
a @samp{poly_int} with @code{unsigned HOST_WIDE_INT} coefficients. |
| 112 |
|
| 113 |
@item poly_offset_int |
| 114 |
a @samp{poly_int} with @code{offset_int} coefficients. |
| 115 |
|
| 116 |
@item poly_wide_int |
| 117 |
a @samp{poly_int} with @code{wide_int} coefficients. |
| 118 |
|
| 119 |
@item poly_widest_int |
| 120 |
a @samp{poly_int} with @code{widest_int} coefficients. |
| 121 |
@end table |
| 122 |
|
| 123 |
Since the main purpose of @code{poly_int} is to represent sizes and |
| 124 |
offsets, the last two typedefs are only rarely used. |
| 125 |
|
| 126 |
@node Consequences of using @code{poly_int} |
| 127 |
@section Consequences of using @code{poly_int} |
| 128 |
|
| 129 |
The two main consequences of using polynomial sizes and offsets are that: |
| 130 |
|
| 131 |
@itemize |
| 132 |
@item |
| 133 |
there is no total ordering between the values at compile time, and |
| 134 |
|
| 135 |
@item |
| 136 |
some operations might yield results that cannot be expressed as a |
| 137 |
@code{poly_int}. |
| 138 |
@end itemize |
| 139 |
|
| 140 |
For example, if @var{x} is a runtime invariant, we cannot tell at |
| 141 |
compile time whether: |
| 142 |
|
| 143 |
@smallexample |
| 144 |
3 + 4@var{x} <= 1 + 5@var{x} |
| 145 |
@end smallexample |
| 146 |
|
| 147 |
since the condition is false when @var{x} <= 1 and true when @var{x} >= 2. |
| 148 |
|
| 149 |
Similarly, @code{poly_int} cannot represent the result of: |
| 150 |
|
| 151 |
@smallexample |
| 152 |
(3 + 4@var{x}) * (1 + 5@var{x}) |
| 153 |
@end smallexample |
| 154 |
|
| 155 |
since it cannot (and in practice does not need to) store powers greater |
| 156 |
than one. It also cannot represent the result of: |
| 157 |
|
| 158 |
@smallexample |
| 159 |
(3 + 4@var{x}) / (1 + 5@var{x}) |
| 160 |
@end smallexample |
| 161 |
|
| 162 |
The following sections describe how we deal with these restrictions. |
| 163 |
|
| 164 |
@cindex @code{poly_int}, use in target-independent code |
| 165 |
As described earlier, a @code{poly_int<1, @var{T}>} has no indeterminates |
| 166 |
and so degenerates to a compile-time constant of type @var{T}. It would |
| 167 |
be possible in that case to do all normal arithmetic on the @var{T}, |
| 168 |
and to compare the @var{T} using the normal C++ operators. We deliberately |
| 169 |
prevent target-independent code from doing this, since the compiler needs |
| 170 |
to support other @code{poly_int<@var{n}, @var{T}>} as well, regardless of |
| 171 |
the current target's @code{NUM_POLY_INT_COEFFS}. |
| 172 |
|
| 173 |
@cindex @code{poly_int}, use in target-specific code |
| 174 |
However, it would be very artificial to force target-specific code |
| 175 |
to follow these restrictions if the target has no runtime indeterminates. |
| 176 |
There is therefore an implicit conversion from @code{poly_int<1, @var{T}>} |
| 177 |
to @var{T} when compiling target-specific translation units. |
| 178 |
|
| 179 |
@node Comparisons involving @code{poly_int} |
| 180 |
@section Comparisons involving @code{poly_int} |
| 181 |
|
| 182 |
In general we need to compare sizes and offsets in two situations: |
| 183 |
those in which the values need to be ordered, and those in which |
| 184 |
the values can be unordered. More loosely, the distinction is often |
| 185 |
between values that have a definite link (usually because they refer to the |
| 186 |
same underlying register or memory location) and values that have |
| 187 |
no definite link. An example of the former is the relationship between |
| 188 |
the inner and outer sizes of a subreg, where we must know at compile time |
| 189 |
whether the subreg is paradoxical, partial, or complete. An example of |
| 190 |
the latter is alias analysis: we might want to check whether two |
| 191 |
arbitrary memory references overlap. |
| 192 |
|
| 193 |
Referring back to the examples in the previous section, it makes sense |
| 194 |
to ask whether a memory reference of size @samp{3 + 4@var{x}} overlaps |
| 195 |
one of size @samp{1 + 5@var{x}}, but it does not make sense to have a |
| 196 |
subreg in which the outer mode has @samp{3 + 4@var{x}} bytes and the |
| 197 |
inner mode has @samp{1 + 5@var{x}} bytes (or vice versa). Such subregs |
| 198 |
are always invalid and should trigger an internal compiler error |
| 199 |
if formed. |
| 200 |
|
| 201 |
The underlying operators are the same in both cases, but the distinction |
| 202 |
affects how they are used. |
| 203 |
|
| 204 |
@menu |
| 205 |
* Comparison functions for @code{poly_int}:: |
| 206 |
* Properties of the @code{poly_int} comparisons:: |
| 207 |
* Comparing potentially-unordered @code{poly_int}s:: |
| 208 |
* Comparing ordered @code{poly_int}s:: |
| 209 |
* Checking for a @code{poly_int} marker value:: |
| 210 |
* Range checks on @code{poly_int}s:: |
| 211 |
* Sorting @code{poly_int}s:: |
| 212 |
@end menu |
| 213 |
|
| 214 |
@node Comparison functions for @code{poly_int} |
| 215 |
@subsection Comparison functions for @code{poly_int} |
| 216 |
|
| 217 |
@code{poly_int} provides the following routines for checking whether |
| 218 |
a particular condition ``may be'' (might be) true: |
| 219 |
|
| 220 |
@example |
| 221 |
maybe_lt maybe_le maybe_eq maybe_ge maybe_gt |
| 222 |
maybe_ne |
| 223 |
@end example |
| 224 |
|
| 225 |
The functions have their natural meaning: |
| 226 |
|
| 227 |
@table @samp |
| 228 |
@item maybe_lt(@var{a}, @var{b}) |
| 229 |
Return true if @var{a} might be less than @var{b}. |
| 230 |
|
| 231 |
@item maybe_le(@var{a}, @var{b}) |
| 232 |
Return true if @var{a} might be less than or equal to @var{b}. |
| 233 |
|
| 234 |
@item maybe_eq(@var{a}, @var{b}) |
| 235 |
Return true if @var{a} might be equal to @var{b}. |
| 236 |
|
| 237 |
@item maybe_ne(@var{a}, @var{b}) |
| 238 |
Return true if @var{a} might not be equal to @var{b}. |
| 239 |
|
| 240 |
@item maybe_ge(@var{a}, @var{b}) |
| 241 |
Return true if @var{a} might be greater than or equal to @var{b}. |
| 242 |
|
| 243 |
@item maybe_gt(@var{a}, @var{b}) |
| 244 |
Return true if @var{a} might be greater than @var{b}. |
| 245 |
@end table |
| 246 |
|
| 247 |
For readability, @code{poly_int} also provides ``known'' inverses of these |
| 248 |
functions: |
| 249 |
|
| 250 |
@example |
| 251 |
known_lt (@var{a}, @var{b}) == !maybe_ge (@var{a}, @var{b}) |
| 252 |
known_le (@var{a}, @var{b}) == !maybe_gt (@var{a}, @var{b}) |
| 253 |
known_eq (@var{a}, @var{b}) == !maybe_ne (@var{a}, @var{b}) |
| 254 |
known_ge (@var{a}, @var{b}) == !maybe_lt (@var{a}, @var{b}) |
| 255 |
known_gt (@var{a}, @var{b}) == !maybe_le (@var{a}, @var{b}) |
| 256 |
known_ne (@var{a}, @var{b}) == !maybe_eq (@var{a}, @var{b}) |
| 257 |
@end example |
| 258 |
|
| 259 |
@node Properties of the @code{poly_int} comparisons |
| 260 |
@subsection Properties of the @code{poly_int} comparisons |
| 261 |
|
| 262 |
All ``maybe'' relations except @code{maybe_ne} are transitive, so for example: |
| 263 |
|
| 264 |
@smallexample |
| 265 |
maybe_lt (@var{a}, @var{b}) && maybe_lt (@var{b}, @var{c}) implies maybe_lt (@var{a}, @var{c}) |
| 266 |
@end smallexample |
| 267 |
|
| 268 |
for all @var{a}, @var{b} and @var{c}. @code{maybe_lt}, @code{maybe_gt} |
| 269 |
and @code{maybe_ne} are irreflexive, so for example: |
| 270 |
|
| 271 |
@smallexample |
| 272 |
!maybe_lt (@var{a}, @var{a}) |
| 273 |
@end smallexample |
| 274 |
|
| 275 |
is true for all @var{a}. @code{maybe_le}, @code{maybe_eq} and @code{maybe_ge} |
| 276 |
are reflexive, so for example: |
| 277 |
|
| 278 |
@smallexample |
| 279 |
maybe_le (@var{a}, @var{a}) |
| 280 |
@end smallexample |
| 281 |
|
| 282 |
is true for all @var{a}. @code{maybe_eq} and @code{maybe_ne} are symmetric, so: |
| 283 |
|
| 284 |
@smallexample |
| 285 |
maybe_eq (@var{a}, @var{b}) == maybe_eq (@var{b}, @var{a}) |
| 286 |
maybe_ne (@var{a}, @var{b}) == maybe_ne (@var{b}, @var{a}) |
| 287 |
@end smallexample |
| 288 |
|
| 289 |
for all @var{a} and @var{b}. In addition: |
| 290 |
|
| 291 |
@smallexample |
| 292 |
maybe_le (@var{a}, @var{b}) == maybe_lt (@var{a}, @var{b}) || maybe_eq (@var{a}, @var{b}) |
| 293 |
maybe_ge (@var{a}, @var{b}) == maybe_gt (@var{a}, @var{b}) || maybe_eq (@var{a}, @var{b}) |
| 294 |
maybe_lt (@var{a}, @var{b}) == maybe_gt (@var{b}, @var{a}) |
| 295 |
maybe_le (@var{a}, @var{b}) == maybe_ge (@var{b}, @var{a}) |
| 296 |
@end smallexample |
| 297 |
|
| 298 |
However: |
| 299 |
|
| 300 |
@smallexample |
| 301 |
maybe_le (@var{a}, @var{b}) && maybe_le (@var{b}, @var{a}) does not imply !maybe_ne (@var{a}, @var{b}) [== known_eq (@var{a}, @var{b})] |
| 302 |
maybe_ge (@var{a}, @var{b}) && maybe_ge (@var{b}, @var{a}) does not imply !maybe_ne (@var{a}, @var{b}) [== known_eq (@var{a}, @var{b})] |
| 303 |
@end smallexample |
| 304 |
|
| 305 |
One example is again @samp{@var{a} == 3 + 4@var{x}} |
| 306 |
and @samp{@var{b} == 1 + 5@var{x}}, where @samp{maybe_le (@var{a}, @var{b})}, |
| 307 |
@samp{maybe_ge (@var{a}, @var{b})} and @samp{maybe_ne (@var{a}, @var{b})} |
| 308 |
all hold. @code{maybe_le} and @code{maybe_ge} are therefore not antisymetric |
| 309 |
and do not form a partial order. |
| 310 |
|
| 311 |
From the above, it follows that: |
| 312 |
|
| 313 |
@itemize @bullet |
| 314 |
@item |
| 315 |
All ``known'' relations except @code{known_ne} are transitive. |
| 316 |
|
| 317 |
@item |
| 318 |
@code{known_lt}, @code{known_ne} and @code{known_gt} are irreflexive. |
| 319 |
|
| 320 |
@item |
| 321 |
@code{known_le}, @code{known_eq} and @code{known_ge} are reflexive. |
| 322 |
@end itemize |
| 323 |
|
| 324 |
Also: |
| 325 |
|
| 326 |
@smallexample |
| 327 |
known_lt (@var{a}, @var{b}) == known_gt (@var{b}, @var{a}) |
| 328 |
known_le (@var{a}, @var{b}) == known_ge (@var{b}, @var{a}) |
| 329 |
known_lt (@var{a}, @var{b}) implies !known_lt (@var{b}, @var{a}) [asymmetry] |
| 330 |
known_gt (@var{a}, @var{b}) implies !known_gt (@var{b}, @var{a}) |
| 331 |
known_le (@var{a}, @var{b}) && known_le (@var{b}, @var{a}) == known_eq (@var{a}, @var{b}) [== !maybe_ne (@var{a}, @var{b})] |
| 332 |
known_ge (@var{a}, @var{b}) && known_ge (@var{b}, @var{a}) == known_eq (@var{a}, @var{b}) [== !maybe_ne (@var{a}, @var{b})] |
| 333 |
@end smallexample |
| 334 |
|
| 335 |
@code{known_le} and @code{known_ge} are therefore antisymmetric and are |
| 336 |
partial orders. However: |
| 337 |
|
| 338 |
@smallexample |
| 339 |
known_le (@var{a}, @var{b}) does not imply known_lt (@var{a}, @var{b}) || known_eq (@var{a}, @var{b}) |
| 340 |
known_ge (@var{a}, @var{b}) does not imply known_gt (@var{a}, @var{b}) || known_eq (@var{a}, @var{b}) |
| 341 |
@end smallexample |
| 342 |
|
| 343 |
For example, @samp{known_le (4, 4 + 4@var{x})} holds because the runtime |
| 344 |
indeterminate @var{x} is a nonnegative integer, but neither |
| 345 |
@code{known_lt (4, 4 + 4@var{x})} nor @code{known_eq (4, 4 + 4@var{x})} hold. |
| 346 |
|
| 347 |
@node Comparing potentially-unordered @code{poly_int}s |
| 348 |
@subsection Comparing potentially-unordered @code{poly_int}s |
| 349 |
|
| 350 |
In cases where there is no definite link between two @code{poly_int}s, |
| 351 |
we can usually make a conservatively-correct assumption. For example, |
| 352 |
the conservative assumption for alias analysis is that two references |
| 353 |
@emph{might} alias. |
| 354 |
|
| 355 |
One way of checking whether [@var{begin1}, @var{end1}) might overlap |
| 356 |
[@var{begin2}, @var{end2}) using the @code{poly_int} comparisons is: |
| 357 |
|
| 358 |
@smallexample |
| 359 |
maybe_gt (@var{end1}, @var{begin2}) && maybe_gt (@var{end2}, @var{begin1}) |
| 360 |
@end smallexample |
| 361 |
|
| 362 |
and another (equivalent) way is: |
| 363 |
|
| 364 |
@smallexample |
| 365 |
!(known_le (@var{end1}, @var{begin2}) || known_le (@var{end2}, @var{begin1})) |
| 366 |
@end smallexample |
| 367 |
|
| 368 |
However, in this particular example, it is better to use the range helper |
| 369 |
functions instead. @xref{Range checks on @code{poly_int}s}. |
| 370 |
|
| 371 |
@node Comparing ordered @code{poly_int}s |
| 372 |
@subsection Comparing ordered @code{poly_int}s |
| 373 |
|
| 374 |
In cases where there is a definite link between two @code{poly_int}s, |
| 375 |
such as the outer and inner sizes of subregs, we usually require the sizes |
| 376 |
to be ordered by the @code{known_le} partial order. @code{poly_int} provides |
| 377 |
the following utility functions for ordered values: |
| 378 |
|
| 379 |
@table @samp |
| 380 |
@item ordered_p (@var{a}, @var{b}) |
| 381 |
Return true if @var{a} and @var{b} are ordered by the @code{known_le} |
| 382 |
partial order. |
| 383 |
|
| 384 |
@item ordered_min (@var{a}, @var{b}) |
| 385 |
Assert that @var{a} and @var{b} are ordered by @code{known_le} and return the |
| 386 |
minimum of the two. When using this function, please add a comment explaining |
| 387 |
why the values are known to be ordered. |
| 388 |
|
| 389 |
@item ordered_max (@var{a}, @var{b}) |
| 390 |
Assert that @var{a} and @var{b} are ordered by @code{known_le} and return the |
| 391 |
maximum of the two. When using this function, please add a comment explaining |
| 392 |
why the values are known to be ordered. |
| 393 |
@end table |
| 394 |
|
| 395 |
For example, if a subreg has an outer mode of size @var{outer} and an |
| 396 |
inner mode of size @var{inner}: |
| 397 |
|
| 398 |
@itemize @bullet |
| 399 |
@item |
| 400 |
the subreg is complete if known_eq (@var{inner}, @var{outer}) |
| 401 |
|
| 402 |
@item |
| 403 |
otherwise, the subreg is paradoxical if known_le (@var{inner}, @var{outer}) |
| 404 |
|
| 405 |
@item |
| 406 |
otherwise, the subreg is partial if known_le (@var{outer}, @var{inner}) |
| 407 |
|
| 408 |
@item |
| 409 |
otherwise, the subreg is ill-formed |
| 410 |
@end itemize |
| 411 |
|
| 412 |
Thus the subreg is only valid if |
| 413 |
@samp{ordered_p (@var{outer}, @var{inner})} is true. If this condition |
| 414 |
is already known to be true then: |
| 415 |
|
| 416 |
@itemize @bullet |
| 417 |
@item |
| 418 |
the subreg is complete if known_eq (@var{inner}, @var{outer}) |
| 419 |
|
| 420 |
@item |
| 421 |
the subreg is paradoxical if maybe_lt (@var{inner}, @var{outer}) |
| 422 |
|
| 423 |
@item |
| 424 |
the subreg is partial if maybe_lt (@var{outer}, @var{inner}) |
| 425 |
@end itemize |
| 426 |
|
| 427 |
with the three conditions being mutually exclusive. |
| 428 |
|
| 429 |
Code that checks whether a subreg is valid would therefore generally |
| 430 |
check whether @code{ordered_p} holds (in addition to whatever other |
| 431 |
checks are required for subreg validity). Code that is dealing |
| 432 |
with existing subregs can assert that @code{ordered_p} holds |
| 433 |
and use either of the classifications above. |
| 434 |
|
| 435 |
@node Checking for a @code{poly_int} marker value |
| 436 |
@subsection Checking for a @code{poly_int} marker value |
| 437 |
|
| 438 |
It is sometimes useful to have a special ``marker value'' that is not |
| 439 |
meant to be taken literally. For example, some code uses a size |
| 440 |
of -1 to represent an unknown size, rather than having to carry around |
| 441 |
a separate boolean to say whether the size is known. |
| 442 |
|
| 443 |
The best way of checking whether something is a marker value is |
| 444 |
@code{known_eq}. Conversely the best way of checking whether something |
| 445 |
is @emph{not} a marker value is @code{maybe_ne}. |
| 446 |
|
| 447 |
Thus in the size example just mentioned, @samp{known_eq (size, -1)} would |
| 448 |
check for an unknown size and @samp{maybe_ne (size, -1)} would check for a |
| 449 |
known size. |
| 450 |
|
| 451 |
@node Range checks on @code{poly_int}s |
| 452 |
@subsection Range checks on @code{poly_int}s |
| 453 |
|
| 454 |
As well as the core comparisons |
| 455 |
(@pxref{Comparison functions for @code{poly_int}}), @code{poly_int} provides |
| 456 |
utilities for various kinds of range check. In each case the range |
| 457 |
is represented by a start position and a size rather than a start |
| 458 |
position and an end position; this is because the former is used |
| 459 |
much more often than the latter in GCC@. Also, the sizes can be |
| 460 |
-1 (or all ones for unsigned sizes) to indicate a range with a known |
| 461 |
start position but an unknown size. All other sizes must be nonnegative. |
| 462 |
A range of size 0 does not contain anything or overlap anything. |
| 463 |
|
| 464 |
@table @samp |
| 465 |
@item known_size_p (@var{size}) |
| 466 |
Return true if @var{size} represents a known range size, false if it |
| 467 |
is -1 or all ones (for signed and unsigned types respectively). |
| 468 |
|
| 469 |
@item ranges_maybe_overlap_p (@var{pos1}, @var{size1}, @var{pos2}, @var{size2}) |
| 470 |
Return true if the range described by @var{pos1} and @var{size1} @emph{might} |
| 471 |
overlap the range described by @var{pos2} and @var{size2} (in other words, |
| 472 |
return true if we cannot prove that the ranges are disjoint). |
| 473 |
|
| 474 |
@item ranges_known_overlap_p (@var{pos1}, @var{size1}, @var{pos2}, @var{size2}) |
| 475 |
Return true if the range described by @var{pos1} and @var{size1} is known to |
| 476 |
overlap the range described by @var{pos2} and @var{size2}. |
| 477 |
|
| 478 |
@item known_subrange_p (@var{pos1}, @var{size1}, @var{pos2}, @var{size2}) |
| 479 |
Return true if the range described by @var{pos1} and @var{size1} is known to |
| 480 |
be contained in the range described by @var{pos2} and @var{size2}. |
| 481 |
|
| 482 |
@item maybe_in_range_p (@var{value}, @var{pos}, @var{size}) |
| 483 |
Return true if @var{value} @emph{might} be in the range described by |
| 484 |
@var{pos} and @var{size} (in other words, return true if we cannot |
| 485 |
prove that @var{value} is outside that range). |
| 486 |
|
| 487 |
@item known_in_range_p (@var{value}, @var{pos}, @var{size}) |
| 488 |
Return true if @var{value} is known to be in the range described |
| 489 |
by @var{pos} and @var{size}. |
| 490 |
|
| 491 |
@item endpoint_representable_p (@var{pos}, @var{size}) |
| 492 |
Return true if the range described by @var{pos} and @var{size} is |
| 493 |
open-ended or if the endpoint (@var{pos} + @var{size}) is representable |
| 494 |
in the same type as @var{pos} and @var{size}. The function returns false |
| 495 |
if adding @var{size} to @var{pos} makes conceptual sense but could overflow. |
| 496 |
@end table |
| 497 |
|
| 498 |
There is also a @code{poly_int} version of the @code{IN_RANGE_P} macro: |
| 499 |
|
| 500 |
@table @samp |
| 501 |
@item coeffs_in_range_p (@var{x}, @var{lower}, @var{upper}) |
| 502 |
Return true if every coefficient of @var{x} is in the inclusive range |
| 503 |
[@var{lower}, @var{upper}]. This function can be useful when testing |
| 504 |
whether an operation would cause the values of coefficients to |
| 505 |
overflow. |
| 506 |
|
| 507 |
Note that the function does not indicate whether @var{x} itself is in the |
| 508 |
given range. @var{x} can be either a constant or a @code{poly_int}. |
| 509 |
@end table |
| 510 |
|
| 511 |
@node Sorting @code{poly_int}s |
| 512 |
@subsection Sorting @code{poly_int}s |
| 513 |
|
| 514 |
@code{poly_int} provides the following routine for sorting: |
| 515 |
|
| 516 |
@table @samp |
| 517 |
@item compare_sizes_for_sort (@var{a}, @var{b}) |
| 518 |
Compare @var{a} and @var{b} in reverse lexicographical order (that is, |
| 519 |
compare the highest-indexed coefficients first). This can be useful when |
| 520 |
sorting data structures, since it has the effect of separating constant |
| 521 |
and non-constant values. If all values are nonnegative, the constant |
| 522 |
values come first. |
| 523 |
|
| 524 |
Note that the values do not necessarily end up in numerical order. |
| 525 |
For example, @samp{1 + 1@var{x}} would come after @samp{100} in the sort order, |
| 526 |
but may well be less than @samp{100} at run time. |
| 527 |
@end table |
| 528 |
|
| 529 |
@node Arithmetic on @code{poly_int}s |
| 530 |
@section Arithmetic on @code{poly_int}s |
| 531 |
|
| 532 |
Addition, subtraction, negation and bit inversion all work normally for |
| 533 |
@code{poly_int}s. Multiplication by a constant multiplier and left |
| 534 |
shifting by a constant shift amount also work normally. General |
| 535 |
multiplication of two @code{poly_int}s is not supported and is not |
| 536 |
useful in practice. |
| 537 |
|
| 538 |
Other operations are only conditionally supported: the operation |
| 539 |
might succeed or might fail, depending on the inputs. |
| 540 |
|
| 541 |
This section describes both types of operation. |
| 542 |
|
| 543 |
@menu |
| 544 |
* Using @code{poly_int} with C++ arithmetic operators:: |
| 545 |
* @code{wi} arithmetic on @code{poly_int}s:: |
| 546 |
* Division of @code{poly_int}s:: |
| 547 |
* Other @code{poly_int} arithmetic:: |
| 548 |
@end menu |
| 549 |
|
| 550 |
@node Using @code{poly_int} with C++ arithmetic operators |
| 551 |
@subsection Using @code{poly_int} with C++ arithmetic operators |
| 552 |
|
| 553 |
The following C++ expressions are supported, where @var{p1} and @var{p2} |
| 554 |
are @code{poly_int}s and where @var{c1} and @var{c2} are scalars: |
| 555 |
|
| 556 |
@smallexample |
| 557 |
-@var{p1} |
| 558 |
~@var{p1} |
| 559 |
|
| 560 |
@var{p1} + @var{p2} |
| 561 |
@var{p1} + @var{c2} |
| 562 |
@var{c1} + @var{p2} |
| 563 |
|
| 564 |
@var{p1} - @var{p2} |
| 565 |
@var{p1} - @var{c2} |
| 566 |
@var{c1} - @var{p2} |
| 567 |
|
| 568 |
@var{c1} * @var{p2} |
| 569 |
@var{p1} * @var{c2} |
| 570 |
|
| 571 |
@var{p1} << @var{c2} |
| 572 |
|
| 573 |
@var{p1} += @var{p2} |
| 574 |
@var{p1} += @var{c2} |
| 575 |
|
| 576 |
@var{p1} -= @var{p2} |
| 577 |
@var{p1} -= @var{c2} |
| 578 |
|
| 579 |
@var{p1} *= @var{c2} |
| 580 |
@var{p1} <<= @var{c2} |
| 581 |
@end smallexample |
| 582 |
|
| 583 |
These arithmetic operations handle integer ranks in a similar way |
| 584 |
to C++. The main difference is that every coefficient narrower than |
| 585 |
@code{HOST_WIDE_INT} promotes to @code{HOST_WIDE_INT}, whereas in |
| 586 |
C++ everything narrower than @code{int} promotes to @code{int}. |
| 587 |
For example: |
| 588 |
|
| 589 |
@smallexample |
| 590 |
poly_uint16 + int -> poly_int64 |
| 591 |
unsigned int + poly_uint16 -> poly_int64 |
| 592 |
poly_int64 + int -> poly_int64 |
| 593 |
poly_int32 + poly_uint64 -> poly_uint64 |
| 594 |
uint64 + poly_int64 -> poly_uint64 |
| 595 |
poly_offset_int + int32 -> poly_offset_int |
| 596 |
offset_int + poly_uint16 -> poly_offset_int |
| 597 |
@end smallexample |
| 598 |
|
| 599 |
In the first two examples, both coefficients are narrower than |
| 600 |
@code{HOST_WIDE_INT}, so the result has coefficients of type |
| 601 |
@code{HOST_WIDE_INT}. In the other examples, the coefficient |
| 602 |
with the highest rank ``wins''. |
| 603 |
|
| 604 |
If one of the operands is @code{wide_int} or @code{poly_wide_int}, |
| 605 |
the rules are the same as for @code{wide_int} arithmetic. |
| 606 |
|
| 607 |
@node @code{wi} arithmetic on @code{poly_int}s |
| 608 |
@subsection @code{wi} arithmetic on @code{poly_int}s |
| 609 |
|
| 610 |
As well as the C++ operators, @code{poly_int} supports the following |
| 611 |
@code{wi} routines: |
| 612 |
|
| 613 |
@smallexample |
| 614 |
wi::neg (@var{p1}, &@var{overflow}) |
| 615 |
|
| 616 |
wi::add (@var{p1}, @var{p2}) |
| 617 |
wi::add (@var{p1}, @var{c2}) |
| 618 |
wi::add (@var{c1}, @var{p1}) |
| 619 |
wi::add (@var{p1}, @var{p2}, @var{sign}, &@var{overflow}) |
| 620 |
|
| 621 |
wi::sub (@var{p1}, @var{p2}) |
| 622 |
wi::sub (@var{p1}, @var{c2}) |
| 623 |
wi::sub (@var{c1}, @var{p1}) |
| 624 |
wi::sub (@var{p1}, @var{p2}, @var{sign}, &@var{overflow}) |
| 625 |
|
| 626 |
wi::mul (@var{p1}, @var{c2}) |
| 627 |
wi::mul (@var{c1}, @var{p1}) |
| 628 |
wi::mul (@var{p1}, @var{c2}, @var{sign}, &@var{overflow}) |
| 629 |
|
| 630 |
wi::lshift (@var{p1}, @var{c2}) |
| 631 |
@end smallexample |
| 632 |
|
| 633 |
These routines just check whether overflow occurs on any individual |
| 634 |
coefficient; it is not possible to know at compile time whether the |
| 635 |
final runtime value would overflow. |
| 636 |
|
| 637 |
@node Division of @code{poly_int}s |
| 638 |
@subsection Division of @code{poly_int}s |
| 639 |
|
| 640 |
Division of @code{poly_int}s is possible for certain inputs. The functions |
| 641 |
for division return true if the operation is possible and in most cases |
| 642 |
return the results by pointer. The routines are: |
| 643 |
|
| 644 |
@table @samp |
| 645 |
@item multiple_p (@var{a}, @var{b}) |
| 646 |
@itemx multiple_p (@var{a}, @var{b}, &@var{quotient}) |
| 647 |
Return true if @var{a} is an exact multiple of @var{b}, storing the result |
| 648 |
in @var{quotient} if so. There are overloads for various combinations |
| 649 |
of polynomial and constant @var{a}, @var{b} and @var{quotient}. |
| 650 |
|
| 651 |
@item constant_multiple_p (@var{a}, @var{b}) |
| 652 |
@itemx constant_multiple_p (@var{a}, @var{b}, &@var{quotient}) |
| 653 |
Like @code{multiple_p}, but also test whether the multiple is a |
| 654 |
compile-time constant. |
| 655 |
|
| 656 |
@item can_div_trunc_p (@var{a}, @var{b}, &@var{quotient}) |
| 657 |
@itemx can_div_trunc_p (@var{a}, @var{b}, &@var{quotient}, &@var{remainder}) |
| 658 |
Return true if we can calculate @samp{trunc (@var{a} / @var{b})} at compile |
| 659 |
time, storing the result in @var{quotient} and @var{remainder} if so. |
| 660 |
|
| 661 |
@item can_div_away_from_zero_p (@var{a}, @var{b}, &@var{quotient}) |
| 662 |
Return true if we can calculate @samp{@var{a} / @var{b}} at compile time, |
| 663 |
rounding away from zero. Store the result in @var{quotient} if so. |
| 664 |
|
| 665 |
Note that this is true if and only if @code{can_div_trunc_p} is true. |
| 666 |
The only difference is in the rounding of the result. |
| 667 |
@end table |
| 668 |
|
| 669 |
There is also an asserting form of division: |
| 670 |
|
| 671 |
@table @samp |
| 672 |
@item exact_div (@var{a}, @var{b}) |
| 673 |
Assert that @var{a} is a multiple of @var{b} and return |
| 674 |
@samp{@var{a} / @var{b}}. The result is a @code{poly_int} if @var{a} |
| 675 |
is a @code{poly_int}. |
| 676 |
@end table |
| 677 |
|
| 678 |
@node Other @code{poly_int} arithmetic |
| 679 |
@subsection Other @code{poly_int} arithmetic |
| 680 |
|
| 681 |
There are tentative routines for other operations besides division: |
| 682 |
|
| 683 |
@table @samp |
| 684 |
@item can_ior_p (@var{a}, @var{b}, &@var{result}) |
| 685 |
Return true if we can calculate @samp{@var{a} | @var{b}} at compile time, |
| 686 |
storing the result in @var{result} if so. |
| 687 |
@end table |
| 688 |
|
| 689 |
Also, ANDs with a value @samp{(1 << @var{y}) - 1} or its inverse can be |
| 690 |
treated as alignment operations. @xref{Alignment of @code{poly_int}s}. |
| 691 |
|
| 692 |
In addition, the following miscellaneous routines are available: |
| 693 |
|
| 694 |
@table @samp |
| 695 |
@item coeff_gcd (@var{a}) |
| 696 |
Return the greatest common divisor of all nonzero coefficients in |
| 697 |
@var{a}, or zero if @var{a} is known to be zero. |
| 698 |
|
| 699 |
@item common_multiple (@var{a}, @var{b}) |
| 700 |
Return a value that is a multiple of both @var{a} and @var{b}, where |
| 701 |
one value is a @code{poly_int} and the other is a scalar. The result |
| 702 |
will be the least common multiple for some indeterminate values but |
| 703 |
not necessarily for all. |
| 704 |
|
| 705 |
@item force_common_multiple (@var{a}, @var{b}) |
| 706 |
Return a value that is a multiple of both @code{poly_int} @var{a} and |
| 707 |
@code{poly_int} @var{b}, asserting that such a value exists. The |
| 708 |
result will be the least common multiple for some indeterminate values |
| 709 |
but not necessarily for all. |
| 710 |
|
| 711 |
When using this routine, please add a comment explaining why the |
| 712 |
assertion is known to hold. |
| 713 |
@end table |
| 714 |
|
| 715 |
Please add any other operations that you find to be useful. |
| 716 |
|
| 717 |
@node Alignment of @code{poly_int}s |
| 718 |
@section Alignment of @code{poly_int}s |
| 719 |
|
| 720 |
@code{poly_int} provides various routines for aligning values and for querying |
| 721 |
misalignments. In each case the alignment must be a power of 2. |
| 722 |
|
| 723 |
@table @samp |
| 724 |
@item can_align_p (@var{value}, @var{align}) |
| 725 |
Return true if we can align @var{value} up or down to the nearest multiple |
| 726 |
of @var{align} at compile time. The answer is the same for both directions. |
| 727 |
|
| 728 |
@item can_align_down (@var{value}, @var{align}, &@var{aligned}) |
| 729 |
Return true if @code{can_align_p}; if so, set @var{aligned} to the greatest |
| 730 |
aligned value that is less than or equal to @var{value}. |
| 731 |
|
| 732 |
@item can_align_up (@var{value}, @var{align}, &@var{aligned}) |
| 733 |
Return true if @code{can_align_p}; if so, set @var{aligned} to the lowest |
| 734 |
aligned value that is greater than or equal to @var{value}. |
| 735 |
|
| 736 |
@item known_equal_after_align_down (@var{a}, @var{b}, @var{align}) |
| 737 |
Return true if we can align @var{a} and @var{b} down to the nearest |
| 738 |
@var{align} boundary at compile time and if the two results are equal. |
| 739 |
|
| 740 |
@item known_equal_after_align_up (@var{a}, @var{b}, @var{align}) |
| 741 |
Return true if we can align @var{a} and @var{b} up to the nearest |
| 742 |
@var{align} boundary at compile time and if the two results are equal. |
| 743 |
|
| 744 |
@item aligned_lower_bound (@var{value}, @var{align}) |
| 745 |
Return a result that is no greater than @var{value} and that is aligned |
| 746 |
to @var{align}. The result will the closest aligned value for some |
| 747 |
indeterminate values but not necessarily for all. |
| 748 |
|
| 749 |
For example, suppose we are allocating an object of @var{size} bytes |
| 750 |
in a downward-growing stack whose current limit is given by @var{limit}. |
| 751 |
If the object requires @var{align} bytes of alignment, the new stack |
| 752 |
limit is given by: |
| 753 |
|
| 754 |
@smallexample |
| 755 |
aligned_lower_bound (@var{limit} - @var{size}, @var{align}) |
| 756 |
@end smallexample |
| 757 |
|
| 758 |
@item aligned_upper_bound (@var{value}, @var{align}) |
| 759 |
Likewise return a result that is no less than @var{value} and that is |
| 760 |
aligned to @var{align}. This is the routine that would be used for |
| 761 |
upward-growing stacks in the scenario just described. |
| 762 |
|
| 763 |
@item known_misalignment (@var{value}, @var{align}, &@var{misalign}) |
| 764 |
Return true if we can calculate the misalignment of @var{value} |
| 765 |
with respect to @var{align} at compile time, storing the result in |
| 766 |
@var{misalign} if so. |
| 767 |
|
| 768 |
@item known_alignment (@var{value}) |
| 769 |
Return the minimum alignment that @var{value} is known to have |
| 770 |
(in other words, the largest alignment that can be guaranteed |
| 771 |
whatever the values of the indeterminates turn out to be). |
| 772 |
Return 0 if @var{value} is known to be 0. |
| 773 |
|
| 774 |
@item force_align_down (@var{value}, @var{align}) |
| 775 |
Assert that @var{value} can be aligned down to @var{align} at compile |
| 776 |
time and return the result. When using this routine, please add a |
| 777 |
comment explaining why the assertion is known to hold. |
| 778 |
|
| 779 |
@item force_align_up (@var{value}, @var{align}) |
| 780 |
Likewise, but aligning up. |
| 781 |
|
| 782 |
@item force_align_down_and_div (@var{value}, @var{align}) |
| 783 |
Divide the result of @code{force_align_down} by @var{align}. Again, |
| 784 |
please add a comment explaining why the assertion in @code{force_align_down} |
| 785 |
is known to hold. |
| 786 |
|
| 787 |
@item force_align_up_and_div (@var{value}, @var{align}) |
| 788 |
Likewise for @code{force_align_up}. |
| 789 |
|
| 790 |
@item force_get_misalignment (@var{value}, @var{align}) |
| 791 |
Assert that we can calculate the misalignment of @var{value} with |
| 792 |
respect to @var{align} at compile time and return the misalignment. |
| 793 |
When using this function, please add a comment explaining why |
| 794 |
the assertion is known to hold. |
| 795 |
@end table |
| 796 |
|
| 797 |
@node Computing bounds on @code{poly_int}s |
| 798 |
@section Computing bounds on @code{poly_int}s |
| 799 |
|
| 800 |
@code{poly_int} also provides routines for calculating lower and upper bounds: |
| 801 |
|
| 802 |
@table @samp |
| 803 |
@item constant_lower_bound (@var{a}) |
| 804 |
Assert that @var{a} is nonnegative and return the smallest value it can have. |
| 805 |
|
| 806 |
@item constant_lower_bound_with_limit (@var{a}, @var{b}) |
| 807 |
Return the least value @var{a} can have, given that the context in |
| 808 |
which @var{a} appears guarantees that the answer is no less than @var{b}. |
| 809 |
In other words, the caller is asserting that @var{a} is greater than or |
| 810 |
equal to @var{b} even if @samp{known_ge (@var{a}, @var{b})} doesn't hold. |
| 811 |
|
| 812 |
@item constant_upper_bound_with_limit (@var{a}, @var{b}) |
| 813 |
Return the greatest value @var{a} can have, given that the context in |
| 814 |
which @var{a} appears guarantees that the answer is no greater than @var{b}. |
| 815 |
In other words, the caller is asserting that @var{a} is less than or equal |
| 816 |
to @var{b} even if @samp{known_le (@var{a}, @var{b})} doesn't hold. |
| 817 |
|
| 818 |
@item lower_bound (@var{a}, @var{b}) |
| 819 |
Return a value that is always less than or equal to both @var{a} and @var{b}. |
| 820 |
It will be the greatest such value for some indeterminate values |
| 821 |
but necessarily for all. |
| 822 |
|
| 823 |
@item upper_bound (@var{a}, @var{b}) |
| 824 |
Return a value that is always greater than or equal to both @var{a} and |
| 825 |
@var{b}. It will be the least such value for some indeterminate values |
| 826 |
but necessarily for all. |
| 827 |
@end table |
| 828 |
|
| 829 |
@node Converting @code{poly_int}s |
| 830 |
@section Converting @code{poly_int}s |
| 831 |
|
| 832 |
A @code{poly_int<@var{n}, @var{T}>} can be constructed from up to |
| 833 |
@var{n} individual @var{T} coefficients, with the remaining coefficients |
| 834 |
being implicitly zero. In particular, this means that every |
| 835 |
@code{poly_int<@var{n}, @var{T}>} can be constructed from a single |
| 836 |
scalar @var{T}, or something compatible with @var{T}. |
| 837 |
|
| 838 |
Also, a @code{poly_int<@var{n}, @var{T}>} can be constructed from |
| 839 |
a @code{poly_int<@var{n}, @var{U}>} if @var{T} can be constructed |
| 840 |
from @var{U}. |
| 841 |
|
| 842 |
The following functions provide other forms of conversion, |
| 843 |
or test whether such a conversion would succeed. |
| 844 |
|
| 845 |
@table @samp |
| 846 |
@item @var{value}.is_constant () |
| 847 |
Return true if @code{poly_int} @var{value} is a compile-time constant. |
| 848 |
|
| 849 |
@item @var{value}.is_constant (&@var{c1}) |
| 850 |
Return true if @code{poly_int} @var{value} is a compile-time constant, |
| 851 |
storing it in @var{c1} if so. @var{c1} must be able to hold all |
| 852 |
constant values of @var{value} without loss of precision. |
| 853 |
|
| 854 |
@item @var{value}.to_constant () |
| 855 |
Assert that @var{value} is a compile-time constant and return its value. |
| 856 |
When using this function, please add a comment explaining why the |
| 857 |
condition is known to hold (for example, because an earlier phase |
| 858 |
of analysis rejected non-constants). |
| 859 |
|
| 860 |
@item @var{value}.to_shwi (&@var{p2}) |
| 861 |
Return true if @samp{poly_int<@var{N}, @var{T}>} @var{value} can be |
| 862 |
represented without loss of precision as a |
| 863 |
@samp{poly_int<@var{N}, @code{HOST_WIDE_INT}>}, storing it in that |
| 864 |
form in @var{p2} if so. |
| 865 |
|
| 866 |
@item @var{value}.to_uhwi (&@var{p2}) |
| 867 |
Return true if @samp{poly_int<@var{N}, @var{T}>} @var{value} can be |
| 868 |
represented without loss of precision as a |
| 869 |
@samp{poly_int<@var{N}, @code{unsigned HOST_WIDE_INT}>}, storing it in that |
| 870 |
form in @var{p2} if so. |
| 871 |
|
| 872 |
@item @var{value}.force_shwi () |
| 873 |
Forcibly convert each coefficient of @samp{poly_int<@var{N}, @var{T}>} |
| 874 |
@var{value} to @code{HOST_WIDE_INT}, truncating any that are out of range. |
| 875 |
Return the result as a @samp{poly_int<@var{N}, @code{HOST_WIDE_INT}>}. |
| 876 |
|
| 877 |
@item @var{value}.force_uhwi () |
| 878 |
Forcibly convert each coefficient of @samp{poly_int<@var{N}, @var{T}>} |
| 879 |
@var{value} to @code{unsigned HOST_WIDE_INT}, truncating any that are |
| 880 |
out of range. Return the result as a |
| 881 |
@samp{poly_int<@var{N}, @code{unsigned HOST_WIDE_INT}>}. |
| 882 |
|
| 883 |
@item wi::shwi (@var{value}, @var{precision}) |
| 884 |
Return a @code{poly_int} with the same value as @var{value}, but with |
| 885 |
the coefficients converted from @code{HOST_WIDE_INT} to @code{wide_int}. |
| 886 |
@var{precision} specifies the precision of the @code{wide_int} cofficients; |
| 887 |
if this is wider than a @code{HOST_WIDE_INT}, the coefficients of |
| 888 |
@var{value} will be sign-extended to fit. |
| 889 |
|
| 890 |
@item wi::uhwi (@var{value}, @var{precision}) |
| 891 |
Like @code{wi::shwi}, except that @var{value} has coefficients of |
| 892 |
type @code{unsigned HOST_WIDE_INT}. If @var{precision} is wider than |
| 893 |
a @code{HOST_WIDE_INT}, the coefficients of @var{value} will be |
| 894 |
zero-extended to fit. |
| 895 |
|
| 896 |
@item wi::sext (@var{value}, @var{precision}) |
| 897 |
Return a @code{poly_int} of the same type as @var{value}, sign-extending |
| 898 |
every coefficient from the low @var{precision} bits. This in effect |
| 899 |
applies @code{wi::sext} to each coefficient individually. |
| 900 |
|
| 901 |
@item wi::zext (@var{value}, @var{precision}) |
| 902 |
Like @code{wi::sext}, but for zero extension. |
| 903 |
|
| 904 |
@item poly_wide_int::from (@var{value}, @var{precision}, @var{sign}) |
| 905 |
Convert @var{value} to a @code{poly_wide_int} in which each coefficient |
| 906 |
has @var{precision} bits. Extend the coefficients according to |
| 907 |
@var{sign} if the coefficients have fewer bits. |
| 908 |
|
| 909 |
@item poly_offset_int::from (@var{value}, @var{sign}) |
| 910 |
Convert @var{value} to a @code{poly_offset_int}, extending its coefficients |
| 911 |
according to @var{sign} if they have fewer bits than @code{offset_int}. |
| 912 |
|
| 913 |
@item poly_widest_int::from (@var{value}, @var{sign}) |
| 914 |
Convert @var{value} to a @code{poly_widest_int}, extending its coefficients |
| 915 |
according to @var{sign} if they have fewer bits than @code{widest_int}. |
| 916 |
@end table |
| 917 |
|
| 918 |
@node Miscellaneous @code{poly_int} routines |
| 919 |
@section Miscellaneous @code{poly_int} routines |
| 920 |
|
| 921 |
@table @samp |
| 922 |
@item print_dec (@var{value}, @var{file}, @var{sign}) |
| 923 |
@itemx print_dec (@var{value}, @var{file}) |
| 924 |
Print @var{value} to @var{file} as a decimal value, interpreting |
| 925 |
the coefficients according to @var{sign}. The final argument is |
| 926 |
optional if @var{value} has an inherent sign; for example, |
| 927 |
@code{poly_int64} values print as signed by default and |
| 928 |
@code{poly_uint64} values print as unsigned by default. |
| 929 |
|
| 930 |
This is a simply a @code{poly_int} version of a wide-int routine. |
| 931 |
@end table |
| 932 |
|
| 933 |
@node Guidelines for using @code{poly_int} |
| 934 |
@section Guidelines for using @code{poly_int} |
| 935 |
|
| 936 |
One of the main design goals of @code{poly_int} was to make it easy |
| 937 |
to write target-independent code that handles variable-sized registers |
| 938 |
even when the current target has fixed-sized registers. There are two |
| 939 |
aspects to this: |
| 940 |
|
| 941 |
@itemize |
| 942 |
@item |
| 943 |
The set of @code{poly_int} operations should be complete enough that |
| 944 |
the question in most cases becomes ``Can we do this operation on these |
| 945 |
particular @code{poly_int} values? If not, bail out'' rather than |
| 946 |
``Are these @code{poly_int} values constant? If so, do the operation, |
| 947 |
otherwise bail out''. |
| 948 |
|
| 949 |
@item |
| 950 |
If target-independent code compiles and runs correctly on a target |
| 951 |
with one value of @code{NUM_POLY_INT_COEFFS}, and if the code does not |
| 952 |
use asserting functions like @code{to_constant}, it is reasonable to |
| 953 |
assume that the code also works on targets with other values of |
| 954 |
@code{NUM_POLY_INT_COEFFS}. There is no need to check this during |
| 955 |
everyday development. |
| 956 |
@end itemize |
| 957 |
|
| 958 |
So the general principle is: if target-independent code is dealing |
| 959 |
with a @code{poly_int} value, it is better to operate on it as a |
| 960 |
@code{poly_int} if at all possible, choosing conservatively-correct |
| 961 |
behavior if a particular operation fails. For example, the following |
| 962 |
code handles an index @code{pos} into a sequence of vectors that each |
| 963 |
have @code{nunits} elements: |
| 964 |
|
| 965 |
@smallexample |
| 966 |
/* Calculate which vector contains the result, and which lane of |
| 967 |
that vector we need. */ |
| 968 |
if (!can_div_trunc_p (pos, nunits, &vec_entry, &vec_index)) |
| 969 |
@{ |
| 970 |
if (dump_enabled_p ()) |
| 971 |
dump_printf_loc (MSG_MISSED_OPTIMIZATION, vect_location, |
| 972 |
"Cannot determine which vector holds the" |
| 973 |
" final result.\n"); |
| 974 |
return false; |
| 975 |
@} |
| 976 |
@end smallexample |
| 977 |
|
| 978 |
However, there are some contexts in which operating on a |
| 979 |
@code{poly_int} is not possible or does not make sense. One example |
| 980 |
is when handling static initializers, since no current target supports |
| 981 |
the concept of a variable-length static initializer. In these |
| 982 |
situations, a reasonable fallback is: |
| 983 |
|
| 984 |
@smallexample |
| 985 |
if (@var{poly_value}.is_constant (&@var{const_value})) |
| 986 |
@{ |
| 987 |
@dots{} |
| 988 |
/* Operate on @var{const_value}. */ |
| 989 |
@dots{} |
| 990 |
@} |
| 991 |
else |
| 992 |
@{ |
| 993 |
@dots{} |
| 994 |
/* Conservatively correct fallback. */ |
| 995 |
@dots{} |
| 996 |
@} |
| 997 |
@end smallexample |
| 998 |
|
| 999 |
@code{poly_int} also provides some asserting functions like |
| 1000 |
@code{to_constant}. Please only use these functions if there is a |
| 1001 |
good theoretical reason to believe that the assertion cannot fire. |
| 1002 |
For example, if some work is divided into an analysis phase and an |
| 1003 |
implementation phase, the analysis phase might reject inputs that are |
| 1004 |
not @code{is_constant}, in which case the implementation phase can |
| 1005 |
reasonably use @code{to_constant} on the remaining inputs. The assertions |
| 1006 |
should not be used to discover whether a condition ever occurs ``in the |
| 1007 |
field''; in other words, they should not be used to restrict code to |
| 1008 |
constants at first, with the intention of only implementing a |
| 1009 |
@code{poly_int} version if a user hits the assertion. |
| 1010 |
|
| 1011 |
If a particular asserting function like @code{to_constant} is needed |
| 1012 |
more than once for the same reason, it is probably worth adding a |
| 1013 |
helper function or macro for that situation, so that the justification |
| 1014 |
only needs to be given once. For example: |
| 1015 |
|
| 1016 |
@smallexample |
| 1017 |
/* Return the size of an element in a vector of size SIZE, given that |
| 1018 |
the vector has NELTS elements. The return value is in the same units |
| 1019 |
as SIZE (either bits or bytes). |
| 1020 |
|
| 1021 |
to_constant () is safe in this situation because vector elements are |
| 1022 |
always constant-sized scalars. */ |
| 1023 |
#define vector_element_size(SIZE, NELTS) \ |
| 1024 |
(exact_div (SIZE, NELTS).to_constant ()) |
| 1025 |
@end smallexample |
| 1026 |
|
| 1027 |
Target-specific code in @file{config/@var{cpu}} only needs to handle |
| 1028 |
non-constant @code{poly_int}s if @code{NUM_POLY_INT_COEFFS} is greater |
| 1029 |
than one. For other targets, @code{poly_int} degenerates to a compile-time |
| 1030 |
constant and is often interchangable with a normal scalar integer. |
| 1031 |
There are two main exceptions: |
| 1032 |
|
| 1033 |
@itemize |
| 1034 |
@item |
| 1035 |
Sometimes an explicit cast to an integer type might be needed, such as to |
| 1036 |
resolve ambiguities in a @code{?:} expression, or when passing values |
| 1037 |
through @code{...} to things like print functions. |
| 1038 |
|
| 1039 |
@item |
| 1040 |
Target macros are included in target-independent code and so do not |
| 1041 |
have access to the implicit conversion to a scalar integer. |
| 1042 |
If this becomes a problem for a particular target macro, the |
| 1043 |
possible solutions, in order of preference, are: |
| 1044 |
|
| 1045 |
@itemize |
| 1046 |
@item |
| 1047 |
Convert the target macro to a target hook (for all targets). |
| 1048 |
|
| 1049 |
@item |
| 1050 |
Put the target's implementation of the target macro in its |
| 1051 |
@file{@var{cpu}.c} file and call it from the target macro in the |
| 1052 |
@file{@var{cpu}.h} file. |
| 1053 |
|
| 1054 |
@item |
| 1055 |
Add @code{to_constant ()} calls where necessary. The previous option |
| 1056 |
is preferable because it will help with any future conversion of the |
| 1057 |
macro to a hook. |
| 1058 |
@end itemize |
| 1059 |
@end itemize |
| 1060 |
|