DPC++ Runtime
Runtime libraries for oneAPI Data Parallel C++
cl::sycl::detail::program_impl Class Reference

#include <detail/program_impl.hpp>

Public Member Functions

 program_impl ()=delete
 
 program_impl (ContextImplPtr Context, const property_list &PropList)
 Constructs an instance of program. More...
 
 program_impl (ContextImplPtr Context, std::vector< device > DeviceList, const property_list &PropList)
 Constructs an instance of SYCL program for the provided DeviceList. More...
 
 program_impl (std::vector< std::shared_ptr< program_impl >> ProgramList, std::string LinkOptions, const property_list &PropList)
 Constructs an instance of SYCL program by linking together each SYCL program instance in ProgramList. More...
 
 program_impl (ContextImplPtr Context, pi_native_handle InteropProgram)
 Constructs a program instance from an interop raw BE program handle. More...
 
 program_impl (ContextImplPtr Context, RT::PiKernel Kernel)
 Constructs a program instance from plugin interface interoperability kernel. More...
 
 ~program_impl ()
 
template<typename propertyT >
bool has_property () const
 Checks if this program_impl has a property of type propertyT. More...
 
template<typename propertyT >
propertyT get_property () const
 Gets the specified property of this program_impl. More...
 
cl_program get () const
 Returns a valid cl_program instance. More...
 
RT::PiProgramgetHandleRef ()
 
const RT::PiProgramgetHandleRef () const
 
bool is_host () const
 
void compile_with_kernel_name (std::string KernelName, std::string CompileOptions, OSModuleHandle Module)
 Compiles the SYCL kernel function into the encapsulated raw program. More...
 
void compile_with_source (std::string KernelSource, std::string CompileOptions="")
 Compiles the OpenCL C kernel function defined by source string. More...
 
void build_with_kernel_name (std::string KernelName, std::string BuildOptions, OSModuleHandle M)
 Builds the SYCL kernel function into encapsulated raw program. More...
 
void build_with_source (std::string KernelSource, std::string BuildOptions="")
 Builds the OpenCL C kernel function defined by source code. More...
 
void link (std::string LinkOptions="")
 Links encapsulated raw program. More...
 
bool has_kernel (std::string KernelName, bool IsCreatedFromSource) const
 Checks if kernel is available for this program. More...
 
kernel get_kernel (std::string KernelName, std::shared_ptr< program_impl > PtrToSelf, bool IsCreatedFromSource) const
 Returns a SYCL kernel for the SYCL kernel function defined by kernel name. More...
 
template<info::program param>
info::param_traits< info::program, param >::return_type get_info () const
 Queries this SYCL program for information. More...
 
std::vector< std::vector< char > > get_binaries () const
 Returns built program binaries. More...
 
context get_context () const
 
const plugingetPlugin () const
 
std::vector< deviceget_devices () const
 
std::string get_compile_options () const
 Returns compile options that were provided when the encapsulated program was explicitly compiled. More...
 
std::string get_link_options () const
 Returns compile options that were provided to the most recent invocation of link member function. More...
 
std::string get_build_options () const
 Returns the compile, link, or build options, from whichever of those operations was performed most recently on the encapsulated cl_program. More...
 
program_state get_state () const
 
void set_spec_constant_impl (const char *Name, const void *ValAddr, size_t ValSize)
 
void flush_spec_constants (const RTDeviceBinaryImage &Img, RT::PiProgram NativePrg=nullptr) const
 Takes current values of specialization constants and "injects" them into the underlying native program program via specialization constant managemment PI APIs. More...
 
OSModuleHandle getOSModuleHandle () const
 Returns the OS module handle this program belongs to. More...
 
void stableSerializeSpecConstRegistry (SerializedObj &Dst) const
 
bool hasSetSpecConstants () const
 Tells whether a specialization constant has been set for this program. More...
 
bool is_cacheable () const
 
pi_native_handle getNative () const
 Returns the native plugin handle. More...
 
bool isInterop () const
 
template<>
cl_uint get_info () const
 
template<>
context get_info () const
 
template<>
std::vector< deviceget_info () const
 

Detailed Description

Definition at line 37 of file program_impl.hpp.

Constructor & Destructor Documentation

◆ program_impl() [1/6]

cl::sycl::detail::program_impl::program_impl ( )
delete

◆ program_impl() [2/6]

