init

docs/_exts/bootstrap.py

@@ -0,0 +1,127 @@
+# BSD 3-Clause License
+#
+# Copyright (c) 2018, pandas
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# * Redistributions of source code must retain the above copyright notice, this
+#   list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+#
+# * Neither the name of the copyright holder nor the names of its
+#   contributors may be used to endorse or promote products derived from
+#   this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+# Based on https://github.com/pydata/pydata-sphinx-theme
+
+from sphinx.ext.autosummary import autosummary_table
+from sphinx.locale import admonitionlabels
+
+import types
+
+
+class BootstrapHTML5TranslatorMixin:
+    def __init__(self, *args, **kwds):
+        super().__init__(*args, **kwds)
+        self.settings.table_style = "table"
+
+    def starttag(self, *args, **kwargs):
+        """ensure an aria-level is set for any heading role"""
+        if kwargs.get("ROLE") == "heading" and "ARIA-LEVEL" not in kwargs:
+            kwargs["ARIA-LEVEL"] = "2"
+        return super().starttag(*args, **kwargs)
+
+    def visit_admonition(self, node, name: str = '') -> None:
+        admonitionclasses = {
+            'attention': 'alert-primary',
+            'caution':   'alert-secondary',
+            'danger':    'alert-danger',
+            'error':     'alert-danger',
+            'hint':      'alert-secondary',
+            'important': 'alert-primary',
+            'note':      'alert-info',
+            'seealso':   'alert-info',
+            'tip':       'alert-info',
+            'warning':   'alert-warning',
+        }
+
+        self.body.append(self.starttag(
+            node, 'div', CLASS=('alert ' + admonitionclasses[name])))
+        if name:
+            self.body.append(self.starttag(node, 'div', '', CLASS='h5'))
+            self.body.append(str(admonitionlabels[name]))
+            self.body.append('</div>')
+
+    def depart_admonition(self, node) -> None:
+        self.body.append('</div>\n')
+
+    def visit_table(self, node):
+        # init the attributes
+        atts = {}
+
+        self._table_row_indices.append(0)
+
+        # get the classes
+        classes = [cls.strip(" \t\n") for cls in self.settings.table_style.split(",")]
+
+        # we're looking at the 'real_table', which is wrapped by an autosummary
+        if isinstance(node.parent, autosummary_table):
+            classes += ["autosummary"]
+
+        # add the width if set in a style attribute
+        if "width" in node:
+            atts["style"] = f'width: {node["width"]}'
+
+        # add specific class if align is set
+        if "align" in node:
+            classes.append(f'table-{node["align"]}')
+
+        tag = self.starttag(node, "table", CLASS=" ".join(classes), **atts)
+        self.body.append(tag)
+
+
+def setup_translators(app):
+    if app.builder.format != "html":
+        return
+
+    if not app.registry.translators.items():
+        translator = types.new_class(
+            "BootstrapHTML5Translator",
+            (
+                BootstrapHTML5TranslatorMixin,
+                app.builder.default_translator_class,
+            ),
+            {},
+        )
+        app.set_translator(app.builder.name, translator, override=True)
+    else:
+        for name, klass in app.registry.translators.items():
+            translator = types.new_class(
+                "BootstrapHTML5Translator",
+                (
+                    BootstrapHTML5TranslatorMixin,
+                    klass,
+                ),
+                {},
+            )
+            app.set_translator(name, translator, override=True)
+
+
+def setup(app):
+    app.connect("builder-inited", setup_translators)

docs/_exts/depfile.py

