Fix docs deployment and refresh README and documentation - #601
Merged
Conversation
The stable docs URL (https://juliagpu.github.io/oneAPI.jl/stable) 404s because gh-pages only ever contained `dev`: Documenter creates the `stable` symlink and versioned directories only on a tag build, and no tag build has ever run. TagBot pushed tags using `secrets.GITHUB_TOKEN`, and GitHub does not trigger workflow runs for events created with the default token, so `docs.yml` never fired for v2.6.0 through v2.7.1 despite its `tags: '*'` trigger. Push tags over SSH with DOCUMENTER_KEY instead. Also add a `workflow_dispatch` trigger to the Documentation workflow so tagged docs can be re-deployed manually, and fix the canonical URL in docs/make.jl, which was copy-pasted from another project and pointed at ExaPF.jl on every page.
The README still described the pre-SPIRVIntrinsics state of the package: - SPIR-V is now produced by LLVM's SPIR-V back-end, not the Khronos SPIRV-LLVM-Translator; refresh the prose and the @device_code_llvm / @device_code_spirv output, which now shows __spirv_ControlBarrier and the new generator string. - Refresh the versioninfo() sample: NEO 26.18, libigc 2.34, SPIRV_Tools 2025.4, oneAPI_Support 0.10 (oneMKL 2025.3), plus the "Julia packages" section that versioninfo() gained. - Update the printed forms of oneArray and ZeDevice, which both changed. - Mention the oneMKL FFT support and the KernelAbstractions oneAPIBackend in the status section, and add a note on writing portable code. - Document deps/generate_interfaces.jl and the Runic formatting check, and give deps/build_local.jl its --project=deps invocation. The sparse example used oneSparseMatrixCSC; switch it to CSR and note that oneMKL's CSR-based sparse back-end leaves the triangular operations unavailable for CSC. Drop the stale "looking for a maintainer" line and the recorded test suite summary, whose counts and timings no longer match.
Several documented APIs did not match the package, and the examples were verified against an Arc A750 while fixing them: - memory.md called zeMemAllocDevice(context(), device(), 1024, 1), but that raw entry point takes six arguments and the example cannot run. Use the oneL0 device_alloc/free wrappers instead. - barrier takes a mandatory flags argument. kernels.md documented it as barrier(), device.md as barrier(flags=0), and performance.md called it without arguments in five kernels. Pass oneAPI.LOCAL_MEM_FENCE. - device.md documented the indexing intrinsics as 0-based (dim=0); they are 1-based in SPIRVIntrinsics, and so are the indices they return. - onemkl.md demonstrated sparse matvec on a oneSparseMatrixCSC. Switch to CSR and describe the CSC-as-transposed-CSR representation along with the triangular operations it rules out. Its Float64 arrays also needed fp64 support the example never mentioned, so use Float32. - The FFT example loaded FFTW, which is not a dependency; AbstractFFTs is what the oneMKL DFT integration hooks into. Also record the SPIRVIntrinsics and KernelAbstractions integrations and the SPIR-V back-end in the feature list, align the OS and hardware requirements with installation.md, and mention EnableDebugBreak and ONEAPI_MEMORY_LIMIT in the troubleshooting guide.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #601 +/- ##
=======================================
Coverage 79.15% 79.15%
=======================================
Files 50 50
Lines 3391 3391
=======================================
Hits 2684 2684
Misses 707 707 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
michel2323
referenced
this pull request
Aug 3, 2026
Aurora and other large deployments run Intel's long-term-servicing branch of the Compute Runtime rather than the rolling release oneAPI.jl targets. That branch predates a number of driver and IGC fixes, several of which corrupt results silently rather than raise an error. Add the workarounds behind a single opt-in switch, oneL0.LTS[], resolved from ONEAPI_LTS at load time and defaulting to off, so the rolling stack behaves exactly as before. Gated on that switch: * SPIR-V codegen goes through the Khronos translator instead of LLVM's SPIR-V back-end, whose output the LTS NEO/IGC runtime does not accept (#491). Both JLLs stay dependencies; GPUCompiler resolves the tool from the target's `backend` field, so the choice is made at compile time. * BFloat16 is forced off. The LTS SPIR-V stack cannot codegen native bfloat in generic kernels -- a kernel that merely keeps a bfloat value fails with InvalidIRError, and declaring SPV_KHR_bfloat16 crashes the runtime. _device_supports_bfloat16() reports hardware capability and does not capture this, so the test suite and examples/bfloat16.jl gate on the switch instead. * Reductions avoid the strided-read miscompile that silently breaks `sum(transpose(x))`, `a == transpose(b)` and `ishermitian`. Non-dense inputs are materialized before reducing, and reductions that keep the contiguous leading dimension use a coalesced one-work-item-per-slice kernel. Reductions that also reduce dim 1 keep a contiguous innermost axis and are left alone; an Int32 regression test covers that boundary. * Buffers are freed only after draining the queues that may still reference them. LTS NEO advertises ZE_extension_memory_free_policies but ignores BLOCKING_FREE, so a GC-driven free of in-flight work faults and bans the context, surfacing later as a ZE_RESULT_ERROR_UNKNOWN at an unrelated call. A per-(context, device) registry tracks every queue -- including the replacement KA.priority! installs -- and the queue finalizer drains before destroying, with a bounded wait so a task that dies mid-submission cannot hang finalization. Independently of that switch, ONEAPI_SYNC_EACH_SUBMISSION=1 synchronizes after every command-list submission, working around a dropped-tail corruption seen when several processes oversubscribe a single tile. It costs roughly 3x throughput and is off by default, with getter, setter and scoped forms available at runtime. Also, not specific to the LTS stack: dlopen the NEO driver by full path during __init__ so libsycl's bundled Level Zero loader finds it in-process. Setting LD_LIBRARY_PATH there never could -- glibc captures it once at process startup -- so it only ever served spawned worker processes. The self-hosted Aurora runner is configured to exercise the LTS path, with buildkite continuing to cover the rolling stack, and docs/src/lts.md documents both switches, what they change, and what they cost.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.