#!/usr/bin/env fuchsia-vendored-python
# Copyright 2019 The Fuchsia Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.

import json
import re
import textwrap
import sys


def usage():
    print(
        "Usage:\n"
        "  magma_h_gen.py INPUT OUTPUT\n"
        "    INPUT    json file containing the magma interface definition\n"
        "    OUTPUT   destination path for the magma header file to generate\n"
        "  Example: ./magma_h_gen.py ./magma.json ./magma.h\n"
        "  Generates the magma header based on a provided json definition.\n"
        "  Description fields are generated in the Doxygen format."
    )


# Generate a string for a comment with a Doxygen tag, wrapping text as necessary.
def format_comment(type, comment):
    wrap = 100
    prefix_first = "/// \\" + type + " "
    prefix_len = len(prefix_first)
    prefix_rest = "///".ljust(prefix_len)
    lines = textwrap.wrap(comment, wrap - prefix_len)
    formatted = [f"{prefix_first}{lines[0]}"]
    formatted.extend(f"{prefix_rest}{line}" for line in lines[1:])
    return "\n".join(formatted)


# Generate a string for a magma export object, including its comment block.
def format_export(export):
    # Verify no use of "struct" in types - these should use type_t instead.
    for arg in export["arguments"]:
        m = re.search(r"(.*)struct ([^\*]*)(\**)", arg["type"])
        if m:
            print(
                f'Error in {export["name"]}: Argument type "{arg["type"]}" appears to be a struct.'
                f' Did you mean to use "{m.group(1)}{m.group(2)}_t{m.group(3)}"?'
            )
            sys.exit(-1)
    # Leading comment
    lines = [f'///\n{format_comment("brief", export["description"])}']
    lines.extend(
        format_comment("param", f'{arg["name"]} {arg["description"]}')
        for arg in export["arguments"]
    )
    lines.append("///")
    # Function signature
    lines.append(f'MAGMA_EXPORT {export["type"]} {export["name"]}(')
    lines.append(
        ",\n".join(
            f'    {arg["type"]} {arg["name"]}' for arg in export["arguments"]
        )
    )
    lines[-1] = f"{lines[-1]});"
    lines.append("")
    return "\n".join(lines)


# License string for the top of the file.
def license():
    return (
        "// Copyright 2016 The Fuchsia Authors. All rights reserved.\n"
        "// Use of this source code is governed by a BSD-style license that can be\n"
        "// found in the LICENSE file.\n"
    )


def top_level_docs():
    return (
        "// Magma is the driver model for GPUs/NPUs on Fuchsia.\n"
        "//\n"
        '// Magma has two driver components: a hardware-specific library loaded into an "application"’s\n'
        '// address space ("client driver", sometimes known as "Installable client driver" or "ICD");\n'
        "// and a system driver that interfaces with the hardware. Magma is described in detail at [0].\n"
        "//\n"
        "// The Magma APIs are vendor independent. Some drivers may implement only the subset of the\n"
        "// APIs that are relevant. The format of data carried inside commands/command buffers is not\n"
        "// defined. Some APIs are explicitly extensible, such as magma_query, to allow for specific\n"
        "// vendor/driver needs.  Vendor specifics must be contained in a separate definitions file.\n"
        "//\n"
        "// Since client driver implementations may be written in a variety of languages (possibly C),\n"
        "// the Magma bindings have a C interface, and may be used to interact with both Magma and Sysmem.\n"
        "//\n"
        "// The Magma bindings are OS independent so a client driver targeting Magma can easily be built\n"
        "// for Fuchsia or Linux. On Fuchsia the APIs are backed by Zircon and FIDL; for virtualized Linux\n"
        "// they are backed by a virtualization transport (virtmagma). APIs prefixed by 'magma_virt_' are\n"
        "// for virtualization only.  32-bit and 64-bit builds are supported for virtualized clients.\n"
        "//\n"
        "// On Fuchsia the system driver is a separate process, so Magma APIs follow a feed forward design\n"
        "// where possible to allow for efficient pipelining of requests.\n"
        "//\n"
        "// [0] https://fuchsia.dev/fuchsia-src/contribute/governance/rfcs/0198_magma_api_design\n"
        "//\n"
    )


# Guard macro that goes at the beginning/end of the header (after license).
def guards(begin):
    macro = "LIB_MAGMA_MAGMA_H_"
    if begin:
        return f"#ifndef {macro}\n#define {macro}\n"
    return f"#endif  // {macro}"


# Begin/end C linkage scope.
def externs(begin):
    if begin:
        return '#if defined(__cplusplus)\nextern "C" {\n#endif\n'
    return "#if defined(__cplusplus)\n}\n#endif\n"


# Includes list.
def includes():
    return (
        "#include <lib/magma/magma_common_defs.h> // IWYU pragma: export\n"
        "#include <stdint.h>\n"
    )


# Warning comment about auto-generation.
def genwarning():
    return (
        "// NOTE: DO NOT EDIT THIS FILE!\n"
        "// It is automatically generated by //src/graphics/lib/magma/include/magma/magma_h_gen.py\n"
    )


def genformatoff():
    return "// clang-format off\n"


def ifchange():
    return "// LINT.IfChange"


def thenchange():
    return "// LINT.ThenChange(magma_common_defs.h:version)"


def main():
    if len(sys.argv) != 3:
        usage()
        return 2
    try:
        with open(sys.argv[1], "r") as file:
            with open(sys.argv[2], "w") as dest:
                magma = json.load(file)["magma-interface"]
                lines = [
                    license(),
                    top_level_docs(),
                    genwarning(),
                    genformatoff(),
                    guards(True),
                    includes(),
                    ifchange(),
                    externs(True),
                ]
                lines.extend(format_export(e) for e in magma["exports"])
                lines.append(externs(False))
                lines.append(thenchange())
                lines.append(guards(False))
                lines.append("")
                dest.write("\n".join(lines))
    except Exception as e:
        print(f"Error accessing files: {e}")
        usage()
        return 1


if __name__ == "__main__":
    sys.exit(main())