halide 19.0.0__cp38-cp38-win_amd64.whl

halide/share/doc/Halide/doc/Vulkan.md

@@ -0,0 +1,287 @@
+# Vulkan Support for Halide
+
+Halide supports the Khronos Vulkan framework as a compute API backend for GPU-like 
+devices, and compiles directly to a binary SPIR-V representation as part of its 
+code generation before submitting it to the Vulkan API. Both JIT and AOT usage 
+are supported via the `vulkan` target flag (e.g. `HL_JIT_TARGET=host-vulkan`).
+
+Vulkan support is actively under development, and considered *BETA* quality
+at this stage.  Tests are passing, but performance tuning and user testing is needed 
+to identify potential issues before rolling this into production.  
+
+See [below](#current-status) for details.
+
+# Compiling Halide w/Vulkan Support
+
+You'll need to configure Halide and enable the cmake option TARGET_VULKAN (which is now ON by default).
+
+For example, on Linux & OSX:
+
+```
+% cmake -G Ninja -DTARGET_VULKAN=ON -DCMAKE_BUILD_TYPE=Release -DLLVM_DIR=$LLVM_ROOT/lib/cmake/llvm 
+% cmake --build build --config Release
+```
+
+On Windows, you may need to specify the location of the Vulkan SDK if the paths aren't resolved by CMake automatically.  For example (assuming the Vulkan SDK is installed in the default path):
+
+```
+C:\> cmake -G Ninja -DTARGET_VULKAN=ON -DCMAKE_BUILD_TYPE=Release -DLLVM_DIR=$LLVM_ROOT/lib/cmake/llvm -DVulkan_LIBRARY=C:\VulkanSDK\1.3.231.1\Lib\vulkan-1.lib -DVulkan_INCLUDE_DIR=C:\VulkanSDK\1.3.231.1\Include\vulkan -S . -B build
+C:\> cmake --build build --config Release
+
+```
+
+# Vulkan Runtime Environment:
+
+Halide has no direct dependency on Vulkan for code-generation, but the runtime
+requires a working Vulkan environment to run Halide generated code. Any valid 
+Vulkan v1.0+ device driver should work.
+
+Specifically, you'll need:
+
+-   A vendor specific Vulkan device driver
+-   The generic Vulkan loader library
+
+For AMD & NVIDIA & Intel devices, download and install the latest graphics driver 
+for your platform. Vulkan support should be included.
+
+## Windows 
+
+To build Halide AOT generators, you'll need the Vulkan SDK (specifically the Vulkan loader library and headers):
+https://sdk.lunarg.com/sdk/download/latest/windows/vulkan-sdk.exe
+
+For Vulkan device drivers, consult the appropriate hardware vendor for your device.  A few common ones are listed below.
+
+-   [AMD Vulkan Driver](https://www.amd.com/en/technologies/vulkan)
+-   [NVIDIA Vulkan Driver](https://developer.nvidia.com/vulkan-driver)
+-   [INTEL Vulkan Driver](https://www.intel.com/content/www/us/en/download-center/home.html)
+
+## Linux 
+
+The Vulkan SDK packages are now being maintained by LunarG.  These include the Vulkan Loader library, as well as the Vulkan Tools packages. Instructions for installing these can be found on their [Getting Started Guide](https://vulkan.lunarg.com/doc/view/latest/linux/getting_started_ubuntu.html).
+
+Once the SDK has been installed, you need to install the appropriate driver for your device.  Proprietary drivers can be installed via 'apt' using PPA's for each vendor. Examples for AMD and NVIDIA are provided below.
+
+For AMD on Ubuntu v22.04:
+```
+$ sudo add-apt-repository ppa:oibaf/graphics-drivers
+$ sudo apt update
+$ sudo apt upgrade
+$ sudo apt install libvulkan1 mesa-vulkan-drivers vulkan-tools
+```
+
+For NVIDIA on Ubuntu v22.04:
+```
+$ sudo add-apt-repository ppa:graphics-drivers/ppa
+$ sudo apt update
+$ sudo apt upgrade
+# - replace ### with latest driver release (e.g. 515)
+$ sudo apt install nvidia-driver-### nvidia-settings libvulkan1 vulkan-tools
+```
+
+Note that only valid drivers for your system should be installed since there are
+reports of the Vulkan loader segfaulting just by having a non-supported driver present. 
+Specifically, the seemingly generic `mesa-vulkan-drivers` actually includes the AMD 
+graphics driver, which can cause problems if installed on an NVIDIA-only system. 
+
+## Mac
+
+You're better off using Halide's Metal backend instead, but it is possible to run 
+Vulkan apps on a Mac via the MoltenVK library:
+
+-   [MoltenVK Project](https://github.com/KhronosGroup/MoltenVK)
+
+The easiest way to get the necessary dependencies is to use the official MoltenVK SDK
+installer provided by LunarG:
+
+-   [MoltenVK SDK (Latest Release)](https://sdk.lunarg.com/sdk/download/latest/mac/vulkan-sdk.dmg)
+
+Alternatively, if you have the [Homebrew](https://brew.sh/) package manager installed 
+for MacOS, you can use it to install the Vulkan Loader and MoltenVK compatibility 
+layer:
+
+```
+$ brew install vulkan-loader molten-vk
+```
+
+# Testing Your Vulkan Environment
+
+You can validate that everything is configured correctly by running the `vulkaninfo`
+app (bundled in the vulkan-utils package) to make sure your device is detected (eg):
+
+```
+$ vulkaninfo
+==========
+VULKANINFO
+==========
+
+Vulkan Instance Version: 1.3.224
+
+
+Instance Extensions: count = 19
+===============================
+	...
+
+Layers: count = 10
+==================
+VK_LAYER_KHRONOS_profiles (Khronos Profiles layer) Vulkan version 1.3.224, layer version 1:
+	Layer Extensions: count = 0
+	Devices: count = 1
+		GPU id = 0 (NVIDIA GeForce RTX 3070 Ti)
+		Layer-Device Extensions: count = 1
+
+...
+
+```
+
+Make sure everything looks correct before continuing!
+
+# Targetting Vulkan
+
+To generate Halide code for Vulkan, simply add the `vulkan` flag to your target as well as any other optional device specific features you wish to enable for Halide:
+
+| Target Feature | Description | 
+| --             | --          |
+| `vulkan`       | Enables the vulkan backend |
+| `vk_int8`      | Allows 8-bit integer storage types to be used |
+| `vk_int16`     | Allows 16-bit integer storage types to be used |
+| `vk_int64`     | Allows 64-bit integer storage types to be used |
+| `vk_float16`   | Allows 16-bit floating-point values to be used for computation |
+| `vk_float64`   | Allows 64-bit floating-point values to be used for computation |
+| `vk_v10`       | Generates code compatible with the Vulkan v1.0+ API |
+| `vk_v12`       | Generates code compatible with the Vulkan v1.2+ API |
+| `vk_v13`       | Generates code compatible with the Vulkan v1.3+ API |
+
+Note that 32-bit integer and floating-point types are always available. All other optional device features are off by default (since they are not required by the Vulkan API, and thus must be explicitly enabled to ensure that the code being generated will be compatible with the device and API version being used for execution). 
+
+For AOT generators add `vulkan` (and any other flags you wish to use) to the target command line option:
+
+```
+$ ./lesson_15_generate -g my_first_generator -o . target=host-vulkan-vk_int8-vk_int16
+```
+
+For JIT apps use the `HL_JIT_TARGET` environment variable:
+
+```
+$ HL_JIT_TARGET=host-vulkan-vk_int8-vk_int16 ./tutorial/lesson_01_basics
+```
+
+# Useful Runtime Environment Variables
+
+To modify the default behavior of the runtime, the following environment 
+variables can be used to adjust the configuration of the Vulkan backend 
+at execution time:
+
+`HL_VK_LAYERS=...` will tell Halide to choose a suitable Vulkan instance
+that supports the given list of layers. If not set, `VK_INSTANCE_LAYERS=...` 
+will be used instead. If neither are present, Halide will use the first 
+Vulkan compute device it can find.  Multiple layers can be specified using 
+the appropriate environment variable list delimiter (`:` on Linux/OSX/Posix, 
+or `;` on Windows).
+
+`HL_VK_DEVICE_TYPE=...` will tell Halide to choose which type of device
+to select for creating the Vulkan instance. Valid options are 'gpu', 
+'discrete-gpu', 'integrated-gpu', 'virtual-gpu', or 'cpu'. If not set,
+Halide will search for the first 'gpu' like device it can find, or fall back
+to the first compute device it can find.
+
+`HL_VK_ALLOC_CONFIG=...` will tell Halide to configure the Vulkan memory
+allocator use the given constraints specified as 5x integer values 
+separated by the appropriate environment variable list delimiter 
+(e.g. `N:N:N:N:N` on Linux/OSX/Posix, or `N;N;N;N;N` on Windows). These values 
+correspond to `maximum_pool_size`, `minimum_block_size`, `maximum_block_size`, 
+`maximum_block_count` and `nearest_multiple`. 
+
+The `maximum_pool_size` constraint will tell Halide to configure the 
+Vulkan memory allocator to never request more than N megabytes for the
+entire pool of allocations for the context. This includes all resource 
+blocks used for suballocations. Setting this to a non-zero value will 
+limit the amount device memory used by Halide, which may be useful when
+other applications and frameworks are competing for resources. 
+Default is 0 ... meaning no limit.
+
+The `minimum_block_size` constraint will tell Halide to configure the 
+Vulkan memory allocator to always request a minimum of N megabytes for 
+a resource block, which will be used as a pool for suballocations.  
+Increasing this value may improve performance while sacrificing the amount 
+of available device memory. Default is 32MB.
+
+The `maximum_block_size` constraint will tell Halide to configure the 
+Vulkan memory allocator to never exceed a maximum of N megabytes for a 
+resource block.  Decreasing this value may free up more memory but may 
+impact performance, and/or restrict allocations to be unusably small. 
+Default is 0 ... meaning no limit.
+
+The `maximum_block_count` constraint will tell Halide to configure the 
+Vulkan memory allocator to never exceed a total of N block allocations.  
+Decreasing this value may free up more memory but may impact performance, 
+and/or restrict allocations. Default is 0 ... meaning no limit.
+
+The `nearest_multiple` constraint will tell Halide to configure the 
+Vulkan memory allocator to always round up the requested allocation sizes
+to the given integer value. This is useful for architectures that
+require specific alignments for subregions allocated within a block.
+Default is 32 ... setting this to zero means no constraint. 
+
+# Debug Environment Variables
+
+The following environment variables may be useful for tracking down potential
+issues related to Vulkan:
+
+`HL_DEBUG_CODEGEN=3` will print out debug info that includees the SPIR-V
+code generator used for Vulkan while it is compiling.
+
+`HL_SPIRV_DUMP_FILE=...` specifies a file to dump the binary SPIR-V generated
+during compilation. Useful for debugging CodeGen issues. Can be inspected,
+validated and disassembled via the SPIR-V tools:
+
+https://github.com/KhronosGroup/SPIRV-Tools
+
+
+In addition to the SPIR-V Tools, you may also wish to install the Khronos Validation 
+Layers which provide an exhaustive suite of runtime checks that can be injected
+by adding `VK_LAYER_KHRONOS_validation` to the `VK_INSTANCE_LAYERS=` environment
+variable. 
+
+To install the validation layers and the SPIR-V tools on Ubuntu v22.04:
+
+```
+$ sudo apt install vulkan-validationlayers vulkan-validationlayers-dev spirv-tools
+```
+
+To test the validation layer, you can prepend your shell command for any Vulkan
+enabled binary with the appropriate environment settings.  For example, 
+you can run one of the JIT-enabled correctness tests w/debug output and validation
+layers enabled like so:
+
+```
+$ VK_INSTANCE_LAYERS=VK_LAYER_KHRONOS_validation HL_JIT_TARGET=host-vulkan-vk_int8-vk_int16-vk_int64-vk_float16-vk_float64-vk_v13-debug ./build/test/correctness/correctness_hello_gpu
+```
+
+# Current Status
+
+All correctness tests are now passing on tested configs for Linux & Windows using the target `host-vulkan-vk_int8-vk_int16-vk_int64-vk_float16-vk_float64-vk_v13` on LLVM v14.x. 
+
+MacOS passes most tests but encounters internal MoltenVK code translation issues for wide vectors, and ambiguous function calls.
+
+Python apps, tutorials and correctness tests are now passing, but the AOT cases are skipped since the runtime environment needs to be customized to locate the platform specific Vulkan loader library.
+
+Android platform support is currently being worked on.
+
+# Caveats:
+
+-   Other than 32-bit floats and integers, every other data type is optional per the Vulkan spec
+-   Float 64-bit types can be enabled, but there aren't any native math functions available in SPIR-V
+-   Only one dynamically sized shared memory allocation can be used, but any number of 
+    fixed sized allocation are supported (up to the maximum amount allowed by the device)
+
+# Known TODO:
+
+-   Performance tuning of CodeGen and Runtime
+-   More platform support (Android is work-in-progress, RISC-V, etc)
+-   Adapt unsupported types to supported types (if missing vk_int8 then promote to uint32_t)?
+-   Better debugging utilities using the Vulkan debug hooks.
+-   Allow debug symbols to be stripped from SPIR-V during codegen to reduce
+    memory overhead for large kernels.
+-   Investigate floating point rounding and precision (v1.3 adds more controls)
+-   Investigate memory model usage (can Halide gain anything from these?)
+

halide/share/doc/Halide/doc/WebAssembly.md

@@ -0,0 +1,228 @@
+# WebAssembly Support for Halide
+
+Halide supports WebAssembly (Wasm) code generation from Halide using the LLVM
+backend.
+
+As WebAssembly itself is still under active development, Halide's support has
+some limitations. Some of the most important:
+
+-   Sign-extension operations are enabled by default (but can be avoided via
+    Target::WasmMvpOnly).
+-   Non-trapping float-to-int conversions are enabled by default (but can be
+    avoided via Target::WasmMvpOnly).
+-   Fixed-width SIMD (128 bit) can be enabled via Target::WasmSimd128.
+-   Threads have very limited support via Target::WasmThreads; see
+    [below](#using-threads) for more details.
+-   Halide's JIT for Wasm is extremely limited and really useful only for
+    internal testing purposes.
+
+# Additional Tooling Requirements:
+
+-   In additional to the usual install of LLVM and clang, you'll need lld.
+-   Locally-installed version of Emscripten, 1.39.19+
+
+Note that for all of the above, earlier versions might work, but have not been
+tested.
+
+# AOT Limitations
+
+Halide outputs a Wasm object (.o) or static library (.a) file, much like any
+other architecture; to use it, of course, you must link it to suitable calling
+code. Additionally, you must link to something that provides an implementation
+of `libc`; as a practical matter, this means using the Emscripten tool to do
+your linking, as it provides the most complete such implementation we're aware
+of at this time.
+
+-   Halide ahead-of-time tests assume/require that you have Emscripten installed
+    and available on your system, with the `EMSDK` environment variable set
+    properly.
+
+# JIT Limitations
+
+It's important to reiterate that the WebAssembly JIT mode is not (and will never
+be) appropriate for anything other than limited self tests, for a number of
+reasons:
+
+-   It actually uses an interpreter (from the WABT toolkit
+    [https://github.com/WebAssembly/wabt]) to execute wasm bytecode; not
+    surprisingly, this can be *very* slow.
+-   Wasm effectively runs in a private, 32-bit memory address space; while the
+    host has access to that entire space, the reverse is not true, and thus any
+    `define_extern` calls require copying all `halide_buffer_t` data across the
+    Wasm<->host boundary in both directions. This has severe implications for
+    existing benchmarks, which don't currently attempt to account for this extra
+    overhead. (This could possibly be improved by modeling the Wasm JIT's buffer
+    support as a `device` model that would allow lazy copy-on-demand.)
+-   Host functions used via `define_extern` or `HalideExtern` cannot accept or
+    return values that are pointer types or 64-bit integer types; this includes
+    things like `const char *` and `user_context`. Fixing this is tractable, but
+    is currently omitted as the fix is nontrivial and the tests that are
+    affected are mostly non-critical. (Note that `halide_buffer_t*` is
+    explicitly supported as a special case, however.)
+-   Threading isn't supported at all (yet); all `parallel()` schedules will be
+    run serially.
+-   The `.async()` directive isn't supported at all, not even in
+    serial-emulation mode.
+-   You can't use `Param<void *>` (or any other arbitrary pointer type) with the
+    Wasm jit.
+-   You can't use `Func.debug_to_file()`, `Func.set_custom_do_par_for()`,
+    `Func.set_custom_do_task()`, or `Func.set_custom_allocator()`.
+-   The implementation of `malloc()` used by the JIT is incredibly simpleminded
+    and unsuitable for anything other than the most basic of tests.
+-   GPU usage (or any buffer usage that isn't 100% host-memory) isn't supported
+    at all yet. (This should be doable, just omitted for now.)
+
+Note that while some of these limitations may be improved in the future, some
+are effectively intrinsic to the nature of this problem. Realistically, this JIT
+implementation is intended solely for running Halide self-tests (and even then,
+a number of them are fundamentally impractical to support in a hosted-Wasm
+environment and are disabled).
+
+In sum: don't plan on using Halide JIT mode with Wasm unless you are working on
+the Halide library itself.
+
+## Using V8 as the interpreter
+
+There is experimental support for using V8 as the interpreter in JIT mode, rather than WABT.
+This is enabled by the CMake command line options `-DWITH_V8=ON -DWITH_WABT=OFF` (only one of them can be used at a time).
+You must build V8 locally V8, then specify the path to the library and headers as CMake options.
+This is currently only tested on x86-64-Linux and requires v8 version 9.8.177 as a minimum.
+
+The canonical instructions to build V8 are at
+[v8.dev](https://v8.dev/docs/build), and [there are examples for embedding
+v8](https://v8.dev/docs/embed). The process for Halide is summarized below.
+
+- Install
+  [`depot_tools`](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up)
+- Fetch v8 source code (and install required dependencies):
+    ```
+    $ gclient
+    $ mkdir ~/v8 && cd ~/v8
+    $ fetch v8
+    $ cd ~/v8/v8
+    $ git checkout origin/9.8.177
+    ```
+- Create a build configuration: `tools/dev/v8gen.py x64.release.sample`
+- Turn off pointer compression: `echo 'v8_enable_pointer_compression = false' >> out.gn/x64.release.sample/args.gn`
+- Disable the GDB-JIT interface (conflicts with LLVM): `echo 'v8_enable_gdbjit = false' >> out.gn/x64.release.sample/args.gn`
+- Build the static library: `autoninja -C out.gn/x64.release.sample v8_monolith`
+
+With V8 built, we can pass the CMake options:
+
+- `V8_INCLUDE_DIR`, path to V8 includes, e.g. `$HOME/v8/v8/include`
+- `V8_LIBRARY`, path to V8 static library, e.g. `$HOME/v8/v8/out.gn/x64.release.sample/obj/libv8_monolith.a`
+
+An example to configure Halide with V8 support, build and run an example test:
+
+```
+$ cd /path/to/halide
+$ export HL_TARGET=wasm-32-wasmrt-wasm_simd128
+$ export HL_JIT_TARGET=${HL_TARGET}
+$ cmake -G Ninja \
+      -DWITH_WABT=OFF \
+      -DWITH_V8=ON \
+      -DV8_INCLUDE_DIR=$HOME/v8/v8/include \
+      -DV8_LIBRARY=$HOME/v8/v8/out.gn/x64.release.sample/obj/libv8_monolith.a \
+      -DHalide_TARGET=${HL_TARGET} \
+      /* other cmake settings here as appropriate */
+
+$ cmake --build .
+$ ctest -L "correctness|generator" -j
+```
+
+
+# To Use Halide For WebAssembly:
+
+-   Ensure WebAssembly is in LLVM_TARGETS_TO_BUILD; if you use the default
+    (`"all"`) then it's already present, but otherwise, add it explicitly:
+
+```
+-DLLVM_TARGETS_TO_BUILD="X86;ARM;NVPTX;AArch64;PowerPC;Hexagon;WebAssembly
+```
+
+## Enabling wasm JIT
+
+If you want to run `test_correctness` and other interesting parts of the Halide
+test suite (and you almost certainly will), you'll need to ensure that LLVM is
+built with wasm-ld:
+
+-   Ensure that you have lld in LVM_ENABLE_PROJECTS:
+
+```
+cmake -DLLVM_ENABLE_PROJECTS="clang;lld" ...
+```
+
+-   To run the JIT tests, set `HL_JIT_TARGET=wasm-32-wasmrt` (possibly adding
+    `wasm_simd128`) and run CMake/CTest normally. Note that wasm testing is
+    only supported under CMake (not via Make).
+
+## Enabling wasm AOT
+
+If you want to test ahead-of-time code generation (and you almost certainly
+will), you need to install Emscripten locally.
+
+-   The simplest way to install is probably via the Emscripten emsdk
+    (https://emscripten.org/docs/getting_started/downloads.html).
+
+-   To run the AOT tests, set `HL_TARGET=wasm-32-wasmrt` (possibly adding
+    `wasm_simd128`) and run CMake/CTest normally. Note that wasm testing is
+    only supported under CMake (not via Make).
+
+# Running benchmarks
+
+The `test_performance` benchmarks are misleading (and thus useless) for Wasm, as
+they include JIT overhead as described elsewhere. Suitable benchmarks for Wasm
+will be provided at a later date. (See
+https://github.com/halide/Halide/issues/5119 and
+https://github.com/halide/Halide/issues/5047 to track progress.)
+
+# Using Threads
+
+You can use the `wasm_threads` feature to enable use of a normal pthread-based
+thread pool in Halide code, but with some careful caveats:
+
+-   This requires that you use a wasm runtime environment that provides
+    pthread-compatible wrappers. At this time of this writing, the only
+    environment known to support this well is Emscripten (when using the
+    `-pthread` flag, and compiling for a Web environment). In this
+    configuration, Emscripten goes to great lengths to make WebWorkers available
+    via the pthreads API. (You can see an example of this usage in
+    apps/HelloWasm.) Note that not all wasm runtimes support WebWorkers;
+    generally, you need a full browser environment to make this work (though
+    some versions of some shell tools may also support this, e.g. nodejs).
+-   There is currently no support for using threads in a WASI environment, due
+    to current limitations in the WASI specification. (We hope that this will
+    improve in the future.)
+-   There is no support for using threads in the Halide JIT environment, and no
+    plans to add them anytime in the near-term future.
+
+# Known Limitations And Caveats
+
+-   Current trunk LLVM (as of July 2020) doesn't reliably generate all of the
+    Wasm SIMD ops that are available; see
+    https://github.com/halide/Halide/issues/5130 for tracking information as
+    these are fixed.
+-   Using the JIT requires that we link the `wasm-ld` tool into libHalide; with
+    some work this need could possibly be eliminated.
+-   OSX and Linux-x64 have been tested. Windows hasn't; it should be supportable
+    with some work. (Patches welcome.)
+-   None of the `apps/` folder has been investigated yet. Many of them should be
+    supportable with some work. (Patches welcome.)
+-   We currently use v8/d8 as a test environment for AOT code; we may want to
+    consider using Node or (better yet) headless Chrome instead (which is
+    probably required to allow for using threads in AOT code).
+
+# Known TODO:
+
+-   There's some invasive hackiness in Codgen_LLVM to support the JIT
+    trampolines; this really should be refactored to be less hacky.
+-   Can we rework JIT to avoid the need to link in wasm-ld? This might be
+    doable, as the wasm object files produced by the LLVM backend are close
+    enough to an executable form that we could likely make it work with some
+    massaging on our side, but it's not clear whether this would be a bad idea
+    or not (i.e., would it be unreasonably fragile).
+-   Buffer-copying overhead in the JIT could possibly be dramatically improved
+    by modeling the copy as a "device" (i.e. `copy_to_device()` would copy from
+    host -> wasm); this would make the performance benchmarks much more useful.
+-   Can we support threads in the JIT without an unreasonable amount of work?
+    Unknown at this point.

halide/share/doc/Halide/doc/WebGPU.md

@@ -0,0 +1,128 @@
+# WebGPU support for Halide
+
+Halide has work-in-progress support for generating and running WebGPU shaders.
+This can be used in conjunction with the WebAssembly backend to bring
+GPU-accelerated Halide pipelines to the web.
+
+As the first version of the WebGPU standard is itself still being developed,
+Halide's support has some limitations and may only work with certain browsers
+and versions of Emscripten.
+
+## Known limitations
+
+The following is a non-comprehensive list of known limitations:
+
+-   Only 32-bit integers and floats have efficient support.
+    * 8-bit and 16-bit integers are implemented using emulation. Future
+      extensions to WGSL will allow them to be implemented more efficiently.
+    * 64-bit integers and floats will likely remain unsupported until WGSL gains
+      extensions to support them.
+-   Wrapping native device buffer handles is not yet implemented.
+-   You must use CMake/CTest to build/test Halide for WebGPU; using the Makefile
+    is not supported for WebGPU testing (and probably never will be).
+
+In addition to these functional limitations, the performance of the WebGPU
+backend has not yet been evaluated, and so optimizations in the runtime or
+device codegen may be required before it becomes profitable to use.
+
+## Running with WebAssembly via Emscripten: `HL_TARGET=wasm-32-wasmrt-webgpu`
+
+> _Tested with top-of-tree Emscripten as of 2023-02-23, against Chrome v113._
+
+Halide can generate WebGPU code that can be integrated with WASM code using
+Emscripten.
+
+When invoking `emcc` to link Halide-generated objects, include these flags:
+`-s USE_WEBGPU=1 -s ASYNCIFY`.
+
+Tests that use AOT compilation can be run using a native WebGPU implementation
+that has Node.js bindings, such as [Dawn](https://dawn.googlesource.com/dawn/).
+You must set an environment variable named `HL_WEBGPU_NODE_BINDINGS` that
+has an absolute path to the bindings to run these tests, e.g. `HL_WEBGPU_NODE_BINDINGS=/path/to/dawn.node`.
+
+See [below](#setting-up-dawn) for instructions on building the Dawn Node.js
+bindings.
+
+JIT compilation is not supported when using WebGPU with WASM.
+
+## Running natively: `HL_TARGET=host-webgpu`
+
+> _Tested with top-of-tree Dawn as of 2023-11-27 [commit b5d38fc7dc2a20081312c95e379c4a918df8b7d4]._
+
+For testing purposes, Halide can also target native WebGPU libraries, such as
+[Dawn](https://dawn.googlesource.com/dawn/) or
+[wgpu](https://github.com/gfx-rs/wgpu).
+This is currently the only path that can run the JIT correctness tests.
+See [below](#setting-up-dawn) for instructions on building Dawn.
+
+> Note that as of 2023-11-27, wgpu is not supported due to
+> [lacking `override` support for WGSL](https://github.com/gfx-rs/wgpu/issues/1762)
+> which we require > in order to set GPU block sizes.
+
+When targeting WebGPU with a native target, Halide defaults to looking for a
+build of Dawn (with several common names and suffixes); you can override this
+by setting the `HL_WEBGPU_NATIVE_LIB` environment variable to the absolute path
+to the library you want.
+
+Note that it is explicitly legal to define both `HL_WEBGPU_NATIVE_LIB` and
+`HL_WEBGPU_NODE_BINDINGS` at the same time; the correct executable environment
+will be selected based on the Halide target specified.
+
+Note that it is explicitly legal to specify both WEBGPU_NATIVE_LIB and
+WEBGPU_NODE_BINDINGS for the same build; the correct executable environment
+will be selected based on the Halide target specified.
+
+## Setting up Dawn
+
+Building Dawn's Node.js bindings currently requires using CMake.
+
+First, [install `depot_tools`](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up) and add it to the
+`PATH` environment variable.
+
+Next, get Dawn and its dependencies:
+
+    # Clone the repo
+    git clone https://dawn.googlesource.com/dawn
+    cd dawn
+
+    # Bootstrap the gclient configuration with Node.js bindings enabled
+    cp scripts/standalone-with-node.gclient .gclient
+
+    # Fetch external dependencies and toolchains with gclient
+    gclient sync
+
+    # Other dependencies that must be installed manually:
+    # - golang
+
+Finally, build Dawn, enabling both the Node.js bindings and shared libraries:
+
+    mkdir -p <build_dir>
+    cd <build_dir>
+
+    cmake <dawn_root_dir> -G Ninja \
+        -DCMAKE_BUILD_TYPE=Release \
+        -DDAWN_BUILD_NODE_BINDINGS=1 \
+        -DDAWN_ENABLE_PIC=1 \
+        -DBUILD_SHARED_LIBS=ON
+
+    ninja dawn.node webgpu_dawn
+
+This will produce the following artifacts:
+- Node.js bindings: `<build_dir>/dawn.node`
+- Native library: `<build_dir>/src/dawn/native/libwebgpu_dawn.{so,dylib,dll}`
+
+These paths can then be used for the `HL_WEBGPU_NODE_BINDINGS` and
+`HL_WEBGPU_NATIVE_LIB` environment variables when using Halide.
+
+## Updating mini_webgpu.h
+
+The recommended method for updating `mini_webgpu.h` is to copy the
+`gen/include/dawn/webgpu.h` file from the Dawn build directory, then:
+- Restore the `// clang-format {off,on}` lines.
+- Comment out the `#include <std*>` lines.
+- Remove the `void` parameter from the `WGPUProc` declaration.
+
+This guarantees a version of the WebGPU header that is compatible with Dawn.
+When the native API eventually stabilizes, it should be possible to obtain a
+header from the `webgpu-native` GitHub organization that will be compatible
+with Dawn, wgpu, and Emscripten.