• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Copyright © 2021 Intel Corporation
2#
3# Permission is hereby granted, free of charge, to any person obtaining a
4# copy of this software and associated documentation files (the
5# "Software"), to deal in the Software without restriction, including
6# without limitation the rights to use, copy, modify, merge, publish,
7# distribute, sub license, and/or sell copies of the Software, and to
8# permit persons to whom the Software is furnished to do so, subject to
9# the following conditions:
10#
11# The above copyright notice and this permission notice (including the
12# next paragraph) shall be included in all copies or substantial portions
13# of the Software.
14#
15# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
16# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
18# IN NO EVENT SHALL VMWARE AND/OR ITS SUPPLIERS BE LIABLE FOR
19# ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
20# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
21# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
22
23import docutils.nodes
24import mako.template
25import os
26import sphinx
27from sphinx.directives import SphinxDirective
28from sphinx.domains import Domain
29from sphinx.util.nodes import make_refnode
30import sys
31import textwrap
32
33THIS_DIR = os.path.dirname(os.path.abspath(__file__))
34MESA_DIR = os.path.join(THIS_DIR, '..', '..')
35NIR_PATH = os.path.join(MESA_DIR, 'src', 'compiler', 'nir')
36sys.path.append(NIR_PATH)
37
38import nir_opcodes
39
40OP_DESC_TEMPLATE = mako.template.Template("""
41<%
42def src_decl_list(num_srcs):
43   return ', '.join('nir_ssa_def *src' + str(i) for i in range(num_srcs))
44
45def to_yn(b):
46    return 'Y' if b else 'N'
47%>
48
49**Properties:**
50
51.. list-table::
52   :header-rows: 1
53
54   * - Per-component
55     - Associative
56     - 2-src commutative
57   * - ${to_yn(op.output_size == 0)}
58     - ${to_yn('associative' in op.algebraic_properties)}
59     - ${to_yn('2src_commutative' in op.algebraic_properties)}
60
61**Constant-folding:**
62
63.. code-block:: c
64
65${textwrap.indent(op.const_expr, '    ')}
66
67**Builder function:**
68
69.. c:function:: nir_ssa_def *nir_${op.name}(nir_builder *, ${src_decl_list(op.num_inputs)})
70""")
71
72def parse_rst(state, parent, rst):
73    vl = docutils.statemachine.ViewList(rst.splitlines())
74    state.nested_parse(vl, 0, parent)
75
76def nir_alu_type_name(t, s):
77    if s:
78        return '{}[{}]'.format(t, s)
79    else:
80        return '{}[N]'.format(t)
81
82def build_alu_op_desc(state, env, op):
83    desc = sphinx.addnodes.desc(domain='nir', objtype='aluop')
84
85    # Add the signature
86    sig = sphinx.addnodes.desc_signature()
87    desc.append(sig)
88    sig += sphinx.addnodes.desc_name(op.name, op.name)
89
90    params = sphinx.addnodes.desc_parameterlist()
91    for i, t, s in zip(range(100), op.input_types, op.input_sizes):
92        params += docutils.nodes.Text(nir_alu_type_name(t, s) + ' ')
93        params += sphinx.addnodes.desc_parameter('', 'src' + str(i))
94    sig += params
95
96    sig += sphinx.addnodes.desc_returns('',
97        nir_alu_type_name(op.output_type, op.output_size))
98
99    nir_domain = env.get_domain('nir')
100    sig['ids'].append(nir_domain.add_alu_op_ref(op))
101
102    # Build the description
103    content = sphinx.addnodes.desc_content()
104    desc.append(content)
105    parse_rst(state, content, OP_DESC_TEMPLATE.render(op=op, textwrap=textwrap))
106
107    return desc
108
109class NIRALUOpcodesDirective(SphinxDirective):
110    def run(self):
111        return [build_alu_op_desc(self.state, self.env, op)
112                for op in nir_opcodes.opcodes.values()]
113
114class NIRDomain(Domain):
115    """A new NIR directive
116
117    To list all NIR ALU opcodes with their descriptions:
118    ```rst
119    .. nir:alu-opcodes::
120    ```
121
122    To reference a NIR opcode, ``:nir:alu-op:`fadd```
123    """
124    name = 'nir'
125    roles = {
126        'alu-op' : sphinx.roles.XRefRole(),
127    }
128    directives = {
129        'alu-opcodes' : NIRALUOpcodesDirective,
130    }
131    initial_data = {
132        'alu-op-refs': [],
133    }
134
135    def add_alu_op_ref(self, op):
136        """Add reference to an ALU op."""
137        self.data['alu-op-refs'].append((op.name, self.env.docname))
138        return 'nir-alu-op-' + op.name
139
140    def resolve_xref(self, env, fromdocname, builder, typ, target, node,
141                     contnode):
142        for opname, todocname in self.data['alu-op-refs']:
143            if target == opname:
144                targ = 'nir-alu-op-' + opname
145                return make_refnode(builder, fromdocname, todocname, targ,
146                                    contnode, targ)
147
148        return None
149
150def setup(app):
151    app.add_domain(NIRDomain)
152