cl::sycl::detail::program_impl::program_impl ( ContextImplPtr  Context,
const property_list PropList 
)
explicit

Constructs an instance of program.

The program will be created in the program_state::none state and associated with the provided context and the devices that are associated with the context.

Parameters
Contextis a pointer to SYCL context impl.
PropListis an instance of property_list.

Definition at line 29 of file program_impl.cpp.

◆ program_impl() [3/6]

cl::sycl::detail::program_impl::program_impl ( ContextImplPtr  Context,
std::vector< device DeviceList,
const property_list PropList 
)

Constructs an instance of SYCL program for the provided DeviceList.

The program will be created in the program_state::none state and associated with the provided context and the devices in the provided DeviceList.

Parameters
Contextis a pointer to SYCL context impl.
DeviceListis a list of SYCL devices.
PropListis an instance of property_list.

Definition at line 34 of file program_impl.cpp.

References cl::sycl::feature_not_supported, and PI_INVALID_OPERATION.

◆ program_impl() [4/6]

cl::sycl::detail::program_impl::program_impl ( std::vector< std::shared_ptr< program_impl >>  ProgramList,
std::string  LinkOptions,
const property_list PropList 
)

Constructs an instance of SYCL program by linking together each SYCL program instance in ProgramList.

Each program in ProgramList must be in the program_state::compiled state and must be associated with the same SYCL context. Otherwise an invalid_object_error SYCL exception will be thrown. A feature_not_supported exception will be thrown if any device that the program is to be linked for returns false for the device information query info::device::is_linker_available. Kernels caching for linked programs won't be allowed due to only compiled state of each and every program in the list and thus unknown state of caching resolution.

Parameters
ProgramListis a list of program_impl instances.
LinkOptionsis a string containing valid OpenCL link options.
PropListis an instance of property_list.

Definition at line 46 of file program_impl.cpp.

References cl::sycl::detail::plugin::call_nocheck(), cl::sycl::detail::plugin::checkPiResult(), cl::sycl::feature_not_supported, getPlugin(), is_host(), PI_INVALID_OPERATION, PI_INVALID_PROGRAM, PI_INVALID_VALUE, and piProgramLink().

◆ program_impl() [5/6]

cl::sycl::detail::program_impl::program_impl ( ContextImplPtr  Context,
pi_native_handle  InteropProgram 
)

Constructs a program instance from an interop raw BE program handle.

TODO: BE generalization will change that to something better.

The state of the constructed program can be either program_state::compiled or program_state::linked, depending on the state of the InteropProgram. Otherwise an invalid_object_error SYCL exception is thrown.

The instance of the program will be retained on construction.

Parameters
Contextis a pointer to SYCL context impl.
InteropProgramis an instance of plugin interface interoperability program.

Definition at line 118 of file program_impl.cpp.

◆ program_impl() [6/6]

cl::sycl::detail::program_impl::program_impl ( ContextImplPtr  Context,
RT::PiKernel  Kernel 
)

Constructs a program instance from plugin interface interoperability kernel.

Parameters
Contextis a pointer to SYCL context impl.
Kernelis a raw PI kernel handle.

Definition at line 200 of file program_impl.cpp.

◆ ~program_impl()

cl::sycl::detail::program_impl::~program_impl ( )

Member Function Documentation

◆ build_with_kernel_name()

void cl::sycl::detail::program_impl::build_with_kernel_name ( std::string  KernelName,
std::string  BuildOptions,
OSModuleHandle  M 
)

Builds the SYCL kernel function into encapsulated raw program.

The SYCL kernel function is defined by the kernel name. This member function sets the state of this SYCL program to program_state::linked. If the program was not in the program_state::none state, an invalid_object_error SYCL exception is thrown. If the compilation fails, a compile_program_error SYCL exception is thrown. If any device that the program is being built for returns false for the device information queries info::device::is_compiler_available or info::device::is_linker_available, a feature_not_supported SYCL exception is thrown.

Parameters
KernelNameis a string containing SYCL kernel name.
BuildOptionsis a string containing OpenCL compile options.
Mis an OS handle to user code module.

Definition at line 254 of file program_impl.cpp.

References cl::sycl::detail::plugin::call(), get_context(), get_devices(), cl::sycl::detail::ProgramManager::getBuiltPIProgram(), cl::sycl::detail::ProgramManager::getInstance(), getPlugin(), cl::sycl::detail::getSyclObjImpl(), is_host(), and piProgramRetain().

