|
131
|
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
|
|
145
|
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
|
|
131
|
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
|
