diff --git a/arm-software/docs/README.md b/arm-software/docs/README.md index 96511112e692..e7ab028067ff 100644 --- a/arm-software/docs/README.md +++ b/arm-software/docs/README.md @@ -6,4 +6,5 @@ Toolchain for Embedded and Arm Toolchain for Linux. Documentation that is specific to a toolchain should be placed in the toolchain specific subdirectory. For example documentation for Arm Toolchain for Embedded should go into the `arm-software/embedded/docs` -directory. \ No newline at end of file +directory while documentation for Arm Toolchain for Linux should go +into the `arm-software/linux/docs` directory. diff --git a/arm-software/linux/build.sh b/arm-software/linux/build.sh index ef97cfe34d41..fe138aef50dd 100755 --- a/arm-software/linux/build.sh +++ b/arm-software/linux/build.sh @@ -16,6 +16,7 @@ MKMODULEDIRS_PATH=${MKMODULEDIRS_PATH:-"${BASE_DIR}/mkmoduledirs.sh.var"} SOURCES_DIR=${SOURCES_DIR:-"$(git -C "${BASE_DIR}" rev-parse --show-toplevel)"} LIBRARIES_DIR=${LIBRARIES_DIR:-"${BASE_DIR}/lib"} PATCHES_DIR=${PATCHES_DIR:-"${BASE_DIR}/patches"} +DOCS_DIR=${DOCS_DIR:-"${BASE_DIR}/docs"} BUILD_DIR=${BUILD_DIR:-"${BASE_DIR}/build"} ATFL_DIR=${ATFL_DIR:-"${BUILD_DIR}/atfl"} LOGS_DIR=${LOGS_DIR:-"${BASE_DIR}/logs"} @@ -186,6 +187,8 @@ Environment Variables: (default: $LIBRARIES_DIR) PATCHES_DIR The optional directory where all patches will be stored (default: $PATCHES_DIR) + DOCS_DIR The directory where ATfL documents will be stored + (default: $DOCS_DIR) BUILD_DIR The directory where all build output will be stored (default: $BUILD_DIR) LOGS_DIR The directory where all build logs will be stored @@ -384,6 +387,8 @@ package() { cp "${SBOM_FILE_PATH}" "${ATFL_DIR}/ATfL-SBOM.spdx.json" mkdir -p "${ATFL_DIR}/arm" cp "${MKMODULEDIRS_PATH}" "${ATFL_DIR}/arm/mkmoduledirs.sh" + mkdir -p "${ATFL_DIR}/arm/docs" + cp "${DOCS_DIR}"/*.md "${ATFL_DIR}/arm/docs" sed -i "s/%ATFL_VERSION%/${ATFL_VERSION}/g" "${ATFL_DIR}/arm/mkmoduledirs.sh" sed -i "s/%ATFL_BUILD%/${BUILD_NUMBER:-"unknown"}/g" "${ATFL_DIR}/arm/mkmoduledirs.sh" sed -i "s/%ATFL_INSTALL_PREFIX%/\$\(dirname \$\(dirname \`realpath \$BASH_SOURCE\`\)\)/g" "${ATFL_DIR}/arm/mkmoduledirs.sh" @@ -500,6 +505,12 @@ then exit 1 fi +if ! [[ -e "${DOCS_DIR}" ]] +then + echo "The documentation directory is configured incorrectly or does not exist." + exit 1 +fi + if ! [[ -e "${SOURCES_DIR}" ]] then echo "The sources directory is configured incorrectly or does not exist." diff --git a/arm-software/linux/build.sh-HOWTO.md b/arm-software/linux/build.sh-HOWTO.md index 3eecf2436332..3fd8778dab15 100644 --- a/arm-software/linux/build.sh-HOWTO.md +++ b/arm-software/linux/build.sh-HOWTO.md @@ -147,6 +147,8 @@ The `build.sh` script reads the following environment variables: (default: `arm-software/linux/lib`) - `PATCHES_DIR` - The **optional** directory where all patches will be stored (default: `arm-software/linux/patches`) +- `DOCS_DIR` - The directory where ATfL documents will be stored + (default: `arm-software/linux/docs`) - `BUILD_DIR` - The directory where all build will be happening (default: `arm-software/linux/build`) - `LOGS_DIR` - The directory where all build logs will be stored diff --git a/arm-software/linux/docs/GettingStarted.md b/arm-software/linux/docs/GettingStarted.md new file mode 100644 index 000000000000..9d86ff224e01 --- /dev/null +++ b/arm-software/linux/docs/GettingStarted.md @@ -0,0 +1,358 @@ +## Getting Started + +This document describes how to get started with the already installed Arm +Toolchain for Linux. Here you will find out how to use it to compile a source +code into an executable binary. + +### Looking at the toolchain + +The default installation site of Arm Toolchain For Linux is the +`/opt/arm/arm-toolchain-for-linux` directory. It contains a complete set of LLVM +tooling, header files, compiler libraries and runtime libraries (including the +OpenMP runtime). The main tools are as follows: + +* `armclang` - the C compiler +* `armclang++` - the C++ compiler +* `armflang` - the Fortran compiler + +Note that the LLVM equivalents of these commands (`clang`, `clang++`, `flang`) +are also available and functionally identical. + +### Configure and load environment modules + +After installation, you should be able to invoke any of those commands with +their absolute paths, e.g.: + +``` +$ /opt/arm/arm-toolchain-for-linux/bin/armclang -print-resource-dir +/opt/arm/arm-toolchain-for-linux/lib/clang/ +``` + +Although fully operable, this is not the most convenient way of using the +toolchain. Therefore, we recommend using the environment modules. These can be +installed on most of the existing Linux distributions, as presented below. + +#### Ubuntu systems + +``` +$ sudo apt install environment-modules +``` + +#### Red Hat Enterprise Linux and Amazon Linux systems + +``` +$ sudo dnf install environment-modules +``` + +#### SUSE Linux Enterprise Server systems + +``` +$ sudo zypper install environment-modules +``` + +After installing environment modules, you need to execute a profile script which +matches with your default shell: + +#### BASH + +``` +$ source /etc/profile.d/modules.sh +``` + +#### csh or tcsh + +``` +$ source /etc/profile.d/modules.csh +``` + +Use the `module use` command to update your `MODULEPATH` environment variable to +include the path to the Arm Toolchain For Linux module files directory: + +``` +$ module use /opt/arm/modulefiles +``` + +Alternatively, you can set or amend your `MODULEPATH` environment variable +manually. Use the `module avail` command to examine the list of available modules. + +To load the module for Arm Toolchain for Linux, type: + +``` +$ module load atfl +``` + +This should load the default version of Arm Toolchain for Linux. Alternatively, +if multiple versions are available, you can load the desired version by +specifying `atfl/`. + +From now on, the toolchain commands should be accessible from the command line: + +``` +$ which armclang +/opt/arm/arm-toolchain-for-linux/bin/armclang + +$ which armclang++ +/opt/arm/arm-toolchain-for-linux/bin/armclang++ + +$ which armflang +/opt/arm/arm-toolchain-for-linux/bin/armflang +``` + +### Using the compiler + +#### Example 1: Compile and run an example C program + +Consider a simple program stored in a `.c` file, for example: `hello.c`: + +``` +#include + +int main() +{ + printf("Hello, World!"); + return 0; +} +``` + +To generate an executable binary, compile your example C program with the +`armclang` compiler. Specify the input file, `hello.c`, and the binary name +(using `-o`), `hello`: + +``` +$ armclang -o hello hello.c +``` + +Run the generated binary `hello`: + +``` +$ ./hello +Hello, World! +``` + +#### Example 2: Compile and run an example Fortran program + +Consider a simple program stored in a `.f90` file, for example: `hello.f90`: + +``` +program hello + print *, 'hello world' +end program +``` + +To generate an executable binary, compile your example Fortran program with the +`armflang` compiler. Specify the input file, `hello.f90`, and the binary name +(using `-o`), `hello`: + +``` +$ armflang -o hello hello.f90 +``` + +Run the generated binary `hello`: + +``` +$ ./hello + hello world +``` + +### Compile and link C/C++ programs + +To generate an executable binary, compile your source file (for example, +`source.c`) with the `armclang` command: + +``` +$ armclang source.c +``` + +A binary with the filename `a.out` is the output. + +Optionally, use the `-o` option to set the binary filename (for example, `binary`): + +``` +$ armclang -o binary source.c +``` + +You can specify multiple source files on a single line. Each source file is +compiled individually and then linked into a single executable binary. For +example, to compile the source files `source1.c` and `source2.c`, use: + +``` +$ armclang -o binary source1.c source2.c +``` + +To compile each of your source files individually into an object (`.o`) file, +specify the compile-only option, `-c`, and then pass the resulting object files +into another invocation of `armclang` to link them into an executable binary: + +``` +$ armclang -c source1.c + +$ armclang -c source2.c + +$ armclang -o binary source1.o source2.o +``` + +#### Note + +For the C/C++ compiler's command line arguments reference visit this page: +[Clang command line argument reference](https://releases.llvm.org/20.1.0/tools/clang/docs/ClangCommandLineReference.html). + +### Compile and link Fortran programs + +To generate an executable binary, compile your source file (for example, +`source.f90`) with the `armflang` command: + +``` +$ armflang source.f90 +``` + +A binary with the filename `a.out` is the output. + +You can specify multiple source files on a single line. Each source file is +compiled individually and then linked into a single executable binary. For +example, to compile the source files `source1.f90` and `source2.f90`, use: + +``` +$ armflang -o binary source1.f90 source2.f90 +``` + +To compile each of your source files individually into an object (`.o`) file, +specify the compile-only option, `-c`, and then pass the resulting object files +into another invocation of `armflang` to link them into an executable binary: + +``` +$ armflang -c source1.f90 + +$ armflang -c source2.f90 + +$ armflang -o binary source1.o source2.o +``` + +When mixing both C/C++ and Fortran codes in a single application, it is +important to to make sure that the Fortran runtime library is always linked in. +This can be ensured by using the `armflang` command for linking: + +``` +$ armflang -c source1.f90 + +$ armclang -c source2.c + +$ armflang -o binary source1.o source2.o +``` + +#### Note + +For the Fortran compiler's command line arguments reference visit this page: +[Flang command line argument reference](https://flang.llvm.org/docs/FlangCommandLineReference.html). + +### Increase the optimization level + +To control the optimization level, specify the `-O` option on your +compile line, and replace `` with one of `0`, `1`, `2` or `3`. The `-O0` +option is the lowest, and the default, optimization level. `-O3` is the highest +optimization level. Arm compilers performs auto-vectorization at level `-O2` and +above. + +For example, to compile the `source.c` file into a binary called `binary`, and +use the `-O3` optimization level, use: + +``` +$ armclang -O3 -o binary source.c +``` + +To compile the `source.f90` file into a binary called binary, and use the `-O3` +optimization level, use: + +``` +$ armflang -O3 -o binary source.f90 +``` + +#### Note + +Similarly to other compilers, the Arm Toolchain for Linux C and C++ compilers +can also be supplied with the `-Ofast` option. This will however result in +displaying the following deprecation warning: + +``` +warning: argument '-Ofast' is deprecated; use '-O3 -ffast-math' for the same behavior, or '-O3' to enable only conforming optimizations [-Wdeprecated-ofast] +``` + +As the warning message states, the effect of applying the `-Ofast` option when +compiling the C/C++ programs can be achieved by using the `-O3 -ffast-math` +options instead. + +In case of Fortran, the use of the `-Ofast` option triggers the following +deprecation warning: + +``` +warning: argument '-Ofast' is deprecated; use '-O3 -ffast-math -fstack-arrays' for the same behavior, or '-O3 -fstack-arrays' to enable only conforming optimizations [-Wdeprecated-ofast] +``` + +As the warning message states, the effect of applying the `-Ofast` option when +compiling Fortram programs can be achieved by using the +`-O3 -ffast-math -fstack-arrays` options instead. + +### Compile and optimize using CPU auto-detection + +If you tell the compiler what target CPU your application will run on, it can +make target-specific optimization decisions. Target-specific optimization +decisions help ensure your application runs as efficiently as possible. To tell +the compiler to make target-specific compilation decisions, use the +`-mcpu=` option and replace `` with your target processor (from +a supported list of targets). + +In addition, the `-mcpu` option also supports the `native` argument. +`-mcpu=native` enables the compiler to auto-detect the architecture and +processor type of the CPU that you are running the compiler on. + +For example, to auto-detect the target CPU and optimize your C application for +this target, use: + +``` +$ armclang -O3 -mcpu=native -o binary source.c +``` + +To auto-detect the target CPU and optimize your Fortran application for this +target, use: + +``` +$ armflang -O3 -mcpu=native -o binary source.f90 +``` + +The `-mcpu` option supports a range of Armv8-A-based Systems-on-Chips (SoCs). +When `-mcpu` is not specified, by default, `-mcpu=generic` is set, which +generates portable output suitable for any Armv8-A-based target. + +#### Note + +* The optimizations that are performed from setting the `-mcpu` option (also + known as hardware, or CPU, tuning) are independent of the optimizations that + are performed from setting the `-O` option. + +* If you run the compiler on one target, but will run the application you are + compiling on a different target, do not use `-mcpu=native`. Instead, use + `-mcpu=` where `` is the target processor that you will run + the application on. + +### Fortran Recommendations + +#### Who should use Arm Toolchain For Linux + +* Code with modern Fortran features (except coarrays/teams/collectives) will + work with ATfL. + +* Applications that are standard compliant will work with ATfL. + +* Applications like CP2K can be compiled with ATfL. + +* Applications requiring quadmath support can be compiled with ATfL. + +#### Who should not use Arm Toolchain For Linux + +* Performance is not guaranteed. For users seeking highest performance ATfL is + not recommended. + +* OpenMP support is experimental. + +* Code containing non-standard features/intrinsics might not work as expected. + +* CMake versions older than 3.20 are not supported. diff --git a/arm-software/linux/docs/Installation.md b/arm-software/linux/docs/Installation.md new file mode 100644 index 000000000000..1b8aadb779be --- /dev/null +++ b/arm-software/linux/docs/Installation.md @@ -0,0 +1,85 @@ +## Installation + +This document describes how to download and install the Arm Toolchain for Linux. + +### Pre-installation step + +The first step is to configure your Linux package manager to be able to fetch +packages from Arm. This step only needs to be performed once. + +From the options below, select the packages repository matching with your +installed Linux distribution. + +#### Ubuntu 22.04 + +``` +$ curl "http://obs.oss.arm.com:82/arm-toolchains:/ubuntu-22/linux/Release.key" | sudo gpg --dearmor -o /usr/share/keyrings/obs-oss-arm-com.gpg + +$ echo "deb [signed-by=/usr/share/keyrings/obs-oss-arm-com.gpg] http://obs.oss.arm.com:82/arm-toolchains:/ubuntu-22/linux/ ./" | sudo tee /etc/apt/sources.list.d/obs-oss-arm-com.list + +$ sudo apt update +``` + +#### Ubuntu 24.04 + +``` +$ curl "http://obs.oss.arm.com:82/arm-toolchains:/ubuntu-24/linux/Release.key" | sudo gpg --dearmor -o /usr/share/keyrings/obs-oss-arm-com.gpg + +$ echo "deb [signed-by=/usr/share/keyrings/obs-oss-arm-com.gpg] http://obs.oss.arm.com:82/arm-toolchains:/ubuntu-24/linux/ ./" | sudo tee /etc/apt/sources.list.d/obs-oss-arm-com.list + +$ sudo apt update +``` + +#### Red Hat Entrprise Linux 8 + +``` +$ sudo dnf install 'dnf-command(config-manager)' + +$ sudo dnf config-manager -y --add-repo http://obs.oss.arm.com:82/arm-toolchains:/rhel-8/linux/arm-toolchains:rhel-8.repo +``` + +#### Red Hat Entrprise Linux 9 + +``` +$ sudo dnf install 'dnf-command(config-manager)' + +$ sudo dnf config-manager -y --add-repo http://obs.oss.arm.com:82/arm-toolchains:/rhel-9/linux/arm-toolchains:rhel-9.repo +``` + +#### Amazon Linux 2023 + +``` +$ sudo dnf install 'dnf-command(config-manager)' + +$ sudo dnf config-manager -y --add-repo http://obs.oss.arm.com:82/arm-toolchains:/amzn-2023/linux/arm-toolchains:amzn-2023.repo +``` + +#### SUSE Linux Enterprise Server 15 + +``` +$ sudo zypper ar -f http://obs.oss.arm.com:82/arm-toolchains:/sles-15/linux/arm-toolchains:sles-15.repo +``` + +### Installation step + +Please select the command below appropriate for your Linux distribution. This +will install Arm Toolchain For Linux, along with Arm Performance Libraries, +which is a required dependency. + +#### Ubuntu systems + +``` +$ sudo apt install arm-toolchain-for-linux +``` + +#### Red Hat Enterprise Linux and Amazon Linux systems + +``` +$ sudo dnf install arm-toolchain-for-linux +``` + +#### SUSE Linux Enterprise Server systems + +``` +$ sudo zypper install arm-toolchain-for-linux +``` diff --git a/arm-software/linux/docs/PortingFromACfL.md b/arm-software/linux/docs/PortingFromACfL.md new file mode 100644 index 000000000000..ecce164b52a4 --- /dev/null +++ b/arm-software/linux/docs/PortingFromACfL.md @@ -0,0 +1,104 @@ +## ACfL to ATfL Porting Guide + +This document outlines the key differences between using the Arm Toolchain for +Linux (ATfL) and the Arm Compiler for Linux (ACfL). It also lists command-line +options and macros that can be used with ATfL as alternatives to those used in +ACfL. + +Both toolchains provide frontends for compiling C, C++, and Fortran code, and +the names of these frontends are consistent across both: `armclang` for C, +`armclang++` for C++, and `armflang` for Fortran. + +The quadmath is supported by ATfL, while it was not supported by ACfL. + +### Reference Version + +|Compiler |Version| +|------------------------------|-------| +|Arm Compiler for Linux (ACfL) |24.10 | +|Arm Toolchain for Linux (ATfL)|20.0 | + +### ArmPL integration + +In ACfL, Arm Performance Libraries (ArmPL) are bundled with the compiler. To +simplify usage, the `-armpl` flag is provided to automatically include the +necessary headers and libraries for BLAS, LAPACK, FFT, and other numerical +routines. + +In contrast, ATfL does not include ArmPL directly, but it depends on the ArmPL +package, which is installed alongside the toolchain. To use ArmPL with ATfL, the +users must manually specify the locations of the headers and libraries using +`pkg-config`. Detailed instructions are available in the +[Getting Started](./GettingStarted.md) guide. + +#### Note + +Vector math functions from libamath are accessible without manually specifying +the libraries. + +### C/C++ Frontend + +The C/C++ frontend in ATfL is identical to the one used in ACfL. Both are built +on the Clang frontend from the upstream LLVM project (`llvm-project/clang`). + +### Fortran Frontend + +The Fortran frontend in ATfL is based on the new LLVM Flang project +(`llvm-project/flang`). This frontend is a modern, from-scratch implementation. +In contrast, ACfL used the older Classic Flang frontend, available at +[https://github.com/flang-compiler/flang](https://github.com/flang-compiler/flang). +Because ATfL introduces a new Fortran frontend, this document will primarily +focus on the differences in Fortran support between the two toolchains. + +#### Major difference + +| |Compatibility| +|----------------|-------------| +|Binary |No | +|Module file |No | +|Array descriptor|No | + +#### Difference in Fortran features + +|Feature |ACfL |ATfL | +|--------------------------|---------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------| +|Base Fortran standard |Fortran 2008 |Fortran 2018 | +|Base OpenMP Specification |OpenMP 4.0 |OpenMP 2.5
Note: OpenMP support is experimental | +|Parameterized Derived Type|Supported |PDT Kind - Supported
PDT Length - Not supported | +|Preprocessor |Use `-cpp` to switch ON |Always ON
Use `-cpp` to switch ON processing of predefined macros and macros from the command line| +|Directives |`ivdep`, `prefetch`, `unroll`, `nounroll`, `vector always`, `vector vectorlength`, `novector`|`vector always` | +|Line length |2100 |Unlimited | +|Recursive functions |Use `-frecursive` |Default | +|Main function |Is a library linked at link-time |Is generated in the object file containing the program statement | + +#### Difference in command line flags + +The following table summarises some of the most commonly used compiler flags in +gfortran and gives their equivalent in the Arm Fortran compiler: + +|ACfL |ATfL |Description | +|------------------|--------------------------|---------------------------------------------------------------------------------------------------| +|`-module ` |`-J `
`-I `|Specifies a directory to place module files
Specifies a directory to search for module files | +|`-Mallocatable=03`|`-frealloc-lhs` |Use Fortran 2003 standard semantics for assignments to allocatables | +|`-Mallocatable=95`|`-fno-realloc-lhs` |Use pre-Fortran 2003 standard semantics for assignments to allocatables | +|`-r8` |`-fdefault-real-8` |Sets the default `KIND` for `REAL` and `COMPLEX` declarations, constants, functions, and intrinsics| +|`-i8` |`-fdefault-integer-8` |Set the default `KIND` for `INTEGER` and `LOGICAL` to 64bit (i.e., `KIND = 8`) | + +#### Pre-defined macros + +`armflang` has the following compiler and machine specific predefined processor +macros: + +|ACfL |ATfL |Value |Description | +|----------------------|----------------------|-------------|----------------------------------------------------------| +|`__FLANG` |`__flang__` |`1` |Selection of compiler dependent source at compile time | +|`__arch64` |N/A |`1` |Selection of architecture dependent source at compile time| +|`__aarch64__` |N/A |`1` |Selection of architecture dependent source at compile time| +|`__ARM_ARCH` |N/A |`8` |Selection of architecture dependent source at compile time| +|`__ARM_ARCH__` |N/A |`8` |Selection of architecture dependent source at compile time| +|`__armflang_major__` |`__flang_major__` |`24`/`20` |Underlying LLVM version details | +|`__armflang_minor__` |`__flang_minor__` |`10`/`1` |Underlying LLVM version details | +|`__armflang_version__`|`__flang_patchlevel__`|`24.10.1`/`0`|Underlying LLVM version details | +|`__linux__` |`__linux__` |`1` |Targeted Operating System | +|`__linux` |`__linux__` |`1` |Targeted Operating System | +|`linux` |`__linux__` |`1` |Targeted Operating System | diff --git a/arm-software/linux/docs/UsingArmPL.md b/arm-software/linux/docs/UsingArmPL.md new file mode 100644 index 000000000000..3faff98729ab --- /dev/null +++ b/arm-software/linux/docs/UsingArmPL.md @@ -0,0 +1,132 @@ +## Using the Arm Performance Libraries + +You can get greater performance from your code if you enable linking to the +optimized math libraries at compilation time. + +### Linking to Arm Performance Libraries + +To enable you to get the best performance on Arm-based systems, Arm recommends +linking to Arm Performance Libraries. Arm Performance Libraries provide +optimized standard core math libraries for high-performance computing +applications on Arm processors. Through a C interface, the following types of +routines are available: + +* BLAS: Basic Linear Algebra Subprograms (including XBLAS, the extended + precision BLAS). + +* LAPACK: A comprehensive package of higher level linear algebra routines. + +* FFT functions: A set of Fast Fourier Transform routines for real and complex + data using the FFTW interface. + +* Sparse linear algebra. + +* libastring: A subset of libc, which is a set of optimized string functions. + +The easiest way to make the Arm Performance Libraries visible to the compiler is +to load the `arm-performance-libraries` environment module. After the `atfl` +environment module has been loaded, the arm-performance-libraries module should +become available for loading: + +``` +$ module load arm-performance-libraries +``` + +This should set the `ARMPL_`-prefixed environment variables and two other +critical environment variables: `LD_LIBRARY_PATH` and `PKG_CONFIG_PATH`. The +recommended way of selecting command line flags for using a specific variant of +Arm Performance Libraries is through invoking the `pkg-config` command. Note +that the Arm Performance Libraries export several `pkg-config` modules, you +should be picking the one that you actually need, particularly when you plan to +use OpenMP (notice the `seq` vs. `omp` suffix): + +``` +$ pkg-config --list-all | grep armpl +armpl ArmPL - Arm Performance Libraries +armpl-Fortran-dynamic-ilp64-omp ArmPL - Arm Performance Libraries +armpl-Fortran-dynamic-ilp64-seq ArmPL - Arm Performance Libraries +armpl-Fortran-dynamic-lp64-omp ArmPL - Arm Performance Libraries +armpl-Fortran-dynamic-lp64-seq ArmPL - Arm Performance Libraries +armpl-Fortran-static-ilp64-omp ArmPL - Arm Performance Libraries +armpl-Fortran-static-ilp64-seq ArmPL - Arm Performance Libraries +armpl-Fortran-static-lp64-omp ArmPL - Arm Performance Libraries +armpl-Fortran-static-lp64-seq ArmPL - Arm Performance Libraries +armpl-dynamic-ilp64-omp ArmPL - Arm Performance Libraries +armpl-dynamic-ilp64-seq ArmPL - Arm Performance Libraries +armpl-dynamic-lp64-omp ArmPL - Arm Performance Libraries +armpl-dynamic-lp64-seq ArmPL - Arm Performance Libraries +armpl-static-ilp64-omp ArmPL - Arm Performance Libraries +armpl-static-ilp64-seq ArmPL - Arm Performance Libraries +armpl-static-lp64-omp ArmPL - Arm Performance Libraries +armpl-static-lp64-seq ArmPL - Arm Performance Libraries +``` + +#### C/C++ examples + +To link to the OpenMP multi-threaded Arm Performance Libraries with a 64-bit +integer interface, and include compiler and library optimizations for an +Neoverse N1-based system, use: + +``` +$ armclang -fopenmp -o binary code_with_math_routines.c -mcpu=neoverse-n1 `pkg-config armpl-dynamic-ilp64-omp --cflags --libs` +``` + +To link to the OpenMP multi-threaded Arm Performance Libraries with a 32-bit +integer interface, and build portable output that is suitable for any +Armv8-A-based system, use: + +``` +$ armclang -fopenmp -o binary code_with_math_routines.c -mcpu=generic `pkg-config armpl-dynamic-lp64-omp --cflags --libs` +``` + +To link to the serial implementation of Arm Performance Libraries with a 32-bit +integer interface, and include compiler and library optimizations for an +Neoverse V2-based system, use: + +``` +$ armclang -o binary code_with_math_routines.c -mcpu=neoverse-v2 `pkg-config armpl-dynamic-lp64-seq --cflags --libs` +``` + +#### Fortran examples + +To link to the OpenMP multi-threaded Arm Performance Libraries with a 64-bit +integer interface, and include compiler and library optimizations for an +Neoverse N2-based system, use: + +``` +$ armflang -fopenmp -o binary code_with_math_routines.f90 -mcpu=neoverse-n2 `pkg-config armpl-dynamic-ilp64-omp --cflags --libs` +``` + +To link to the OpenMP multi-threaded Arm Performance Libraries with a 32-bit +integer interface, and build portable output that is suitable for any +Armv8-A-based system, use: + +``` +$ armflang -fopenmp -o binary code_with_math_routines.f90 -mcpu=generic `pkg-config armpl-dynamic-lp64-omp --cflags --libs` +``` + +To link to the serial implementation of Arm Performance Libraries with a 32-bit +integer interface, and include compiler and library optimizations for an +Neoverse V1-based system, use: + +``` +$ armflang -o binary code_with_math_routines.f90 -mcpu=neoverse-v1 `pkg-config armpl-dynamic-lp64-seq --cflags --libs` +``` + +#### More information + +For more information please visit this page: +[Get started with Arm Performance Libraries (stand-alone Linux version) Version 24.10](https://developer.arm.com/documentation/102620/latest). + +To learn more about integrating Arm Performance Libraries with Arm Toolchain For +Linux please visit [Using Arm Performance Libraries (ArmPL) with ATfL](https://github.com/arm/arm-toolchain/blob/arm-software/arm-software/linux/README.md#using-arm-performance-libraries-armpl-with-atfl). + +#### Note + +The Arm Performance Libraries suite is also the provider of the vectorized math +routines library (libamath). This is a subset of the libm functions, which makes +it possible to vectorize the loops containing calls to those functions. The Arm +Toolchain for Linux default configuration instructs the C/C++ and Fortran +compilers to make use of this library during vectorization automatically, no +further command line options are needed. This can be disabled by specifying the +`-fveclib=none` option. diff --git a/arm-software/linux/docs/index.md b/arm-software/linux/docs/index.md new file mode 100644 index 000000000000..0770f11a1dd5 --- /dev/null +++ b/arm-software/linux/docs/index.md @@ -0,0 +1,17 @@ +# Welcome to the Arm Toolchain For Linux + +The Arm Toolchain for Linux provides a complete compiling environment for +natively developing and tuning your server and HPC applications on Arm-based +platforms. + +## Contents + +```{eval-rst} +.. toctree:: + :titlesonly: + + Installation + GettingStarted + UsingArmPL + PortingFromACfL +```