Module: Mesa Branch: main Commit: eabd93bba8e8bb2330412ae5997855e948b028a1 URL: http://cgit.freedesktop.org/mesa/mesa/commit/?id=eabd93bba8e8bb2330412ae5997855e948b028a1
Author: Jani Nikula <[email protected]> Date: Sun Aug 20 20:42:34 2023 +0300 docs/nir: use hawkmoth instead of doxygen Use the hawkmoth c:auto* directives to incorporate nir documentation. Convert @param style parameter descriptions to rst info field lists. Add static stubs for generated headers. Fix a lot of references, in particular the symbols are now in the Sphinx C domain, not C++ domain. Tweak syntax here and there. Based on the earlier work by Erik Faye-Lund <[email protected]> Reviewed-by: Erik Faye-Lund <[email protected]> Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/24507> --- docs/conf.py | 1 + docs/header-stubs/builtin_types.h | 0 docs/header-stubs/nir_intrinsics.h | 2 + docs/header-stubs/nir_intrinsics_indices.h | 0 docs/header-stubs/nir_opcodes.h | 1 + docs/nir/alu.rst | 17 +++--- docs/nir/tex.rst | 54 ++++++++++++------- src/compiler/nir/nir.h | 87 ++++++++++++++++-------------- 8 files changed, 95 insertions(+), 67 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 2fb1e9e7b52..15581f322a7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -224,6 +224,7 @@ hawkmoth_clang = [ '-Idocs/header-stubs/', '-Iinclude/', '-Isrc/', + '-Isrc/gallium/include/', '-DHAVE_STRUCT_TIMESPEC', '-DHAVE_PTHREAD', '-DHAVE_ENDIAN_H', diff --git a/docs/header-stubs/builtin_types.h b/docs/header-stubs/builtin_types.h new file mode 100644 index 00000000000..e69de29bb2d diff --git a/docs/header-stubs/nir_intrinsics.h b/docs/header-stubs/nir_intrinsics.h new file mode 100644 index 00000000000..a2c0a3ee112 --- /dev/null +++ b/docs/header-stubs/nir_intrinsics.h @@ -0,0 +1,2 @@ +typedef enum { nir_num_intrinsics = 0 } nir_intrinsic_op; +typedef enum { NIR_INTRINSIC_NUM_INDEX_FLAGS } nir_intrinsic_index_flag; diff --git a/docs/header-stubs/nir_intrinsics_indices.h b/docs/header-stubs/nir_intrinsics_indices.h new file mode 100644 index 00000000000..e69de29bb2d diff --git a/docs/header-stubs/nir_opcodes.h b/docs/header-stubs/nir_opcodes.h new file mode 100644 index 00000000000..7eca02fa3b0 --- /dev/null +++ b/docs/header-stubs/nir_opcodes.h @@ -0,0 +1 @@ +typedef enum { nir_num_opcodes = 0 } nir_op; diff --git a/docs/nir/alu.rst b/docs/nir/alu.rst index 4b1eb3c53e1..ad91c5bee3c 100644 --- a/docs/nir/alu.rst +++ b/docs/nir/alu.rst @@ -9,13 +9,13 @@ identical output. A good rule of thumb is that only things which can be constant folded should be ALU operations. If it can't be constant folded, then it should probably be an intrinsic instead. -Each ALU instruction has an opcode, which is a member of the :cpp:enum:`nir_op` +Each ALU instruction has an opcode, which is a member of the :c:enum:`nir_op` enum, that describes what it does as well as how many arguments it takes. Associated with each opcode is an metadata structure, -:cpp:struct:`nir_op_info`, which shows how many arguments the opcode takes, +:c:struct:`nir_op_info`, which shows how many arguments the opcode takes, information about data types, and algebraic properties such as associativity and commutativity. The info structure for each opcode may be accessed through -a global :cpp:var:`nir_op_infos` array that’s indexed by the opcode. +a global :c:var:`nir_op_infos` array that’s indexed by the opcode. ALU operations are typeless, meaning that they're only defined to convert a certain bit-pattern input to another bit-pattern output. The only concrete @@ -48,21 +48,22 @@ components required by each source which is fixed by the opcode. While most instruction types in NIR require vector sizes to perfectly match on inputs and outputs, ALU instruction sources have an additional -:cpp:member:`nir_alu_src::swizzle` field which allows them to act on vectors +:c:member:`nir_alu_src.swizzle` field which allows them to act on vectors which are not the native vector size of the instruction. This is ideal for hardware with a native data type of `vec4` but also means that ALU instructions are often used (and required) for packing/unpacking vectors for use in other instruction types like intrinsics or texture ops. -.. doxygenstruct:: nir_op_info +.. c:autostruct:: nir_op_info + :file: src/compiler/nir/nir.h :members: -.. doxygenvariable:: nir_op_infos +.. c:autovar:: nir_op_infos -.. doxygenstruct:: nir_alu_instr +.. c:autostruct:: nir_alu_instr :members: -.. doxygenstruct:: nir_alu_src +.. c:autostruct:: nir_alu_src :members: NIR ALU Opcode Reference: diff --git a/docs/nir/tex.rst b/docs/nir/tex.rst index 492142ae18a..a21330fd682 100644 --- a/docs/nir/tex.rst +++ b/docs/nir/tex.rst @@ -5,14 +5,17 @@ Even though texture instructions *could* be supported as intrinsics, the vast number of combinations mean that doing so is practically impossible. Instead, NIR has a dedicated texture instruction. There are several texture operations: -.. doxygenenum:: nir_texop +.. c:autoenum:: nir_texop + :file: src/compiler/nir/nir.h + :members: As with other instruction types, there is still an array of sources, except that each source also has a *type* associated with it. There are various source types, each corresponding to a piece of information that the different texture operations require. -.. doxygenenum:: nir_tex_src_type +.. c:autoenum:: nir_tex_src_type + :members: Of particular interest are the texture/sampler deref/index/handle source types. First, note that textures and samplers are specified separately in NIR. While @@ -28,12 +31,12 @@ Also, like a lot of other resources, there are multiple ways to represent a texture in NIR. It can be referenced by a variable dereference, an index, or a bindless handle. When using an index or a bindless handle, the texture type information is generally not available. To handle this, various information -from the type is redundantly stored in the :cpp:struct:`nir_tex_instr` itself. +from the type is redundantly stored in the :c:struct:`nir_tex_instr` itself. -.. doxygenstruct:: nir_tex_instr +.. c:autostruct:: nir_tex_instr :members: -.. doxygenstruct:: nir_tex_src +.. c:autostruct:: nir_tex_src :members: Texture instruction helpers @@ -42,17 +45,27 @@ Texture instruction helpers There are a number of helper functions for working with NIR texture instructions. They are documented here in no particular order. -.. doxygenfunction:: nir_tex_instr_create -.. doxygenfunction:: nir_tex_instr_need_sampler -.. doxygenfunction:: nir_tex_instr_result_size -.. doxygenfunction:: nir_tex_instr_dest_size -.. doxygenfunction:: nir_tex_instr_is_query -.. doxygenfunction:: nir_tex_instr_has_implicit_derivative -.. doxygenfunction:: nir_tex_instr_src_type -.. doxygenfunction:: nir_tex_instr_src_size -.. doxygenfunction:: nir_tex_instr_src_index -.. doxygenfunction:: nir_tex_instr_add_src -.. doxygenfunction:: nir_tex_instr_remove_src +.. c:autofunction:: nir_tex_instr_create + +.. c:autofunction:: nir_tex_instr_need_sampler + +.. c:autofunction:: nir_tex_instr_result_size + +.. c:autofunction:: nir_tex_instr_dest_size + +.. c:autofunction:: nir_tex_instr_is_query + +.. c:autofunction:: nir_tex_instr_has_implicit_derivative + +.. c:autofunction:: nir_tex_instr_src_type + +.. c:autofunction:: nir_tex_instr_src_size + +.. c:autofunction:: nir_tex_instr_src_index + +.. c:autofunction:: nir_tex_instr_add_src + +.. c:autofunction:: nir_tex_instr_remove_src Texture instruction lowering ---------------------------- @@ -61,7 +74,10 @@ Because most hardware only supports some subset of all possible GLSL/SPIR-V texture operations, NIR provides a quite powerful lowering pass which is able to implement more complex texture operations in terms of simpler ones. -.. doxygenfunction:: nir_lower_tex -.. doxygenstruct:: nir_lower_tex_options +.. c:autofunction:: nir_lower_tex + +.. c:autostruct:: nir_lower_tex_options + :members: + +.. c:autoenum:: nir_lower_tex_packing :members: -.. doxygenenum:: nir_lower_tex_packing diff --git a/src/compiler/nir/nir.h b/src/compiler/nir/nir.h index 38aae170a2e..c8aa26608e3 100644 --- a/src/compiler/nir/nir.h +++ b/src/compiler/nir/nir.h @@ -167,7 +167,7 @@ struct nir_xfb_info; /** * Description of built-in state associated with a uniform * - * \sa nir_variable::state_slots + * :c:member:`nir_variable.state_slots` */ typedef struct { gl_state_index16 tokens[STATE_LENGTH]; @@ -405,7 +405,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 nir_variable. Constants may be + * by the type associated with the ``nir_variable``. Constants may be * scalars, vectors, or matrices. */ nir_const_value values[NIR_MAX_VEC_COMPONENTS]; @@ -423,7 +423,7 @@ typedef struct nir_constant { } nir_constant; /** - * \brief Layout qualifiers for gl_FragDepth. + * Layout qualifiers for gl_FragDepth. * * The AMD/ARB_conservative_depth extensions allow gl_FragDepth to be redeclared * with a layout qualifier. @@ -481,14 +481,14 @@ typedef struct nir_variable { /** * Storage class of the variable. * - * \sa nir_variable_mode + * :c:struct:`nir_variable_mode` */ unsigned mode : 18; /** * Is the variable read-only? * - * This is set for variables declared as \c const, shader inputs, + * This is set for variables declared as ``const``, shader inputs, * and uniforms. */ unsigned read_only : 1; @@ -556,7 +556,7 @@ typedef struct nir_variable { /** * Interpolation mode for shader inputs / outputs * - * \sa glsl_interp_mode + * :c:enum:`glsl_interp_mode` */ unsigned interpolation : 3; @@ -565,7 +565,7 @@ typedef struct nir_variable { * into a single varying slot, so this offset should be applied when * accessing components. For example, an offset of 1 means that the x * component of this variable is actually stored in component y of the - * location specified by \c location. + * location specified by ``location``. */ unsigned location_frac : 2; @@ -597,8 +597,8 @@ typedef struct nir_variable { /** * Was the location explicitly set in the shader? * - * If the location is explicitly set in the shader, it \b cannot be changed - * by the linker or by the API (e.g., calls to \c glBindAttribLocation have + * If the location is explicitly set in the shader, it **cannot** be changed + * by the linker or by the API (e.g., calls to ``glBindAttribLocation`` have * no effect). */ unsigned explicit_location : 1; @@ -685,10 +685,10 @@ typedef struct nir_variable { unsigned per_vertex : 1; /** - * \brief Layout qualifier for gl_FragDepth. See nir_depth_layout. + * Layout qualifier for gl_FragDepth. See nir_depth_layout. * - * This is not equal to \c ir_depth_layout_none if and only if this - * variable is \c gl_FragDepth and a layout qualifier is specified. + * This is not equal to ``ir_depth_layout_none`` if and only if this + * variable is ``gl_FragDepth`` and a layout qualifier is specified. */ unsigned depth_layout : 3; @@ -730,15 +730,15 @@ typedef struct nir_variable { * * The precise meaning of this field depends on the nature of the variable. * - * - Vertex shader input: one of the values from \c gl_vert_attrib. - * - Vertex shader output: one of the values from \c gl_varying_slot. - * - Geometry shader input: one of the values from \c gl_varying_slot. - * - Geometry shader output: one of the values from \c gl_varying_slot. - * - Fragment shader input: one of the values from \c gl_varying_slot. - * - Fragment shader output: one of the values from \c gl_frag_result. - * - Task shader output: one of the values from \c gl_varying_slot. - * - Mesh shader input: one of the values from \c gl_varying_slot. - * - Mesh shader output: one of the values from \c gl_varying_slot. + * - Vertex shader input: one of the values from ``gl_vert_attrib``. + * - Vertex shader output: one of the values from ``gl_varying_slot``. + * - Geometry shader input: one of the values from ``gl_varying_slot``. + * - Geometry shader output: one of the values from ``gl_varying_slot``. + * - Fragment shader input: one of the values from ``gl_varying_slot``. + * - Fragment shader output: one of the values from ``gl_frag_result``. + * - Task shader output: one of the values from ``gl_varying_slot``. + * - Mesh shader input: one of the values from ``gl_varying_slot``. + * - Mesh shader output: one of the values from ``gl_varying_slot``. * - Uniforms: Per-stage uniform slot number for default uniform block. * - Uniforms: Index within the uniform block definition for UBO members. * - Non-UBO Uniforms: uniform slot number. @@ -806,13 +806,13 @@ typedef struct nir_variable { /** * Built-in state that backs this uniform * - * Once set at variable creation, \c state_slots must remain invariant. + * Once set at variable creation, ``state_slots`` must remain invariant. * This is because, ideally, this array would be shared by all clones of * this variable in the IR tree. In other words, we'd really like for it * to be a fly-weight. * - * If the variable is not a uniform, \c num_state_slots will be zero and - * \c state_slots will be \c NULL. + * If the variable is not a uniform, ``num_state_slots`` will be zero and + * ``state_slots`` will be ``NULL``. * * Number of state slots used. */ @@ -839,9 +839,9 @@ typedef struct nir_variable { /** * For variables that are in an interface block or are an instance of an - * interface block, this is the \c GLSL_TYPE_INTERFACE type for that block. + * interface block, this is the ``GLSL_TYPE_INTERFACE`` type for that block. * - * \sa ir_variable::location + * ``ir_variable.location`` */ const struct glsl_type *interface_type; @@ -1164,6 +1164,7 @@ nir_is_sequential_comp_swizzle(uint8_t *swiz, unsigned nr_comp) return true; } +/***/ typedef struct nir_alu_src { /** Base source */ nir_src src; @@ -1463,6 +1464,7 @@ typedef enum { */ #define NIR_ALU_MAX_INPUTS NIR_MAX_VEC_COMPONENTS +/***/ typedef struct nir_op_info { /** Name of the NIR ALU opcode */ const char *name; @@ -1530,6 +1532,7 @@ nir_op_is_derivative(nir_op op) return (nir_op_infos[op].algebraic_properties & NIR_OP_IS_DERIVATIVE) != 0; } +/***/ typedef struct nir_alu_instr { /** Base instruction */ nir_instr instr; @@ -1564,7 +1567,7 @@ typedef struct nir_alu_instr { /** Sources * - * The size of the array is given by nir_op_info::num_inputs. + * The size of the array is given by :c:member:`nir_op_info.num_inputs`. */ nir_alu_src src[]; } nir_alu_instr; @@ -1874,11 +1877,11 @@ typedef enum { } nir_memory_semantics; /** - * \name NIR intrinsics semantic flags + * NIR intrinsics semantic flags * * information about what the compiler can do with the intrinsics. * - * \sa nir_intrinsic_info::flags + * :c:member:`nir_intrinsic_info.flags` */ typedef enum { /** @@ -2121,7 +2124,7 @@ nir_intrinsic_is_ray_query(nir_intrinsic_op intrinsic) typedef enum nir_tex_src_type { /** Texture coordinate * - * Must have nir_tex_instr::coord_components components. + * Must have :c:member:`nir_tex_instr.coord_components` components. */ nir_tex_src_coord, @@ -2142,7 +2145,8 @@ typedef enum nir_tex_src_type { * Interpolation happens after this conversion so the actual result may be * anywhere in the range [0.0, 1.0]. * - * Only valid if nir_tex_instr::is_shadow and must be a float scalar. + * Only valid if :c:member:`nir_tex_instr.is_shadow` and must be a float + * scalar. */ nir_tex_src_comparator, @@ -2191,16 +2195,16 @@ typedef enum nir_tex_src_type { /** Texture index offset * - * This is added to nir_tex_instr::texture_index. Unless - * nir_tex_instr::texture_non_uniform is set, this is guaranteed to be - * dynamically uniform. + * This is added to :c:member:`nir_tex_instr.texture_index`. Unless + * :c:member:`nir_tex_instr.texture_non_uniform` is set, this is guaranteed + * to be dynamically uniform. */ nir_tex_src_texture_offset, /** Dynamically uniform sampler index offset * - * This is added to nir_tex_instr::sampler_index. Unless - * nir_tex_instr::sampler_non_uniform is set, this is guaranteed to be + * This is added to :c:member:`nir_tex_instr.sampler_index`. Unless + * :c:member:`nir_tex_instr.sampler_non_uniform` is set, this is guaranteed to be * dynamically uniform. This should not be present until GLSL ES 3.20, GLSL * 4.00, or ARB_gpu_shader5, because in ES 3.10 and GL 3.30 samplers said * "When aggregated into arrays within a shader, samplers can only be indexed @@ -2345,7 +2349,7 @@ typedef struct nir_tex_instr { /** Array of sources * - * This array has nir_tex_instr::num_srcs elements + * This array has :c:member:`nir_tex_instr.num_srcs` elements */ nir_tex_src *src; @@ -2420,6 +2424,7 @@ typedef struct nir_tex_instr { * * The following operations do not require a sampler and, as such, this * field should be ignored: + * * - nir_texop_txf * - nir_texop_txf_ms * - nir_texop_txs @@ -2445,7 +2450,7 @@ typedef struct nir_tex_instr { * Note that the specific hw/driver backend could require to a sampler * object/configuration packet in any case, for some other reason. * - * @see nir_tex_instr::sampler_index. + * See also :c:member:`nir_tex_instr.sampler_index`. */ bool nir_tex_instr_need_sampler(const nir_tex_instr *instr); @@ -3731,7 +3736,7 @@ typedef struct nir_shader_compiler_options { * If this flag is set, the lowering will be applied to all bit-sizes of * these instructions. * - * \sa ::lower_hadd64 + * :c:member:`lower_hadd64` */ bool lower_hadd; @@ -3742,7 +3747,7 @@ typedef struct nir_shader_compiler_options { * If this flag is set, the lowering will be applied to only 64-bit * versions of these instructions. * - * \sa ::lower_hadd + * :c:member:`lower_hadd` */ bool lower_hadd64; @@ -5572,6 +5577,7 @@ bool nir_lower_sysvals_to_varyings(nir_shader *shader, const struct nir_lower_sysvals_to_varyings_options *options); +/***/ enum ENUM_PACKED nir_lower_tex_packing { /** No packing */ nir_lower_tex_packing_none = 0, @@ -5584,6 +5590,7 @@ enum ENUM_PACKED nir_lower_tex_packing { nir_lower_tex_packing_8, }; +/***/ typedef struct nir_lower_tex_options { /** * bitmask of (1 << GLSL_SAMPLER_DIM_x) to control for which
