Class CompilationDiagnostics

Namespace: Orleans.GpuBridge.Abstractions.Models.Compilation

Assembly: Orleans.GpuBridge.Abstractions.dll

Provides detailed diagnostic information about kernel compilation for debugging, optimization analysis, and performance tuning.

public sealed record CompilationDiagnostics : IEquatable<CompilationDiagnostics>

Inheritance: object

CompilationDiagnostics

Implements: IEquatable<CompilationDiagnostics>

Inherited Members: object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Examples

// Basic diagnostics with timing information
var basicDiagnostics = new CompilationDiagnostics(
    CompilationTime: TimeSpan.FromMilliseconds(150),
    CompiledCodeSize: 2048);

// Detailed diagnostics with all information
var detailedDiagnostics = new CompilationDiagnostics(
    IntermediateCode: "define void @kernel(...) { ... }",
    AssemblyCode: "ld.global.f32 %f1, [%rd1+0];\nmul.f32 %f2, %f1, %f1;",
    OptimizationReport: "Applied loop unrolling (factor 4), vectorized memory accesses",
    CompilationTime: TimeSpan.FromMilliseconds(350),
    CompiledCodeSize: 1536,
    AdditionalInfo: new Dictionary<string, object>
    {
        ["RegistersPerThread"] = 24,
        ["OccupancyPercent"] = 75.0,
        ["InstructionCount"] = 128
    });

// Diagnostics for performance analysis
var performanceDiagnostics = new CompilationDiagnostics(
    OptimizationReport: "Memory coalescing: 95% efficient, Branch divergence: minimal",
    CompilationTime: TimeSpan.FromMilliseconds(200),
    CompiledCodeSize: 1024,
    AdditionalInfo: new Dictionary<string, object>
    {
        ["EstimatedPerformance"] = "High",
        ["MemoryBandwidthUtilization"] = 0.85
    });

Remarks

Compilation diagnostics provide valuable insights for:

Performance optimization and tuning
Understanding compiler behavior and optimizations
Debugging compilation issues and unexpected behavior
Comparing different compilation strategies
Educational purposes and learning GPU programming

The availability of specific diagnostic information depends on the compiler backend and compilation options. Not all backends support all diagnostic features, and some information may only be available when debug information is enabled.

For production use, diagnostic information is typically only gathered when specifically requested, as it can significantly increase compilation time and memory usage.

Constructors

CompilationDiagnostics(string?, string?, string?, TimeSpan, long, IReadOnlyDictionary<string, object>?)

Provides detailed diagnostic information about kernel compilation for debugging, optimization analysis, and performance tuning.

public CompilationDiagnostics(string? IntermediateCode = null, string? AssemblyCode = null, string? OptimizationReport = null, TimeSpan CompilationTime = default, long CompiledCodeSize = 0, IReadOnlyDictionary<string, object>? AdditionalInfo = null)

Parameters

IntermediateCode string: The intermediate representation (IR) code generated during compilation. This may be LLVM IR, SPIR-V, or another intermediate format depending on the compiler backend. Useful for understanding compiler transformations and optimizations. May be null if not available or not requested.
AssemblyCode string: The final assembly code generated for the target GPU architecture. This is the human-readable representation of the compiled binary code, such as PTX for NVIDIA GPUs or GCN assembly for AMD GPUs. Valuable for performance analysis and low-level optimization. May be null if not available or not supported by the backend.
OptimizationReport string: A detailed report of optimizations applied during compilation. Includes information about loop unrolling, vectorization, memory coalescing, register allocation, and other compiler optimizations. Helps understand performance characteristics and identify optimization opportunities. May be null if not available or not requested.
CompilationTime TimeSpan: The total time taken to compile the kernel from source to final binary. Includes parsing, optimization, and code generation phases. Useful for performance analysis of the compilation pipeline and identifying compilation bottlenecks. Default is Zero.
CompiledCodeSize long: The size in bytes of the final compiled binary code. Larger kernels may have longer load times and higher memory usage. This metric helps assess the impact of optimizations on code size. Default is 0.
AdditionalInfo IReadOnlyDictionary<string, object>: Backend-specific additional diagnostic information that doesn't fit into the standard diagnostic categories. May include profiling data, resource usage statistics, or vendor-specific metrics. Keys should be descriptive names, values can be any serializable diagnostic data. Default is null.

Examples

// Basic diagnostics with timing information
var basicDiagnostics = new CompilationDiagnostics(
    CompilationTime: TimeSpan.FromMilliseconds(150),
    CompiledCodeSize: 2048);

