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.
319319
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::
325
326 %1:_(s32) = G_CONSTANT i32 1
327 %2:_(s32) = G_FOO %0:_(s32), %1:_(s32)
328
329 it's impossible to say that G_FOO is legal iff %1 is a ``G_CONSTANT`` with
330 value ``1``. However, the following::
331
332 %2:_(s32) = G_FOO %0:_(s32), i32 1
333
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.
336
320337 .. _api-legalizerinfo:
321338
322339 API: LegalizerInfo
323340 ^^^^^^^^^^^^^^^^^^
324341
325 Currently the API is broadly similar to SelectionDAG/TargetLowering, but
326 extended in two ways:
327
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).
331
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.
337
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.
341
342 An example use might be:
343
344 .. code-block:: c++
345
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);
350
342 The recommended [#legalizer-legacy-footnote]_ API looks like this::
343
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);
351
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.
354
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:
361
362 * The opcode for the instruction
363
364 * The type of each type index (see ``type0``, ``type1``, etc.)
365
366 * The size in bytes and atomic ordering for each MachineMemOperand
367
368 Rule Processing and Declaring Rules
369 """""""""""""""""""""""""""""""""""
370
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.
377
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.
384
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.
389
390 As a concrete example, consider the rule::
391
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);
396
397 and the instruction::
398
399 %2:_(s7) = G_ADD %0:_(s7), %1:_(s7)
400
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::
407
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)
412
413 where the ``G_ADD`` is legal and the other instructions are scheduled for
414 processing by the legalizer.
415
416 Rule Actions
417 """"""""""""
418
419 There are various rule factories that append rules to a ruleset but they have a
420 few actions in common:
421
422 .. _legalfor:
423
424 * ``legalIf()``, ``legalFor()``, etc. declare an instruction to be legal if the
425 predicate is satisfied.
426
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.
431
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.
436
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.
441
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.
446
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.
451
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.
456
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.
460
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.
464
465 * ``fallback()`` falls back on an older API and should only be used while porting
466 existing code from that API.
467
468 Rule Predicates
469 """""""""""""""
470
471 The rule factories also have predicates in common:
472
473 * ``legal()``, ``lower()``, etc. are always satisfied.
474
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, ...)``.
479
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}``.
487
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.
491
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}``.
496
497 Composite Rules
498 """""""""""""""
499
500 There are some composite rules for common situations built out of the above facilities:
501
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.
505
506 .. _clampscalar:
507
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.
512
513 * ``minScalarSameAs()`` is like ``minScalar()`` but the minimum is taken from another
514 type index.
515
516 * ``moreElementsToNextMultiple()`` is like ``moreElementsToNextPow2()`` but is based on
517 multiples of X rather than powers of 2.
518
519 Other Information
520 """""""""""""""""
351521
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.
362532
363 .. _milegalizer-non-power-of-2:
364
365 Non-power of 2 types
366 ^^^^^^^^^^^^^^^^^^^^
367
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).
379
380 .. _milegalizer-vector:
381
382 Vector types
383 ^^^^^^^^^^^^
384
385 Vectors first get their element type legalized: ```` becomes
386 ```` such that at least one operation is legal with ``sC``.
387
388 This is currently specified by the function ``setScalarInVectorAction``, called
389 for example as:
390
391 setScalarInVectorAction(G_ICMP, s1, WidenScalar);
392
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>``).
397
533 .. rubric:: Footnotes
534
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.
398538
399539 .. _regbankselect:
400540