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.
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.
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.
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:
Mentions that FMV may be disabled at compile time by a compiler flag, but this flag is not documented
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.
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.
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")))voidoptimized_function(){// Optimized implementation}#else
// FMV is not supported by the compilervoidoptimized_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.
