xref: /external/mesa3d/src/mesa/main/APIspec.py

#!/usr/bin/python
#
# Copyright (C) 2009 Chia-I Wu <olv@0xlab.org>
#
# 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
# on 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
# IBM 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.
"""
A parser for APIspec.
"""

class SpecError(Exception):
    """Error in the spec file."""


class Spec(object):
    """A Spec is an abstraction of the API spec."""

    def __init__(self, doc):
        self.doc = doc

        self.spec_node = doc.getRootElement()
        self.tmpl_nodes = {}
        self.api_nodes = {}
        self.impl_node = None

        # parse <apispec>
        node = self.spec_node.children
        while node:
            if node.type == "element":
                if node.name == "template":
                    self.tmpl_nodes[node.prop("name")] = node
                elif node.name == "api":
                    self.api_nodes[node.prop("name")] = node
                else:
                    raise SpecError("unexpected node %s in apispec" %
                            node.name)
            node = node.next

        # find an implementation
        for name, node in self.api_nodes.iteritems():
            if node.prop("implementation") == "true":
                self.impl_node = node
                break
        if not self.impl_node:
            raise SpecError("unable to find an implementation")

    def get_impl(self):
        """Return the implementation."""
        return API(self, self.impl_node)

    def get_api(self, name):
        """Return an API."""
        return API(self, self.api_nodes[name])


class API(object):
    """An API consists of categories and functions."""

    def __init__(self, spec, api_node):
        self.name = api_node.prop("name")
        self.is_impl = (api_node.prop("implementation") == "true")

        self.categories = []
        self.functions = []

        # parse <api>
        func_nodes = []
        node = api_node.children
        while node:
            if node.type == "element":
                if node.name == "category":
                    cat = node.prop("name")
                    self.categories.append(cat)
                elif node.name == "function":
                    func_nodes.append(node)
                else:
                    raise SpecError("unexpected node %s in api" % node.name)
            node = node.next

        # realize functions
        for func_node in func_nodes:
            tmpl_node = spec.tmpl_nodes[func_node.prop("template")]
            try:
                func = Function(tmpl_node, func_node, self.is_impl,
                                self.categories)
            except SpecError, e:
                func_name = func_node.prop("name")
                raise SpecError("failed to parse %s: %s" % (func_name, e))
            self.functions.append(func)

    def match(self, func, conversions={}):
        """Find a matching function in the API."""
        match = None
        need_conv = False
        for f in self.functions:
            matched, conv = f.match(func, conversions)
            if matched:
                match = f
                need_conv = conv
                # exact match
                if not need_conv:
                    break
        return (match, need_conv)


