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_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${("**Description:** " + op.description) if op.description != "" else ""} 62 63**Constant-folding:** 64 65.. code-block:: c 66 67${textwrap.indent(op.const_expr, ' ')} 68 69**Builder function:** 70 71.. c:function:: nir_def *nir_${op.name}(nir_builder *, ${src_decl_list(op.num_inputs)}) 72""") 73 74def parse_rst(state, parent, rst): 75 vl = docutils.statemachine.ViewList(rst.splitlines()) 76 state.nested_parse(vl, 0, parent) 77 78def nir_alu_type_name(t, s): 79 if s: 80 return '{}[{}]'.format(t, s) 81 else: 82 return '{}[N]'.format(t) 83 84def build_alu_op_desc(state, env, op): 85 desc = sphinx.addnodes.desc(domain='nir', objtype='aluop') 86 87 # Add the signature 88 sig = sphinx.addnodes.desc_signature() 89 desc.append(sig) 90 sig += sphinx.addnodes.desc_name(op.name, op.name) 91 92 params = sphinx.addnodes.desc_parameterlist() 93 for i, t, s in zip(range(100), op.input_types, op.input_sizes): 94 params += docutils.nodes.Text(nir_alu_type_name(t, s) + ' ') 95 params += sphinx.addnodes.desc_parameter('', 'src' + str(i)) 96 sig += params 97 98 sig += sphinx.addnodes.desc_returns('', 99 nir_alu_type_name(op.output_type, op.output_size)) 100 101 nir_domain = env.get_domain('nir') 102 sig['ids'].append(nir_domain.add_alu_op_ref(op)) 103 104 # Build the description 105 content = sphinx.addnodes.desc_content() 106 desc.append(content) 107 parse_rst(state, content, OP_DESC_TEMPLATE.render(op=op, textwrap=textwrap)) 108 109 return desc 110 111class NIRALUOpcodesDirective(SphinxDirective): 112 def run(self): 113 return [build_alu_op_desc(self.state, self.env, op) 114 for op in nir_opcodes.opcodes.values()] 115 116class NIRDomain(Domain): 117 """A new NIR directive 118 119 To list all NIR ALU opcodes with their descriptions: 120 ```rst 121 .. nir:alu-opcodes:: 122 ``` 123 124 To reference a NIR opcode, ``:nir:alu-op:`fadd``` 125 """ 126 name = 'nir' 127 roles = { 128 'alu-op' : sphinx.roles.XRefRole(), 129 } 130 directives = { 131 'alu-opcodes' : NIRALUOpcodesDirective, 132 } 133 initial_data = { 134 'alu-op-refs': [], 135 } 136 137 def add_alu_op_ref(self, op): 138 """Add reference to an ALU op.""" 139 self.data['alu-op-refs'].append((op.name, self.env.docname)) 140 return 'nir-alu-op-' + op.name 141 142 def resolve_xref(self, env, fromdocname, builder, typ, target, node, 143 contnode): 144 for opname, todocname in self.data['alu-op-refs']: 145 if target == opname: 146 targ = 'nir-alu-op-' + opname 147 return make_refnode(builder, fromdocname, todocname, targ, 148 contnode, targ) 149 150 return None 151 152def setup(app): 153 app.add_domain(NIRDomain) 154