Project Stage 2 : Fixing the ACLE Documentation
Published: 2024-04-11 00:26:16

## 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:
{% github https://github.com/ARM-software/acle %}

### Forked Repo:
{% github https://github.com/HeavenMunjal/acle %}

## 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](https://github.com/HeavenMunjal/acle/commit/6c01fdfc45879802a5aa50bd7d3fd47b0a839c1d) 

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:

```sh
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](https://github.com/HeavenMunjal/acle/commit/a014c2d617f68d11cbe31c9ae07a5efdb2fda3ec)

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:

```c
#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.