class Function(object):
    """Parse and realize a <template> node."""

    def __init__(self, tmpl_node, func_node, force_skip_desc=False, categories=[]):
        self.tmpl_name = tmpl_node.prop("name")
        self.direction = tmpl_node.prop("direction")

        self.name = func_node.prop("name")
        self.prefix = func_node.prop("default_prefix")
        self.is_external = (func_node.prop("external") == "true")

        if force_skip_desc:
            self._skip_desc = True
        else:
            self._skip_desc = (func_node.prop("skip_desc") == "true")

        self._categories = categories

        # these attributes decide how the template is realized
        self._gltype = func_node.prop("gltype")
        if func_node.hasProp("vector_size"):
            self._vector_size = int(func_node.prop("vector_size"))
        else:
            self._vector_size = 0
        self._expand_vector = (func_node.prop("expand_vector") == "true")

        self.return_type = "void"
        param_nodes = []

        # find <proto>
        proto_node = tmpl_node.children
        while proto_node:
            if proto_node.type == "element" and proto_node.name == "proto":
                break
            proto_node = proto_node.next
        if not proto_node:
            raise SpecError("no proto")
        # and parse it
        node = proto_node.children
        while node:
            if node.type == "element":
                if node.name == "return":
                    self.return_type = node.prop("type")
                elif node.name == "param" or node.name == "vector":
                    if self.support_node(node):
                        # make sure the node is not hidden
                        if not (self._expand_vector and
                                (node.prop("hide_if_expanded") == "true")):
                            param_nodes.append(node)
                else:
                    raise SpecError("unexpected node %s in proto" % node.name)
            node = node.next

        self._init_params(param_nodes)
        self._init_descs(tmpl_node, param_nodes)

    def __str__(self):
        return "%s %s%s(%s)" % (self.return_type, self.prefix, self.name,
                self.param_string(True))

    def _init_params(self, param_nodes):
        """Parse and initialize parameters."""
        self.params = []

        for param_node in param_nodes:
            size = self.param_node_size(param_node)
            # when no expansion, vector is just like param
            if param_node.name == "param" or not self._expand_vector:
                param = Parameter(param_node, self._gltype, size)
                self.params.append(param)
                continue

            if not size or size > param_node.lsCountNode():
                raise SpecError("could not expand %s with unknown or "
                                "mismatch sizes" % param.name)

            # expand the vector
            expanded_params = []
            child = param_node.children
            while child:
                if (child.type == "element" and child.name == "param" and
                    self.support_node(child)):
                    expanded_params.append(Parameter(child, self._gltype))
                    if len(expanded_params) == size:
                        break
                child = child.next
            # just in case that lsCountNode counts unknown nodes
            if len(expanded_params) < size:
                raise SpecError("not enough named parameters")

            self.params.extend(expanded_params)

    def _init_descs(self, tmpl_node, param_nodes):
        """Parse and initialize parameter descriptions."""
        self.checker = Checker()
        if self._skip_desc:
            return

        node = tmpl_node.children
        while node:
            if node.type == "element" and node.name == "desc":
                if self.support_node(node):
                    # parse <desc>
                    desc = Description(node, self._categories)
                    self.checker.add_desc(desc)
            node = node.next

        self.checker.validate(self, param_nodes)

    def support_node(self, node):
        """Return true if a node is in the supported category."""
        return (not node.hasProp("category") or
                node.prop("category") in self._categories)

    def get_param(self, name):
        """Return the named parameter."""
        for param in self.params:
            if param.name == name:
                return param
        return None

    def param_node_size(self, param):
        """Return the size of a vector."""
        if param.name != "vector":
            return 0

        size = param.prop("size")
        if size.isdigit():
            size = int(size)
        else:
            size = 0
        if not size:
            size = self._vector_size
            if not size and self._expand_vector:
                # return the number of named parameters
                size = param.lsCountNode()
        return size

    def param_string(self, declaration):
        """Return the C code of the parameters."""
        args = []
        if declaration:
            for param in self.params:
                sep = "" if param.type.endswith("*") else " "
                args.append("%s%s%s" % (param.type, sep, param.name))
            if not args:
                args.append("void")
        else:
            for param in self.params:
                args.append(param.name)
        return ", ".join(args)

    def match(self, other, conversions={}):
        """Return true if the functions match, probably with a conversion."""
        if (self.tmpl_name != other.tmpl_name or
            self.return_type != other.return_type or
            len(self.params) != len(other.params)):
            return (False, False)

        need_conv = False
        for i in xrange(len(self.params)):
            src = other.params[i]
            dst = self.params[i]
            if (src.is_vector != dst.is_vector or src.size != dst.size):
                return (False, False)
            if src.type != dst.type:
                if dst.base_type() in conversions.get(src.base_type(), []):
                    need_conv = True
                else:
                    # unable to convert
                    return (False, False)

        return (True, need_conv)


class Parameter(object):
    """A parameter of a function."""

    def __init__(self, param_node, gltype=None, size=0):
        self.is_vector = (param_node.name == "vector")

        self.name = param_node.prop("name")
        self.size = size

        type = param_node.prop("type")
        if gltype:
            type = type.replace("GLtype", gltype)
        elif type.find("GLtype") != -1:
            raise SpecError("parameter %s has unresolved type" % self.name)

        self.type = type

    def base_type(self):
        """Return the base GL type by stripping qualifiers."""
        return [t for t in self.type.split(" ") if t.startswith("GL")][0]


