Standard Fixed-length Vector Calling Convention Variant #418

kito-cheng · 2024-01-04T09:32:09Z

This proposal outlines a new variant of the calling convention specifically designed for fixed-length vectors. The primary aim of this variant is to facilitate the passing of fixed-length vectors through vector registers. This approach is derived from the standard vector calling convention, it uses the same register conventions and argument passing and return value rules.

A key aspect of this variant is the introduction of ABI_VLEN, which denotes the width of a vector register within this convention. The ABI_VLEN is constrained to be no wider than the ISA's VLEN (Vector Length), ensuring compatibility while allowing for flexibility in different implementations. This parameter can be configured via compiler command line options or through function attributes in source code.

The document recommends setting the default ABI_VLEN to 128 bits, acknowledging it as a common minimal requirement while allowing the flexibility for lower VLEN (32 or 64 bits) as permitted by the ISA. This flexibility is crucial for optimizing the utilization of longer VLENs in various cores.

The proposal specifies how fixed-length vector arguments are passed based on their size relative to ABI_VLEN. Vectors smaller than ABI_VLEN are passed in a single vector argument register, while larger vectors are passed in multiple registers, following the LMUL (Length Multiplier) pattern of 2, 4, or 8, depending on their size.

Additionally, the proposal addresses the handling of structs and unions containing fixed-length vectors. Structs with members that are all fixed-length vectors follow the vector tuple type rules if they conform to size constraints. In contrast, unions with fixed-length vectors adhere to the integer calling convention.

kito-cheng · 2024-01-04T09:32:32Z

cc. @palmer-dabbelt @JeffreyALaw @preames @topperc @rofirrim @lhtin

riscv-cc.adoc

sorear · 2024-01-09T12:38:24Z

riscv-cc.adoc

@@ -329,6 +329,81 @@ type would be passed.
 Floating-point registers fs0-fs11 shall be preserved across procedure calls,
 provided they hold values no more than ABI_FLEN bits wide.

+=== Standard Fixed-length Vector Calling Convention Variant


The variant itself seems fine, modulo nits, but how are we planning to enable it?

If it's automatically used by -march=rva23 -mabi=ilp32d that will create major compatibility issues for binary distributions that use a fixed ABI and allow mixing packages at different architecture levels (either as an explicit user action, or as an implementation detail when rebuilding the distribution to change the architecture requirement).

If a new -mabi= value is required to enable use of the variant, it will be usable on closed systems where all packages are built at once, but not on binary distributions, since there is no expectation that binary code built with different -mabi= options is interoperable at all. This will include Debian and Alpine and might include Android and Fedora if their ABIs are finalized prior to the acceptance of this PR.

If it's enabled on a per-function basis using an attribute, or automatically for functions not visible across DSO boundaries, then it's effectively part of the definition of the attribute or a compiler implementation detail and may belong in riscv-c-api-doc or gccint, not here.

My expectation is that should be enabled by per-function basis by attribute, and I think that should have a riscv-c-api-doc PR for that, will send that in the next few days.

riscv-cc.adoc

kito-cheng · 2024-01-26T10:02:46Z

ChangeLog:

Reorder rule.
Pass struct as tuple-type in register only when vector arg reg is
enough, otherwise passed in reference.
Add NOTE for describe what if ABI_VLEN is smaller than VLEN, also
come with an example.
Add NOTE for describe different functions may use different
ABI_VLEN values.

kito-cheng · 2024-01-29T08:49:02Z

ChangeLog:

Add rule for single fixed-length vector or fixed-length vector array with size 1.
Add rule for zero-length fixed-length arrays.
Add explicitly rule for fixed-length vector struct as vector tuple type: pass by ref if no enough arg register.

…n variant Fixed-length vector are passed via general purposed register or memory within current ABI design, we proposed a standard fixed-length vector calling convention variant for passing the fixed-length vector via vector register. This is the syntax part in the proposal, further detail for that calling convention variant see riscv-non-isa/riscv-elf-psabi-doc#418

kito-cheng · 2024-02-02T09:21:48Z

Proposal for function attribute syntax: riscv-non-isa/riscv-c-api-doc#68

riscv-cc.adoc

