//===-- Kernel.td - Kernel definitions for Offload ---------*- tablegen -*-===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//
//
// This file contains Offload API definitions related to kernels
//
//===----------------------------------------------------------------------===//

def ol_kernel_launch_size_args_t : Struct {
    let desc = "Size-related arguments for a kernel launch.";
    let members = [
        StructMember<"size_t", "Dimensions", "Number of work dimensions">,
        StructMember<"struct ol_dimensions_t", "NumGroups", "Number of work groups in each dimension">,
        StructMember<"struct ol_dimensions_t", "GroupSize", "Size of a work group in each dimension">,
        StructMember<"size_t", "DynSharedMemory", "Size of dynamic shared memory in bytes.">
    ];
}

def OL_KERNEL_LAUNCH_PROP_END : Macro {
  let desc = "last element of the ol_kernel_launch_prop_t array";
  let value = "{OL_KERNEL_LAUNCH_PROP_TYPE_NONE, NULL}";
}

def ol_kernel_launch_prop_type_t : Enum {
  let desc = "Defines structure type";
  let is_typed = 1;
  let etors =
      [TaggedEtor<"none", "void *", "Used for null terminating property array">,
       TaggedEtor<"is_cooperative ", "bool *", "Cooperative kernel launch">];
}

def ol_kernel_launch_prop_t : Struct {
  let desc = "Optional properties for kernel launch.";
  let members = [StructMember<"ol_kernel_launch_prop_type_t", "type",
                              "Type of the data field">,
                 StructMember<"void *", "data",
                              "Pointer to property-specific data.">];
}

def olLaunchKernel : Function {
    let desc = "Enqueue a kernel launch with arguments specified as an array of pointers and sizes.";
    let details = [
        "If a queue is not specified, kernel execution happens synchronously",
        "Each element of ArgPtrs points to the value of the corresponding kernel argument",
        "Each element of ArgSizes specifies the size in bytes of the corresponding argument",
        "NumArgs must match the number of arguments expected by the kernel",
        "ArgPtrs and ArgSizes must both be NULL (when NumArgs == 0) or both be non-NULL"
    ];
    let params = [
        Param<"ol_queue_handle_t", "Queue", "handle of the queue", PARAM_IN_OPTIONAL>,
        Param<"ol_device_handle_t", "Device", "handle of the device to execute on", PARAM_IN>,
        Param<"ol_symbol_handle_t", "Kernel", "handle of the kernel", PARAM_IN>,
        Param<"const ol_kernel_launch_size_args_t*", "LaunchSizeArgs", "pointer to the struct containing launch size parameters", PARAM_IN>,
        Param<"const ol_kernel_launch_prop_t *", "Properties", "Array of optional properties, last element must be OL_KERNEL_LAUNCH_PROP_END", PARAM_IN_OPTIONAL>,
        Param<"size_t", "NumArgs", "number of kernel arguments", PARAM_IN>,
        Param<"void**", "ArgPtrs", "array of pointers, each pointing to a kernel argument value", PARAM_IN_OPTIONAL>,
        Param<"const size_t*", "ArgSizes", "array of kernel argument sizes", PARAM_IN_OPTIONAL>,
    ];
    let returns = [
        Return<"OL_ERRC_INVALID_ARGUMENT", [
            "`(ArgPtrs == NULL) != (ArgSizes == NULL)`",
            "`NumArgs > 0 && (ArgPtrs == NULL || ArgSizes == NULL)`",
            "NumArgs does not match the number of arguments expected by the kernel",
        ]>,
        Return<"OL_ERRC_INVALID_DEVICE", ["If Queue is non-null but does not belong to Device"]>,
        Return<"OL_ERRC_SYMBOL_KIND", ["The provided symbol is not a kernel"]>,
    ];
}

def olCalculateOptimalOccupancy : Function {
    let desc = "Given dynamic memory size, query the device for a workgroup size that will result in optimal occupancy.";
    let details = [
        "For most devices, this will be the largest workgroup size that will result in all work items fitting on the device at once.",
    ];
    let params = [
        Param<"ol_device_handle_t", "Device", "device intended to run the kernel", PARAM_IN>,
        Param<"ol_symbol_handle_t", "Kernel", "handle of the kernel", PARAM_IN>,
        Param<"size_t", "SharedMemory", "dynamic shared memory required per work item in bytes", PARAM_IN>,
        Param<"size_t*", "GroupSize", "optimal block size", PARAM_OUT>
    ];
    let returns = [
        Return<"OL_ERRC_SYMBOL_KIND", ["The provided symbol is not a kernel"]>,
        Return<"OL_ERRC_UNSUPPORTED", ["The backend cannot provide this information"]>,
    ];
}

def olGetKernelMaxCooperativeGroupCount : Function {
  let desc = "Query the maximum number of work groups that can be launched "
             "cooperatively for a kernel.";
  let details =
      ["This function returns the maximum number of work groups that can "
       "participate in a cooperative launch for the given kernel.",
       "The maximum count depends on the work group size and dynamic shared "
       "memory usage.",
  ];
  let params = [Param<"ol_device_handle_t", "Device",
                      "device intended to run the kernel", PARAM_IN>,
                Param<"ol_symbol_handle_t", "Kernel", "handle of the kernel",
                      PARAM_IN>,
                Param<"const ol_kernel_launch_size_args_t*", "LaunchSizeArgs",
                      "launch size parameters", PARAM_IN>,
                Param<"uint32_t*", "MaxGroupCount",
                      "maximum number of cooperative groups", PARAM_OUT>];
  let returns =
      [Return<"OL_ERRC_SYMBOL_KIND", ["The provided symbol is not a kernel"]>,
       Return<
           "OL_ERRC_UNSUPPORTED", ["Cooperative launch is not supported or "
                                   "backend cannot provide this information"]>,
  ];
}