Command line arguments

Here are a number of command line arguments to use with Linaro MAP.

--capture-environment-variables

Capture the environment variables of the profiled application in the Linaro MAP Program details dialog.

Note

Enabling --capture-environment-variables will capture all variables for your applications environment and store them in the Linaro MAP file. For security reasons, consider what information is stored in the environment before enabling this option.

--no-mpi

Run Linaro MAP with one process and without invoking mpirun, mpiexec, or equivalent.

--queue

Force Linaro MAP to submit the job to the queuing system.

--no-queue

Run Linaro MAP without submitting the job to the queuing system.

--view=<view>

Start Linaro MAP using the specified initial view mode (see Main-thread, OpenMP, and Thread view modes). This must be one of (main|openmp|pthread). If the selected view is not available, the main view will be displayed.

--export=<output.json>

Export an input .map file to output.json in JSON format, without user interaction. e.g.:

map --export=output.json input.map

For the format specification see JSON format.

--profile

Generate an Linaro MAP profile but without user interaction. This will not display the Linaro MAP user interface. Messages are printed to the standard output and error. The job is not run using the queuing system unless used in conjunction with --queue. When the job finishes a map file is written and its name is printed.

--export-functions=<file>

Export all the profiled functions to <file>. Use this in conjunction with --profile. The output should be CSV file name. For example, --profile --export-functions=foo.csv ...

Note

Exported functions will be from Main Thread Only view mode.

--select-ranks=<ranks>

Only collect profiling data from the specified set of ranks. <ranks> is a comma separated list of ranks and/or rank ranges. Example 5,6-10.

--start-after=<time>

Start profiling <time> seconds after the start of your program. Use this in conjunction with --stop-after to focus Linaro MAP on a particular time interval of the run of your program.

--stop-after=<time>

Stop profiling <time> seconds after the start of your program. This will terminate your program and proceed to gather the samples taken after the time given has elapsed. Use this in conjunction with --start-after to focus Linaro MAP on a particular time interval of the run of your program.

--enable-metrics=<metrics>, --disable-metrics=<metrics>

Allows you to specify comma-separated lists which explicitly enable or disable metrics for which data is to be collected. If the metrics specified cannot be found, or if a metric is both enabled and disabled, an error message is displayed and Linaro MAP exits.

Metrics which are always enabled or disabled cannot be explicitly disabled or enabled, respectively. A metrics source library which has all its metrics disabled, either in the XML definition or via --disable-metrics, will not be loaded.

Metrics which can be explicitly enabled or disabled can be listed using the --list-metrics option. The enabled/disabled metrics settings do not persist when running Linaro MAP without the user interface, so they will need to be specified for each profiling session. When running Linaro MAP in user interface mode, the effect of these settings will be displayed in the Metrics section of the Run dialog, where you can further refine the settings. These settings will then persist to the next user interface session.

--list-metrics

Lists the metric IDs which can be explicitly enabled or disabled using --enable-metrics and --disable-metrics.

--cuda-kernel-analysis

Enables CUDA kernel analysis mode, providing line level profiling information on CUDA kernels running on a NVIDIA GPU at the cost of potentially significant overhead. See CUDA Kernel analysis.

--cuda-transfer-analysis

Enables CUDA transfer analysis mode, providing insights into the memory transfers managed via CUDA. See Memory transfers analysis.

--report=<types>

Generate a report in addition to the standard .map file when using --profile. <types> is a either a comma separated list of one or more from (txt|csv|html|summary), or none.

For txt, csv and html a Linaro Performance Reports file of the corresponding format and file extension will be created using the same base file name as the .map file that is generated.

summary prints a minimal summary report to the standard output. This is the default behavior if no --report option is provided.

none (mutually exclusive with all other <type> values) blocks the creation of any type of report other than the .map file, slightly reducing Linaro MAP’s post-processing time.

To generate a report from an existing .map file, See Summarize an existing MAP file.

--spe=<type>

For Arm®v8.2 or greater targets implementing the option Arm Statistical Profiling Extension (SPE) this option enables gathering the specified type of SPE events. <type> may be one of (cache|mispredict|tlb|sve-predicate). See Arm Statistical Profiling Extension (SPE).

--perf-metrics=<file>

Defines one or more Linux perf event counters to sample when profiling. These will be displayed as metric graphs by Linaro MAP and report lines within Linaro Performance Reports. Often used along with --target-host. See Specify Perf metrics using a file and Specify Perf metrics using the command line.

--target-host=<hostname>

Specifies the intended CPU from which perf-metrics are to be acquired as described by an accompanying --perf-metrics argument. The known CPU types can be listed with --target-host=list`. CPUs may be added to this list by using the ``forge-probe utility, see Probe target hosts.

--build-directories=PATH1[:PATH2]

Colon delimited list of build directories to search for compiler optimization reports.

--embed-compiler-remarks

Embed compiler remarks into the generated .map file.

--exclude-compiler-remarks=TYPE1[,TYPE2,...]

Comma delimited list of remark types or optimization passes to exclude from embedding into the .map file. Types include Failed, Success, or Information. Optimization passes are compiler-specific.

When running without the user interface, normal redirection syntax can be used to read data from a file as a source for the executable’s standard input.

Examples:

cat <input-file> | map --profile ...
map --profile ... < <input-file>

Normal redirection can also be used to write data to a file from the executable’s standard output:

map --profile ... > <output-file>

For OpenMP jobs, simply use the OMP_NUM_THREADS environment variable (or leave it blank) exactly as you usually would when running your program. There is no need to pass the number of threads to Linaro MAP as an argument.

OMP_NUM_THREADS=8 map --profile ... > <output-file>