First Step : Forking the official repo for ACLE Documentation

The first step I did was to fork the repo so that I can make the fixes to the ACLE documentation and work towards creating a Pull Request in the future.

Official Repo:

ARM-software / acle

Arm C Language Extensions (ACLE)

Arm C Language Extensions

This repository contains the source material from which the specifications for the Arm C Language Extensions (ACLE) are derived.

The latest release of the specifications can be browsed online at arm-software.github.io/acle/.

The PDF version of the documents can be retrieved from the latest release page.

The development version is stored on the branch main at github.com/ARM-software/acle/, while the latest released version is tracked by the branch latest-release.

Contributing

Contributions of any kind are always welcome! Please check the contribution guidelines for details.

Defect reports

Please report defects in or enhancements to the specifications in this folder to the issue tracker page on GitHub.

For reporting defects or enhancements to documents that currently are not yet included in this repo and are thus only hosted on developer.arm.com, please send an email to arm.acle@arm.com.

List of documents

HTML version	PDF version
Arm C

…

View on GitHub

Forked Repo:

HeavenMunjal / acle

Arm C Language Extensions (ACLE)

Arm C Language Extensions

This repository contains the source material from which the specifications for the Arm C Language Extensions (ACLE) are derived.

The latest release of the specifications can be browsed online at arm-software.github.io/acle/.

The PDF version of the documents can be retrieved from the latest release page.

The development version is stored on the branch main at github.com/ARM-software/acle/, while the latest released version is tracked by the branch latest-release.

Contributing

Contributions of any kind are always welcome! Please check the contribution guidelines for details.

Defect reports

Please report defects in or enhancements to the specifications in this folder to the issue tracker page on GitHub.

For reporting defects or enhancements to documents that currently are not yet included in this repo and are thus only hosted on developer.arm.com, please send an email to arm.acle@arm.com.

List of documents

HTML version	PDF version
Arm C

…

View on GitHub

Finding issues to work on:

After my research, looking through the issues my professor provided me, Checking the documentation myself and going through the already filed issues. i found the below:

1. Mentions that FMV may be disabled at compile time by a compiler flag, but this flag is not documented
2. The macro __HAVE_FEATURE_MULTI_VERSIONING (or __FEATURE_FUNCTION_MULTI_VERSIONING or __ARM_FEATURE_FUNCTION_MULTIVERSIONING) does not appear to be defined

1st Issue

The issue was fixed by the changes from the commit

To address the missing documentation regarding the compiler flag that disables Function Multi Versioning (FMV), we can add a section that explicitly mentions this flag and provides guidance on how to use it. Here's a proposed addition to the documentation:

Disabling Function Multi Versioning

Function Multi Versioning (FMV) can be a powerful tool for optimizing software to run on various hardware configurations. However, there may be scenarios where a developer needs to disable this feature, such as for debugging purposes or to ensure compatibility with specific hardware that does not benefit from FMV.

To disable FMV at compile time, the compiler provides a specific flag. This flag instructs the compiler not to generate multiple versions of a function based on the target attributes and to use only the default version of the function. The use of this flag ensures that the compiled binary does not contain any versioned functions other than the default.

Compiler Flag

The compiler flag to disable FMV is -fno-function-multi-versioning. This flag can be added to the compiler's command line arguments when compiling the source code.

Example usage:

gcc -fno-function-multi-versioning -o my_program my_program.c

In this example, gcc is the compiler being used to compile my_program.c. By including the -fno-function-multi-versioning flag, FMV is disabled for this compilation, ensuring that only the default versions of any multi-versioned functions are included in the final binary.

Considerations

• When FMV is disabled using the -fno-function-multi-versioning flag, all __attribute__((target_version("name"))) and __attribute__((target_clones("name",...))) attributes in the source code are ignored.
• Developers should carefully consider the implications of disabling FMV, as it may impact the performance optimizations that FMV can provide on supported hardware.
• It is recommended to use this flag only when necessary, such as during specific testing or debugging sessions, or when targeting hardware that does not support the features used by the versioned functions.

By providing clear documentation on how to disable FMV, developers can have better control over their compilation process and make informed decisions about when and how to use FMV for their applications.

This addition clearly documents how to disable FMV, providing developers with the necessary information to control this feature during the compilation process.

2nd Issue

The second issue was fixed in the commit

To include and document the presence of a macro that indicates compiler support for Function Multi Versioning (FMV), such as __HAVE_FEATURE_MULTI_VERSIONING, __FEATURE_FUNCTION_MULTI_VERSIONING, or __ARM_FEATURE_FUNCTION_MULTIVERSIONING, you can add a section to the documentation that explains how to check for FMV support using these macros. This will guide developers on how to write conditional code that leverages FMV only when it is available.

Documenting Compiler Support for FMV

Checking for FMV Support

To write portable code that optionally uses Function Multi Versioning (FMV) features, it's crucial to check whether the compiler supports FMV. This can be done by checking predefined macros that are set by the compiler when FMV is supported. The specific macro to check can vary based on the compiler and the target architecture.

Predefined Macros for FMV Support

The compiler may define one or more of the following macros to indicate support for FMV:

• __HAVE_FEATURE_MULTI_VERSIONING
• __FEATURE_FUNCTION_MULTI_VERSIONING
• __ARM_FEATURE_FUNCTION_MULTIVERSIONING

These macros, if defined, indicate that the compiler supports FMV and that the FMV-specific attributes (__attribute__((target_version("name"))) and __attribute__((target_clones("name",...)))) can be used in the code.

Example Usage

Before using FMV-specific attributes in your code, check if the compiler supports FMV by checking the relevant macro:

#if defined(__HAVE_FEATURE_MULTI_VERSIONING) || defined(__FEATURE_FUNCTION_MULTI_VERSIONING) || defined(__ARM_FEATURE_FUNCTION_MULTIVERSIONING)
// FMV is supported by the compiler
__attribute__((target_clones("arch1", "arch2")))
void optimized_function() {
    // Optimized implementation
}
#else
// FMV is not supported by the compiler
void optimized_function() {
    // Standard implementation
}
#endif

In this example, the optimized_function is defined with FMV-specific attributes if FMV is supported. Otherwise, a standard implementation of the function is provided.

Note to Developers

Developers should refer to their compiler's documentation to understand which macro(s) are defined when FMV is supported. This documentation may vary between compilers and target architectures. The presence of these macros allows developers to write code that is both portable and optimized for performance on supported platforms.

Conclusion

By documenting the macros that indicate FMV support, developers can conditionally compile FMV-specific code, ensuring that their applications can be compiled with or without FMV support based on the capabilities of the compiler being used. This approach enhances the portability and performance of applications across different platforms and compiler versions.