class Checker(object):
    """A checker is the collection of all descriptions on the same level.
    Descriptions of the same parameter are concatenated.
    """

    def __init__(self):
        self.switches = {}
        self.switch_constants = {}

    def add_desc(self, desc):
        """Add a description."""
        # TODO allow index to vary
        const_attrs = ["index", "error", "convert", "size_str"]
        if desc.name not in self.switches:
            self.switches[desc.name] = []
            self.switch_constants[desc.name] = {}
            for attr in const_attrs:
                self.switch_constants[desc.name][attr] = None

        # some attributes, like error code, should be the same for all descs
        consts = self.switch_constants[desc.name]
        for attr in const_attrs:
            if getattr(desc, attr) is not None:
                if (consts[attr] is not None and
                    consts[attr] != getattr(desc, attr)):
                    raise SpecError("mismatch %s for %s" % (attr, desc.name))
                consts[attr] = getattr(desc, attr)

        self.switches[desc.name].append(desc)

    def validate(self, func, param_nodes):
        """Validate the checker against a function."""
        tmp = Checker()

        for switch in self.switches.itervalues():
            valid_descs = []
            for desc in switch:
                if desc.validate(func, param_nodes):
                    valid_descs.append(desc)
            # no possible values
            if not valid_descs:
                return False
            for desc in valid_descs:
                if not desc._is_noop:
                    tmp.add_desc(desc)

        self.switches = tmp.switches
        self.switch_constants = tmp.switch_constants
        return True

    def flatten(self, name=None):
        """Return a flat list of all descriptions of the named parameter."""
        flat_list = []
        for switch in self.switches.itervalues():
            for desc in switch:
                if not name or desc.name == name:
                    flat_list.append(desc)
                flat_list.extend(desc.checker.flatten(name))
        return flat_list

    def always_check(self, name):
        """Return true if the parameter is checked in all possible pathes."""
        if name in self.switches:
            return True

        # a param is always checked if any of the switch always checks it
        for switch in self.switches.itervalues():
            # a switch always checks it if all of the descs always check it
            always = True
            for desc in switch:
                if not desc.checker.always_check(name):
                    always = False
                    break
            if always:
                return True
        return False

    def _c_switch(self, name, indent="\t"):
        """Output C switch-statement for the named parameter, for debug."""
        switch = self.switches.get(name, [])
        # make sure there are valid values
        need_switch = False
        for desc in switch:
            if desc.values:
                need_switch = True
        if not need_switch:
            return []

        stmts = []
        var = switch[0].name
        if switch[0].index >= 0:
            var += "[%d]" % switch[0].index
        stmts.append("switch (%s) { /* assume GLenum */" % var)

        for desc in switch:
            if desc.values:
                for val in desc.values:
                    stmts.append("case %s:" % val)
                for dep_name in desc.checker.switches.iterkeys():
                    dep_stmts = [indent + s for s in desc.checker._c_switch(dep_name, indent)]
                    stmts.extend(dep_stmts)
                stmts.append(indent + "break;")

        stmts.append("default:")
        stmts.append(indent + "ON_ERROR(%s);" % switch[0].error);
        stmts.append(indent + "break;")
        stmts.append("}")

        return stmts

    def dump(self, indent="\t"):
        """Dump the descriptions in C code."""
        stmts = []
        for name in self.switches.iterkeys():
            c_switch = self._c_switch(name)
            print "\n".join(c_switch)


