1Known Bits Analysis 2=================== 3 4The Known Bits Analysis pass makes information about the known values of bits 5available to other passes to enable transformations like those in the examples 6below. The information is lazily computed so you should only pay for what you 7use. 8 9Examples 10-------- 11 12A simple example is that transforming:: 13 14 a + 1 15 16into:: 17 18 a | 1 19 20is only valid when the addition doesn't carry. In other words it's only valid 21if ``a & 1`` is zero. 22 23Another 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 32We can use the constants and the definition of ``G_AND`` to determine the known 33bits: 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 43and 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 51Note that ``%4`` still has the same known bits as before the transformation. 52Many transformations share this property. The main exception being when the 53transform causes undefined bits to become defined to either zero, one, or 54defined but unknown. 55 56Usage 57----- 58 59To use Known Bits Analysis in a pass, first include the header and register the 60dependency 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 72and 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 83Then 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 99There are many more API's beyond ``getKnownBits()``. See the `API reference 100<https://llvm.org/doxygen>`_ for more information 101