◆ build_with_source()

void cl::sycl::detail::program_impl::build_with_source ( std::string  KernelSource,
std::string  BuildOptions = "" 
)

Builds the OpenCL C kernel function defined by source code.

This member function sets the state of this SYCL program to program_state::linked. If this program was not in program_state::none, an invalid_object_error SYCL exception is thrown. If the compilation fails, a compile_program_error SYCL exception is thrown. If any device that the program is being built for returns false for the device information queries info::device::is_compiler_available or info::device::is_linker_available, a feature_not_supported SYCL exception is thrown.

Parameters
KernelSourceis a string containing OpenCL C kernel source code.
BuildOptionsis a string containing OpenCL build options.

Definition at line 273 of file program_impl.cpp.

References is_host().

◆ compile_with_kernel_name()

void cl::sycl::detail::program_impl::compile_with_kernel_name ( std::string  KernelName,
std::string  CompileOptions,
OSModuleHandle  Module 
)

Compiles the SYCL kernel function into the encapsulated raw program.

The kernel function is defined by its name. This member function sets the state of this SYCL program to program_state::compiled. If this program was not in the program_state::none state, an invalid_object_error exception is thrown. If the compilation fails, a compile_program_error SYCL exception is thrown. If any device that the program is being compiled for returns false for the device information query info::device::is_compiler_available, a feature_not_supported exception is thrown.

Parameters
KernelNameis a string containing SYCL kernel name.
CompileOptionsis a string of valid OpenCL compile options.
Moduleis an OS handle to user code module.

Definition at line 226 of file program_impl.cpp.

References is_host().

◆ compile_with_source()

void cl::sycl::detail::program_impl::compile_with_source ( std::string  KernelSource,
std::string  CompileOptions = "" 
)

Compiles the OpenCL C kernel function defined by source string.

This member function sets the state of this SYCL program to program_state::compiled. If the program was not in the program_state::none state, an invalid_object_error SYCL exception is thrown. If the compilation fails, a compile_program_error SYCL exception is thrown. If any device that the program is being compiled for returns false for the device information query info::device::is_compiler_available, a feature_not_supported SYCL exception is thrown.

Parameters
KernelSourceis a string containing OpenCL C kernel source code.
CompileOptionsis a string containing OpenCL compile options.

Definition at line 241 of file program_impl.cpp.

References is_host().

◆ flush_spec_constants()

void cl::sycl::detail::program_impl::flush_spec_constants ( const RTDeviceBinaryImage Img,
RT::PiProgram  NativePrg = nullptr 
) const

Takes current values of specialization constants and "injects" them into the underlying native program program via specialization constant managemment PI APIs.

The native program passed as non-null argument overrides the MProgram native program field.

Parameters
Imgdevice binary image corresponding to this program, used to resolve spec constant name to SPIR-V integer ID
NativePrgif not null, used as the flush target, otherwise MProgram is used

Definition at line 538 of file program_impl.cpp.

References cl::sycl::detail::pi::DeviceBinaryProperty::asByteArray(), get_context(), getHandleRef(), cl::sycl::detail::pi::DeviceBinaryImage::getSpecConstants(), cl::sycl::detail::getSyclObjImpl(), cl::sycl::detail::spec_constant_impl::getValuePtr(), cl::sycl::detail::spec_constant_impl::isSet(), piextProgramSetSpecializationConstant(), and cl::sycl::detail::pi::ByteArray::size().

Referenced by cl::sycl::detail::ProgramManager::flushSpecConstants().

◆ get()

cl_program cl::sycl::detail::program_impl::get ( ) const

Returns a valid cl_program instance.

The instance of cl_program will be retained before returning. If the program is created for a SYCL host device, an invalid_object_error exception is thrown.

Returns
a valid OpenCL cl_program instance.

Definition at line 215 of file program_impl.cpp.

References cl::sycl::detail::plugin::call(), getPlugin(), is_host(), PI_INVALID_PROGRAM, and piProgramRetain().

Referenced by cl::sycl::detail::ProgramManager::flushSpecConstants().

◆ get_binaries()

std::vector< std::vector< char > > cl::sycl::detail::program_impl::get_binaries ( ) const

Returns built program binaries.

If this program is not in the program_state::compiled or program_state::linked states, an invalid_object_error SYCL exception is thrown.