This patch adds a function attribute `riscv_vls_cc` for RISCV VLS calling convention which takes 0 or 1 argument, the argument is the `ABI_VLEN` which is the `VLEN` for passing the fixed-vector arguments, it wraps the argument as a scalable vector(VLA) using the `ABI_VLEN` and uses the corresponding mechanism to handle it. The range of `ABI_VLEN` is [32, 65536], if not specified, the default value is 128. Here is an example of VLS argument passing: Non-VLS call: ``` void original_call(__attribute__((vector_size(16))) int arg) {} => define void @original_call(i128 noundef %arg) { entry: ... ret void } ``` VLS call: ``` void __attribute__((riscv_vls_cc(256))) vls_call(__attribute__((vector_size(16))) int arg) {} => define riscv_vls_cc void @vls_call(<vscale x 1 x i32> %arg) { entry: ... ret void } } ``` The first Non-VLS call passes generic vector argument of 16 bytes by flattened integer. On the contrary, the VLS call uses `ABI_VLEN=256` which wraps the vector to <vscale x 1 x i32> where the number of scalable vector elements is calaulated by: `ORIG_ELTS * RVV_BITS_PER_BLOCK / ABI_VLEN`. Note: ORIG_ELTS = Vector Size / Type Size = 128 / 32 = 4. PsABI PR: riscv-non-isa/riscv-elf-psabi-doc#418 C-API PR: riscv-non-isa/riscv-c-api-doc#68

kito-cheng · 2025-03-25T14:46:38Z

Changes:

Rebase
Fix typos
Drop non-mandatory note about default ABI_VLEN setting

kito-cheng · 2025-05-12T08:43:11Z

LLVM has supported VLS CC llvm/llvm-project@c804e86

kito-cheng · 2025-05-19T09:25:30Z

Ping, LLVM part has landed a while, does any one from LLVM community is interested to review this again?

riscv-cc.adoc

riscv-elf.adoc

This proposal outlines a new variant of the calling convention specifically designed for fixed-length vectors. The primary aim of this variant is to facilitate the passing of fixed-length vectors through vector registers. This approach is derived from the standard vector calling convention, it uses the same register conventions and argument passing and return value rules. A key aspect of this variant is the introduction of ABI_VLEN, which denotes the width of a vector register within this convention. The ABI_VLEN is constrained to be no wider than the ISA's VLEN (Vector Length), ensuring compatibility while allowing for flexibility in different implementations. This parameter can be configured via compiler command line options or through function attributes in source code. The document recommends setting the default ABI_VLEN to 128 bits, acknowledging it as a common minimal requirement while allowing the flexibility for lower VLEN (32 or 64 bits) as permitted by the ISA. This flexibility is crucial for optimizing the utilization of longer VLENs in various cores. The proposal specifies how fixed-length vector arguments are passed based on their size relative to ABI_VLEN. Vectors smaller than ABI_VLEN are passed in a single vector argument register, while larger vectors are passed in multiple registers, following the LMUL (Length Multiplier) pattern of 2, 4, or 8, depending on their size. Additionally, the proposal addresses the handling of structs and unions containing fixed-length vectors. Structs with members that are all fixed-length vectors follow the vector tuple type rules if they conform to size constraints. In contrast, unions with fixed-length vectors adhere to the integer calling convention.

- Reorder rule. - Pass struct as tuple-type in register only when vector arg reg is enough, otherwise passed in reference. - Add NOTE for describe what if ABI_VLEN is smaller than VLEN, also come with an example. - Add NOTE for describe different functions may use different ABI_VLEN values.

- Add rule for single fixed-length vector or fixed-length vector array with size 1. - Add rule for zero-length fixed-length arrays. - Add explicitly rule for fixed-length vector struct as vector tuple type: pass by ref if no enough arg register.

Co-authored-by: Brandon Wu <[email protected]> Signed-off-by: Kito Cheng <[email protected]>

Signed-off-by: Kito Cheng <[email protected]>

Co-authored-by: Craig Topper <[email protected]> Signed-off-by: Kito Cheng <[email protected]>

kito-cheng requested review from asb, cmuellner, jrtc27 and aswaterman January 4, 2024 09:32

kito-cheng requested a review from lhtin January 4, 2024 09:57

topperc reviewed Jan 8, 2024

View reviewed changes

riscv-cc.adoc Show resolved Hide resolved

lhtin reviewed Jan 9, 2024

View reviewed changes

riscv-cc.adoc Outdated Show resolved Hide resolved

riscv-cc.adoc Show resolved Hide resolved

sorear reviewed Jan 9, 2024

View reviewed changes

kito-cheng force-pushed the fixed-length-vector-cc branch from b9f0bc2 to 2386a73 Compare January 26, 2024 10:02

kito-cheng mentioned this pull request Feb 2, 2024

Function attribute for standard fixed-length vector calling convention variant riscv-non-isa/riscv-c-api-doc#68

Open

4vtomat reviewed May 5, 2024

View reviewed changes