pub mod cache;
pub mod discovery;
mod jsonrpc;
pub mod types;
pub use cache::{
cache_native_binary, cached_native_binary, cached_native_binary_any_arch, shader_hash,
};
pub use discovery::{
DEFAULT_ECOPRIMALS_DISCOVERY_DIR, discover_cpu_shader_compiler, discover_shader_compiler,
discover_shader_validator,
};
pub use types::{
AdapterDescriptor, BufferBinding, CompileCpuRequest, CompileCpuResponse, CoralBinary,
CoralCapabilitiesResponse, CoralF64Capabilities, ExecuteCpuRequest, ExecuteCpuResponse,
ExpectedBinding, HealthResponse, ValidateRequest, ValidateResponse, ValidationMismatch,
ValidationTolerance,
};
#[must_use]
pub fn is_coral_available() -> bool {
if let Ok(h) = tokio::runtime::Handle::try_current() {
let can_block = std::panic::catch_unwind(|| {
tokio::task::block_in_place(|| {});
})
.is_ok();
if can_block {
return tokio::task::block_in_place(|| {
h.block_on(async { discover_shader_compiler().await.is_some() })
});
}
}
tokio::runtime::Builder::new_current_thread()
.enable_all()
.build()
.is_ok_and(|r| r.block_on(async { discover_shader_compiler().await.is_some() }))
}
use jsonrpc::{jsonrpc_call, wgsl_to_spirv};
use std::sync::Arc;
use tokio::sync::RwLock;
use types::{CompileRequest, CompileResponse, CompileWgslRequest, PrecisionAdvice};
#[derive(Debug)]
enum ConnectionState {
Uninit,
Connected { addr: Arc<str> },
Unavailable,
}
#[derive(Debug)]
pub struct CoralCompiler {
state: Arc<RwLock<ConnectionState>>,
}
impl CoralCompiler {
#[must_use]
pub fn new() -> Self {
Self {
state: Arc::new(RwLock::new(ConnectionState::Uninit)),
}
}
pub async fn compile_wgsl(
&self,
wgsl: &str,
arch: &str,
fp64_software: bool,
) -> Option<CoralBinary> {
let spirv_words = wgsl_to_spirv(wgsl)?;
self.compile_spirv(&spirv_words, arch, fp64_software).await
}
pub async fn compile_spirv(
&self,
spirv_words: &[u32],
arch: &str,
fp64_software: bool,
) -> Option<CoralBinary> {
let addr = self.ensure_connected().await?;
let request = CompileRequest {
spirv_words: spirv_words.to_vec(),
arch: arch.to_owned(),
opt_level: 2,
fp64_software,
};
match jsonrpc_call::<CompileRequest, CompileResponse>(
&addr,
"shader.compile.spirv",
&request,
)
.await
{
Ok(resp) => Some(resp.into_coral_binary(arch.to_owned())),
Err(e) => {
tracing::debug!("shader compile failed: {e}");
None
}
}
}
pub async fn compile_wgsl_direct(
&self,
wgsl: &str,
arch: &str,
fp64_software: bool,
) -> Option<CoralBinary> {
let addr = self.ensure_connected().await?;
let fp64_strategy = if fp64_software {
Some("native".to_owned())
} else {
Some("f32_only".to_owned())
};
let request = CompileWgslRequest {
wgsl_source: wgsl.to_owned(),
arch: arch.to_owned(),
opt_level: 2,
fp64_software,
fp64_strategy,
adapter: None,
precision_advice: None,
};
match jsonrpc_call::<CompileWgslRequest, CompileResponse>(
&addr,
"shader.compile.wgsl",
&request,
)
.await
{
Ok(resp) => Some(resp.into_coral_binary(arch.to_owned())),
Err(e) => {
tracing::debug!("shader compile_wgsl direct failed: {e}, trying SPIR-V path");
self.compile_wgsl(wgsl, arch, fp64_software).await
}
}
}
pub async fn compile_wgsl_with_advice(
&self,
wgsl: &str,
arch: &str,
fp64_software: bool,
advice: PrecisionAdvice,
) -> Option<CoralBinary> {
let addr = self.ensure_connected().await?;
let fp64_strategy = if fp64_software {
Some("native".to_owned())
} else {
Some("f32_only".to_owned())
};
let request = CompileWgslRequest {
wgsl_source: wgsl.to_owned(),
arch: arch.to_owned(),
opt_level: 2,
fp64_software,
fp64_strategy,
adapter: None,
precision_advice: Some(advice),
};
match jsonrpc_call::<CompileWgslRequest, CompileResponse>(
&addr,
"shader.compile.wgsl",
&request,
)
.await
{
Ok(resp) => Some(resp.into_coral_binary(arch.to_owned())),
Err(e) => {
tracing::debug!("shader compile_wgsl with advice failed: {e}, trying basic path");
self.compile_wgsl_direct(wgsl, arch, fp64_software).await
}
}
}
pub async fn supported_archs(&self) -> Option<Vec<String>> {
if let Some(archs) = self.capabilities().await {
return Some(archs);
}
self.health().await.map(|h| h.supported_archs)
}
pub async fn capabilities(&self) -> Option<Vec<String>> {
let addr = self.ensure_connected().await?;
jsonrpc_call::<(), Vec<String>>(&addr, "shader.compile.capabilities", &())
.await
.ok()
}
pub async fn capabilities_structured(&self) -> Option<CoralCapabilitiesResponse> {
let addr = self.ensure_connected().await?;
jsonrpc_call::<(), CoralCapabilitiesResponse>(&addr, "shader.compile.capabilities", &())
.await
.ok()
}
pub async fn has_f64_lowering(&self) -> bool {
self.capabilities_structured()
.await
.is_some_and(|c| c.f64_transcendental_capabilities.has_full_lowering())
}
pub async fn health(&self) -> Option<HealthResponse> {
let addr = self.ensure_connected().await?;
jsonrpc_call::<(), HealthResponse>(&addr, "shader.compile.status", &())
.await
.ok()
}
pub async fn supports_cpu_execution(&self) -> bool {
self.capabilities_structured()
.await
.is_some_and(|c| c.supports_cpu_execution)
}
pub async fn supports_validation(&self) -> bool {
self.capabilities_structured()
.await
.is_some_and(|c| c.supports_validation)
}
pub async fn compile_cpu(
&self,
wgsl: &str,
entry_point: &str,
arch: &str,
) -> Option<types::CompileCpuResponse> {
let addr = self.ensure_connected().await?;
let request = types::CompileCpuRequest {
wgsl_source: wgsl.to_owned(),
arch: arch.to_owned(),
opt_level: 2,
entry_point: entry_point.to_owned(),
};
match jsonrpc_call::<types::CompileCpuRequest, types::CompileCpuResponse>(
&addr,
"shader.compile.cpu",
&request,
)
.await
{
Ok(resp) => Some(resp),
Err(e) => {
tracing::debug!("shader.compile.cpu failed: {e}");
None
}
}
}
pub async fn execute_cpu(
&self,
request: &types::ExecuteCpuRequest,
) -> Option<types::ExecuteCpuResponse> {
let addr = self.ensure_connected().await?;
match jsonrpc_call::<types::ExecuteCpuRequest, types::ExecuteCpuResponse>(
&addr,
"shader.execute.cpu",
request,
)
.await
{
Ok(resp) => Some(resp),
Err(e) => {
tracing::debug!("shader.execute.cpu failed: {e}");
None
}
}
}
pub async fn validate_shader(
&self,
request: &types::ValidateRequest,
) -> Option<types::ValidateResponse> {
let addr = self.ensure_connected().await?;
match jsonrpc_call::<types::ValidateRequest, types::ValidateResponse>(
&addr,
"shader.validate",
request,
)
.await
{
Ok(resp) => Some(resp),
Err(e) => {
tracing::debug!("shader.validate failed: {e}");
None
}
}
}
async fn ensure_connected(&self) -> Option<Arc<str>> {
{
let state = self.state.read().await;
match &*state {
ConnectionState::Connected { addr } => return Some(Arc::clone(addr)),
ConnectionState::Unavailable => return None,
ConnectionState::Uninit => {}
}
}
let mut state = self.state.write().await;
match &*state {
ConnectionState::Connected { addr } => return Some(Arc::clone(addr)),
ConnectionState::Unavailable => return None,
ConnectionState::Uninit => {}
}
if let Some(addr) = discover_shader_compiler().await {
tracing::info!(addr = %addr, "discovered shader compiler service");
let addr: Arc<str> = Arc::from(addr);
*state = ConnectionState::Connected {
addr: Arc::clone(&addr),
};
Some(addr)
} else {
tracing::debug!("shader compiler not available — using standard compilation path");
*state = ConnectionState::Unavailable;
None
}
}
pub async fn reset(&self) {
let mut state = self.state.write().await;
*state = ConnectionState::Uninit;
}
}
impl Default for CoralCompiler {
fn default() -> Self {
Self::new()
}
}
pub static GLOBAL_CORAL: std::sync::LazyLock<CoralCompiler> =
std::sync::LazyLock::new(CoralCompiler::new);
#[must_use]
pub fn global_coral() -> &'static CoralCompiler {
&GLOBAL_CORAL
}
pub async fn probe_health() -> bool {
GLOBAL_CORAL.health().await.is_some()
}
pub fn spawn_coral_compile_for_adapter(
optimized_wgsl: &str,
adapter_info: &wgpu::AdapterInfo,
fp64_software: bool,
) {
let source = optimized_wgsl.to_owned();
let hash = shader_hash(&source);
let adapter = types::AdapterDescriptor::from_adapter_info(adapter_info);
let adapter_key = adapter.cache_key();
if cached_native_binary(&hash, &adapter_key).is_some() {
return;
}
let Ok(handle) = tokio::runtime::Handle::try_current() else {
return;
};
handle.spawn(async move {
let Some(archs) = GLOBAL_CORAL.supported_archs().await else {
return;
};
let Some(target) = best_target_for_adapter(&archs, &adapter) else {
return;
};
if let Some(binary) = GLOBAL_CORAL
.compile_wgsl_direct(&source, &target, fp64_software)
.await
{
tracing::debug!(
target = %target,
size = binary.binary.len(),
"cached native binary ({} bytes) for adapter {}",
binary.binary.len(),
adapter.device_name,
);
cache_native_binary(&hash, &adapter_key, binary);
}
});
}
fn best_target_for_adapter(
supported_archs: &[String],
adapter: &types::AdapterDescriptor,
) -> Option<String> {
use crate::device::vendor::{VENDOR_AMD, VENDOR_NVIDIA};
let prefix = match adapter.vendor_id {
VENDOR_NVIDIA => "sm_",
VENDOR_AMD => "gfx",
_ => return None,
};
supported_archs
.iter()
.filter(|a| a.starts_with(prefix))
.min()
.cloned()
}
#[cfg(test)]
#[path = "coral_compiler_tests.rs"]
mod tests;