Returns
a vector of vectors representing the compiled binaries for each associated SYCL device.

Definition at line 351 of file program_impl.cpp.

References cl::sycl::detail::plugin::call(), getPlugin(), is_host(), PI_PROGRAM_INFO_BINARIES, PI_PROGRAM_INFO_BINARY_SIZES, and piProgramGetInfo().

◆ get_build_options()

std::string cl::sycl::detail::program_impl::get_build_options ( ) const
inline

Returns the compile, link, or build options, from whichever of those operations was performed most recently on the encapsulated cl_program.

If no compile, link, or build operations have been performed on this program, or if the program includes the host device in its device list, then an empty string is returned.

Returns
a string of valid OpenCL build options.

Definition at line 310 of file program_impl.hpp.

Referenced by cl::sycl::detail::ProgramManager::getBuiltPIProgram(), and cl::sycl::detail::ProgramManager::getOrCreateKernel().

◆ get_compile_options()

std::string cl::sycl::detail::program_impl::get_compile_options ( ) const
inline

Returns compile options that were provided when the encapsulated program was explicitly compiled.

If the program was built instead of explicitly compiled, if the program has not yet been compiled, or if the program has been compiled for only the host device, then an empty string is return, unless the underlying cl_program was explicitly compiled, in which case the compile options used in the explicit compile are returned.

Returns
a string of valid OpenCL compile options.

Definition at line 284 of file program_impl.hpp.

◆ get_context()

context cl::sycl::detail::program_impl::get_context ( ) const
inline
Returns
the SYCL context that this program was constructed with.

Definition at line 259 of file program_impl.hpp.

Referenced by build_with_kernel_name(), and flush_spec_constants().

◆ get_devices()

std::vector<device> cl::sycl::detail::program_impl::get_devices ( ) const
inline
Returns
a vector of devices that are associated with this program.

Definition at line 272 of file program_impl.hpp.

Referenced by build_with_kernel_name().

◆ get_info() [1/4]

template<info::program param>
info::param_traits<info::program, param>::return_type cl::sycl::detail::program_impl::get_info ( ) const

Queries this SYCL program for information.

The return type depends on the information being queried.

◆ get_info() [2/4]

template<>
cl_uint cl::sycl::detail::program_impl::get_info ( ) const

◆ get_info() [3/4]

template<>
context cl::sycl::detail::program_impl::get_info ( ) const

◆ get_info() [4/4]

template<>
std::vector<device> cl::sycl::detail::program_impl::get_info ( ) const

◆ get_kernel()

kernel cl::sycl::detail::program_impl::get_kernel ( std::string  KernelName,
std::shared_ptr< program_impl PtrToSelf,
bool  IsCreatedFromSource 
) const

Returns a SYCL kernel for the SYCL kernel function defined by kernel name.

If program is in the program_state::none state or if the SYCL kernel function is not available, an invalid_object_error exception is thrown.

Returns
a valid instance of SYCL kernel.

Definition at line 334 of file program_impl.cpp.

References is_host(), and PI_INVALID_PROGRAM.

◆ get_link_options()

std::string cl::sycl::detail::program_impl::get_link_options ( ) const
inline

Returns compile options that were provided to the most recent invocation of link member function.

If the program has not been explicitly linked using the aforementioned function, constructed with an explicitly linking constructor, or if the program has been linked for only the host device, then an empty string is returned. If the program was constructed from cl_program, then an empty string is returned unless the cl_program was explicitly linked, in which case the link options used in that explicit link are returned. If the program object was constructed using a constructor form that links a vector of programs, then the link options passed to this constructor are returned.

Returns
a string of valid OpenCL compile options.

Definition at line 300 of file program_impl.hpp.

◆ get_property()

template<typename propertyT >
propertyT cl::sycl::detail::program_impl::get_property ( ) const
inline

Gets the specified property of this program_impl.

Throws invalid_object_error if this program_impl does not have a property of type propertyT.

Returns
a copy of the property of type propertyT.

Definition at line 118 of file program_impl.hpp.

◆ get_state()

program_state cl::sycl::detail::program_impl::get_state ( ) const
inline
Returns
the current state of this SYCL program.

Definition at line 313 of file program_impl.hpp.

◆ getHandleRef() [1/2]

RT::PiProgram& cl::sycl::detail::program_impl::getHandleRef ( )
inline
Returns
a reference to a raw PI program handle. PI program is not retained before return.

