Skip to content

Diagnostics-Reference.md

Latest commit

 

History

History
145 lines (91 loc) · 4.51 KB

Diagnostics-Reference.md

File metadata and controls

145 lines (91 loc) · 4.51 KB
Raw

Diagnostics Reference

This page explains the common JavaToGpu diagnostic families and what to try next.

For step-by-step fixes, start with Troubleshooting. Use this page when you need to understand what a diagnostic category usually means.

Kernel Diagnostics

Unknown @CCode Helper

The compiler found a helper call inside GPU code but could not match it to a known helper.

Common causes:

  • The helper method is missing @CCode.
  • The helper class was not included in the compilation input set.
  • The method owner, name, parameter types, or return type do not match the call site.

Typical fix: keep helper signatures simple and make sure helper methods are visible to the processor.

Ambiguous Helper Call

More than one helper shape can match the same call.

Typical fix: remove overload ambiguity, use explicit parameter types, or split helpers into clearer names.

Unsupported GPU Parameter Type

The method boundary contains a type the current GPU ABI cannot pass safely.

Typical fix: use primitives, annotated arrays, vectors, @GPUStruct values, pointer views, images, or samplers.

Unsupported @GPUStruct Field

The struct contains a field that cannot be marshalled today.

Typical fix: use primitive fields, vector fields, or nested @GPUStruct values. Move arrays out of the struct.

Unsupported Java Construct

The kernel uses Java behavior that does not map to the current GPU subset.

Typical examples:

  • Object allocation.
  • Virtual/interface dispatch.
  • Exceptions.
  • Recursion.
  • Synchronization blocks.
  • Arbitrary Java library calls.

Typical fix: move that logic to CPU setup code, then pass simpler data into the kernel.

Runtime Diagnostics

OpenCL Backend Not Available

The runtime could not select an OpenCL backend.

Common causes:

  • Missing OpenCL driver.
  • No compatible device visible to the process.
  • Runtime policy required a capability the selected device does not expose.

Use GpuRuntime.trySelect(...) when GPU execution should be optional.

OpenCL Build Failure

OpenCL rejected the generated source.

Common next steps:

  • Inspect the generated source and validation report.
  • Retry without custom compile flags.
  • Check required capabilities such as double precision or images.
  • Compare with Device Quirks if the failure is vendor-specific.

Upload Or Readback Failure

The runtime could not marshal a Java value to or from the GPU backend.

Common causes:

  • Unsupported array element type.
  • Struct layout that is not ABI-safe.
  • Missing readback constructor for a value type.
  • Invalid image or sampler handle.

ASM Diagnostics

The ASM path is for advanced integrations that intentionally emit supported bytecode. It is not a general JVM decompiler.

Use a preflight report before lowering externally generated bytecode:

GpuProgramCompiler compiler = GpuProgramCompiler.createDefault();
AsmFrontendFailureReport report = compiler.reportStructuredAsmArtifact(path);

if (!report.successful()) {
    System.err.println(report.summaryLine());
}

Common ASM failure families:

  • arrayLength - JVM array metadata was used directly.
  • arrayAllocation - runtime array allocation appeared in bytecode.
  • exceptionControlFlow - exceptions or ATHROW were used.
  • monitorSynchronization - synchronized/monitor bytecode was used.
  • methodInvocation - unsupported call kind or owner.
  • methodDescriptor - unsupported argument or return type.
  • fieldAccess - unsupported field access pattern.
  • objectType - unsupported casts, type checks, or constructors.

Rust-Like Source Diagnostics

When source location information is available, JavaToGpu can render diagnostics with source snippets that point at the likely failing expression.

Use these messages first. The machine-readable metadata is useful for CI and tools, but the source snippet is usually the fastest way to fix application code.

CI Report Strategy

For CI, prefer archiving reports instead of relying only on console output.

Useful report locations:

processor/build/reports/opencl/
build/reports/javatogpu-ir-validation.properties
build/reports/javatogpu-asm-preflight.properties

Recommended approach:

  • Use console diagnostics for quick local fixes.
  • Use .properties reports for CI gates and trend tracking.
  • Use validation-report.md for human-readable OpenCL validation summaries.

Read Next