oneDNN Documentation Audit
Docs site self-identifies as v3.13.0 but no v3.13 release exists on GitHub (latest stable is v3.11.3, v3.12 is still -rc), and the site systematically offloads canonical reference data (system requirements, dependency versions) to the GitHub README while exposing a half-renamed ONEDNN_*/DNNL_* build-option surface, an undocumented f4_e3m0 deprecation, a typo'd Windows DLL path, and a broken navigation link to the Graph guide.
1. Docs version (v3.13.0) does not match any released artifact (critical)
Location: https://uxlfoundation.github.io/oneDNN/ (top-level index) vs. https://github.com/uxlfoundation/oneDNN/releases
Problem: The documentation site self-labels as "oneDNN v3.13.0 documentation," but the most recent stable GitHub release is v3.11.3 (April 17, 2025), and v3.12 exists only as a pre-release (v3.12-rc, April 17, 2025). There is no v3.13 release of any kind — pre-release or otherwise — on the releases page. The docs are describing APIs and behavior for a version no consumer can install. Compounding this, no per-feature "Available since" markers appear on data types, ISAs, attributes, or experimental features, so any APIs added between v3.11.3 and v3.13.0 are surfaced as if they exist in installed library versions.
Consequence: A developer who pins to whatever is currently shipping (v3.11.3) and reads the docs is reading a forward-dated specification. Any feature, type, attribute, or build flag that landed between v3.11.3 and v3.13.0 is documented with no version annotation telling the reader "this requires unreleased master." For agents this is worse — they cannot tell which API surface is real, and will confidently emit code that fails to compile against the installed library.
The fix: Either publish a v3.13.0 tag/release, or relabel the live docs to match what shipped (e.g., "v3.12 (pre-release)" or "main / unreleased") and host versioned doc archives keyed to actual releases. Add a per-feature "Available since" tag on data types, ISAs, and attributes so readers can tell what their installed version supports.
2. bindnnl.dll typo in Windows linking instructions (high)
Location: https://uxlfoundation.github.io/oneDNN/dev_guide_link.html (Windows libraries section)
Problem: The Windows libraries table lists the dynamic library as "bindnnl.dll". This is a path-joining error — the file is bin/dnnl.dll (under the bin/ subdirectory), not a single token bindnnl.dll. Compounding the problem, this same page references DNNL_LIBRARY_TYPE=STATIC while the canonical build-options page uses the ONEDNN_LIBRARY_TYPE prefix.
Consequence: A Windows developer copy-pasting the file name into a deployment script, installer manifest, or runtime DLL-locator gets a path that does not exist. A developer would notice quickly when the build fails, but an AI agent extracting the dynamic-library filename for packaging instructions emits a broken artifact list with no indication anything is wrong. The mixed DNNL_*/ONEDNN_* references on the same page also mean a reader following this page lands on a CMake variable name that the build-options page documents under a different prefix.
The fix: Replace "bindnnl.dll" with bin/dnnl.dll (matching the Linux/macOS rows that already use directory-prefixed paths like lib/libdnnl.so). Replace DNNL_LIBRARY_TYPE=STATIC with ONEDNN_LIBRARY_TYPE=STATIC to match the canonical build-options page.
3. Two parallel build-option prefixes (ONEDNN_* and DNNL_*) with contradictory canonical examples; deprecated BLAS-like API not flagged in main docs (significant)
Location: https://uxlfoundation.github.io/oneDNN/dev_guide_build_options.html, https://uxlfoundation.github.io/oneDNN/dev_guide_verbose.html, https://uxlfoundation.github.io/oneDNN/dev_guide_transition_to_dnnl.html, https://github.com/uxlfoundation/oneDNN/releases
Problem: The build-options page documents the entire option table under the ONEDNN_* prefix and adds a footnote: "All options support DNNL_* prefix equivalents, which take precedence if both versions are specified." Yet the migration page (Transition to DNNL) tells users coming from MKL-DNN to use DNNL_CPU_RUNTIME, DNNL_GPU_RUNTIME, DNNL_BUILD_TESTS — which by the footnote's own rule would override any ONEDNN_* setting silently. The verbose-mode page goes the opposite direction and uses ONEDNN_VERBOSE exclusively as both the CMake option and runtime env var, with no mention of the legacy DNNL_VERBOSE env name despite the precedence rule. Separately, the GitHub release notes state the BLAS-like API (dnnl::sgemm, dnnl::gemm_u8s8s32, dnnl::gemm_s8s8s32) "is deprecated and will be removed in future releases" with users advised to switch to matmul — but this deprecation is not surfaced on the relevant API pages in the docs site.
Consequence: A developer who follows the migration guide ends up with a CMake configuration where DNNL_* silently wins over any ONEDNN_* they set later (e.g., from a CI template). The opposite happens at runtime for verbose: someone who exported DNNL_VERBOSE=profile from an old script will find it ignored or behaving inconsistently because the page only documents ONEDNN_VERBOSE. Developers writing new code against dnnl::sgemm/dnnl::gemm_* on the strength of the docs have no in-page indication those entry points are scheduled for removal, and agents emitting BLAS-like calls inherit the same blind spot.
The fix: Pick one prefix as canonical (clearly ONEDNN_* based on the build-options table) and mark DNNL_* as a deprecated compatibility alias with a deprecation timeline. Update the migration page to recommend ONEDNN_* directly, with a note that DNNL_* is accepted for backward compatibility. Add ONEDNN_VERBOSE/DNNL_VERBOSE parity language to the verbose page so the precedence rule is consistent across the docs. Add a deprecation banner to the BLAS-like API reference pages pointing users to the matmul primitive.
4. Critical reference data offloaded from docs to GitHub README; compiler validation matrix asymmetric (significant)
Location: https://uxlfoundation.github.io/oneDNN/dev_guide_system_requirements.html, https://uxlfoundation.github.io/oneDNN/dev_guide_build.html, https://github.com/uxlfoundation/oneDNN (README)
Problem: The System Requirements page in the rendered docs contains only the sentence "oneDNN supports a broad list of hardware platforms, operating systems, and compilers" and a link to the GitHub README. Every concrete fact a developer needs — supported architectures, validated GCC/Clang versions (8.5–11.3, 11.0–14.0.6), CMake 3.13+ minimum, Doxygen/Sphinx versions, ROCm/cuDNN version floors, OS validation matrix — exists only in the GitHub README. The Build From Source page repeats the offload, telling readers to "ensure that all software dependencies are in place and have at least the minimal supported version" without listing those versions inline. The README's validation matrix is itself platform-asymmetric: x86-64 is validated on RHEL 8 / Windows Server 2019 / macOS 14 only; AArch64 is validated on Ubuntu 22.04 / macOS 14 only — there is no Windows AArch64 validation row and no Ubuntu x86-64 row, and the docs do not explain whether those gaps mean unsupported, untested, or simply unreported.
Consequence: A developer trying to determine "will this build on my Ubuntu 22.04 + GCC 11 + CMake 3.20 x86-64 box?" cannot answer the question from the documentation site at all — they must context-switch to the GitHub README, then make a guess about whether their OS+arch combination falls inside the validated set. For AI agents this is worse: an agent indexing the docs site sees a stub page that reads as "supported broadly" with no actionable constraints, then generates build advice that may not match validated configurations.
The fix: Render the system-requirements and dependency-version tables directly into the docs site (single source of truth in the repo, rendered into both README and Sphinx). At minimum, inline the validated compiler matrix, CMake floor, and architecture support tiers so the docs page is self-contained. Explicitly annotate gaps in the OS×arch validation grid as "not validated" vs. "unsupported."
5. Broken navigation link to Graph extension guide (significant)
Location: https://uxlfoundation.github.io/oneDNN/ (index navigation), https://uxlfoundation.github.io/oneDNN/dev_guide_examples.html
Problem: The navigation entry for dev_guide_graph.html returned HTTP 404 during research, even though the top-level index lists "graph extension" as a developer-guide section and many examples (e.g., MatMul tutorials, ONEDNN_VERBOSE=profile_exec,filter=graph) reference graph behavior. The graph extension is a major feature area of oneDNN, and its primary developer-guide entry point is unreachable from the rendered navigation.
Consequence: Developers and agents following the Graph extension navigation hit a dead page, breaking discovery of an entire major feature area. A reader cannot find the canonical guide for the graph API by the path the index advertises.
The fix: Either restore dev_guide_graph.html or update the navigation to point to the actual graph guide URL (or to the graph examples landing page); add a CI check that 404s any internal link in the rendered Sphinx output.
6. No enumerated error-code catalog; primitive limitations don't tell the developer what to catch (significant)
Location: https://uxlfoundation.github.io/oneDNN/dev_guide_attributes.html, https://uxlfoundation.github.io/oneDNN/dev_guide_matmul.html, https://uxlfoundation.github.io/oneDNN/dev_guide_int8_computations.html
Problem: The Attributes page is the only place error handling is described, and it mentions exactly one error name: "the library returns an dnnl_unimplemented status (C API) or throws an exception (C++ API)." No enumerated catalog of dnnl_status_t values or C++ exception types is surfaced anywhere reachable from the developer guide. Primitive pages (Convolution, MatMul, Int8) describe many configurations that will fail at runtime — INT8 src/s8 weights/f16 dst on CPU, GPU dim limits >6, INT8 saturation requiring u7 instead of full u8 range — without telling the developer which status code or exception they should expect to catch. The INT8 saturation caveat in particular is buried in narrative prose with no API-level surface.
Consequence: A developer cannot write robust try/catch or status-checking code from the docs alone — they must either catch the generic dnnl::error and stringify, or read the C header directly. Agents writing example code emit either no error handling or hallucinated status names because none are documented.
The fix: Add a dedicated "Error handling" page enumerating every dnnl_status_t value and the corresponding C++ exception types, cross-linking from each primitive page's Limitations section so "INT8 src/s8 weights/f16 dst is unsupported" tells the reader which status they will observe.
7. f4_e3m0 deprecation in v3.12-rc not reflected on the data-types page (significant)
Location: https://uxlfoundation.github.io/oneDNN/dev_guide_data_types.html vs. https://github.com/uxlfoundation/oneDNN/releases (v3.12-rc notes)
Problem: The v3.12-rc release notes deprecate the f4_e3m0 data type for future removal. The data-types page in the docs site enumerates the supported f4/f8 types — f8_e5m2, f8_e4m3, e8m0, f4_e2m1 — without flagging any deprecation status, and without cross-referencing the release notes. A reader on the data-types page therefore cannot tell whether f4_e3m0 ever existed, whether it is current, or whether it is on the way out.
Consequence: A developer who learned about f4_e3m0 from older material, a third-party tutorial, or a colleague has no way to discover from the docs site that the type is deprecated. Agents synthesizing code against the data-types page will not warn users away from a soon-to-be-removed type because the page itself contains no deprecation signal.
The fix: Add an explicit "Deprecated data types" subsection to the data-types page (or a deprecation column on the main table) listing f4_e3m0 with the version it was deprecated in and a pointer to the release notes. Apply the same treatment to any other types removed or deprecated across recent releases.
8. Convolution backward-bias data type listed as "Same as input" — ambiguous (minor)
Location: https://uxlfoundation.github.io/oneDNN/dev_guide_convolution.html (Backward propagation supported types)
Problem: The Convolution primitive's backward-propagation table lists supported bias data types as "Same as input." Convolution backward has multiple inputs (diff_dst, weights, and in some flows src), and the page does not specify which one bias is meant to track. Forward and backward type sets differ (e.g., forward dst includes s32/u8/s8 while backward dst is restricted to bf16/f16/f8/f32), so "same as input" cannot be inferred unambiguously.
Consequence: A developer setting up backward-bias tensors must guess which input governs the bias dtype, then validate by trial and error or by reading source. Agents emitting backward-bias allocation code have no canonical mapping to follow.
The fix: Replace "Same as input" with the explicit set of supported bias data types for backward propagation, matching the explicit enumeration used in the forward table.
What they do well
- Comprehensive primitive reference: Convolution, MatMul, and Int8 Computations pages document supported data types, post-op sequences, and platform-specific limitations in detail (e.g., the explicit u7 quantization caveat for AVX2/AVX-512 saturation).
- Honest scoping of experimental support: PPC64, s390x, RISC-V, NVIDIA, and AMD GPU support are explicitly flagged as experimental rather than implied first-class.
- Rich examples surface — INT8 inference, MXFP8, sparse COO/CSR, grouped GEMM, SYCL USM — covering both fundamentals and advanced quantization workflows.
Top 3 recommendations
- Reconcile docs version with shipped releases — relabel
v3.13.0to match what's actually released, or ship v3.13.0; add per-feature "Available since" tags and surface thef4_e3m0and BLAS-like API deprecations on their respective pages. - Pick one canonical build-option prefix (
ONEDNN_*), update the migration and verbose pages to use it, and markDNNL_*as a deprecated alias with a timeline. - Inline system requirements and dependency versions into the docs site, fix the
bindnnl.dll/bin/dnnl.dlltypo, repair the Graph guide navigation 404, and publish an enumerated error-code catalog cross-linked from primitive Limitations sections.