-
Notifications
You must be signed in to change notification settings - Fork 41
Improve Linaro DDT docs #72
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Changes from 5 commits
Commits
Show all changes
14 commits
Select commit
Hold shift + click to select a range
e87da34
improve linaro ddt docs
RMeli c6cfa27
owner
RMeli ea849a2
Update docs/software/devtools/linaro/index.md
RMeli 9e397e2
uniform note
RMeli b68702d
Merge branch 'debug' of github.com:eth-cscs/cscs-docs into debug
RMeli a79363f
Update docs/software/devtools/linaro/linaro-map.md
RMeli 559819f
Update docs/software/devtools/linaro/index.md
RMeli 496506b
flatten
RMeli 8ffc371
Merge branch 'debug' of github.com:eth-cscs/cscs-docs into debug
RMeli 846e455
merge
RMeli 8cd8517
Update .github/CODEOWNERS
msimberg 67b5317
performance analysis tool
RMeli 60f75ff
owner
RMeli 8b638af
Merge branch 'debug' of github.com:eth-cscs/cscs-docs into debug
RMeli File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,6 @@ | ||
| * @bcumming @msimberg @RMeli | ||
| docs/services/firecrest @jpdorsch @ekouts | ||
| docs/software/communication @msimberg | ||
| docs/software/devtools/linaro @jpghpc | ||
| docs/software/prgenv/linalg.md @finkandreas @msimberg | ||
| docs/software/sciapps/cp2k.md @abussy @RMeli | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -3,27 +3,27 @@ | |
|
|
||
| [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. | ||
|
|
||
| !!! note | ||
| !!! note "Linaro DDT debugger and Linaro MAP profiler" | ||
| 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 profiler][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" | ||
|
|
||
| ``` | ||
| > uenv image find linaro-forge | ||
| ```console | ||
| $ uenv image find linaro-forge | ||
RMeli marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| uenv arch system id size(MB) date | ||
| linaro-forge/24.1.1:v1 gh200 daint e0e79f5c3e6a8ee0 365 2025-02-12 | ||
|
|
||
| > uenv image pull linaro-forge/24.1.1:v1 | ||
| $ uenv image pull linaro-forge/24.1.1:v1 | ||
| pulling e0e79f5c3e6a8ee0 100.00% --- 365/365 (0.00 MB/s) | ||
| ``` | ||
|
|
||
|
|
@@ -32,93 +32,138 @@ 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. | ||
|
|
||
| ```bash | ||
| > uenv start linaro-forge/14.1.1 | ||
| > source /user-tools/activate | ||
| > ddt --version | ||
| ```console | ||
| $ uenv start linaro-forge/14.1.1 | ||
| $ source /user-tools/activate | ||
| $ ddt --version | ||
| Linaro DDT Part of Linaro Forge. | ||
| Copyright (c) 2023-2024 Linaro Limited. All rights reserved. | ||
| 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 desktrop client and uenv versions" | ||
RMeli marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| 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 | `[email protected] [email protected]` | | ||
| | 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 | `[email protected] [email protected]` | | ||
| | 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 | `[email protected] [email protected]` | | ||
| | 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 | `[email protected] [email protected]` | | ||
| | 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 | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.