Update docs

docs/.readthedocs.yaml

@@ -5,7 +5,7 @@ build:
     rust: latest
   jobs:
     install:
-      - cargo install mdbook --root .
+      - cargo install mdbook mdbook-alerts --root .
     build:
       html:
         - ./bin/mdbook build docs --dest-dir $READTHEDOCS_OUTPUT/html

docs/book.toml

@@ -1,5 +1,8 @@
 [book]
 authors = ["Andrzej Janik"]
 language = "en"
+multilingual = false
 src = "src"
 title = "ZLUDA"
+
+[preprocessor.alerts]

docs/src/SUMMARY.md

@@ -1,3 +1,11 @@
 # Summary
 
-- [Chapter 1](./chapter_1.md)
+# Introduction
+- [Usage](./usage.md)
+- [Troubleshooting](./troubleshooting.md)
+# For developers
+- [Building from source](./building.md)
+# FAQ
+- [General questions](./general-questions.md)
+- [Supported hardware](./supported-hw.md)
+- [Supported software](./supported-sw.md)

docs/src/building.md

@@ -0,0 +1 @@
+# Building

docs/src/chapter_1.md

@@ -1 +0,0 @@
-# Chapter 1

docs/src/general-questions.md

@@ -0,0 +1,13 @@
+# General questions
+
+1. How I can donate to ZLUDA development?
+
+    The ZLUDA project is fully funded and only accepts donations of labor
+
+1. What organization is funding ZLUDA development?
+
+    This will be revealed in due time
+
+1. How can I follow ZLUDA's progress
+   
+   Every quarter we publish a progress report [ZLUDA's blog](https://vosen.github.io/ZLUDA/)

docs/src/supported-hw.md

@@ -0,0 +1,37 @@
+# Supported hardware
+
+1. AMD GPU support?
+
+     ZLUDA supports AMD Radeon RX 5000 series and newer GPUs (both desktop and integrated).
+     Older GPUs (Polaris, Vega, etc.) are not supported, server GPUs are not supported; those GPUs are sufficiently different as to require significant effort
+
+1. Intel GPU support?
+
+    ZLUDA used to support Intel GPUs, but it does not anymore. It is possible to add an Intel GPU backend again. The development team is focusing on high‑quality AMD GPU support, but we welcome contributions.
+
+1. NVIDIA GPU support?
+
+    Unlikely to ever be on the roadmap, because NVIDIA users can use the original CUDA. That said, if someone wants to add support we are open to contributions.
+
+1. Qualcomm GPU support?
+
+    It would be interesting to have Qualcomm GPU support, but the development team is focusing on high‑quality AMD GPU support. We welcome contributions.
+
+1. macOS support?
+
+    macOS support is not likely to ever be on the roadmap. There is very little non‑deprecated CUDA software for macOS and what remains will soon be unsupported.
+
+1. ZLUDA on top of OpenCL or Vulkan?
+
+    ZLUDA could be ported to OpenCL or Vulkan, but with drastically reduced functionality. This might be acceptable for a narrow use case, but it would not be as general‑purpose as using the native backend. Here is a sample of hardware/software features available with the current compilation path that are not exposed by either Vulkan or OpenCL:
+    * Disabling FP contraction
+    * Explicit alignment
+    * Some subgroup and group operators
+    * Bindless images
+    * Pointer casts
+    * Arbitrary virtual calls
+    * Inline assembly
+    * Rounding modes
+    * Denormal modes
+  
+    Additionally, performance libraries (cuBLAS, cuDNN, etc.) cannot be mapped through Vulkan or OpenCL.

docs/src/supported-sw.md

@@ -0,0 +1,25 @@
+# Supported software
+
+1. PyTorch support?
+
+    PyTorch support is currently the top priority for ZLUDA. We expect to have initial support fourth quarter of 2025
+
+1. Tensorflow support?
+
+   Tensorflow support is currently a top priority for ZLUDA and will follow PyTorch support
+
+1. Blender support
+
+    Blender is not on the roadmap, but it's often requested. Supported might be added aat certain point, but it's a low priority. If ZLUDA supports Blender, it will not support hardware ray-tracing (see _Hardware ray-tracing (OptiX) support?_ section below)
+
+1. Hardware ray-tracing (OptiX) support?
+
+    OptiX support is exceedingly complex. Wile it's built on top of CUDA, it uses its own dialect of PTX, uses its own host code and requires its own specific optimizations. It's unlikely that ZLUDA will ever support OptiX again. OptiX would require a very dedicated contributor to step in
+
+1. Support for games using 32 bit PhysX?
+
+   We are convinced that it's possible (both for AMD GPUs and NVIDIA GPUs). Necessary groundwork has been done (log collection) and there is a plan how to implement the feature. It's not on the roadmap and we are hoping for outside contributors to step in
+
+1. Support for games using 64 bit PhysX (GameWorks)?
+
+    It is definietely possible, pre-rollback ZLUDA had this capability. It's not on the roadmap and woulds require outside contributions

docs/src/troubleshooting.md

@@ -0,0 +1 @@
+# Troubleshooting

docs/src/usage.md

@@ -0,0 +1,43 @@
+# Usage
+
+> [!WARNING]  
+> This version of ZLUDA is under heavy development and will likely not work with your application yet. In the meantime, yuou are encouraged to try it and report results.
+
+## Get it
+
+ZLUDA evolves quickly. Download the [most recent pre-release version](https://github.com/vosen/ZLUDA/releases). From time to time we arbitrarily pick a pre-release version and we mark it as a new major version, but you don't have to wait for that
+
+## Use it
+
+### Windows
+You should have a recent AMD GPU driver ("AMD Software: Adrenalin Edition") installed.\
+To run your application either:
+* (_Recommended_) Copy all ZLUDA files (including `nvcuda.dll`) from `zluda` (if you downloaded a zip package) or `target\release` (if you built from sources) into a path which your application uses to load CUDA. Paths vary application to application, but usually it's the directory where the .exe file is located
+* Use ZLUDA launcher:
+    ```
+    <ZLUDA_DIRECTORY>\zluda_with.exe -- <APPLICATION> <APPLICATION_ARGUMENTS>
+    ```
+    ZLUDA launcher is known to be buggy and incomplete, but it's less invasive
+
+### Linux
+
+Run your application like this:
+* Recommended method
+    ```
+    LD_LIBRARY_PATH="<ZLUDA_DIRECTORY>:$LD_LIBRARY_PATH" <APPLICATION> <APPLICATION_ARGUMENTS>
+    ```
+
+    where `<ZLUDA_DIRECTORY>` is the directory which contains ZLUDA-provided `libcuda.so`: `zluda` if you downloaded a prebuilt package or `target/release` if you built from sources.
+
+* Alternative method
+    ```
+    LD_PRELOAD="<ZLUDA_DIRECTORY>/zluda_preload" <APPLICATION> <APPLICATION_ARGUMENTS>
+    ```
+
+    where `<ZLUDA_DIRECTORY>` is the directory which contains ZLUDA-provided `libcuda.so`: `zluda` if you downloaded a prebuilt package or `target/release` if you built from sources.
+
+
+
+### macOS
+
+Not supported