llvm.org GIT mirror llvm / 41f17d5
[globalisel] Update the legalizer documentation Summary: * The getActionDefinitionsBuilder() is now documented. * Includes descriptions of the various actions (legal*, widenScalar*, lower*, etc). * Includes descriptions of the various predicates (*If, *For, *ForCartesianProduct, etc.) * Includes the rule-order details * Removed the out-of-date prohibition on non-power-of-2 types. * Removed the Vector types section since it was incorrect and vectors follow the same ruleset as scalars. They're only special in the sense that more of the actions and predicates are meaningful for them (e.g. moreElements). * Clarified the position on context sensitive legality (which is not permitted) and contrasted this with context sensitive legalization (which is permitted). Reviewers: bogner, aditya_nandakumar, volkan, aemerson, paquette, arsenm Reviewed By: paquette Subscribers: wdng, rovka, kristof.beyls, jfb, Petar.Avramovic, llvm-commits Tags: #llvm Differential Revision: https://reviews.llvm.org/D61273 git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@359705 91177308-0d34-0410-b5e6-96231b3b80d8 Daniel Sanders 1 year, 6 months ago
1 changed file(s) with 201 addition(s) and 61 deletion(s). Raw diff Collapse all Expand all
317317 If any remain, they are expected to always be selectable, using loads and stores
318318 if necessary.
320 The legality of an instruction may only depend on the instruction itself and
321 must not depend on any context in which the instruction is used. However, after
322 deciding that an instruction is not legal, using the context of the instruction
323 to decide how to legalize the instruction is permitted. As an example, if we
324 have a ``G_FOO`` instruction of the form::
326 %1:_(s32) = G_CONSTANT i32 1
327 %2:_(s32) = G_FOO %0:_(s32), %1:_(s32)
329 it's impossible to say that G_FOO is legal iff %1 is a ``G_CONSTANT`` with
330 value ``1``. However, the following::
332 %2:_(s32) = G_FOO %0:_(s32), i32 1
334 can say that it's legal iff operand 2 is an immediate with value ``1`` because
335 that information is entirely contained within the single instruction.
320337 .. _api-legalizerinfo:
322339 API: LegalizerInfo
323340 ^^^^^^^^^^^^^^^^^^
325 Currently the API is broadly similar to SelectionDAG/TargetLowering, but
326 extended in two ways:
328 * The set of available actions is wider, avoiding the currently very
329 overloaded ``Expand`` (which can cover everything from libcalls to
330 scalarization depending on the node's opcode).
332 * Since there's no separate type legalization, independently varying
333 types on an instruction can have independent actions. For example a
334 ``G_ICMP`` has 2 independent types: the result and the inputs; we need
335 to be able to say that comparing 2 s32s is OK, but the s1 result
336 must be dealt with in another way.
338 As such, the primary key when deciding what to do is the ``InstrAspect``,
339 essentially a tuple consisting of ``(Opcode, TypeIdx, Type)`` and mapping to a
340 suggested course of action.
342 An example use might be:
344 .. code-block:: c++
346 // The CPU can't deal with an s1 result, do something about it.
347 setAction({G_ICMP, 0, s1}, WidenScalar);
348 // An s32 input (the second type) is fine though.
349 setAction({G_ICMP, 1, s32}, Legal);
342 The recommended [#legalizer-legacy-footnote]_ API looks like this::
344 getActionDefinitionsBuilder({G_ADD, G_SUB, G_MUL, G_AND, G_OR, G_XOR, G_SHL})
345 .legalFor({s32, s64, v2s32, v4s32, v2s64})
346 .clampScalar(0, s32, s64)
347 .widenScalarToNextPow2(0)
348 .clampNumElements(0, v2s32, v4s32)
349 .clampNumElements(0, v2s64, v2s64)
350 .moreElementsToNextPow2(0);
352 and describes a set of rules by which we can either declare an instruction legal
353 or decide which action to take to make it more legal.
355 At the core of this ruleset is the ``LegalityQuery`` which describes the
356 instruction. We use a description rather than the instruction to both allow other
357 passes to determine legality without having to create an instruction and also to
358 limit the information available to the predicates to that which is safe to rely
359 on. Currently, the information available to the predicates that determine
360 legality contains:
362 * The opcode for the instruction
364 * The type of each type index (see ``type0``, ``type1``, etc.)
366 * The size in bytes and atomic ordering for each MachineMemOperand
368 Rule Processing and Declaring Rules
369 """""""""""""""""""""""""""""""""""
371 The ``getActionDefinitionsBuilder`` function generates a ruleset for the given
372 opcode(s) that rules can be added to. If multiple opcodes are given, they are
373 all permanently bound to the same ruleset. The rules in a ruleset are executed
374 from top to bottom and will start again from the top if an instruction is
375 legalized as a result of the rules. If the ruleset is exhausted without
376 satisfying any rule, then it is considered unsupported.
378 When it doesn't declare the instruction legal, each pass over the rules may
379 request that one type changes to another type. Sometimes this can cause multiple
380 types to change but we avoid this as much as possible as making multiple changes
381 can make it difficult to avoid infinite loops where, for example, narrowing one
382 type causes another to be too small and widening that type causes the first one
383 to be too big.
385 In general, it's advisable to declare instructions legal as close to the top of
386 the rule as possible and to place any expensive rules as low as possible. This
387 helps with performance as testing for legality happens more often than
388 legalization and legalization can require multiple passes over the rules.
390 As a concrete example, consider the rule::
392 getActionDefinitionsBuilder({G_ADD, G_SUB, G_MUL, G_AND, G_OR, G_XOR, G_SHL})
393 .legalFor({s32, s64, v2s32, v4s32, v2s64})
394 .clampScalar(0, s32, s64)
395 .widenScalarToNextPow2(0);
397 and the instruction::
399 %2:_(s7) = G_ADD %0:_(s7), %1:_(s7)
401 this doesn't meet the predicate for the :ref:`.legalFor() ` as ``s7``
402 is not one of the listed types so it falls through to the
403 :ref:`.clampScalar() `. It does meet the predicate for this rule
404 as the type is smaller than the ``s32`` and this rule instructs the legalizer
405 to change type 0 to ``s32``. It then restarts from the top. This time it does
406 satisfy ``.legalFor()`` and the resulting output is::
408 %3:_(s32) = G_ANYEXT %0:_(s7)
409 %4:_(s32) = G_ANYEXT %1:_(s7)
410 %5:_(s32) = G_ADD %3:_(s32), %4:_(s32)
411 %2:_(s7) = G_TRUNC %5:_(s32)
413 where the ``G_ADD`` is legal and the other instructions are scheduled for
414 processing by the legalizer.
416 Rule Actions
417 """"""""""""
419 There are various rule factories that append rules to a ruleset but they have a
420 few actions in common:
422 .. _legalfor:
424 * ``legalIf()``, ``legalFor()``, etc. declare an instruction to be legal if the
425 predicate is satisfied.
427 * ``narrowScalarIf()``, ``narrowScalarFor()``, etc. declare an instruction to be illegal
428 if the predicate is satisfied and indicates that narrowing the scalars in one
429 of the types to a specific type would make it more legal. This action supports
430 both scalars and vectors.
432 * ``widenScalarIf()``, ``widenScalarFor()``, etc. declare an instruction to be illegal
433 if the predicate is satisfied and indicates that widening the scalars in one
434 of the types to a specific type would make it more legal. This action supports
435 both scalars and vectors.
437 * ``fewerElementsIf()``, ``fewerElementsFor()``, etc. declare an instruction to be
438 illegal if the predicate is satisfied and indicates reducing the number of
439 vector elements in one of the types to a specific type would make it more
440 legal. This action supports vectors.
442 * ``moreElementsIf()``, ``moreElementsFor()``, etc. declare an instruction to be illegal
443 if the predicate is satisfied and indicates increasing the number of vector
444 elements in one of the types to a specific type would make it more legal.
445 This action supports vectors.
447 * ``lowerIf()``, ``lowerFor()``, etc. declare an instruction to be illegal if the
448 predicate is satisfied and indicates that replacing it with equivalent
449 instruction(s) would make it more legal. Support for this action differs for
450 each opcode.
452 * ``libcallIf()``, ``libcallFor()``, etc. declare an instruction to be illegal if the
453 predicate is satisfied and indicates that replacing it with a libcall would
454 make it more legal. Support for this action differs for
455 each opcode.
457 * ``customIf()``, ``customFor()``, etc. declare an instruction to be illegal if the
458 predicate is satisfied and indicates that the backend developer will supply
459 a means of making it more legal.
461 * ``unsupportedIf()``, ``unsupportedFor()``, etc. declare an instruction to be illegal
462 if the predicate is satisfied and indicates that there is no way to make it
463 legal and the compiler should fail.
465 * ``fallback()`` falls back on an older API and should only be used while porting
466 existing code from that API.
468 Rule Predicates
469 """""""""""""""
471 The rule factories also have predicates in common:
473 * ``legal()``, ``lower()``, etc. are always satisfied.
475 * ``legalIf()``, ``narrowScalarIf()``, etc. are satisfied if the user-supplied
476 ``LegalityPredicate`` function returns true. This predicate has access to the
477 information in the ``LegalityQuery`` to make its decision.
478 User-supplied predicates can also be combined using ``all(P0, P1, ...)``.
480 * ``legalFor()``, ``narrowScalarFor()``, etc. are satisfied if the type matches one in
481 a given set of types. For example ``.legalFor({s16, s32})`` declares the
482 instruction legal if type 0 is either s16 or s32. Additional versions for two
483 and three type indices are generally available. For these, all the type
484 indices considered together must match all the types in one of the tuples. So
485 ``.legalFor({{s16, s32}, {s32, s64}})`` will only accept ``{s16, s32}``, or
486 ``{s32, s64}`` but will not accept ``{s16, s64}``.
488 * ``legalForTypesWithMemSize()``, ``narrowScalarForTypesWithMemSize()``, etc. are
489 similar to ``legalFor()``, ``narrowScalarFor()``, etc. but additionally require a
490 MachineMemOperand to have a given size in each tuple.
492 * ``legalForCartesianProduct()``, ``narrowScalarForCartesianProduct()``, etc. are
493 satisfied if each type index matches one element in each of the independent
494 sets. So ``.legalForCartesianProduct({s16, s32}, {s32, s64})`` will accept
495 ``{s16, s32}``, ``{s16, s64}``, ``{s32, s32}``, and ``{s32, s64}``.
497 Composite Rules
498 """""""""""""""
500 There are some composite rules for common situations built out of the above facilities:
502 * ``widenScalarToNextPow2()`` is like ``widenScalarIf()`` but is satisfied iff the type
503 size in bits is not a power of 2 and selects a target type that is the next
504 largest power of 2.
506 .. _clampscalar:
508 * ``minScalar()`` is like ``widenScalarIf()`` but is satisfied iff the type
509 size in bits is smaller than the given minimum and selects the minimum as the
510 target type. Similarly, there is also a ``maxScalar()`` for the maximum and a
511 ``clampScalar()`` to do both at once.
513 * ``minScalarSameAs()`` is like ``minScalar()`` but the minimum is taken from another
514 type index.
516 * ``moreElementsToNextMultiple()`` is like ``moreElementsToNextPow2()`` but is based on
517 multiples of X rather than powers of 2.
519 Other Information
520 """""""""""""""""
352522 ``TODO``:
353523 An alternative worth investigating is to generalize the API to represent
360530 Expanding that to describe legalization actions is a much larger but
361531 potentially useful project.
363 .. _milegalizer-non-power-of-2:
365 Non-power of 2 types
366 ^^^^^^^^^^^^^^^^^^^^
368 ``TODO``:
369 Types which have a size that isn't a power of 2 aren't currently supported.
370 The setAction API will probably require changes to support them.
371 Even notionally explicitly specified operations only make suggestions
372 like "Widen" or "Narrow". The eventual type is still unspecified and a
373 search is performed by repeated doubling/halving of the type's
374 size.
375 This is incorrect for types that aren't a power of 2. It's reasonable to
376 expect we could construct an efficient set of side-tables for more general
377 lookups though, encoding a map from the integers (i.e. the size of the current
378 type) to types (the legal size).
380 .. _milegalizer-vector:
382 Vector types
383 ^^^^^^^^^^^^
385 Vectors first get their element type legalized: ```` becomes
386 ```` such that at least one operation is legal with ``sC``.
388 This is currently specified by the function ``setScalarInVectorAction``, called
389 for example as:
391 setScalarInVectorAction(G_ICMP, s1, WidenScalar);
393 Next the number of elements is chosen so that the entire operation is
394 legal. This aspect is not controllable at the moment, but probably
395 should be (you could imagine disagreements on whether a ``<2 x s8>``
396 operation should be scalarized or extended to ``<8 x s8>``).
533 .. rubric:: Footnotes
535 .. [#legalizer-legacy-footnote] An API is broadly similar to
536 SelectionDAG/TargetLowering is available but is not recommended as a more
537 powerful API is available.
399539 .. _regbankselect: