Ubuntu 24.04 environment docs

docs/env/ubuntu/24.04.md

@@ -0,0 +1,82 @@
+# Ubuntu 24.04 Setup Instructions
+
+## Verify Hardware Support
+
+Most modern GPUs support OpenCL. For integrated graphics devices (iGPUs), use `lscpu` to get the processor SKU. Detailed information for Intel SKUs is available from [ark.intel.com](ark.intel.com). Detailed information for AMD processors is available from [AMD's product page](https://www.amd.com/en/products/specifications/processors).
+
+## Build Dependencies
+
+OCL Headers:
+
+```bash
+sudo apt install opencl-c-headers opencl-clhpp-headers
+```
+
+The OpenCL API has its own set of header files; the above command installs both C and C++ headers files. The C header can be found in `<CL/cl.h>`; the C++ header is in `<CL/cl.hpp>`.
+
+OCL ICD Loader:
+
+```bash
+sudo apt install ocl-icd-opencl-dev
+```
+
+OpenCL applications generally link against an OpenCL Installable Compute Device (ICD) loader instead of a specific OpenCL implementation; see [https://github.com/bashbaug/OpenCLPapers/blob/master/OpenCLOnLinux.asciidoc](https://github.com/bashbaug/OpenCLPapers/blob/master/OpenCLOnLinux.asciidoc) for more information about this system.
+
+## Runtime Dependencies
+
+OpenCL requires a compute runtime to manage the interaction between the OpenCL API and the GPU.
+
+### OCL ICD Loader
+
+```bash
+sudo apt install ocl-icd-libopencl1
+```
+
+OpenCL applications generally link against an OpenCL Installable Compute Device (ICD) loader instead of a specific OpenCL implementation; see [https://github.com/bashbaug/OpenCLPapers/blob/master/OpenCLOnLinux.asciidoc](https://github.com/bashbaug/OpenCLPapers/blob/master/OpenCLOnLinux.asciidoc) for more information about this system.
+
+### AMD Compute Runtime
+
+AMD supports OpenCL through their ROCm platform. Installation instructions are [here](https://rocmdocs.amd.com/en/latest/Installation_Guide/Installation-Guide.html#ubuntu).
+
+### Intel Compute Runtime
+
+Intel's OpenCL support is provided through the NEO compute runtime. Download packages from the project's [GitHub releases page](https://github.com/intel/compute-runtime/releases).
+
+### Nvidia Compute Runtime
+
+Nvidia provides OpenCL support through their proprietary driver, available from the [graphics-drivers PPA](https://launchpad.net/~graphics-drivers/+archive/ubuntu/ppa).
+
+```bash
+sudo add-apt-repository ppa:graphics-drivers/ppa
+sudo apt update
+sudo apt install nvidia-graphics-drivers-<version>
+```
+
+### Configure Permissions
+
+```bash
+sudo usermod -a -G video $USER
+sudo usermod -a -G render $USER
+```
+
+Users running OpenCL applications on a GPU require additional permissions granted by the groups above.
+
+## Verification
+
+The `clinfo` utility can be used to verify the environment has been properly configured.
+
+```bash
+$ sudo apt install clinfo
+$ clinfo
+<platform information should show here>
+```
+
+## Troubleshooting
+
+If `clinfo` indicates there are 0 supported platforms:
+
+1. Verify your host has OpenCL-capable hardware attached
+2. Verify clinfo is running as a user with appropriate group membership
+3. Verify new group membership has been applied (this may require logout or reboot)
+4. Verify the correct compute runtime is installed
+5. Check the kernel log (`sudo dmesg`) for related errors