class Description(object):
    """A description desribes a parameter and its relationship with other
    parameters.
    """

    def __init__(self, desc_node, categories=[]):
        self._categories = categories
        self._is_noop = False

        self.name = desc_node.prop("name")
        self.index = -1

        self.error = desc_node.prop("error") or "GL_INVALID_ENUM"
        # vector_size may be C code
        self.size_str = desc_node.prop("vector_size")

        self._has_enum = False
        self.values = []
        dep_nodes = []

        # parse <desc>
        valid_names = ["value", "range", "desc"]
        node = desc_node.children
        while node:
            if node.type == "element":
                if node.name in valid_names:
                    # ignore nodes that require unsupported categories
                    if (node.prop("category") and
                        node.prop("category") not in self._categories):
                        node = node.next
                        continue
                else:
                    raise SpecError("unexpected node %s in desc" % node.name)

                if node.name == "value":
                    val = node.prop("name")
                    if not self._has_enum and val.startswith("GL_"):
                        self._has_enum = True
                    self.values.append(val)
                elif node.name == "range":
                    first = int(node.prop("from"))
                    last = int(node.prop("to"))
                    base = node.prop("base") or ""
                    if not self._has_enum and base.startswith("GL_"):
                        self._has_enum = True
                    # expand range
                    for i in xrange(first, last + 1):
                        self.values.append("%s%d" % (base, i))
                else: # dependent desc
                    dep_nodes.append(node)
            node = node.next

        # default to convert if there is no enum
        self.convert = not self._has_enum
        if desc_node.hasProp("convert"):
            self.convert = (desc_node.prop("convert") == "true")

        self._init_deps(dep_nodes)

    def _init_deps(self, dep_nodes):
        """Parse and initialize dependents."""
        self.checker = Checker()

        for dep_node in dep_nodes:
            # recursion!
            dep = Description(dep_node, self._categories)
            self.checker.add_desc(dep)

    def _search_param_node(self, param_nodes, name=None):
        """Search the template parameters for the named node."""
        param_node = None
        param_index = -1

        if not name:
            name = self.name
        for node in param_nodes:
            if name == node.prop("name"):
                param_node = node
            elif node.name == "vector":
                child = node.children
                idx = 0
                while child:
                    if child.type == "element" and child.name == "param":
                        if name == child.prop("name"):
                            param_node = node
                            param_index = idx
                            break
                        idx += 1
                    child = child.next
            if param_node:
                break
        return (param_node, param_index)

    def _find_final(self, func, param_nodes):
        """Find the final parameter."""
        param = func.get_param(self.name)
        param_index = -1

        # the described param is not in the final function
        if not param:
            # search the template parameters
            node, index = self._search_param_node(param_nodes)
            if not node:
                raise SpecError("invalid desc %s in %s" %
                        (self.name, func.name))

            # a named parameter of a vector
            if index >= 0:
                param = func.get_param(node.prop("name"))
                param_index = index
            elif node.name == "vector":
                # must be an expanded vector, check its size
                if self.size_str and self.size_str.isdigit():
                    size = int(self.size_str)
                    expanded_size = func.param_node_size(node)
                    if size != expanded_size:
                        return (False, None, -1)
            # otherwise, it is a valid, but no-op, description

        return (True, param, param_index)

    def validate(self, func, param_nodes):
        """Validate a description against certain function."""
        if self.checker.switches and not self.values:
            raise SpecError("no valid values for %s" % self.name)

        valid, param, param_index = self._find_final(func, param_nodes)
        if not valid:
            return False

        # the description is valid, but the param is gone
        # mark it no-op so that it will be skipped
        if not param:
            self._is_noop = True
            return True

        if param.is_vector:
            # if param was known, this should have been done in __init__
            if self._has_enum:
                self.size_str = "1"
            # size mismatch
            if (param.size and self.size_str and self.size_str.isdigit() and
                param.size != int(self.size_str)):
                return False
        elif self.size_str:
            # only vector accepts vector_size
            raise SpecError("vector_size is invalid for %s" % param.name)

        if not self.checker.validate(func, param_nodes):
            return False

        # update the description
        self.name = param.name
        self.index = param_index

        return True


def main():
    import libxml2

    filename = "APIspec.xml"
    apinames = ["GLES1.1", "GLES2.0"]

    doc = libxml2.readFile(filename, None,
            libxml2.XML_PARSE_DTDLOAD +
            libxml2.XML_PARSE_DTDVALID +
            libxml2.XML_PARSE_NOBLANKS)

    spec = Spec(doc)
    impl = spec.get_impl()
    for apiname in apinames:
        spec.get_api(apiname)

    doc.freeDoc()

    print "%s is successfully parsed" % filename


if __name__ == "__main__":
    main()