Skip to content

docs: clarify RISC-V RVV target selection and GCC 14+ requirement for ZVL128B/ZVL256B#5819

Open
trg-rgb wants to merge 1 commit into
OpenMathLib:developfrom
trg-rgb:docs/riscv-zvl-target-selection
Open

docs: clarify RISC-V RVV target selection and GCC 14+ requirement for ZVL128B/ZVL256B#5819
trg-rgb wants to merge 1 commit into
OpenMathLib:developfrom
trg-rgb:docs/riscv-zvl-target-selection

Conversation

@trg-rgb
Copy link
Copy Markdown

@trg-rgb trg-rgb commented May 24, 2026

Summary

Add two notes to the RISC-V section of the build instructions, before
the per-target entries, addressing a documented source of user confusion:

  1. Target selection: RISCV64_GENERIC is intentionally scalar by
    design — Makefile.riscv64 appends a scalar march override that
    takes precedence over any -march=rv64gcv flag. Users who supply
    the V extension without changing TARGET get a silently scalar build
    with no diagnostic. The correct targets for RVV 1.0 hardware are
    RISCV64_ZVL128B / RISCV64_ZVL256B, as documented in the design
    rationale at Updated RISC-V vector support for review.  #3808.
  2. Compiler floor: GCC 14+ is required for the current _rvv.c
    kernel set. GCC 13 builds complete and produce a library but routines
    using segmented load/store intrinsics (__riscv_vsseg*) fall back to
    scalar silently. Functional tests pass; only disassembly detects this.
    Verified on OpenBLAS 0.3.33: GCC 13 (scalar fallback), GCC 14
    (~12,691 RVV opcodes), GCC 15 (~14,355 RVV opcodes).
    Both points are consistent with existing upstream documentation; this PR
    surfaces them at the TARGET selection step where a user would first
    encounter the choice.

Related: #3808
Community investigations: clusterchallenge/Hardware-Abstraction-Layer-Transitional-Libraries#25 (trg-rgb), clusterchallenge/Hardware-Abstraction-Layer-Transitional-Libraries#23 (Vaibhav805)

Co-authored-by: Vaibhav805 Vaibhav805@users.noreply.github.com

@martin-frbg
Copy link
Copy Markdown
Collaborator

Thanks - actually the GENERIC or ARCH_GENERIC target maps to the same non-vectorized plain C code on all platforms - it will result in a working build of libopenblas on cpus that have no specific optimized support, but is likely to be only a little faster than the original "netlib" Reference BLAS.

Maybe the compiler requirements for RISCV_ZVL... would be better placed in the "Building from source" documentation, probably near the end where there are architecture-specific notes for other platforms already ? The documentation is still kind of patchy, but I fear README.md is getting too bloated for something that is displayed on the github page by default.
(My experience with the RISCV platform suggests one would normally want to use the latest stable compiler version to keep up with the ever-changing extensions - hopefully we're moving past this phase now)

… ZVL128B/ZVL256B

Add a RISC-V subsection to docs/install.md inside 'Building from source',
between the existing MIPS and FreeBSD sections, covering:

  - Target selection table (RISCV64_GENERIC / RISCV64_ZVL128B /
    RISCV64_ZVL256B / C910V / x280) and what each is for.
  - The general property that GENERIC / ARCH_GENERIC targets across
    all architectures map to the non-vectorized plain-C reference
    path, with the Makefile.riscv64 scalar -march override noted as
    the RISC-V-specific compounding factor.
  - GCC 14+ requirement for the ZVL targets on current OpenBLAS
    releases (GCC 13 does not implement the __riscv_vsseg* intrinsics
    used by the _rvv.c kernels and falls back to scalar silently,
    detectable only by disassembly).
  - Reference objdump-based verification command and expected
    opcode-count range for a correct RISCV64_ZVL128B build.

README.md now keeps a single one-line pointer to the new install.md
section at the spot where users encounter the RISC-V build commands,
so the signposting is preserved without bloating the page that GitHub
renders by default.

v2 of this PR, addresses review feedback from @martin-frbg on
relocation and on the broader GENERIC framing.

Co-authored-by: Vaibhav805 <Vaibhav805@users.noreply.github.com>
@trg-rgb trg-rgb force-pushed the docs/riscv-zvl-target-selection branch from 82e8f2e to 601ff0e Compare May 25, 2026 13:31
@trg-rgb
Copy link
Copy Markdown
Author

trg-rgb commented May 25, 2026

Thanks @martin-frbg — that GENERIC framing is right, and I've reworded.

v2 (just pushed):

  • Moved the target-selection details and compiler-requirements note out of README.md and into a new ### RISC-V subsection in docs/install.md, placed inside ## Building from source between the MIPS and FreeBSD sections, so it lives with the other per-platform build notes.
  • README.md now keeps a single one-line pointer to the new section at the spot where users encounter the RISC-V build commands, so the signposting is still there without bloating the page that GitHub renders by default.
  • Reworded the GENERIC framing per your correction — it's now positioned as the general "GENERIC / ARCH_GENERIC maps to plain-C on all architectures" property, with the Makefile.riscv64 -march override called out as the RISC-V-specific compounding factor.

The earlier CI failure (RISCV64_GENERIC runner, exit 140) looks unrelated to this docs-only change; happy to look more closely if it persists on this push.

trg-rgb added a commit to trg-rgb/riscv-hpc-port that referenced this pull request May 27, 2026
Reframes from application-era demonstration to completed program portfolio.
Adds inline issue links throughout, new sections for LAMMPS (#30), OpenMM
(#29), and verify-rvv-port.sh (#31). Updates repo tree to reflect scripts/,
ports/, openmm-port/, lammps-port/. Expanded Related section covering all
11 cohort issues plus OpenMathLib/OpenBLAS#5819 upstream PR. References
closing methodology issue #32.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants