Getting started with Arm Code Advisor

This tutorial walks through the diagnostic process with Arm Code Advisor and shows how to identify and fix problems in a code example.

Introduction

Arm Code Advisor helps users produce high quality, high performing code on Arm target systems by advising users how they can improve their code to take better advantage of the Arm architecture's features. Arm Code Advisor forms an integral part of the develop-compile-optimize cycle.

 

The overall development flow with Arm Code Advisor is:

  1. Compile your application with insights enabled.

  2. Run armcadvisor collect to gather dynamic performance profiling data.

  3. Run armcadvisor analyze to examine the insights together with the performance data to produce prioritized advice. Run armcadvisor web to start the Arm Code Advisor web application, and use your web browser to navigate and view the advice inline with code.

  4. Optimize your code using the insights and advice from Arm Code Advisor.

Installing Arm HPC tools suite

Full instructions on configuring your environment for each Arm tool can be found in Environment configuration. Refer to the following topics for instructions on how to install the Arm HPC tools:

Configuring your environment

To see which environment modules are available:

module avail
Note: you may need to configure the MODULEPATH environment variable to include the installation directory:

export MODULEPATH=$MODULEPATH:/opt/arm/modulefiles/

To configure your Linux environment to make Arm Compiler for HPC available:

module load <architecture>/<linux_variant>/<linux_version>/suites/arm-compiler-for-hpc/<version>

For example:

module load Generic-AArch64/SUSE/12/suites/arm-compiler-for-hpc/1.4

To configure your Linux environment to make Arm Code Advisor available:

module load <architecture>/<linux_variant>/<linux_version>/suites/arm-code-advisor/<code_advisor_version>

For example:

module load Generic-AArch64/SUSE/12/suites/arm-code-advisor/1.2

You can use the which command to check that the Arm C/C++ Compiler armclang command, or the Arm Code Advisor armcadvisor command is available:

which armclang
/opt/arm/arm-compiler-for-hpc-1.4_Generic-AArch64_SUSE-12_aarch64-linux/bin/armclang

% which armcadvisor
/opt/arm/arm-code-advisor-1.2_Generic-AArch64_SUSE-12_aarch64-linux/bin/armcadvisor
Note: You might want to consider adding the module load command to your .profile to run it automatically every time you log in.

Full instructions on configuring your environment for each Arm tool can be found in Environment configuration.

Tutorial Example

This tutorial walks through the diagnostic process with Arm Code Advisor and demonstrates how to identify and fix problems.

The following example code manipulates the contents of two arrays. The core loop, in the function inc_copy, contains a backwards memory dependency that prevents optimization. The example code is contained within 2 files, example1.c and example 2.c:

example1.c

#define ARRAY_SIZE 3000

void inc_copy(int *A, int *B, int n);

int main() {
  int A[ARRAY_SIZE];
  int B[ARRAY_SIZE];
  for (int j = 0; j < ARRAY_SIZE; j++) {
    A[j] = j;
    B[j] = j * 2;
  }

  for (int i = 0; i < 10000; i++) {
    inc_copy(A, B, ARRAY_SIZE);
  }

  return 0;
}

example2.c

void inc_copy(int *A, int *B, int n) {
  for (int i = 1; i < n; i++) {
    A[i-1] = A[i-1] + 1;
    B[i] = A[i];
  }
}

Compiling the application with insights

Note: Arm Fortran Compiler for HPC does not support insights. 

The -insight option instructs the compiler to embed insights in the final executable. Insights provide information about what action the compiler took during optimization and why. This information gives reasons why the compiler might not have been able to generate the best code possible, and shows how you might improve the code to enable the compiler to do more. For example, compiler insights might warn about a function it could not inline due to lack of a function definition at compile time, or explain that a loop could not be vectorized due to the presence of a function call in the loop.

To compile the code with insights enabled:

armclang -O3 -g -insight -o example example1.c example2.c

The options are as follows:

  • -O3 specifies the optimization level. -O3 is a high optimization level that enables auto-vectorization.

  • -g generates debug information and is a mandatory option for Arm Code Advisor.

  • -insight specifies that the compiler should generate insights.

  • -o example produces an output executable called example.

