summaryrefslogtreecommitdiffstats
path: root/src/glsl/nir
diff options
context:
space:
mode:
authorJason Ekstrand <[email protected]>2014-12-18 17:13:22 -0800
committerJason Ekstrand <[email protected]>2015-01-15 07:20:23 -0800
commit8599b30c67f6918a77578fd5d67ae38cecaf189c (patch)
treede12a479313182a805ede39c06f84d91876f0621 /src/glsl/nir
parentad9d0a9ea6d40db776e6680a44d614cd447dc17c (diff)
nir: Add some documentation
Signed-off-by: Jason Ekstrand <[email protected]> Reviewed-by: Connor Abbott <[email protected]>
Diffstat (limited to 'src/glsl/nir')
-rw-r--r--src/glsl/nir/nir.h91
1 files changed, 69 insertions, 22 deletions
diff --git a/src/glsl/nir/nir.h b/src/glsl/nir/nir.h
index c6134f939d6..56b6ab0ed7e 100644
--- a/src/glsl/nir/nir.h
+++ b/src/glsl/nir/nir.h
@@ -98,7 +98,7 @@ typedef struct nir_constant {
* Value of the constant.
*
* The field used to back the values supplied by the constant is determined
- * by the type associated with the \c ir_instruction. Constants may be
+ * by the type associated with the \c nir_variable. Constants may be
* scalars, vectors, or matrices.
*/
union nir_constant_data value;
@@ -175,7 +175,7 @@ typedef struct {
/**
* Interpolation mode for shader inputs / outputs
*
- * \sa ir_variable_interpolation
+ * \sa glsl_interp_qualifier
*/
unsigned interpolation:2;
@@ -398,7 +398,7 @@ typedef struct {
/** set of nir_instr's where this register is defined (written to) */
struct set *defs;
- /** set of ifs where this register is used as a condition */
+ /** set of nir_if's where this register is used as a condition */
struct set *if_uses;
} nir_register;
@@ -441,7 +441,10 @@ typedef struct {
nir_instr *parent_instr;
+ /** set of nir_instr's where this register is used (read from) */
struct set *uses;
+
+ /** set of nir_if's where this register is used as a condition */
struct set *if_uses;
uint8_t num_components;
@@ -494,8 +497,8 @@ typedef struct {
*/
/*@{*/
/**
- * For inputs interpreted as a floating point, flips the sign bit. For inputs
- * interpreted as an integer, performs the two's complement negation.
+ * For inputs interpreted as floating point, flips the sign bit. For
+ * inputs interpreted as integers, performs the two's complement negation.
*/
bool negate;
@@ -584,8 +587,8 @@ typedef struct {
unsigned output_size;
/**
- * The type of vector that the instruction outputs. Note that this
- * determines whether the saturate modifier is allowed.
+ * The type of vector that the instruction outputs. Note that the
+ * staurate modifier is only allowed on outputs with the float type.
*/
nir_alu_type output_type;
@@ -596,9 +599,9 @@ typedef struct {
unsigned input_sizes[4];
/**
- * The type of vector that each input takes. Note that negate is only
- * allowed on inputs with int or float type, and behaves differently on the
- * two, and absolute value is only allowed on float type inputs.
+ * The type of vector that each input takes. Note that negate and
+ * absolute value are only allowed on inputs with int or float type and
+ * behave differently on the two.
*/
nir_alu_type input_types[4];
@@ -698,6 +701,32 @@ typedef enum {
#undef INTRINSIC
#undef LAST_INTRINSIC
+/** Represents an intrinsic
+ *
+ * An intrinsic is an instruction type for handling things that are
+ * more-or-less regular operations but don't just consume and produce SSA
+ * values like ALU operations do. Intrinsics are not for things that have
+ * special semantic meaning such as phi nodes and parallel copies.
+ * Examples of intrinsics include variable load/store operations, system
+ * value loads, and the like. Even though texturing more-or-less falls
+ * under this category, texturing is its own instruction type because
+ * trying to represent texturing with intrinsics would lead to a
+ * combinatorial explosion of intrinsic opcodes.
+ *
+ * By having a single instruction type for handling a lot of different
+ * cases, optimization passes can look for intrinsics and, for the most
+ * part, completely ignore them. Each intrinsic type also has a few
+ * possible flags that govern whether or not they can be reordered or
+ * eliminated. That way passes like dead code elimination can still work
+ * on intrisics without understanding the meaning of each.
+ *
+ * Each intrinsic has some number of constant indices, some number of
+ * variables, and some number of sources. What these sources, variables,
+ * and indices mean depends on the intrinsic and is documented with the
+ * intrinsic declaration in nir_intrinsics.h. Intrinsics and texture
+ * instructions are the only types of instruction that can operate on
+ * variables.
+ */
typedef struct {
nir_instr instr;
@@ -705,7 +734,14 @@ typedef struct {
nir_dest dest;
- /** number of components if this is a vectorized intrinsic */
+ /** number of components if this is a vectorized intrinsic
+ *
+ * Similarly to ALU operations, some intrinsics are vectorized.
+ * An intrinsic is vectorized if nir_intrinsic_infos.dest_components == 0.
+ * For vectorized intrinsics, the num_components field specifies the
+ * number of destination components and the number of source components
+ * for all sources with nir_intrinsic_infos.src_components[i] == 0.
+ */
uint8_t num_components;
int const_index[3];
@@ -947,14 +983,18 @@ typedef struct {
typedef struct {
struct exec_node node;
+
+ /* The predecessor block corresponding to this source */
struct nir_block *pred;
+
nir_src src;
} nir_phi_src;
typedef struct {
nir_instr instr;
- struct exec_list srcs;
+ struct exec_list srcs; /** < list of nir_phi_src */
+
nir_dest dest;
} nir_phi_instr;
@@ -1020,8 +1060,10 @@ typedef struct nir_cf_node {
typedef struct nir_block {
nir_cf_node cf_node;
- struct exec_list instr_list;
+ struct exec_list instr_list; /** < list of nir_instr */
+
+ /** generic block index; generated by nir_index_blocks */
unsigned index;
/*
@@ -1030,6 +1072,7 @@ typedef struct nir_block {
*/
struct nir_block *successors[2];
+ /* Set of nir_block predecessors in the CFG */
struct set *predecessors;
/*
@@ -1042,6 +1085,7 @@ typedef struct nir_block {
unsigned num_dom_children;
struct nir_block **dom_children;
+ /* Set of nir_block's on the dominance frontier of this block */
struct set *dom_frontier;
/* live in and out for this block; used for liveness analysis */
@@ -1064,8 +1108,9 @@ typedef struct nir_block {
typedef struct {
nir_cf_node cf_node;
nir_src condition;
- struct exec_list then_list;
- struct exec_list else_list;
+
+ struct exec_list then_list; /** < list of nir_cf_node */
+ struct exec_list else_list; /** < list of nir_cf_node */
} nir_if;
#define nir_if_first_then_node(if) \
@@ -1079,7 +1124,8 @@ typedef struct {
typedef struct {
nir_cf_node cf_node;
- struct exec_list body;
+
+ struct exec_list body; /** < list of nir_cf_node */
} nir_loop;
#define nir_loop_first_cf_node(loop) \
@@ -1177,7 +1223,7 @@ typedef struct nir_function_overload {
typedef struct nir_function {
struct exec_node node;
- struct exec_list overload_list;
+ struct exec_list overload_list; /** < list of nir_function_overload */
const char *name;
struct nir_shader *shader;
} nir_function;
@@ -1187,23 +1233,24 @@ typedef struct nir_function {
exec_list_get_head(&(func)->overload_list), node)
typedef struct nir_shader {
- /** hash table of name -> uniform */
+ /** hash table of name -> uniform nir_variable */
struct hash_table *uniforms;
- /** hash table of name -> input */
+ /** hash table of name -> input nir_variable */
struct hash_table *inputs;
- /** hash table of name -> output */
+ /** hash table of name -> output nir_variable */
struct hash_table *outputs;
/** list of global variables in the shader */
struct exec_list globals;
+ /** list of system value variables in the shader */
struct exec_list system_values;
- struct exec_list functions;
+ struct exec_list functions; /** < list of nir_function */
- /** list of global registers in the shader */
+ /** list of global register in the shader */
struct exec_list registers;
/** structures used in this shader */