cubecl_runtime/
compiler.rs

1use crate::kernel::KernelDefinition;
2use alloc::string::{String, ToString};
3use cubecl_environment::backtrace::BackTrace;
4use thiserror::Error;
5
6/// JIT compilation error.
7#[derive(Error, Clone)]
8#[cfg_attr(serializable, derive(serde::Serialize, serde::Deserialize))]
9pub enum CompilationError {
10    /// An instruction isn't supported.
11    #[error(
12        "An unsupported instruction caused the compilation to fail\nCaused by:\n  {reason}\nBacktrace:\n{backtrace}"
13    )]
14    UnsupportedInstruction {
15        /// The caused of the error.
16        reason: String,
17        /// The backtrace for this error.
18        #[cfg_attr(serializable, serde(skip))]
19        backtrace: BackTrace,
20    },
21
22    /// A generic compilation error.
23    #[error(
24        "An error caused the compilation to fail\nCaused by:\n  {reason}\nBacktrace:\n{backtrace}"
25    )]
26    Generic {
27        /// The error context.
28        reason: String,
29        /// The backtrace for this error.
30        #[cfg_attr(serializable, serde(skip))]
31        backtrace: BackTrace,
32    },
33    /// A generic compilation error.
34    #[error(
35        "A validation error caused the compilation to fail\nCaused by:\n  {reason}\nBacktrace:\n{backtrace}"
36    )]
37    Validation {
38        /// The error context.
39        reason: String,
40        /// The backtrace for this error.
41        #[cfg_attr(serializable, serde(skip))]
42        backtrace: BackTrace,
43    },
44}
45
46impl core::fmt::Debug for CompilationError {
47    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
48        write!(f, "{self}")
49    }
50}
51
52impl From<pliron::result::Error> for CompilationError {
53    fn from(value: pliron::result::Error) -> Self {
54        CompilationError::Validation {
55            reason: value.to_string(),
56            backtrace: BackTrace::capture(),
57        }
58    }
59}
60
61/// Compiles the representation into its own representation that can be formatted into tokens.
62pub trait Compiler: Sync + Send + 'static + Clone + core::fmt::Debug {
63    /// The representation for the compiled code.
64    type Representation: core::fmt::Display;
65    /// The compilation options used to configure the compiler
66    type CompilationOptions: Send + Default + core::fmt::Debug;
67
68    /// Compiles the [kernel definition](KernelDefinition) into the compiler's representation.
69    fn compile(
70        &mut self,
71        kernel: KernelDefinition,
72        compilation_options: &Self::CompilationOptions,
73    ) -> Result<Self::Representation, CompilationError>;
74
75    /// What the compiled kernel does with each buffer binding, by buffer
76    /// position — the visibility analysis's answer, when the representation
77    /// kept it (see [`BufferIOAttr`](crate::kernel::BufferIOAttr)).
78    ///
79    /// `None` reads as every buffer both read and written, the conservative
80    /// direction. A compiler overriding this must answer from the IR
81    /// attributes the annotate pass stamped, never from what its shader
82    /// language kept — wgpu's shader visibility, for one, is deliberately
83    /// forced wider than the kernel's own behavior.
84    fn buffer_io(
85        _repr: &Self::Representation,
86    ) -> Option<alloc::vec::Vec<crate::kernel::BufferIOAttr>> {
87        None
88    }
89
90    /// The default extension for the runtime's kernel/shader code.
91    /// Might change based on which compiler is used.
92    fn extension(&self) -> &'static str;
93
94    /// Short identifier of the language this compiler produces, such as
95    /// `"wgsl"` or `"cuda"`.
96    ///
97    /// What a [`PrecompiledSource`](crate::kernel::PrecompiledSource) has to
98    /// name to be accepted by this compiler.
99    fn lang_tag(&self) -> &'static str;
100}
cubecl_runtime/compiler.rs

cubecl_runtime/
compiler.rs
