Intel® Integrated Performance Primitives (Intel® IPP) Developer Guide and Reference
Performance Test Tool (perfsys) Command Line Options
Intel® Integrated Performance Primitives (Intel® IPP) installation includes command-line tools for performance testing in the <install_dir>/tools/intel64/perfsys directory. There is one perfsys tool for each domain. For example, ps_ipps executable measures performance for all Intel IPP signal processing domain functions. Before running the tools, set the environment as described in Setting Environment Variables.
Many factors may affect Intel IPP performance. One of the best way to understand them is to run multiple tests in the specific environment you are targeting for optimization. The purpose of the perfsys tools is to simplify performance experiments and empower developers with useful information to get the best performance from Intel IPP functions.
With the command-line options you can:
Create a list of functions to test
Set parameters for each function
Set image/buffer sizes
To simplify re-running specific tests, you can define the functions and parameters in the initialization file, or enter them directly from the console.
The command-line format is:
ps_ipp*.exe [option_1] [option_2] ... [option_n]
To invoke the short reference for the command-line options, use -? or -h commands:
ps_ipp*.exe -h
The command-line options are divided into several groups by functionality. You can enter options in arbitrary order with at least one space between each option name. Some options (like -r, -R, -o, -O) may be entered several times with different file names, and option -f may be entered several times with different function patterns. For detailed descriptions of the perfsys command-line options see the following table:
Option |
Description |
-T[cpu-features] |
Call ippSetCpuFeatures. Options: Y8 (SSE4.2), L9 (AVX2), K0 (AVX512), D1 (AVX10.2). |
-A<Timing|Params|Misalign|All> |
Set detail level of the console input: prompt for the timing method, the common parameters, and the data misalignment at the start of the session. With All, prompt for the parameters of every test as well. If the option is specified without a mode, All is used |
-B |
Batch mode: never prompt for anything from console. If neither -A nor -B is specified, the tool behaves as with -ATimingParams and waits for the console input |
-o[ <file-name> ] |
Create <file-name>.txt file and write console output to it |
-O[ <file-name> ] |
Add console output to the file <file-name>.txt |
-L<ERR|WARN|PERF|INFO|TRACE|MEM|DATA> |
Set detail level of the console output. Several levels may be combined; only the first letter of each level name is significant |
-r[ <file-name> ] |
Create <file-name>.csv file and write perfsys results to it |
-R[ <file-name> ] |
Add test results to the file <file-name>.csv |
-q[<file-name>] |
Create <file-name>_name.csv and write function parameter name lines to it |
-q+ |
Add function parameter name lines to perfsys results table file |
-Q |
Exit after creation of the function parameter name table |
-u[ <file-name> ] |
Create <file-name>_sum.csv file and write summary table to it (’_sum’ is added to the file name) |
-U[ <file-name> ] |
Add summary table to the file <file-name>_sum.csv |
-g[ <file-name> ] |
Create signal file at the end of the whole testing |
-l <dir-name> |
Set default directory for output files |
-k<and|or> |
Compose different keys (-f, -t, -m) by logical operation |
-F <func-name> |
Start testing from function with func-name full name |
-Y <HIGH/NORMAL> |
Set high or normal process priority (normal is default) |
-H[ONLY] |
Add ‘Interest’ column to .csv file [and run only hot tests] |
-N <num-threads> |
Call ippSetNumThreads_LT(<num-threads>) |
-c[ <num-ms> ] |
Set the minimal duration of a single measurement, in milliseconds |
-j[ <min-loops> ] |
Set the minimal number of the measurement loops |
-J[ <min-loops> ] |
Set the number of the external measurement loops |
-W |
Unmask floating-point exceptions |
-s[-] |
Sort or do not sort functions (sort mode is default) |
-e |
Enumerate tests and exit |
-v |
Display the version number of the perfsys and exit |
-@<file-name> |
Read command-line options from the specified file |
-d<name>=<value> |
Set perfsys parameter value |
-i[ <file-name> ] |
Read perfsys parameters from the file <file-name>.ini |
-I[ <file-name> ] |
Write perfsys parameters to the file <file-name>.ini and exit |
-P |
Read tested function names from the .ini file |
-n <title-name> |
Set default title name for .ini file and output files |
-p <dir-name> |
Set default directory for .ini file and input test data files |
-f <or-pattern> |
Run tests for functions with pattern in their names, case sensitive |
-f- <not-pattern> |
Do not test functions with pattern in their names, case sensitive |
-f+ <and-pattern> |
Run tests only for functions with pattern in their names, case sensitive |
-f= <eq-pattern> |
Run tests for functions with pattern full name |
-t[-|+|=] <pattern> |
Run (do not run) tests with pattern in test name |
-m[-|+|=] <pattern> |
Run (do not run) tests registered in file with pattern in file name |
-h |
Display short help and exit |
-hh |
Display extended help and exit |
-h<key> |
Display extended help for the key and exit |
-?, -??, -?<key> |
The same as -h, -hh, and -h<key>, but list the hidden options as well |
Performance Results File Format
The -r and -R options write the measurement results to a comma-separated (.csv) file. The file starts with a header that describes the environment: the processor, the operating system, the computer name, the version of every loaded Intel IPP library, and the start time of the session. The header is followed by one line per test. The result files are large, so restrict the set of the tested functions with the -f and -t options. Related files that perfsys can produce next to it are <file-name>_name.csv (-q, function parameter names) and <file-name>_sum.csv (-u, -U, summary table).
Each test line contains the function name, the values of the function parameters, and the following result columns. The signal processing domain reports the name in a single function column, while the image domains split it into the funcBase, funcDataType, and funcDescriptor columns.
Column |
Description |
|---|---|
Comment |
Cache state of the test data, deprecated mark, and other test remarks |
Clocks |
Measured number of CPU clocks, divided by the amount of data given in the per column |
per |
Measurement unit for the Clocks column, see the table below |
Time (usec) |
Total execution time of one function call, in microseconds |
MFlops |
Millions of floating-point operations per second; reported for floating-point functions only, the cell is empty for the other functions |
Interest |
Present only with the -H option; contains Hot for the tests of the highest interest |
The Clocks column is normalized, so its value does not depend on the data size and can be compared across tests of the same function. The lower the value, the better the performance. The per column tells which amount of data one clock count refers to:
Unit |
Meaning |
|---|---|
(empty) |
Clocks per function call; the result is not normalized |
e |
Clocks per vector element: clocks/len |
px |
Clocks per pixel: clocks/(width*height) |
pxch |
Clocks per pixel channel: clocks/(width*height*channels) |
byte |
Clocks per byte of the input data |
cpMac |
Clocks per multiply-accumulate operation: clocks/(vectorLen*filterLen) |
e_kp, e_krnPnt |
Clocks per vector element and kernel point: clocks/(len*kernelLen) |
px_kp |
Reserved: clocks per pixel and kernel point, clocks/(width*height*kw*kh), where kw and kh are the kernel width and height |
pxch_kp |
Reserved: clocks per pixel channel and kernel point, clocks/(width*height*kw*kh*channels) |
The unit is chosen by the test itself, so different functions of the same domain may report different units. Functions that process an image channel-by-channel typically use pxch, while functions that process all channels at once, such as color conversion, use px. Filter, convolution, and correlation functions of the signal processing domain use cpMac, because their cost is proportional to the product of the signal and the filter length.
Measurement Accuracy
The results are valid for the processor of the system the tests run on, and they are sensitive to normal system activities such as CPU power state transitions and background task activity. To get the results that can be compared across multiple runs, perform the measurements on a system with Intel® Turbo Boost Technology and C-state transitions disabled, and with all the background tasks stopped. Running without these settings may produce console warnings about the variability of the output data.
Some tests consume a large amount of memory. If you get the memory error: can't allocate <N> bytes message, make sure the system has enough available memory, or exclude the tests that produce the error with the -f- option.
Use the -B option for the unattended runs: without it the tool prompts for the timing method and the common parameters from the console.