dpctl/libsyclinterface/include/syclinterface/dpctl_sycl_kernel_bundle_interface.h at dev-milestone · IntelPython/dpctl · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
//===- dpctl_sycl_kernel_bundle_interface.h - C API for
//     sycl::kernel_bundle<sycl::bundle_state::executable>      -*-C++-*- ===//
//
//                      Data Parallel Control (dpctl)
//
// Copyright 2020 Intel Corporation
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//    http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
//===----------------------------------------------------------------------===//
///
/// \file
/// This header declares a C API to create Sycl kernel bundles for OpenCL and
/// Level Zero backends.
///
//===----------------------------------------------------------------------===//

#pragma once

#include "Support/DllExport.h"
#include "Support/ExternC.h"
#include "Support/MemOwnershipAttrs.h"
#include "dpctl_data_types.h"
#include "dpctl_sycl_types.h"

DPCTL_C_EXTERN_C_BEGIN

typedef struct DPCTLSpecConstTy
{
    uint32_t id;
    size_t size;
    const void *value;
} DPCTLSpecConst;

/**
 * @defgroup KernelBundleInterface Kernel_bundle class C wrapper
 */

/*!
 * @brief Create a Sycl kernel_bundle from an OpenCL SPIR-V binary file.
 *
 * Uses SYCL2020 interoperability layer to create sycl::kernel_bundle object
 * in executable state for OpenCL and Level-Zero backends from SPIR-V binary.
 *
 * @param    Ctx            An opaque pointer to a sycl::context
 * @param    Dev            An opaque pointer to a sycl::device
 * @param    IL             SPIR-V binary
 * @param    Length         The size of the IL binary in bytes.
 * @param    CompileOpts    Optional compiler flags used when compiling the
 *                          SPIR-V binary.
 * @param    NumSpecConsts  The number of specialization constants.
 * @param    SpecConsts     An array of specialization constants.
 * @return   A new SyclKernelBundleRef pointer if the kernel_bundle creation
 * succeeded, else returns NULL.
 * @ingroup KernelBundleInterface
 */
DPCTL_API
__dpctl_give DPCTLSyclKernelBundleRef DPCTLKernelBundle_CreateFromSpirv(
    __dpctl_keep const DPCTLSyclContextRef Ctx,
    __dpctl_keep const DPCTLSyclDeviceRef Dev,
    __dpctl_keep const void *IL,
    size_t Length,
    const char *CompileOpts,
    size_t NumSpecConsts,
    __dpctl_keep const DPCTLSpecConst *SpecConsts);

/*!
 * @brief Create a Sycl kernel bundle from an OpenCL kernel source string.
 *
 * @param    Ctx            An opaque pointer to a sycl::context
 * @param    Dev            An opaque pointer to a sycl::device
 * @param    Source         OpenCL source string
 * @param    CompileOpts    Extra compiler flags (refer Sycl spec.)
 * @return   A new SyclKernelBundleRef pointer if the kernel bundle creation
 * succeeded, else returns NULL.
 * @ingroup KernelBundleInterface
 */
DPCTL_API
__dpctl_give DPCTLSyclKernelBundleRef DPCTLKernelBundle_CreateFromOCLSource(
    __dpctl_keep const DPCTLSyclContextRef Ctx,
    __dpctl_keep const DPCTLSyclDeviceRef Dev,
    __dpctl_keep const char *Source,
    __dpctl_keep const char *CompileOpts);

/*!
 * @brief Returns the SyclKernel with given name from the kernel bundle, if
 * not found then return NULL.
 *
 * @param    KBRef          Opaque pointer to a sycl::kernel_bundle
 * @param    KernelName     Name of kernel
 * @return   A SyclKernel reference if the kernel exists, else NULL
 * @ingroup KernelBundleInterface
 */
DPCTL_API
__dpctl_give DPCTLSyclKernelRef
DPCTLKernelBundle_GetKernel(__dpctl_keep DPCTLSyclKernelBundleRef KBRef,
                            __dpctl_keep const char *KernelName);

/*!
 * @brief Return True if a SyclKernel with given name exists in the kernel
 * bundle, if not found then returns False.
 *
 * @param    KBRef          Opaque pointer to a sycl::kernel_bundle
 * @param    KernelName     Name of kernel
 * @return   True if the kernel exists, else False
 * @ingroup KernelBundleInterface
 */
DPCTL_API
bool DPCTLKernelBundle_HasKernel(__dpctl_keep DPCTLSyclKernelBundleRef KBRef,
                                 __dpctl_keep const char *KernelName);

/*!
 * @brief Frees the DPCTLSyclKernelBundleRef pointer.
 *
 * @param   KBRef           Opaque pointer to a sycl::kernel_bundle
 * @ingroup KernelBundleInterface
 */
DPCTL_API
void DPCTLKernelBundle_Delete(__dpctl_take DPCTLSyclKernelBundleRef KBRef);

/*!
 * @brief Returns a copy of the DPCTLSyclKernelBundleRef object.
 *
 * @param    KBRef           DPCTLSyclKernelBundleRef object to be copied.
 * @return   A new DPCTLSyclKernelBundleRef created by copying the passed in
 * DPCTLSyclKernelBundleRef object.
 * @ingroup KernelBundleInterface
 */
DPCTL_API
__dpctl_give DPCTLSyclKernelBundleRef
DPCTLKernelBundle_Copy(__dpctl_keep const DPCTLSyclKernelBundleRef KBRef);

DPCTL_C_EXTERN_C_END