// Detailed diagnostics with all information
var detailedDiagnostics = new CompilationDiagnostics(
    IntermediateCode: "define void @kernel(...) { ... }",
    AssemblyCode: "ld.global.f32 %f1, [%rd1+0];\nmul.f32 %f2, %f1, %f1;",
    OptimizationReport: "Applied loop unrolling (factor 4), vectorized memory accesses",
    CompilationTime: TimeSpan.FromMilliseconds(350),
    CompiledCodeSize: 1536,
    AdditionalInfo: new Dictionary<string, object>
    {
        ["RegistersPerThread"] = 24,
        ["OccupancyPercent"] = 75.0,
        ["InstructionCount"] = 128
    });

// Diagnostics for performance analysis
var performanceDiagnostics = new CompilationDiagnostics(
    OptimizationReport: "Memory coalescing: 95% efficient, Branch divergence: minimal",
    CompilationTime: TimeSpan.FromMilliseconds(200),
    CompiledCodeSize: 1024,
    AdditionalInfo: new Dictionary<string, object>
    {
        ["EstimatedPerformance"] = "High",
        ["MemoryBandwidthUtilization"] = 0.85
    });

Remarks

Compilation diagnostics provide valuable insights for:

Performance optimization and tuning
Understanding compiler behavior and optimizations
Debugging compilation issues and unexpected behavior
Comparing different compilation strategies
Educational purposes and learning GPU programming

For production use, diagnostic information is typically only gathered when specifically requested, as it can significantly increase compilation time and memory usage.

Properties

AdditionalInfo

Backend-specific additional diagnostic information that doesn't fit into the standard diagnostic categories. May include profiling data, resource usage statistics, or vendor-specific metrics. Keys should be descriptive names, values can be any serializable diagnostic data. Default is null.

public IReadOnlyDictionary<string, object>? AdditionalInfo { get; init; }

Property Value

IReadOnlyDictionary<string, object>

AssemblyCode

The final assembly code generated for the target GPU architecture. This is the human-readable representation of the compiled binary code, such as PTX for NVIDIA GPUs or GCN assembly for AMD GPUs. Valuable for performance analysis and low-level optimization. May be null if not available or not supported by the backend.

public string? AssemblyCode { get; init; }

Property Value

string

CompilationTime

The total time taken to compile the kernel from source to final binary. Includes parsing, optimization, and code generation phases. Useful for performance analysis of the compilation pipeline and identifying compilation bottlenecks. Default is Zero.

public TimeSpan CompilationTime { get; init; }

Property Value

TimeSpan

CompiledCodeSize

The size in bytes of the final compiled binary code. Larger kernels may have longer load times and higher memory usage. This metric helps assess the impact of optimizations on code size. Default is 0.

public long CompiledCodeSize { get; init; }

Property Value

long

HasAdditionalInfo

Gets a value indicating whether this diagnostic instance contains additional backend-specific information.

public bool HasAdditionalInfo { get; }

Property Value

bool: true if additional information is available; otherwise, false.

HasAssemblyCode

Gets a value indicating whether this diagnostic instance contains assembly code information.

public bool HasAssemblyCode { get; }

Property Value

bool: true if assembly code is available; otherwise, false.

HasIntermediateCode

Gets a value indicating whether this diagnostic instance contains intermediate code information.

public bool HasIntermediateCode { get; }

Property Value

bool: true if intermediate code is available; otherwise, false.

HasOptimizationReport

Gets a value indicating whether this diagnostic instance contains an optimization report.

public bool HasOptimizationReport { get; }

Property Value

bool: true if an optimization report is available; otherwise, false.

IntermediateCode

The intermediate representation (IR) code generated during compilation. This may be LLVM IR, SPIR-V, or another intermediate format depending on the compiler backend. Useful for understanding compiler transformations and optimizations. May be null if not available or not requested.

public string? IntermediateCode { get; init; }

Property Value

string

OptimizationReport

A detailed report of optimizations applied during compilation. Includes information about loop unrolling, vectorization, memory coalescing, register allocation, and other compiler optimizations. Helps understand performance characteristics and identify optimization opportunities. May be null if not available or not requested.

public string? OptimizationReport { get; init; }

Property Value

string

Table of Contents

Class CompilationDiagnostics

Examples

Remarks

Constructors

CompilationDiagnostics(string?, string?, string?, TimeSpan, long, IReadOnlyDictionary<string, object>?)

Parameters

Examples

Remarks

Properties

AdditionalInfo

Property Value

AssemblyCode

Property Value

CompilationTime

Property Value

CompiledCodeSize

Property Value

HasAdditionalInfo

Property Value

HasAssemblyCode

Property Value

HasIntermediateCode

Property Value

HasOptimizationReport

Property Value

IntermediateCode

Property Value

OptimizationReport

Property Value