llvm/docs/GlobalISel/KnownBits.rst

   1 Known Bits Analysis
   2 ===================
   3
   4 The Known Bits Analysis pass makes information about the known values of bits
   5 available to other passes to enable transformations like those in the examples
   6 below. The information is lazily computed so you should only pay for what you
   7 use.
   8
   9 Examples
  10 --------
  11
  12 A simple example is that transforming::
  13
  14   a + 1
  15
  16 into::
  17
  18   a | 1
  19
  20 is only valid when the addition doesn't carry. In other words it's only valid
  21 if ``a & 1`` is zero.
  22
  23 Another example is:
  24
  25 .. code-block:: none
  26
  27   %1:(s32) = G_CONSTANT i32 0xFF0
  28   %2:(s32) = G_AND %0, %1
  29   %3:(s32) = G_CONSTANT i32 0x0FF
  30   %4:(s32) = G_AND %2, %3
  31
  32 We can use the constants and the definition of ``G_AND`` to determine the known
  33 bits:
  34
  35 .. code-block:: none
  36
  37                                    ; %0 = 0x????????
  38   %1:(s32) = G_CONSTANT i32 0xFF0  ; %1 = 0x00000FF0
  39   %2:(s32) = G_AND %0, %1          ; %2 = 0x00000??0
  40   %3:(s32) = G_CONSTANT i32 0x0FF  ; %3 = 0x000000FF
  41   %4:(s32) = G_AND %2, %3          ; %4 = 0x000000?0
  42
  43 and then use this to simplify the expression:
  44
  45 .. code-block:: none
  46
  47                                    ; %0 = 0x????????
  48   %5:(s32) = G_CONSTANT i32 0x0F0  ; %5 = 0x00000FF0
  49   %4:(s32) = G_AND %0, %5          ; %4 = 0x000000?0
  50
  51 Note that ``%4`` still has the same known bits as before the transformation.
  52 Many transformations share this property. The main exception being when the
  53 transform causes undefined bits to become defined to either zero, one, or
  54 defined but unknown.
  55
  56 Usage
  57 -----
  58
  59 To use Known Bits Analysis in a pass, first include the header and register the
  60 dependency with ``INITIALIZE_PASS_DEPENDENCY``.
  61
  62 .. code-block:: c++
  63
  64   #include "llvm/CodeGen/GlobalISel/GISelKnownBits.h"
  65
  66   ...
  67
  68   INITIALIZE_PASS_BEGIN(...)
  69   INITIALIZE_PASS_DEPENDENCY(GISelKnownBitsAnalysis)
  70   INITIALIZE_PASS_END(...)
  71
  72 and require the pass in ``getAnalysisUsage``.
  73
  74 .. code-block:: c++
  75
  76   void MyPass::getAnalysisUsage(AnalysisUsage &AU) const {
  77     AU.addRequired<GISelKnownBitsAnalysis>();
  78     // Optional: If your pass preserves known bits analysis (many do) then
  79     //           indicate that it's preserved for re-use by another pass here.
  80     AU.addPreserved<GISelKnownBitsAnalysis>();
  81   }
  82
  83 Then it's just a matter of fetching the analysis and using it:
  84
  85 .. code-block:: c++
  86
  87   bool MyPass::runOnMachineFunction(MachineFunction &MF) {
  88     ...
  89     GISelKnownBits &KB = getAnalysis<GISelKnownBitsAnalysis>().get(MF);
  90     ...
  91     MachineInstr *MI = ...;
  92     KnownBits Known = KB->getKnownBits(MI->getOperand(0).getReg());
  93     if (Known.Zeros & 1) {
  94       // Bit 0 is known to be zero
  95     }
  96     ...
  97   }
  98
  99 There are many more API's beyond ``getKnownBits()``. See the `API reference
 100 <https://llvm.org/doxygen>`_ for more information