Gathering profiling data

Performance profiling allows Arm Code Advisor to prioritize the advice it offers. For example, code problems that affect rarely-executed code are a lower priority than code problems in performance bottlenecks.

To run the generated executable and collect performance profiling data about the code:

% armcadvisor collect ./example 
Starting collection of program [./example] to profile temp in /home/user1/.armcadvisor/profiles

Arm Code Advisor stores profiling data in subdirectories of the collect repository. By default, the collect repository is the .armcadvisor/profiles folder in your home directory. Use the --repository option to specify a different folder. By default, Arm Code Advisor uses the profile name temp, with each collect operation overwriting the last. Use the --persistent option to use uniquely numbered profile names for each collect operation.

Analyze insights and performance data

Analysis brings together the insights generated by the compiler, and the performance data collected by Arm Code Advisor to produce prioritized advice, ranking insights in order of importance.

To perform analysis:

% armcadvisor analyze
Generating analysis file, armcadvisor.advice

The analyze operation uses the data produced by the collect operation, located in the collect repository. By default this is the latest profile in the armcadvisor-profiles folder in your home directory. If you specified a different location when using armcadvisor collect, use the --repository and --profile options to select the required profile.

View advice in the web interface

Arm Code Advisor displays compiler insights, prioritized using the performance data, in an intuitive web interface. Insights are displayed directly in the source code, helping you navigate to problem areas quickly and easily.

To launch the web interface:

% armcadvisor web -ne
Open your browser to one of:
  http://server.arm.com:8080
  http://127.0.0.1:8080
Note: By default, the web interface is password-protected and only available from the local host. The -ne options we specified allow for unrestricted access across the network. For more information, see Configuring secure access to Arm Code Advisor.

Open your web browser to the specified location to see the project summary. The project summary gives an overview of your project including key project statistics, a summary of the highest priority insights, and performance measures:

ARM Code Advisor project summary page

Click Open Project to continue.

Choose an insight from the list on the left to show the related code in the source code viewer on the right. Advice is shown inline with your code to describe what was found and how you could make improvements.

Code Advisor showing actionable advice

Analyzing insights

 An example list of insights in the Code Advisor web viewer 

Let's investigate some of the insights Arm Code Advisor is telling us about. The list of insights is prioritized by impact. Click an insight to go directly to the relevant location in your source code.

The first three insights tell us that there is a memory dependency in the code that is preventing optimization. The impact bar next to each insight shows us that this is a high priority insight: it's preventing optimization in a highly-exercised piece of code.

In this example, there is a memory dependency because the same loop is both modifying values in the A[] array and using those same values to set the B[] array. Vectorizing this loop as it stands could result in operations occurring out-of- order, so the compiler does not optimize it.

For more information about memory dependency problems, and a discussion of potential solutions, see Cannot vectorize due to unsafe memory dependencies.

Note: The sixth insight in the list tells us that a loop was vectorized successfully. This is good news: there's nothing more for us to worry about here. However, this insight relates to one instance of the loop. There could be many instances of the same loop due to inlining. The same loop was successfully vectorized in one instance but may not be in another due to inlining.

Making the fix

We can fix the memory dependency problem by breaking out the two operations (modifying A[] and setting B[]) into two separate loops:

example2fix.c

void inc_copy(int *A, int *B, int n) { 
  for (int i = 1; i < n; i++)
   B[i] = A[i];
  for (int i = 1; i < n; i++)
   A[i-1] = A[i-1] + 1; 
}

Now we compile and run Arm Code Advisor again:

% armclang -O3 -insight -g -o example example1.c example2fix.c 
% armcadvisor collect ./example
Starting collection of [./example] to /home/user1/armcadvisor-profiles % armcadvisor analyze Generating analysis file, armcadvisor.advice % armcadvisor web -ne Open your browser to one of: http://server.arm.com:8080 http://127.0.0.1:8080

This time, when we look at the web interface, we can see that the insights now report successful vectorization:

Code Advisor showing vectorization confirmed

You have successfully used Arm Code Advisor to diagnose and fix a code problem that was preventing optimization.

Refer to the examples directory in your install location to see more examples and their solutions.

Related information