diff --git a/llvm/docs/GlobalISel.rst b/llvm/docs/GlobalISel.rst --- a/llvm/docs/GlobalISel.rst +++ b/llvm/docs/GlobalISel.rst @@ -396,6 +396,90 @@ should be (you could imagine disagreements on whether a ``<2 x s8>`` operation should be scalarized or extended to ``<8 x s8>``). +.. _min-legalizerinfo: + +Minimum Rule Set +^^^^^^^^^^^^^^^^ + +GlobalISel's legalizer has a great deal of flexibility in how a given target +shapes the gMIR that the rest of the backend must handle. However, there are +a small number of requirements that all targets must meet. + +Before discussing the minimum requirements, we'll need some terminology. +Each target has a set of types which is the union of all possible types produced +by at least one legal instruction. We'll call this the Producer Type Set. +Similarly, each target has a set of types which is the union of all possible +types consumed by at least one legal instruction. We'll call this the Consumer +Type Set. Both sets are often identical but there's no guarantee of that. For +example, it's not uncommon to be unable to consume s64 but still be able to +produce it for a few specific instructions. + +Minimum Rules For Scalars +""""""""""""""""""""""""" + +There are three operations produced by the IRTranslator that can increase the +size of a scalar: +* G_ANYEXT +* G_SEXT +* G_ZEXT +* G_FPEXT +of these, the only one with mandatory legality is G_ANYEXT. It's required that +G_ANYEXT is legal for all inputs from the producer type set and all larger +outputs from the consumer type set. The lack of any defined value for the +additional bits usually makes this trivial and this ensures that we can always +lower other type conversions using G_ANYEXT and some operations on the larger +value. For example, G_SEXT can always lower to: + %1 = G_ANYEXT %0 + %2 = G_CONSTANT ... + %3 = G_SHL %1, %2 + %4 = G_ASHR %3, %2 +and the G_CONSTANT/G_SHL/G_ASHR can further lower to other operations or target +instructions. Similarly, G_FPEXT has no legality requirement since it can lower +to a G_ANYEXT followed by a target instruction. + +G_TRUNC has the same requirements as G_ANYEXT but with the input/output types +reversed. + +G_MERGE_VALUES and G_UNMERGE_VALUES do not have legality requirements since the +former can lower to G_ANYEXT and some other legalizable instructions, while the +latter can lower to some legalizable instructions followed by G_TRUNC. + +Minimum Legality For Vectors +"""""""""""""""""""""""""""" + +Within the vector types, there aren't any defined conversions in LLVM-IR as +vectors are often converted by reinterpreting the bits or by decomposing the +vector and reconstituting it as a different type. As such, G_BITCAST is the +only operation to account for. We don't require that it's legal because it +can be lowered to COPY (or to nothing using replaceAllUses()). + +There are no legality requirements for G_BUILD_VECTOR, or G_BUILD_VECTOR_TRUNC +since these can be lowered to target instructions which are legal by definition. +The same reasoning also allows G_UNMERGE_VALUES to lack legality requirements +for vector inputs. + +Minimum Legality for Pointers +""""""""""""""""""""""""""""" + +There are no minimum rules for pointers since G_INTTOPTR and G_PTRTOINT can +be lowered to COPY (or to nothing using replaceAllUses()) by the legalizer. + +Minimum Legality For Operations +""""""""""""""""""""""""""""""" + +The rules for G_ANYEXT, G_MERGE_VALUES, G_BITCAST, G_BUILD_VECTOR, +G_BUILD_VECTOR_TRUNC, G_CONCAT_VECTORS, G_UNMERGE_VALUES, G_PTRTOINT, and +G_INTTOPTR have already been noted above. In addition to those, the following +operations have requirements: +* At least one G_IMPLICIT_DEF must be legal. This is usually trivial as it + requires no code to be selected. +* G_PHI must be legal for all types in the producer and consumer typesets. This + is usually trivial as it requires no code to be selected. +* At least one G_FRAME_INDEX must be legal +* At least one G_BLOCK_ADDR must be legal + +There are many other operations you'd expect to have legality requirements but +they can be lowered to target instructions which are legal by definition. .. _regbankselect: