hat/schema/hat.tosd

# HAT TOML Schema
[toml-schema]
version = "0.0.0.3"

# Types to be used elsewhere in this schema
[types]

    # Parameter type of arguments and return values
    [types.paramType]
    type = "table"

        # Name of the parameter
        [types.paramType.name]
        type = "string"

        # Friendly string describing the parameter
        [types.paramType.description]
        type = "string"

        # The logical type of the parameter, such as if it's really a multi-dimensional array
        [types.paramType.logical_type]
        type = "string"
        allowedvalues = ["affine_array", "runtime_array", "void", "element"]

        # The declared type of the parameter as a valid C type declaration
        [types.paramType.declared_type]
        type = "string"

        # The type of elements in the parameter. E.g. "float" if the declared type is "const float*", "float*", or "float"
        [types.paramType.element_type]
        type = "string"

        # The usage of the parameter in the context of the function
        [types.paramType.usage]
        type = "string"
        allowedvalues = [ "input_output", "input", "output" ]

        # Optional array giving the logical shape of the buffer for an affine_array logical type, e.g. [256, 256]
        [types.paramType.shape]
        type = "array"
        arraytype = "integer"
        optional = true

        # Optional array giving the affine map coefficients used to map from multi-dimensional coordinates to an
        # offset in the C-style array buffer for an affine_array logical type.
        # e.g. [256, 1] would indicate that for index (i, j), the position in the buffer is (256 * i) + (1 * j)
        # Should have the same number of elements as the shape array
        [types.paramType.affine_map]
        type = "array"
        arraytype = "integer"
        optional = true

        # Offset from the buffer pointer where the array data begins for an affine_array logical type.
        [types.paramType.affine_offset]
        type = "integer"
        optional = true

        # A string describing the number of elements in the buffer for a runtime_array logical type.
        # Typically expected to reference other parameters in the function in their shape order.
        # e.g. "N", "lda * K" for shape (lda, K)
        [types.paramType.size]
        type = "string"
        optional = true

    # Type for a function described by TOML data and declared in the C declaration later in the HAT file
    [types.functionType]
    type = "table"

        ##########
        # Required
        ##########

        # The name of the function
        [types.functionType.name]
        type = "string"

        # A friendly description of what the function does
        [types.functionType.description]
        type = "string"

        # The calling convention for this function
        [types.functionType.calling_convention]
        type = "string"
        allowedvalues = [ "stdcall", "cdecl", "fastcall", "vectorcall", "device" ]

        # An array of arguments to the function
        [types.functionType.arguments]
        type = "array"
        arraytype = "types.paramType"

        # The return type description of the function
        [types.functionType.return]
        typeof = "paramType"

        ##########
        # Optional
        ##########

        # The parameters needed to launch this function, if applicable
        [types.functionType.launch_parameters]
        type = "array"
        optional = true

        # The dynamic shared memory size in bytes to be allocated for this device function
        [types.functionType.dynamic_shared_mem_bytes]
        type = "integer"
        optional = true

        # The function that is launched by this function
        [types.functionType.launches]
        type = "string"
        optional = true

        # The provider of this function, if any
        [types.functionType.provider]
        type = "string"
        optional = true

        # The runtime used by the function
        [types.functionType.runtime]
        type = "string"
        optional = true

        # Optional additional usage-specific information about the function that isn't part of this schema
        [types.functionType.auxiliary]
        type = "table"
        optional = true

    # Type of an external library referenced by this metadata, such as a library that was linked into this one or a dependency a user must link
    [types.referencedLibraryType]
    type = "table"

        # Friendly name of the library
        [types.referencedLibraryType.name]
        type = "string"

        # Friendly version string of the library
        [types.referencedLibraryType.version]
        type = "string"

        # The name of the library that is linked or a flag to link it with, as could be used by a build system.
        # E.g. "ucrtbase.dll" or "/openmp"
        [types.referencedLibraryType.target_file]
        type = "string"


