[Mesa-dev] [PATCH 144/133] nir: Add some documentation

[Connor Abbott]

On Thu, Dec 18, 2014 at 8:15 PM, Jason Ekstrand <jason at jlekstrand.net> wrote:
> ---
>  src/glsl/nir/nir.h | 43 +++++++++++++++++++++++++++++++++----------
>  1 file changed, 33 insertions(+), 10 deletions(-)
>
> diff --git a/src/glsl/nir/nir.h b/src/glsl/nir/nir.h
> index 19781c1..aa128ad 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;
>
> @@ -494,8 +494,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 +584,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 +596,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 +698,22 @@ typedef enum {
>  #undef INTRINSIC
>  #undef LAST_INTRINSIC
>
> +/** Represents an intrinsic
> + *
> + * An intrinsic is an instruction type for handling all of the little
> + * special cases that we have to represent in the IR.  This provides us
> + * with a single instruction type for handling a lot of different cases.
> + * This way, optimization passes can look for intrinsics and, for the most
> + * part, completely ignore them.  Some special cases such as phi nodes and
> + * parallel copies really do need their own instruction type, but most
> + * things can be intrinsics.

I think I would put things a little differently: intrinsics are for
loads, stores, or really anything we don't need to special-case that
requires some kind of dependency on the outside world, or rather
anything which doesn't merely consume some SSA values to produce
another SSA value. Feel free to say something like this in addition to
what you said, replacing what you said, or not at all. Also, I think
textures are a special case too (I originally wanted to use intrinsics
for them, but the combinatorial explosion was too much to deal with).

> + *
> + * 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 are the only type
> + * of instruction that can operate on variables.

(except for textures)

> + */
>  typedef struct {
>     nir_instr instr;
>
> @@ -705,7 +721,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];
> --
> 2.2.0
>
> _______________________________________________
> mesa-dev mailing list
> mesa-dev at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/mesa-dev