Definition at line 133 of file program_impl.hpp.

Referenced by flush_spec_constants(), and cl::sycl::detail::ProgramManager::flushSpecConstants().

◆ getHandleRef() [2/2]

const RT::PiProgram& cl::sycl::detail::program_impl::getHandleRef ( ) const
inline
Returns
a constant reference to a raw PI program handle. PI program is not retained before return.

Definition at line 136 of file program_impl.hpp.

◆ getNative()

pi_native_handle cl::sycl::detail::program_impl::getNative ( ) const

Returns the native plugin handle.

Definition at line 578 of file program_impl.cpp.

References getPlugin(), cl::sycl::opencl, piextProgramGetNativeHandle(), and piProgramRetain().

◆ getOSModuleHandle()

OSModuleHandle cl::sycl::detail::program_impl::getOSModuleHandle ( ) const
inline

Returns the OS module handle this program belongs to.

A program belongs to an OS module if it was built from device image(s) belonging to that module. TODO Some programs can be linked from images belonging to different modules. May need a special fake handle for the resulting program.

Definition at line 334 of file program_impl.hpp.

◆ getPlugin()

const plugin& cl::sycl::detail::program_impl::getPlugin ( ) const
inline
Returns
the Plugin associated with the context of this program.

Definition at line 266 of file program_impl.hpp.

Referenced by build_with_kernel_name(), get(), get_binaries(), getNative(), has_kernel(), link(), program_impl(), and ~program_impl().

◆ has_kernel()

bool cl::sycl::detail::program_impl::has_kernel ( std::string  KernelName,
bool  IsCreatedFromSource 
) const

Checks if kernel is available for this program.

The SYCL kernel is defined by kernel name. If the program state is program_state::none an invalid_object_error SYCL exception is thrown.

Returns
true if the SYCL kernel is available.

Definition at line 307 of file program_impl.cpp.

References cl::sycl::detail::plugin::call_nocheck(), getPlugin(), is_host(), PI_FUNCTION_ADDRESS_IS_NOT_AVAILABLE, PI_INVALID_KERNEL_NAME, PI_SUCCESS, and piextGetDeviceFunctionPointer().

◆ has_property()

template<typename propertyT >
bool cl::sycl::detail::program_impl::has_property ( ) const
inline

Checks if this program_impl has a property of type propertyT.

Returns
true if this program_impl has a property of type propertyT.

Definition at line 108 of file program_impl.hpp.

◆ hasSetSpecConstants()

bool cl::sycl::detail::program_impl::hasSetSpecConstants ( ) const
inline

Tells whether a specialization constant has been set for this program.

Definition at line 341 of file program_impl.hpp.

Referenced by cl::sycl::detail::ProgramManager::flushSpecConstants().

◆ is_cacheable()

bool cl::sycl::detail::program_impl::is_cacheable ( ) const
inline
Returns
true if caching is allowed for this program.

Definition at line 344 of file program_impl.hpp.

◆ is_host()

bool cl::sycl::detail::program_impl::is_host ( ) const
inline

◆ isInterop()

bool cl::sycl::detail::program_impl::isInterop ( ) const
inline

Definition at line 349 of file program_impl.hpp.

◆ link()

void cl::sycl::detail::program_impl::link ( std::string  LinkOptions = "")

Links encapsulated raw program.

This member function sets the state of this SYCL program to program_state::linked. If the program was not in the program_state::compiled state, an invalid_object_error SYCL exception is thrown. If linking fails, a compile_program_error is thrown. If any device that the program is to be linked for returns false for the device information query info::device::is_linker_available, a feature_not_supported exception is thrown.

Parameters
LinkOptionsis a string containing OpenCL link options.

Definition at line 286 of file program_impl.cpp.

References cl::sycl::detail::plugin::call_nocheck(), cl::sycl::detail::plugin::checkPiResult(), cl::sycl::detail::SYCLConfig< Config >::get(), getPlugin(), is_host(), and piProgramLink().

◆ set_spec_constant_impl()

void cl::sycl::detail::program_impl::set_spec_constant_impl ( const char Name,
const void *  ValAddr,
size_t  ValSize 
)

◆ stableSerializeSpecConstRegistry()

void cl::sycl::detail::program_impl::stableSerializeSpecConstRegistry ( SerializedObj Dst) const
inline

The documentation for this class was generated from the following files: