Merge pull request #1562 from kieranhejmadi01/main

Learn Basic C++ Optimisation Techniques using the G++ Compiler - LP

Author: jasonrandrews

content/learning-paths/servers-and-cloud-computing/c++_compilers_and_flags/1.md

@@ -0,0 +1,93 @@
+---
+title: Basics of Compilers 
+weight: 2
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Introduction to C++ and Compilers
+
+The C++ language gives the programmer the freedom to be expressive in the way they write code - allowing low-level manipulation of memory and data structures. Compared to managed languages, such as Java, C++ source code is generally less portable, requiring recompilation to the target Arm architecture. In the context of optimizing C++ workloads on Arm, significant performance improvements can be achieved without modifying the source code, simply by using the compiler correctly.
+
+Writing performant C++ code is a topic in itself and out of scope for this learning path. Instead we will focus on how to effectively use the compiler to target Arm instances in a cloud environment. 
+
+## Purpose of a Compiler
+
+The g++ compiler is part of the GNU Compiler Collection (GCC), which is a set of compilers for various programming languages, including C++. The primary objective of the g++ compiler is to translate C++ source code into machine code that can be executed by a computer. This process involves several high-level stages:
+
+- Preprocessing: In this initial stage, the preprocessor handles directives that start with a # symbol, such as `#include`, `#define`, and `#if`. It expands included header files, replaces macros, and processes conditional compilation statements.
+
+- Compilation: The compiler translates the preprocessed source code into an intermediate representation specific to the target processor architecture. This step includes syntax checking, semantic analysis, and generating error messages for any issues encountered in the source code.
+
+- Assembly: The intermediate representation is converted into assembly language, which uses mnemonics and syntax specific to the target processor architecture. Assemblers then convert this assembly code into object code (machine code).
+
+- Linking: The final stage involves linking the object code with necessary libraries and other object files. The linker merges multiple object files and libraries, resolves external references, allocates memory addresses for functions and variables, and generates an executable file that can be run on the target platform.
+
+An interesting fact about the g++ compiler is that it is designed to optimize both the performance and the size of the generated code. The compiler performs various optimizations based on the knowledge it has of the program, and it can be configured to prioritize reducing the size of the generated executable.  
+
+
+### Compiler Versioning
+
+Two popular compilers of C++ are the GNU Compiler Collection (GCC) and LLVM - both of which are open-source compilers and have contributions from Arm engineers to support the latest architectures. Proprietary or vendor-specific compilers, such as `nvcc` for compiling for NVIDIA GPUs, are often based on these open-source compilers. Alternative proprietary compilers are often designed for specific use cases. For example, safety-critical applications may need to comply with various ISO standards, which also include the compiler. The functional safety [Arm Compiler for Embedded](https://developer.arm.com/Tools%20and%20Software/Arm%20Compiler%20for%20Embedded%20FuSa) is such an example of a C/C++ compiler. 
+
+Most application developers are not in this safety qualification domain so we will be using the open-source GCC/G++ compiler for this learning path. 
+
+There are multiple Linux distribtions available to choose from. Each Linux distribution and operating system has a default compiler. For example after installing the default g++ on an `r8g` AWS instance, the default g++ compiler as of January 2025 is below.
+
+``` output
+g++ --version
+g++ (Ubuntu 13.3.0-6ubuntu2~24.04) 13.3.0
+Copyright (C) 2023 Free Software Foundation, Inc.
+This is free software; see the source for copying conditions.  There is NO
+warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+```
+
+The table below shows the default (*) and available compilers for a variety of linux distributions. This is taken from the [AWS-graviton performance runbook](https://github.com/aws/aws-graviton-getting-started/blob/main/c-c%2B%2B.md).
+
+
+Distribution    | GCC                  | Clang/LLVM
+----------------|----------------------|-------------
+Amazon Linux 2023  | 11*               | 15*
+Amazon Linux 2  | 7*, 10               | 7, 11*
+Ubuntu 24.04    | 9, 10, 11, 12, 13*, 14 | 14, 15, 16, 17, 18*
+Ubuntu 22.04    | 9, 10, 11*, 12       | 11, 12, 13, 14*
+Ubuntu 20.04    | 7, 8, 9*, 10         | 6, 7, 8, 9, 10, 11, 12
+Ubuntu 18.04    | 4.8, 5, 6, 7*, 8     | 3.9, 4, 5, 6, 7, 8, 9, 10
+Debian10        | 7, 8*                | 6, 7, 8
+Red Hat EL8     | 8*, 9, 10            | 10
+SUSE Linux ES15 | 7*, 9, 10            | 7
+
+
+The biggest and most simple performance gain can be achieved by using the most recent compiler available. The most recent optimisations and support will be available through the latest compiler. 
+
+Looking at the g++ documentation as an example, the most recent version of GCC available at the time of writing, version 14.2, has the following support and optimisations listed on their website [change note](https://gcc.gnu.org/gcc-14/changes.html). 
+
+```output
+A number of new CPUs are supported through the -mcpu and -mtune options (GCC identifiers in parentheses).
+    - Ampere-1B (ampere1b).
+    - Arm Cortex-A520 (cortex-a520).
+    - Arm Cortex-A720 (cortex-a720).
+    - Arm Cortex-X4 (cortex-x4).
+    - Microsoft Cobalt-100 (cobalt-100).
+...
+```
+
+Sufficient due diligence should be taken when updating your C++ compiler because the process may reveal bugs in your source code. These bugs are often undefined behaviour caused by not adhering to the C++ standard. It is rare that the compiler itself will introduced a bug. However, in such events known bugs are made publicly available in the compiler documentation. 
+
+## Basic g++ Optimisation Levels
+
+Using the g++ compiler as an example, the most course-grained dial you can adjust is the optimisation level, denoted with `-O<x>`. This adjusts a variety of lower-level optimsation flags at the expense of increased computation time, memory use and debuggability. When aggresive optimisation is used, the optimised binary may not show expected behaviour when hooked up to a debugger such as `gdb`. This is because the generated code may not match the original source code or program order, for example from loop unrolling and vectorisation. 
+
+A few of the most common optimization levels are in the table below. 
+
+| Optimization Level | Description                                                                                  |
+|--------------------|----------------------------------------------------------------------------------------------|
+| `-O0`              | No optimization; useful for debugging.                                                       |
+| `-O1`              | Basic optimizations that improve performance without significantly increasing compilation time. |
+| `-O2`              | More aggressive optimizations that further enhance performance.                              |
+| `-O3`              | Enables aggressive optimizations that can significantly improve execution speed.             |
+| `-Os`              | Optimizes code size, reducing the overall binary size.                                       |
+| `-Ofast`           | Enables optimizations that may not strictly adhere to standard compliance.                   |
+
+ Please refer to your compiler documentation for full details on the optimisation level, for example [GCC](https://gcc.gnu.org/onlinedocs/gcc-14.2.0/gcc/Optimize-Options.html).

content/learning-paths/servers-and-cloud-computing/c++_compilers_and_flags/2.md

@@ -0,0 +1,84 @@
+---
+title: Setup Your Environment
+weight: 3
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+If you are new to cloud computing, please refer to our learning path on [Getting started with Servers and Cloud Computing](https://learn.arm.com/learning-paths/servers-and-cloud-computing/intro/).
+
+## Connect to an AWS Arm-based Instance
+
+In this example we will be building and running our C++ application on an AWS Graviton 4 (`r8g.xlarge`) instance running Ubuntu 24.04 LTS. Once connected run the following commands to confirm the operating system and archiecture version. 
+
+```bash
+cat /etc/*lsb*
+```
+
+You will see an output such as the following:
+
+```output
+DISTRIB_ID=Ubuntu
+DISTRIB_RELEASE=24.04
+DISTRIB_CODENAME=noble
+DISTRIB_DESCRIPTION="Ubuntu 24.04.1 LTS"
+```
+
+Next, we will confirm we are using a 64-bit Arm-based system using the following command
+
+```bash
+uname -m
+```
+
+You will see the following output.
+
+```output
+aarch64
+```
+
+## Enable Environment modules
+
+Environment modules are a tool to quickly modify your shell configuration and environment variables. For this learning path, it allows us to quickly switch between different compiler versions to demonstrate potential improvements. 
+
+Install Environment Modules
+
+   First, you need to install the environment modules package. Open your terminal and run the following command:
+   ```bash
+   sudo apt update
+   sudo apt install environment-modules
+   ```
+
+Load environment modules after the package is installed. 
+
+```bash
+sudo chmod 755 /usr/share/modules/init/bash
+source /usr/share/modules/init/bash
+```
+Reload your shell configuration. 
+
+```bash
+source ~/.bashrc
+```
+
+Install various compiler version on your Ubuntu system. For this example we will install version 9 of the gcc/g++ compiler to demonstrate potential improvements your application could achieve. 
+
+```bash
+sudo add-apt-repository ppa:ubuntu-toolchain-r/test
+sudo apt update
+sudo apt install gcc-9 g++-9
+```
+
+Create a module file for each compiler installed. 
+
+```bash
+mkdir -p ~/modules/gcc
+nano ~/modules/gcc/9
+```
+Copy and paste the text below into the nano text editor and save the file
+```ouput
+#%Module1.0
+prepend-path PATH /usr/bin/gcc-9
+prepend-path PATH /usr/bin/g++-9
+```
+

content/learning-paths/servers-and-cloud-computing/c++_compilers_and_flags/3.md

@@ -0,0 +1,139 @@
+---
+title: Finding Supported Neoverse Features
+weight: 3
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Identify the Neoverse Version
+
+To understand which Neoverse version a cloud instance uses check the [Arm partner webpage](https://www.arm.com/partners/aws).
+
+Alternatively, if you already have access to the instance, run the `lscpu` command and observe the underlying Neoverse Architecture under the `Model Name` row.
+
+```output
+lscpu | grep -i model
+Model name:                           Neoverse-V2
+Model:                                1
+```
+Here you can confirm the AWS`r8g.xlarge` instance, is based on the Neoverse-V2 Arm IP. We will use this instance for the remainder of this learning path.
+
+## Understand Supported CPU Features
+
+Next, to identify the CPU extensions supported by this architecture at runtime we can observe the Linux hardware capabilities (HWCAP) vector. The C++ source code below that reads a specific vector that contains the information.
+
+Copy and paste the c program into a file named, `hw_cap.c`.
+
+```c
+
+#include <stdio.h>
+#include <sys/auxv.h>
+#include <asm/hwcap.h>
+
+int main()
+{
+    long hwcaps = getauxval(AT_HWCAP);
+
+    if (hwcaps & HWCAP_AES) {
+        printf("AES instructions are available\n");
+    } else {
+        printf("AES instructions are not available\n");
+    }
+    if (hwcaps & HWCAP_CRC32) {
+        printf("CRC32 instructions are available\n");
+    } else {
+        printf("CRC32 instructions are not available\n");
+    }
+    if (hwcaps & HWCAP_PMULL) {
+        printf("PMULL/PMULL2 instructions that operate on 64-bit data are available\n");
+    } else {
+        printf("PMULL/PMULL2 instructions are not available\n");
+    }
+    if (hwcaps & HWCAP_SHA1) {
+        printf("SHA1 instructions are available\n");
+    } else {
+        printf("SHA1 instructions are not available\n");
+    }
+    if (hwcaps & HWCAP_SHA2) {
+        printf("SHA2 instructions are available\n");
+    } else {
+        printf("SHA2 instructions are not available\n");
+    }
+    if (hwcaps & HWCAP_SVE) {
+        printf("Scalable Vector Extension (SVE) instructions are available\n");
+    } else {
+        printf("Scalable Vector Extension (SVE) instructions are not available\n");
+    }
+
+    return 0;
+}
+
+```
+
+Compile and run with the command below. 
+
+```bash
+gcc hw_cap.c -o hw_cap
+./hw_cap
+```
+
+On Graviton 4, I the output below confirms the scalable vector extensions (SVE) are available.
+
+```output
+AES instructions are available
+CRC32 instructions are available
+PMULL/PMULL2 instructions that operate on 64-bit data are available
+SHA1 instructions are available
+SHA2 instructions are available
+Scalable Vector Extension (SVE) instructions are available
+```
+
+For the latest list of all hardware capabilities available for a specific linux kernel version, refer to the `arch/arm/include/uapi/asm/hwcap.h` header file in the Linux Kernel source code.
+
+Further, knowing the width of SVE (Scalable Vector Extension) can be useful for optimizing software performance, as it allows developers to tailor their code to fully utilize the available vector processing capabilities of the hardware. Copy the following C code into a file named `sve_width.c`.  
+
+```c
+#include <arm_sve.h>
+#include <stdio.h>
+
+int main() {
+    int sve_width = svcntb();
+    printf("SVE vector length: %d bytes\n", sve_width);
+    return 0;
+}
+```
+
+Compile with the following command. 
+
+```bash
+g++ sve_width.c -o sve_width -mcpu=neoverse-v2
+```
+
+This shows that the Neoverse-V2 based Graviton 4 instance has a SVE width of 8 bytes (128 bits).
+
+```output
+SVE vector length: 16 bytes
+```
+
+## Supported Compiler Features
+
+Fortunately, the g++ compiler will automatically identify the host systems capability. The `-###` argument can be used to show the full options used when compiling. 
+
+If the host is the same platform you are compiling for, you can observe which CPUs are potential targets for your command with the following g++ command. 
+
+```output
+g++ -E -mcpu=help -xc /dev/null
+cc1: note: valid arguments are: cortex-a34 cortex-a35 cortex-a53 cortex-a57 cortex-a72 cortex-a73 thunderx thunderxt88p1 thunderxt88 octeontx octeontx81 octeontx83 thunderxt81 thunderxt83 ampere1 ampere1a emag xgene1 falkor qdf24xx exynos-m1 phecda thunderx2t99p1 vulcan thunderx2t99 cortex-a55 cortex-a75 cortex-a76 cortex-a76ae cortex-a77 cortex-a78 cortex-a78ae cortex-a78c cortex-a65 cortex-a65ae cortex-x1 cortex-x1c **neoverse-n1** ares neoverse-e1 octeontx2 octeontx2t98 octeontx2t96 octeontx2t93 octeontx2f95 octeontx2f95n octeontx2f95mm a64fx tsv110 thunderx3t110 neoverse-v1 zeus neoverse-512tvb saphira cortex-a57.cortex-a53 cortex-a72.cortex-a53 cortex-a73.cortex-a35 cortex-a73.cortex-a53 cortex-a75.cortex-a55 cortex-a76.cortex-a55 cortex-r82 cortex-a510 cortex-a710 cortex-a715 cortex-x2 cortex-x3 neoverse-n2 cobalt-100 neoverse-v2 grace demeter generic
+```
+
+Comparing to when using `g++9` we can see there are fewer CPU targets to optimise for as recently released CPUs are omitted, for example the Neoverse V2. 
+
+```
+g++-9 -E -mcpu=help -xc /dev/null
+cc1: note: valid arguments are: cortex-a35 cortex-a53 cortex-a57 cortex-a72 cortex-a73 thunderx thunderxt88p1 thunderxt88 octeontx octeontx81 octeontx83 thunderxt81 thunderxt83 emag xgene1 falkor qdf24xx exynos-m1 phecda thunderx2t99p1 vulcan thunderx2t99 cortex-a55 cortex-a75 cortex-a76 ares neoverse-n1 neoverse-e1 a64fx tsv110 zeus neoverse-v1 neoverse-512tvb saphira neoverse-n2 cortex-a57.cortex-a53 cortex-a72.cortex-a53 cortex-a73.cortex-a35 cortex-a73.cortex-a53 cortex-a75.cortex-a55 cortex-a76.cortex-a55 generic
+```
+
+
+
+