1 # Building HAT
 2 
 3 ----
 4 * [Contents](hat-00.md)
 5 * Build Babylon and HAT
 6     * [Quick Install](hat-01-quick-install.md)
 7     * [Building Babylon with jtreg](hat-01-02-building-babylon.md)
 8     * [Building HAT with jtreg](hat-01-03-building-hat.md)
 9         * [Enabling the NVIDIA CUDA Backend](hat-01-05-building-hat-for-cuda.md)
10 * [Testing Framework](hat-02-testing-framework.md)
11 * [Running Examples](hat-03-examples.md)
12 * [HAT Programming Model](hat-03-programming-model.md)
13 * Interface Mapping
14     * [Interface Mapping Overview](hat-04-01-interface-mapping.md)
15     * [Cascade Interface Mapping](hat-04-02-cascade-interface-mapping.md)
16 * Development
17     * [Project Layout](hat-01-01-project-layout.md)
18 * Implementation Details
19     * [Walkthrough Of Accelerator.compute()](hat-accelerator-compute.md)
20     * [How we minimize buffer transfers](hat-minimizing-buffer-transfers.md)
21 * [Running HAT with Docker on NVIDIA GPUs](hat-07-docker-build-nvidia.md)
22 ---
23 
24 This guide provides step-by-step instructions to configure Babylon/HAT for CUDA-based GPU acceleration.
25 
26 ### Prerequisites
27 
28 To run Babylon/HAT with the CUDA backend, ensure the following components are properly installed:
29 
30 1. **The NVIDIA GPU Driver:** Download and install the latest appropriate driver for your operating system from the [NVIDIA Drivers page](https://www.nvidia.com/en-us/drivers/)
31 2. **The CUDA Toolkit (SDK):** Download the matching CUDA Toolkit from the [NVIDIA CUDA Downloads page](https://developer.nvidia.com/cuda-downloads).
32 
33 The CUDA Toolkit version must be compatible with your installed NVIDIA driver.
34 For example, as of June 2025, the stable NVIDIA driver for Linux is `570.169`, which supports CUDA Toolkit version `12.8`.
35 
36 
37 Always verify compatibility before installation to prevent runtime errors:
38 - You can find previous CUDA Toolkit versions on the [NVIDIA CUDA Toolkit Archive](https://developer.nvidia.com/cuda-toolkit-archive)
39 - Review supported CUDA versions and PTX ISA implementations in the [NVIDIA Parallel Thread Execution documentation](https://docs.nvidia.com/cuda/parallel-thread-execution/index.html#release-notes).
40 
41 
42 ### Troubleshooting: Unsupported CUDA/PTX Versions
43 
44 If Babylon/HAT runs with an incompatible CUDA/PTX version, you may encounter an error similar to:
45 
46 ```bash
47 cuModuleLoadDataEx CUDA error = 222 CUDA_ERROR_UNSUPPORTED_PTX_VERSION
48       /<path/to/babylon>/hat/backends/ffi/cuda/src/main/native/cpp/cuda_backend.cpp line 220
49 ```
50 
51 If this is your case, you can:
52   - **update your GPU driver**.
53   - **or downgrade your CUDA version.**
54 
55 ### Building HAT for the CUDA backend
56 
57 If the NVIDIA driver and the CUDA Toolkit SDK are installed, the HAT build process will automatically compile
58 all sources to dispatch with the CUDA backend.
59 
60 ```bash
61 java @hat/bld
62 ```
63 
64 ### Run HAT with the CUDA Backend
65 
66 You can enable the CUDA backend by using the `ffi-cuda` option from HAT.
67 For example, to run the Matrix Multiplication example:
68 
69 ```bash
70 java @hat/run ffi-cuda matmul 1D
71 ```