@@ -0,0 +1,36 @@
+# Copyright © 2021 Collabora Ltd
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sub license, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice (including the
+# next paragraph) shall be included in all copies or substantial portions
+# of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
+# IN NO EVENT SHALL VMWARE AND/OR ITS SUPPLIERS BE LIABLE FOR
+# ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+def create_depfile(app, env):
+    if not app.config.depfile:
+        return
+
+    with open(app.config.depfile, 'w') as f:
+        for doc in env.found_docs:
+            path = env.doc2path(doc)
+            f.write('{0}: {1}\n'.format(app.outdir, path))
+
+
+def setup(app):
+    app.add_config_value('depfile', None, 'env')
+    app.connect('env-updated', create_depfile)

docs/_exts/formatting.py

@@ -0,0 +1,50 @@
+# formatting.py
+# Sphinx extension providing formatting for Gallium-specific data
+# (c) Corbin Simpson 2010
+# Public domain to the extent permitted; contact author for special licensing
+
+import sphinx.addnodes
+
+from sphinx.util.nodes import split_explicit_title
+from docutils import nodes, utils
+
+
+def parse_opcode(env, sig, signode):
+    opcode, desc = sig.split("-", 1)
+    opcode = opcode.strip().upper()
+    desc = " (%s)" % desc.strip()
+    signode += sphinx.addnodes.desc_name(opcode, opcode)
+    signode += sphinx.addnodes.desc_annotation(desc, desc)
+    return opcode
+
+
+def ext_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+    text = utils.unescape(text)
+    has_explicit_title, title, ext = split_explicit_title(text)
+
+    parts = ext.split('_', 2)
+    if parts[0] == 'VK':
+        full_url = f'https://docs.vulkan.org/refpages/latest/refpages/source/{ext}.html'
+    elif parts[0] == 'GL':
+        full_url = f'https://registry.khronos.org/OpenGL/extensions/{parts[1]}/{parts[1]}_{parts[2]}.txt'
+    else:
+        raise Exception(f'Unexpected API: {parts[0]}')
+
+    pnode = nodes.reference(title, title, internal=False, refuri=full_url)
+    return [pnode], []
+
+
+def vkfeat_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+    text = utils.unescape(text)
+    has_explicit_title, title, ext = split_explicit_title(text)
+
+    full_url = f'https://docs.vulkan.org/spec/latest/chapters/features.html#features-{ext}'
+
+    pnode = nodes.reference(title, title, internal=False, refuri=full_url)
+    return [pnode], []
+
+
+def setup(app):
+    app.add_object_type("opcode", "opcode", "%s (TGSI opcode)", parse_opcode)
+    app.add_role('ext', ext_role)
+    app.add_role('vk-feat', vkfeat_role)

docs/_exts/nir.py

@@ -0,0 +1,158 @@
+# Copyright © 2021 Intel Corporation
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sub license, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice (including the
+# next paragraph) shall be included in all copies or substantial portions
+# of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
+# IN NO EVENT SHALL VMWARE AND/OR ITS SUPPLIERS BE LIABLE FOR
+# ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+import docutils.nodes
+import mako.template
+import os
+import sphinx
+from sphinx.directives import SphinxDirective
+from sphinx.domains import Domain
+from sphinx.util.nodes import make_refnode
+import sys
+import textwrap
+
+THIS_DIR = os.path.dirname(os.path.abspath(__file__))
+MESA_DIR = os.path.join(THIS_DIR, '..', '..')
+NIR_PATH = os.path.join(MESA_DIR, 'src', 'compiler', 'nir')
+sys.path.append(NIR_PATH)
+
+import nir_opcodes
+
+OP_DESC_TEMPLATE = mako.template.Template("""
+<%
+def src_decl_list(num_srcs):
+   return ', '.join('nir_def *src' + str(i) for i in range(num_srcs))
+
+def to_yn(b):
+    return 'Y' if b else 'N'
+%>
+
+**Properties:**
+
+.. list-table::
+   :header-rows: 1
+
+   * - Per-component
+     - Associative
+     - 2-src commutative
+   * - ${to_yn(op.output_size == 0)}
+     - ${to_yn('associative' in op.algebraic_properties)}
+     - ${to_yn('2src_commutative' in op.algebraic_properties)}
+
+${("**Description:** " + op.description) if op.description != "" else ""}
+
+**Constant-folding:**
+
+.. code-block:: c
+
+${textwrap.indent(op.const_expr, '    ')}
+
+**Builder function:**
+
+.. c:function:: nir_def *nir_${op.name}(nir_builder *, ${src_decl_list(op.num_inputs)})
+""")
+
+
+def parse_rst(state, parent, rst):
+    vl = docutils.statemachine.ViewList(rst.splitlines())
+    state.nested_parse(vl, 0, parent)
+
+
+def nir_alu_type_name(t, s):
+    if s:
+        return '{}[{}]'.format(t, s)
+    else:
+        return '{}[N]'.format(t)
+
+
+def build_alu_op_desc(state, env, op):
+    desc = sphinx.addnodes.desc(domain='nir', objtype='aluop')
+
+    # Add the signature
+    sig = sphinx.addnodes.desc_signature()
+    desc.append(sig)
+    sig += sphinx.addnodes.desc_name(op.name, op.name)
+
+    params = sphinx.addnodes.desc_parameterlist()
+    for i, t, s in zip(range(100), op.input_types, op.input_sizes):
+        params += docutils.nodes.Text(nir_alu_type_name(t, s) + ' ')
+        params += sphinx.addnodes.desc_parameter('', 'src' + str(i))
+    sig += params
+
+    sig += sphinx.addnodes.desc_returns('', nir_alu_type_name(op.output_type, op.output_size))
+
+    nir_domain = env.get_domain('nir')
+    sig['ids'].append(nir_domain.add_alu_op_ref(op))
+
+    # Build the description
+    content = sphinx.addnodes.desc_content()
+    desc.append(content)
+    parse_rst(state, content, OP_DESC_TEMPLATE.render(op=op, textwrap=textwrap))
+
+    return desc
+
+
+class NIRALUOpcodesDirective(SphinxDirective):
+    def run(self):
+        return [build_alu_op_desc(self.state, self.env, op)
+                for op in nir_opcodes.opcodes.values()]
+
+
+class NIRDomain(Domain):
+    """A new NIR directive
+
+    To list all NIR ALU opcodes with their descriptions:
+    ```rst
+    .. nir:alu-opcodes::
+    ```
+
+    To reference a NIR opcode, ``:nir:alu-op:`fadd```
+    """
+    name = 'nir'
+    roles = {
+        'alu-op': sphinx.roles.XRefRole(),
+    }
+    directives = {
+        'alu-opcodes': NIRALUOpcodesDirective,
+    }
+    initial_data = {
+        'alu-op-refs': [],
+    }
+
+    def add_alu_op_ref(self, op):
+        """Add reference to an ALU op."""
+        self.data['alu-op-refs'].append((op.name, self.env.docname))
+        return 'nir-alu-op-' + op.name
+
+    def resolve_xref(self, env, fromdocname, builder, typ, target, node,
+                     contnode):
+        for opname, todocname in self.data['alu-op-refs']:
+            if target == opname:
+                targ = 'nir-alu-op-' + opname
+                return make_refnode(builder, fromdocname, todocname, targ,
+                                    contnode, targ)
+
+        return None
+
+
+def setup(app):
+    app.add_domain(NIRDomain)