GPU API Reference

GPU compute support for CUDA, Metal, OpenCL with host-side runtime management

Import

U std/gpu

Overview

The GPU module provides two categories of functions:

1. Kernel-side intrinsics: Thread indexing, synchronization, atomics, math - replaced by GPU codegen when compiling with --gpu
2. Host-side runtime API: Memory allocation, kernel launching, device management - linked from gpu_runtime.c

Compile with: vaisc build file.vais --gpu cuda --gpu-compile

Thread Indexing Functions

Basic Thread/Block Indices

Dimensions

Global Indexing

Synchronization Functions

Atomic Operations

GPU Math Functions

Shared Memory

Memory Operations

Utility Functions

Warp/Wavefront Operations

Block Reduction Operations

Grid Configuration Helpers

Struct

KernelConfig

Configure kernel launch parameters.

Fields:

• grid_x: i64 - Grid dimension x
• grid_y: i64 - Grid dimension y
• grid_z: i64 - Grid dimension z
• block_x: i64 - Block dimension x
• block_y: i64 - Block dimension y
• block_z: i64 - Block dimension z
• shared_memory: i64 - Shared memory bytes

Host-Side API

Memory Management

Kernel Execution

Stream Management

Device Management

Event Timing

Async Memory Transfer

Unified Memory Hints

Multi-GPU Peer Access

Error Handling

Metal-Specific Functions (Apple GPU)

AVX-512 SIMD Operations (Intel/AMD)

Load/Store (512-bit vectors)

Arithmetic

Reduction

Broadcast

AVX2 SIMD Operations (Intel/AMD)

Load/Store (256-bit vectors)

Arithmetic

Broadcast

ARM NEON SIMD Operations

Load/Store (128-bit vectors)

Arithmetic

Reduction

Broadcast

Usage

Basic Vector Addition Kernel

U std/gpu

#[gpu]
F vector_add(a: *f64, b: *f64, c: *f64, n: i64) -> i64 {
    idx := global_idx()
    I idx < n {
        c[idx] = a[idx] + b[idx]
    }
    0
}

F main() -> i64 {
    n := 1000000
    size := n * 8  # 8 bytes per f64

    # Allocate device memory
    d_a := gpu_alloc(size)
    d_b := gpu_alloc(size)
    d_c := gpu_alloc(size)

    # Copy input data
    gpu_memcpy_h2d(d_a, host_a, size)
    gpu_memcpy_h2d(d_b, host_b, size)

    # Launch kernel
    block_size := 256
    grid_size := calc_blocks(n, block_size)
    gpu_launch_kernel(vector_add, grid_size, 1, 1, block_size, 1, 1, 0, [d_a, d_b, d_c, n], 4)

    # Copy results back
    gpu_memcpy_d2h(host_c, d_c, size)

    # Synchronize and cleanup
    gpu_synchronize()
    gpu_free(d_a)
    gpu_free(d_b)
    gpu_free(d_c)

    0
}

Matrix Multiplication (2D Grid)

U std/gpu

#[gpu]
F matmul(A: *f64, B: *f64, C: *f64, N: i64) -> i64 {
    row := global_idx_y()
    col := global_idx_x()

    I row < N && col < N {
        sum := 0.0
        k := 0
        L k < N {
            sum = sum + A[row * N + k] * B[k * N + col]
            k = k + 1
        }
        C[row * N + col] = sum
    }
    0
}

F main() -> i64 {
    N := 1024
    config := kernel_config_2d(N, N, 16, 16)

    # Launch 2D kernel
    gpu_launch_kernel(matmul, config.grid_x, config.grid_y, 1,
                      config.block_x, config.block_y, 1,
                      0, [d_A, d_B, d_C, N], 4)

    gpu_synchronize()
    0
}

Using Shared Memory

U std/gpu

#[gpu]
F reduce_sum(input: *f64, output: *f64, n: i64) -> i64 {
    tid := thread_idx_x()
    idx := global_idx()

    # Allocate shared memory
    shared := shared_alloc(256 * 8) as *f64

    # Load into shared memory
    I idx < n {
        shared[tid] = input[idx]
    } ! {
        shared[tid] = 0.0
    }

    sync_threads()

    # Reduction in shared memory
    stride := 128
    L stride > 0 {
        I tid < stride {
            shared[tid] = shared[tid] + shared[tid + stride]
        }
        sync_threads()
        stride = stride / 2
    }

    # Write result
    I tid == 0 {
        output[block_idx_x()] = shared[0]
    }

    0
}

Atomic Operations

U std/gpu

#[gpu]
F histogram(data: *i64, bins: *i64, n: i64, num_bins: i64) -> i64 {
    idx := global_idx()
    I idx < n {
        bin := data[idx] % num_bins
        atomic_add(&bins[bin], 1)
    }
    0
}

Warp-Level Reduction

U std/gpu

#[gpu]
F warp_reduce(input: *f64, output: *f64, n: i64) -> i64 {
    idx := global_idx()
    val := I idx < n { input[idx] } ! { 0.0 }

    # Warp-level shuffle reduction
    val = val + warp_shuffle_down(val, 16)
    val = val + warp_shuffle_down(val, 8)
    val = val + warp_shuffle_down(val, 4)
    val = val + warp_shuffle_down(val, 2)
    val = val + warp_shuffle_down(val, 1)

    # First lane writes result
    I lane_id() == 0 {
        output[block_idx_x() * 32 + thread_idx_x() / 32] = val
    }

    0
}

Stream-Based Async Execution

U std/gpu

F main() -> i64 {
    # Create streams
    stream1 := gpu_stream_create()
    stream2 := gpu_stream_create()

    # Async copies and kernels
    gpu_memcpy_h2d_async(d_a1, h_a1, size, stream1)
    gpu_memcpy_h2d_async(d_a2, h_a2, size, stream2)

    # Launch on different streams
    gpu_launch_kernel_stream(kernel1, grid, block, stream1, args1)
    gpu_launch_kernel_stream(kernel2, grid, block, stream2, args2)

    # Async copy results
    gpu_memcpy_d2h_async(h_c1, d_c1, size, stream1)
    gpu_memcpy_d2h_async(h_c2, d_c2, size, stream2)

    # Synchronize streams
    gpu_stream_synchronize(stream1)
    gpu_stream_synchronize(stream2)

    # Cleanup
    gpu_stream_destroy(stream1)
    gpu_stream_destroy(stream2)

    0
}

GPU Timing with Events

U std/gpu

F main() -> i64 {
    start := gpu_event_create()
    stop := gpu_event_create()

    gpu_event_record(start)

    # Launch kernel
    gpu_launch_kernel(my_kernel, grid, block, 0, args, arg_count)

    gpu_event_record(stop)
    gpu_event_synchronize(stop)

    elapsed_ms := gpu_event_elapsed(start, stop)

    gpu_event_destroy(start)
    gpu_event_destroy(stop)

    0
}

Notes

• Kernel-side functions (thread_idx_, atomic_, etc.) are replaced by the GPU codegen backend. Host-side placeholders return dummy values.
• Host-side functions (gpu_alloc, gpu_launch_kernel, etc.) are extern C functions linked from gpu_runtime.c.
• Compile with --gpu cuda for NVIDIA, --gpu metal for Apple, or --gpu opencl for cross-platform.
• Memory pointers returned by gpu_alloc are device pointers and cannot be dereferenced on the host.
• Always call gpu_synchronize() before reading results back to the host.
• SIMD functions (AVX-512, AVX2, NEON) are CPU-side optimizations, not GPU kernels.