# Definition of the well-known tables/keys/etc in HAT TOML data
[elements]

    # Description of the HAT contents
    [elements.description]
    type = "table"

        # Optional user-specified author name
        [elements.description.author]
        type = "string"
        optional = true

        # Version number of the HAT package
        [elements.description.version]
        type = "string"

        # Url to the full license text for this package
        [elements.description.license_url]
        type = "string"

        # Optional additional description that isn't part of this schema
        [elements.description.auxiliary]
        type = "table"
        optional = true

    # Collection of host functions declared within the HAT file and their metadata
    # The keys in a collection are not prescribed by the schema, and in this case are the names of the functions as the HAT format does not support function overloading.
    [elements.functions]
    type = "collection"
    typeof = "functionType"

    # Collection of device functions declared within the HAT file and their metadata
    # The keys in a collection are not prescribed by the schema, and in this case are the names of the functions as the HAT format does not support function overloading.
    [elements.device_functions]
    type = "collection"
    typeof = "functionType"

    # Table of information about the target device the functions described in this HAT file are intended to be used with
    [elements.target]
    type = "table"

        # Required target features in order to run these functions without error
        [elements.target.required]
        type = "table"

            # The OS that this HAT package is built for
            [elements.target.required.os]
            type = "string"
            allowedvalues = [ "windows", "macos", "linux" ]

            # Required CPU characteristics
            [elements.target.required.CPU]
            type = "table"

                # Instruction set architecture, e.g. "x86_64"
                [elements.target.required.CPU.architecture]
                type = "string"

                # Instruction set extensions used by these functions, e.g. "AVX2", "AVX512", etc
                [elements.target.required.CPU.extensions]
                type = "array"
                arraytype = "string"

                # Optional CPU runtime library
                [elements.target.required.CPU.runtime]
                type = "string"
                allowedvalues = [ "openmp" ]
                optional = true

                # Optional additional information not defined in this schema
                [elements.target.required.CPU.auxiliary]
                type = "table"
                optional = true

            # Required GPU characteristics if there are GPU functions in this HAT package
            [elements.target.required.GPU]
            type = "table"
            optional = true

                # Required GPU runtime library
                [elements.target.required.GPU.runtime]
                type = "string"
                allowedvalues = [ "cuda", "rocm", "vulkan" ]

                # Minimum GPU instruction set version
                [elements.target.required.GPU.instruction_set_version]
                type = "string"

                # Minimum number of GPU threads functions declared in this .hat file will attempt to use
                [elements.target.required.GPU.min_threads]
                type = "integer"

                # Minimum global memory in KB that will be allocated
                [elements.target.required.GPU.min_global_memory_KB]
                type = "integer"

                # Minimum shared memory in KB that will be allocated
                [elements.target.required.GPU.min_shared_memory_KB]
                type = "integer"

                # Minimum texture memory in KB that will be allocated
                [elements.target.required.GPU.min_texture_memory_KB]
                type = "integer"

                # Optional additional requirements not specified in this schema
                [elements.target.required.GPU.auxiliary]
                type = "table"
                optional = true

        # Target characteristics that these functions are optimized for, but are not required in order to function
        [elements.target.optimized_for]
        type = "table"
        optional = true

            # Optimized CPU target information
            [elements.target.optimized_for.CPU]
            type = "table"
            optional = true

                # Full name and version of the CPU, e.g. "Intel Xeon E5-4669 v4"
                [elements.target.optimized_for.CPU.name]
                type = "string"

                # Processor family, e.g. "Broadwell"
                [elements.target.optimized_for.CPU.family]
                type = "string"

                # Base processor clock speed
                [elements.target.optimized_for.CPU.clock_frequency]
                type = "integer"

                # Number of CPU cores
                [elements.target.optimized_for.CPU.cores]
                type = "integer"

                # Number of CPU threads
                [elements.target.optimized_for.CPU.threads]
                type = "integer"

                # Optimized cache characteristics
                [elements.target.optimized_for.CPU.cache]
                type = "table"
                optional = true

                    # Instruction cache size in KB
                    [elements.target.optimized_for.CPU.cache.instruction_KB]
                    type = "integer"

                    # Ordered cache sizes in KB
                    [elements.target.optimized_for.CPU.cache.sizes_KB]
                    type = "array"
                    arraytype = "integer"

                    # Ordered cache line sizes in bytes
                    [elements.target.optimized_for.CPU.cache.line_sizes]
                    type = "array"
                    arraytype = "integer"

                # Optional additional optimized target characteristics not specified in this schema
                [elements.target.optimized_for.CPU.auxiliary]
                type = "table"
                optional = true

            # Optimized GPU target information
            [elements.target.optimized_for.GPU]
            type = "table"
            optional = true

                # Full name and version of the GPU, e.g. "NVIDIA GTX 3090"
                [elements.target.optimized_for.GPU.name]
                type = "string"

                # Architecture family, e.g. "Ampere"
                [elements.target.optimized_for.GPU.family]
                type = "string"

                # Base GPU clock speed
                [elements.target.optimized_for.GPU.clock_frequency]
                type = "integer"

                # Best optimized GPU core count
                [elements.target.optimized_for.GPU.cores]
                type = "integer"

                # Best optimized GPU thread count
                [elements.target.optimized_for.GPU.threads]
                type = "integer"

                # Optimized instruction set version
                [elements.target.optimized_for.GPU.instruction_set_version]
                type = "string"

                # Optimized global memory size in KB
                [elements.target.optimized_for.GPU.global_memory_KB]
                type = "integer"

                # Optimized shared memory size in KB
                [elements.target.optimized_for.GPU.shared_memory_KB]
                type = "integer"

                # Optimized shared memory cache line size in bytes
                [elements.target.optimized_for.GPU.shared_memory_line_size]
                type = "integer"

                # Optimized texture memory size in KB
                [elements.target.optimized_for.GPU.texture_memory_KB]
                type = "integer"

                # Optional additional optimized target characteristics not specified in this schema
                [elements.target.optimized_for.GPU.auxiliary]
                type = "table"
                optional = true

    # Table describing dependencies that consumers of this HAT package will need to
    # provide or otherwise satisfy in order to properly consume the package, such as library
    # files in the package to link and dynamic libraries to make available at runtime
    [elements.dependencies]
    type = "table"

        # Name of the library file in this HAT package that the consumer should link
        [elements.description.link_target]
        type = "string"

        # Names of files in this HAT package that must be deployed with a built binary that consumes this package,
        # such as dynamic library files
        [elements.description.deploy_files]
        type = "array"
        arraytype = "string"

        # Dynamic libraries outside of this HAT package that must be made available at runtime
        [elements.dependencies.dynamic]
        type = "array"
        arraytype = "types.referencedLibraryType"

        # Optonal additonal dependency information not specified in this schema
        [elements.dependencies.auxiliary]
        type = "table"
        optional = true

    # Table giving information about how this HAT package was built. It is expected
    # that a consumer of the package may find this information useful but may not
    # necessarily need to act on in order to successfully consume this package
    [elements.compiled_with]
    type = "table"

        # Compiler name and version, e.g. "MSVC141"
        [elements.compiled_with.compiler]
        type = "string"

        # Compilation flags, e.g. "-std=c++14 -ffast-math"
        [elements.compiled_with.flags]
        type = "string"

        # C Runtime linked against, e.g. "ucrt"
        [elements.compiled_with.crt]
        type = "string"

        # Libraries that were statically linked into the library files in this HAT package
        [elements.compiled_with.libraries]
        type = "array"
        arraytype = "types.referencedLibraryType"

        # Optional additional compilation information not specified in this schema
        [elements.compiled_with.auxiliary]
        type = "table"
        optional = true

    # Table containing the C header code in this HAT file
    [elements.declaration]
    type = "table"

        # String containing the entirety of the C header code
        [elements.declaration.code]
        type = "string"