Improve Linaro DDT docs

.github/CODEOWNERS

@@ -1,5 +1,6 @@
 * @bcumming @msimberg @RMeli
 docs/services/firecrest @jpdorsch @ekouts
 docs/software/communication @msimberg
+docs/software/devtools/linaro @jgphpc
 docs/software/prgenv/linalg.md @finkandreas @msimberg
 docs/software/sciapps/cp2k.md @abussy @RMeli

docs/software/devtools/index.md

@@ -1,12 +1,12 @@
 [](){#ref-software-devtools}
 # Debugging and Performance Analysis tools
 
-Debugging and Performance Analysis tools can assist users in developing and optimizing scientific parallel applications, especially in a high-performance computing (HPC) environment.
-Efficient tools can significantly improve workflows and save valuable computational resources.
+Debugging and performance analysis tools can assist users in developing and optimizing scientific parallel applications, especially in a high-performance computing (HPC) environment.
+These tools can significantly improve workflows and save valuable computational resources.
 
-CSCS provides debuggers and performance analysis tools on Alps Clusters.
+CSCS provides debuggers and performance analysis tools on [Alps][ref-alps] clusters.
 
-!!! note "get in touch"
+!!! note "Get in touch"
     If you have issues or questions about debugging or performance analysis tools, please do not hesitate to [contact us][ref-get-in-touch].
 
 [](){#ref-devtools-debug}

docs/software/devtools/linaro-ddt.md

@@ -2,12 +2,12 @@
 # Linaro DDT
 
 DDT allows source-level debugging of Fortran, C, C++ and Python codes.
-It can be used for debugging serial, multi-threaded (OpenMP), multi-process (MPI) and accelerated (CUDA, OpenACC) programs running on research and production systems, including the CSCS Alps system.
+It can be used for debugging serial, multi-threaded (OpenMP), multi-process (MPI), and accelerated (CUDA, OpenACC) programs running on research and production systems, including the CSCS [Alps][ref-alps] system.
 DDT can be executed either with its graphical user interface or from the command-line.
 
 !!! note
-    Linaro DDT is provided in the `linaro-forge` uenv.
-    Before using DDT, please read the [`linaro-forge` documentation][ref-uenv-linaro], which explains how to download and set up the latest version and set it up.
+    Linaro DDT is provided in the `linaro-forge` [uenv][ref-uenv].
+    Before using DDT, please read the [`linaro-forge` uenv documentation][ref-uenv-linaro], which explains how to download and set up the latest version.
 
 ## User guide
 
@@ -27,29 +27,33 @@ mpicxx -g test_cpu.cpp test_gpu.o -o myexe
 ### Launch Linaro DDT
 
 To use the DDT client with uenv, it must be launched in `Manual Launch` mode
-(assuming that it is connected to Alps via `Remote Launch`):
+(assuming that it is connected to [Alps][ref-alps] via `Remote Launch`):
 
-=== "on local machine"
+=== "On local machine"
 
     Start DDT, and connect to the target cluster using the drop down menu for `Remote Launch`.
+    If you don't have a target cluster,
+    the [`linaro-forge` uenv documentation][ref-uenv-linaro] explains how to set up the connection the first time.
 
-    Click on `Manual launch`, set the number of processes to listen to, then wait for the slurm job to start (see the "on Alps" tab).
+    Click on `Manual launch`, set the number of processes to listen to, then wait for the Slurm job to start 
+    (see the "on Alps" tab for how to start the Slurm job).
 
     <img src="https://raw.githubusercontent.com/jgphpc/cornerstone-octree/ddt/scripts/img/ddt/0.png" width="600" />
 
-=== "on Alps"
+=== "On Alps"
 
     Log into the system and launch with the `srun` command:
 
     ```console
-    # start a session with both the PE used to build your application
-    # and the linaro-forge uenv mounted
-    $ uenv start prgenv-gnu/24.11:v1,linaro-forge/24.1.1:v1 --view=prgenv-gnu:default
+    $ uenv start prgenv-gnu/24.11:v1,linaro-forge/24.1.1:v1 --view=prgenv-gnu:default # (1)!
     $ source /user-tools/activate
-
     $ srun -N1 -n4 -t15 -pdebug ./cuda_visible_devices.sh   ddt-client   ./myexe
     ```
 
+    1. Start a session with both the uenv used to build your application and the `linaro-forge` uenv mounted.
+
+
+
 ### Start debugging
 
 By default, DDT will pause execution on the call to `MPI_Init`:
@@ -65,14 +69,16 @@ There are two mechanisms for controlling program execution:
 
 === "Stop at"
 
-    Execution can be paused in every CUDA kernel launch by activating the default breakpoints from the Control menu:
+    Execution can be paused in every CUDA kernel launch by activating the default breakpoints from the `Control` menu:
 
     <img src="https://raw.githubusercontent.com/jgphpc/cornerstone-octree/ddt/scripts/img/ddt/4.png" width="400" />
 
 
-This screenshot shows a debugging session on 128 gpus:
+??? example  "Debugging with 128 GPUs"
+
+    This screenshot shows a debugging session on 128 GPUs:
 
-![DDTgpus](https://raw.githubusercontent.com/jgphpc/cornerstone-octree/ddt/scripts/img/ddt/5.png)
+    ![DDTgpus](https://raw.githubusercontent.com/jgphpc/cornerstone-octree/ddt/scripts/img/ddt/5.png)
 
 More informations regarding how to use Linaro DDT are provided in the Forge [User Guide](https://docs.linaroforge.com/latest/html/forge/index.html).
 

docs/software/devtools/linaro-map.md

@@ -7,8 +7,8 @@ In the first case, the user can set the profiling configuration using the GUI an
 In the latter (recommended) case, the user can use the MAP executable to launch the application they want to profile which will generate a report file that can then be opened from the locally installed [client](https://docs.linaroforge.com/latest/html/forge/forge/installing/mac_install.html).
 
 !!! note
-    Linaro Map is provided in the `linaro-forge` uenv.
-    Before using Map, please read the [`linaro-forge` documentation][ref-uenv-linaro], which explains how to download and set up the latest version and set it up.
+    Linaro MAP is provided in the `linaro-forge` [uenv][ref-uenv].
+    Before using MAP, please read the [`linaro-forge` uenv documentation][ref-uenv-linaro], which explains how to download and set up the latest version.
 
 ## Linaro Forge MAP
 

docs/software/devtools/linaro-forge.md → docs/software/devtools/linaro-uenv.md

@@ -1,22 +1,22 @@
 [](){#ref-uenv-linaro}
 # Linaro Forge
 
-[Linaro Forge](https://docs.linaroforge.com/latest/html/forge/index.html) is a suite of profiling and debugging tools, that includes the DDT debugger and the MAP profiler.
+[Linaro Forge](https://docs.linaroforge.com/latest/html/forge/index.html) is a suite of profiling and debugging tools, that includes the DDT debugger and the MAP performance analysis tool.
 
-!!! note
+!!! note "Linaro DDT debugger and Linaro MAP performance analysis tool"
     We have separate user guides for the tools provided by the `linaro-forge` uenv.
     The documentation here shows how to download the uenv, and how to set up your environment.
 
     Once you are set up, follow the specific guides:
 
-    * the [DDT debugger][ref-devtools-ddt]
-    * the [MAP profiler][ref-devtools-map].
+    * [DDT debugger][ref-devtools-ddt],
+    * [MAP performance analysis tool][ref-devtools-map].
 
 ## Quickstart guide
 
-The Linaro uenv is named `linaro-forge`, and the available versions can be determined using the `uenv image find` command:
+The Linaro [uenv][ref-uenv] is named `linaro-forge`, and the available versions can be determined using the `uenv image find` command, as explained in the [uenv documentation][ref-uenv].
 
-!!! example "finding available linaro-forge versions"
+??? example "Finding available `linaro-forge` versions"
 
     ```console
     $ uenv image find linaro-forge
@@ -32,21 +32,22 @@ This uenv is configured to be mounted in the `/user-tools` path so that they can
 When using alongside another uenv, start a uenv session with both uenv.
 In the following example, the `prgenv-gnu` and `linaro-forge` uenv will be mounted at `/user-environment` and `/user-tools`  respectively:
 
-```bash
-> uenv start prgenv-gnu/24.11,linaro-forge/24.1.1 \
+```console
+$ uenv start prgenv-gnu/24.11,linaro-forge/24.1.1 \
     --view=prgenv-gnu:default,forge
 
-# test that everything has been mounted correctly
-# (will give warnings if there are problems)
-> uenv status
+$ uenv status # (1)!
 
-# check that ddt is in the path
-> ddt --version
+$ ddt --version # (2)!
 Linaro DDT Part of Linaro Forge.
 Copyright (c) 2023-2024 Linaro Limited. All rights reserved.
 Version: 24.1.1
 ```
 
+1. Test that everything has been mounted correctly by looking at `uenv status`.
+   There will be warnings if there are problems.
+2. Check that the [DDT debugger][ref-devtools-ddt] is in the path.
+
 !!! note
     The `linaro-forge` uenv is always mounted at the `/user-tools` mount point, and a script `/user-tools/activate` is provided to load both ddt and map into your environment, without needing to use a view.
 
@@ -61,64 +62,108 @@ Version: 24.1.1
 
 ### Install and configure the Linaro client on your local machine
 
-We recommend installing the [desktop client](https://www.linaroforge.com/downloadForge) on your local workstation/laptop.
+We recommend installing the [Linaro desktop client] on your local workstation or laptop.
 It can be downloaded for a selection of operating systems.
-The client can be configured to connect with the debug jobs running on Alps, offering a better user experience compared to running with X11 forwarding.
+
+!!! warning
+
+    Make sure you download the [Linaro desktop client] matching the version of the `linaro-forge` uenv you are planning to use.
+
+    !!! example "Mismatched desktop client and uenv versions"
+        Mismatches between the client and the uenv version will lead to the following error when trying to establish a remote connection:
+
+        ```
+        The local version of Linaro DDT (24.0.6) is not compatible with the remote version (24.1.1).
+        ```
+
+The client can be configured to connect with the debug jobs running on [Alps][ref-alps], offering a better user experience compared to running with X11 forwarding.
 Once installed, the client needs to be configured to connect to the vCluster on which you are working.
 
 First, start the client on your laptop:
 
 === "Linux"
 
-    The path will change if you have installed a different version, or if it has been installed in a non-standard installation location.
+    !!! warning 
+
+        The path will change if you have installed a different version, or if it has been installed in a non-standard installation location.
 
     ```bash
     $HOME/linaro/forge/24.1.1/bin/ddt
     ```
 
-=== "MacOS"
+=== "macOS"
 
-    The path will change if you have installed a different version, or if it has been installed in a non-standard installation location.
+    !!! warning
+
+        The path will change if you have installed a different version, or if it has been installed in a non-standard installation location.
+        Please use the appropriate path and version for your installation.
 
     ```bash
     open /Applications/Linaro\ Forge\ Client\ 24.1.1.app/
     ```
 
 Next, configure a connection to the target system.
-Open the *Remote Launch* menu and click on *configure* then *Add*.
+Open the `Remote Launch` menu and click on `Configure...` then `Add`.
 Examples of the settings are below.
 
 === "Daint"
+
+    !!! warning
+
+        The `Remote Installation Directory` will change if you are using a different version of the `linaro-forge` uenv.
+        Please use the appropriate version for your setup.
 
     | Field       | Value                                   |
     | ----------- | --------------------------------------- |
     | Connection  | `daint`                                  |
     | Host Name   | `cscsusername@ela.cscs.ch cscsusername@daint.cscs.ch`  |
     | Remote Installation Directory | `uenv run linaro-forge/24.1.1:/user-tools -- /user-tools/env/forge/` |    
+    | Private Key | `~/.ssh/cscs-key`                         |
 
 === "Santis"
+
+    !!! warning
+
+        The `Remote Installation Directory` will change if you are using a different version of the `linaro-forge` uenv.
+        Please use the appropriate version for your setup.
+
 
     | Field       | Value                                   |
     | ----------- | --------------------------------------- |
     | Connection  | `santis`                                |
     | Host Name   | `cscsusername@ela.cscs.ch cscsusername@santis.cscs.ch`  |
     | Remote Installation Directory | `uenv run linaro-forge/24.1.1:/user-tools -- /user-tools/env/forge/` |
+    | Private Key | `~/.ssh/cscs-key`                         |
 
 === "Clariden"
+
+    !!! warning
+
+        The `Remote Installation Directory` will change if you are using a different version of the `linaro-forge` uenv.
+        Please use the appropriate version for your setup.
+
 
     | Field       | Value                                   |
     | ----------- | --------------------------------------- |
     | Connection  | `clariden`                                |
     | Host Name   | `cscsusername@ela.cscs.ch cscsusername@clariden.cscs.ch`  |
     | Remote Installation Directory | `uenv run linaro-forge/24.1.1:/user-tools -- /user-tools/env/forge/` |
+    | Private Key | `~/.ssh/cscs-key`                         |
 
 === "Eiger"
+
+    !!! warning
+
+        The `Remote Installation Directory` will change if you are using a different version of the `linaro-forge` uenv.
+        Please use the appropriate version for your setup.
+
 
     | Field       | Value                                   |
     | ----------- | --------------------------------------- |
     | Connection  | `eiger`                                |
     | Host Name   | `cscsusername@ela.cscs.ch cscsusername@eiger.cscs.ch`  |
     | Remote Installation Directory | `uenv run linaro-forge/24.1.1:/user-tools -- /user-tools/env/forge/` |
+    | Private Key | `~/.ssh/cscs-key`                         |
 
 !!! tip
 
@@ -129,16 +174,16 @@ Some notes on the examples above:
 
 * SSH forwarding via `ela.cscs.ch` is used to access the cluster;
 * replace the username `cscsusername` with your CSCS user name that you would normally use to open an SSH connection to CSCS;
-* `Remote Installation Path` is pointing to the install directory of ddt inside the image;
+* `Remote Installation Directory` is pointing to the install directory of DDT inside the uenv image;
 * private keys should be the ones generated for CSCS MFA, and this field does not need to be set if you have added the key to your [SSH agent][ref-ssh-agent].
 
 Once configured, test and save the configuration:
 
-1. check whether the configuration is correct, click `Test Remote Launch`.
-2. Click on `ok` and `close` to save the configuration.
-3. You can now connect by going to `Remote Launch` and choose the `Alps` entry.
+1. check whether the configuration is correct by clicking `Test Remote Launch` (and then `OK` when the test is successful),
+2. click on `OK` and then `Close` to save the configuration.
+3. You can now connect by going to `Remote Launch` and choose the entry (`Connection` name) you added.
    If the client fails to connect, look at the error message, check your SSH
-   configuration and make sure you can ssh without the client.
+   configuration and make sure you can SSH without the client.
 
 [](){#ref-uenv-linaro-troubleshooting}
 ## Troubleshooting
@@ -149,12 +194,16 @@ Notes about known issues.
 
     If the tool fails to launch with the following error message: 
 
-        Error communicating with Licence Server velan.cscs.ch:
-        The proxy type is invalid for this operation
-        Attempting again while ignoring proxies.
+    ```
+    Error communicating with Licence Server velan.cscs.ch:
+    The proxy type is invalid for this operation
+    Attempting again while ignoring proxies.
+    ```
 
     Proxy environment variables need to be set to let the tool connect to the license server, as explained in [Compute node proxy configuration][ref-guides-internet-access].
 
 !!! note "AMD GPU support"
 
-    CSCS does not currently have a Linaro license for AMD gpus.
+    CSCS does not currently have a Linaro license for AMD GPUs.
+
+[Linaro desktop client]: https://www.linaroforge.com/downloadForge

mkdocs.yml

@@ -72,12 +72,10 @@ nav:
       - 'Python with pip': build-install/pip.md
     - 'Debugging and Performance Analysis':
       - software/devtools/index.md
-      - 'Linaro Forge uenv': software/devtools/linaro-forge.md
-      - 'Linaro MAP': software/devtools/linaro-map.md
-      - 'Linaro DDT': software/devtools/linaro-ddt.md
+      - 'Linaro uenv': software/devtools/linaro-uenv.md
+      - 'Using Linaro performance analysis tool': software/devtools/linaro-map.md
+      - 'Using Linaro debugger': software/devtools/linaro-ddt.md
       - 'NVIDIA Nsight': software/devtools/nvidia-nsight.md
-      #- 'Debugging': software/devtools/debug/index.md
-      #- 'Performance Analysis': software/devtools/perf/index.md
     - 'uenv': software/uenv.md
     - 'Container Engine': software/container-engine.md
   - 'Services':