1 /* 2 * Copyright © 2016 Intel Corporation 3 * 4 * Permission is hereby granted, free of charge, to any person obtaining a 5 * copy of this software and associated documentation files (the "Software"), 6 * to deal in the Software without restriction, including without limitation 7 * the rights to use, copy, modify, merge, publish, distribute, sublicense, 8 * and/or sell copies of the Software, and to permit persons to whom the 9 * Software is furnished to do so, subject to the following conditions: 10 * 11 * The above copyright notice and this permission notice (including the next 12 * paragraph) shall be included in all copies or substantial portions of the 13 * Software. 14 * 15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 18 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 20 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 21 * IN THE SOFTWARE. 22 */ 23 24 #pragma once 25 26 #include "nir.h" 27 28 /** A helper for placing phi nodes in a NIR shader 29 * 30 * Basic usage goes something like this: 31 * 32 * each variable, var, has: 33 * a bitset var.defs of blocks where the variable is defined 34 * a struct nir_phi_builder_value *pb_val 35 * 36 * // initialize bitsets 37 * foreach block: 38 * foreach def of variable var: 39 * var.defs[def.block] = true; 40 * 41 * // initialize phi builder 42 * pb = nir_phi_builder_create() 43 * foreach var: 44 * var.pb_val = nir_phi_builder_add_value(pb, var.defs) 45 * 46 * // Visit each block. This needs to visit dominators first; 47 * // nir_foreach_block() will be ok. 48 * 49 * foreach block: 50 * foreach instruction: 51 * foreach use of variable var: 52 * replace use with nir_phi_builder_get_block_def(var.pb_val) 53 * foreach def of variable var: 54 * create ssa def, register with 55 * nir_phi_builder_set_block_def(var.pb_val) 56 * 57 * nir_phi_builder_finish(pb) 58 */ 59 struct nir_phi_builder; 60 61 struct nir_phi_builder_value; 62 63 /* Create a new phi builder. 64 * 65 * While this is fairly cheap, it does allocate some memory and walk the list 66 * of blocks so it's recommended that you only call it once and use it to 67 * build phis for several values. 68 */ 69 struct nir_phi_builder *nir_phi_builder_create(nir_function_impl *impl); 70 71 /* Register a value with the builder. 72 * 73 * The 'defs' parameter specifies a bitset of blocks in which the given value 74 * is defined. This is used to determine where to place the phi nodes. 75 */ 76 struct nir_phi_builder_value * 77 nir_phi_builder_add_value(struct nir_phi_builder *pb, unsigned num_components, 78 unsigned bit_size, const BITSET_WORD *defs); 79 80 /* Register a definition for the given value and block. 81 * 82 * It is safe to call this function as many times as you wish for any given 83 * block/value pair. However, it always replaces whatever was there 84 * previously even if that definition is from a phi node. The phi builder 85 * always uses the latest information it has, so you must be careful about the 86 * order in which you register definitions. The final value at the end of the 87 * block must be the last value registered. 88 */ 89 void 90 nir_phi_builder_value_set_block_def(struct nir_phi_builder_value *val, 91 nir_block *block, nir_ssa_def *def); 92 93 /* Get the definition for the given value in the given block. 94 * 95 * This definition will always be the latest definition known for the given 96 * block. If no definition is immediately available, it will crawl up the 97 * dominance tree and insert phi nodes as needed until it finds one. In the 98 * case that no suitable definition is found, it will return the result of a 99 * nir_ssa_undef_instr with the correct number of components. 100 * 101 * Because this function only uses the latest available information for any 102 * given block, you must have already finished registering definitions for any 103 * blocks that dominate the current block in order to get the correct result. 104 */ 105 nir_ssa_def * 106 nir_phi_builder_value_get_block_def(struct nir_phi_builder_value *val, 107 nir_block *block); 108 109 /* Finish building phi nodes and free the builder. 110 * 111 * This function does far more than just free memory. Prior to calling 112 * nir_phi_builder_finish, no phi nodes have actually been inserted in the 113 * program. This function is what finishes setting up phi node sources and 114 * adds the phi nodes to the program. 115 */ 116 void nir_phi_builder_finish(struct nir_phi_builder *pb); 117