SVE2 API Proposal: Extra Parameter For ConvertToSingleOdd

Nov 28, 2025 by Alex Johnson 58 views

This article discusses a proposed update to the SVE2 API, specifically focusing on the ConvertToSingleOddRoundToOdd API. The proposal suggests adding an extra parameter to this API to align with the underlying instruction requirements. This modification aims to improve the accuracy and efficiency of vector operations within the .NET runtime.

Background and Motivation

The need for this change stems from a detailed examination of the Scalable Vector Extension 2 (SVE2) instructions and their implementation within the .NET runtime. A previous discussion on GitHub (https://github.com/dotnet/runtime/issues/94018#issuecomment-3126709279) highlighted the discrepancy between the intended functionality of the FCVTXNT instruction and the current API design. Further details and context can be found in the approved proposal (https://github.com/dotnet/runtime/issues/94018).

Understanding the Instructions: FCVTX and FCVTXNT

To fully grasp the rationale behind this API change, it's crucial to understand the behavior of the underlying instructions:

FCVTX: This instruction converts active double-precision floating-point elements from a source vector to single-precision, rounding the results to the nearest odd integer. The converted values are then placed in the even-numbered 32-bit elements of the destination vector. Importantly, the odd-numbered elements are set to zero by this instruction. Inactive elements in the destination vector remain unmodified.
FCVTXNT: Similar to FCVTX, this instruction converts active double-precision floating-point elements to single-precision, rounding to the nearest odd integer. However, the results are placed in the odd-numbered 32-bit elements of the destination vector. The crucial difference is that the even-numbered elements are left unchanged. This behavior necessitates an additional input to preserve or manipulate the even-numbered elements as needed. Inactive elements in the destination vector remain unmodified.

When initially implemented, both ConvertToSingleEvenRoundToOdd and ConvertToSingleOddRoundToOdd APIs were designed with an even argument. However, a closer look reveals that only FCVTXNT (and thus ConvertToSingleOddRoundToOdd) truly requires this extra input to manage the even-numbered elements. The ConvertToSingleEvenRoundToOdd API correctly reflects the behavior of FCVTX, which inherently sets the odd-numbered elements to zero, so no extra argument is needed.

The Problem with the Initial Implementation

The initial design, while seemingly symmetrical, introduces unnecessary complexity and potential for errors when using ConvertToSingleOddRoundToOdd. Without the ability to directly control the even-numbered elements, developers might resort to workarounds that could impact performance or introduce subtle bugs. The core issue is that FCVTXNT does not overwrite the even-numbered elements; it preserves them. Therefore, to use ConvertToSingleOddRoundToOdd effectively, the caller needs a way to provide the existing values for the even-numbered elements. This is where the even argument becomes essential.

API Proposal: A Refined Approach

To address this discrepancy and provide a more accurate and efficient API, the following changes are proposed:

ConvertToSingleEvenRoundToOdd: This API should remain as currently designed. It accurately reflects the behavior of the FCVTX instruction and doesn't require an extra input for the odd-numbered elements as they are implicitly set to zero.
```
  public static unsafe Vector<float> ConvertToSingleEvenRoundToOdd(Vector<double> value); // FCVTX // predicated, MOVPRFX
```
ConvertToSingleOddRoundToOdd: This API should be updated to accept an even argument. This argument will allow developers to explicitly control the values of the even-numbered elements in the destination vector, aligning with the behavior of the FCVTXNT instruction.
```
  public static unsafe Vector<float> ConvertToSingleOddRoundToOdd(Vector<float> even, Vector<double> value); // FCVTXNT // predicated
```

Benefits of the Proposed Change

This seemingly small change has significant implications for the usability and performance of the SVE2 API:

Improved Accuracy: By providing an even argument to ConvertToSingleOddRoundToOdd, developers gain precise control over the output, ensuring that the even-numbered elements are handled correctly according to their specific needs. This eliminates the need for manual manipulation and reduces the risk of errors.
Enhanced Efficiency: The ability to directly specify the even-numbered elements can lead to more efficient code. Without this option, developers might need to perform extra operations to achieve the desired result, potentially impacting performance, especially in performance-critical scenarios.
Clearer API Contract: The updated API more accurately reflects the underlying instruction's behavior. This makes the API easier to understand and use, reducing the learning curve and improving developer productivity. A well-defined API contract is essential for building robust and maintainable software.
Consistency with Hardware: This proposal ensures that the API directly mirrors the capabilities of the hardware. This consistency is crucial for maximizing the benefits of SVE2 instructions and achieving optimal performance.

Detailed Explanation of the Modified API

The proposed signature for ConvertToSingleOddRoundToOdd is:

public static unsafe Vector<float> ConvertToSingleOddRoundToOdd(Vector<float> even, Vector<double> value);

Let's break down each part of this signature:

public static unsafe Vector<float>: This indicates that the method is a static method (can be called directly on the Vector type), it operates in an unsafe context (due to the use of pointers and low-level memory access), and it returns a Vector<float>, which is a vector of single-precision floating-point numbers.
ConvertToSingleOddRoundToOdd: This is the name of the method, clearly indicating its purpose: to convert double-precision floating-point numbers to single-precision, rounding to the nearest odd integer, and placing the result in the odd-numbered elements of the vector.
Vector<float> even: This is the newly proposed parameter. It's a Vector<float> that represents the values that should be present in the even-numbered elements of the result vector. The method will take these values and insert them into the even-numbered positions.
Vector<double> value: This is the input vector containing the double-precision floating-point numbers to be converted. The method will convert these values to single-precision, round them to the nearest odd integer, and place the results in the odd-numbered elements of the output vector.

In essence, the ConvertToSingleOddRoundToOdd method will now take two input vectors: even, which provides the values for the even-numbered elements of the output, and value, which provides the double-precision values to be converted and placed in the odd-numbered elements. This provides the necessary control and flexibility to fully utilize the capabilities of the FCVTXNT instruction.

Conclusion

This API proposal to add an even parameter to the ConvertToSingleOddRoundToOdd API in SVE2 is a crucial step towards a more accurate, efficient, and developer-friendly interface. By aligning the API with the underlying hardware instruction (FCVTXNT), this change empowers developers to leverage the full potential of SVE2 vector operations within the .NET runtime. The addition of the even parameter not only addresses a functional gap but also enhances the overall usability and clarity of the API, leading to more robust and performant code.

For more information on .NET runtime and API proposals, visit the official .NET Runtime GitHub repository. 📝