Copyright 2012-2017, Intel Corporation, All Rights Reserved.

This software is supplied under the terms of a license
agreement or nondisclosure agreement with Intel Corp.
and may not be copied or disclosed except in accordance
with the terms of that agreement.

================================================================================
                                    CHANGES
================================================================================

================================================================================
                                   2014-2-21
                                   MPSS-3.3
================================================================================

Moved the executable Python scripts to the base of the micp package,
and added symbolic links to /usr/bin that point to the executable
scripts.  This simplifies the installation procedure considerably.
Please note changes to /usr/share/doc/micperf-3.3/INSTALL.txt.

The windows environment variable INTEL_MPSS_HOME has replaced
INTEL_MPSS_SDK for storing the MPSS installation directory.

Fixed Linpack automatic offload executable name in windows.

micp now allows for kernels which mix short form, long form and
positional arguments as is done by POSIX getopt.

Updated stream benchmark to newest publicly available version 5.10.

Will now silently plot nothing if an attempt to plot empty data is
made.

Now only prints help documentation for offload methods that are
supported.

Added instructions to rebuild the workloads and execute with micperf
to source code section of README.


================================================================================
                                   2014-2-12
                                   MPSS-3.2
================================================================================

Now output file is created prior to application termination with
results collected so far if an exception is encountered during
micprun's execution.

Fixed link URL to composer redist package to point to the rc1 version
in the error message printed when libraries are missing.

Added code for dealing with SKU name changes (inclusion of QS and PRQ
in some SKU's).

Fixed the path to the mic configuration files stored by micpinfo to
point to the location for mpss 3.x.


================================================================================
                                   2013-7-9
                                   MPSS-3.1
================================================================================

Naming conventions for RPM's has changed: intel-mic-perf is now
micperf and intel-mic-perf-data is now micperf-data.

Paths to all files have changed in this release to conform with Linux standards.
Source code:                 /usr/src/micperf
Documentation and licenses:  /usr/share/doc/micperf-MPSSVERSION
Benchmark binaries:          /usr/libexec/micperf
Reference data:              /usr/share/micperf

Since binaries and data are located in different directories now, the
MIC_PERF_PATH environment variable no longer makes sense.  Its
functionality has been replaced with two environment variables:
MIC_PERF_EXEC and MIC_PERF_DATA.  Note that MIC_PERF_EXEC points to
the micperf libexec directory where the binary executables are located
and MIC_PERF_DATA points to the reference data directory.

With the mic driver for the Gold Update 4 release, the card side file
system that gets mounted at Intel(R) Xeon Phi(TM) boot time is not
readily accessible on the host.  The network configuration of the card
is modified with micctrl after boot (rather than modifying the file
system to be mounted before card boot time).  For this reason there is
no easy way to get the IP address of the card from a host process.  To
deal with this, micprun now takes a resolvable host name or IP address
for the -d command line option rather than simply an index that is
mapped to an IP address.  Micprun is then able to determine which
offload index this refers to.  If only an index is given, say 1, and
mic1 is not a resolvable address then micprun will use the default IP
addresses for the card: 172.31.x.1 where x is card index plus one.

User ID and SSH keys can now be controlled with the environment
variables INTEL_MPSS_USER AND INTEL_MPSS_SSH_KEY.

Linpack now scales to larger problems sizes.

All helper applications can now use the -R option to select reference
data from the installed location.


================================================================================
                                   2013-4-5
                                 Gold Update 3
================================================================================

BUG FIXES:

Now removes Linpack parameter file from host system's /tmp directory
as soon as micprun has finished using it.  Previous to this release
this file was not cleaned up and this could cause failures due to
permissions issues if two different users called micprun.  The name of
this file has also been changed so that it is unique to the process
that created it in case two users are running simultaneously.

Files now cleaned up on card in the case of an interrupt after file
transfer has begun, but before job is executed.  In previous releases
this window had not been included in the try statement.

Added new line to the end of csv file output.  In previous releases
file would terminate without a new line.

Adjusted offload builds to reflect changes in the Intel Composer XE
command line options.

Fixed potential security issues discovered in static analysis of the
shoc download and readback benchmarks.

Properly aligned table printed to stdout by shoc download and shoc
readback.

Fixed an issue where backgrounded micprun tasks that ran native
benchmarks would get a SIGSTOP signal.  This is because ssh was trying
to read from standard input during native benchmark execution.  Now
micprun can be backgrounded for all offload types.

Changed the timer in the gemm benchmark from mkl dsecnd to sys/time.h
gettimeofday.  This was done because mkl dsecnd was not cpu clock
speed invariant.

Previous to this release the standard error from the benchmark
executables was being suppressed.  This is now being printed to the
terminal.

FEATURES:

Added version number to the standard output of micpinfo.

Added "env" to the micpinfo command set.

Added parser to stream and Linpack that will raise exceptions if self
check does not pass.  The benchmarks print a message, but give a zero
return code in the case where self check fails, now micprun will give
a non-zero return code in this case.

Feature added to micprun to allow for add on kernel packages.  This is
the -e flag and is documented in micprun --help.

Added backwards compatibility to allow user to load reference files
created by a micperf older than gold u1 if symbolic links to old
modules are made. To create these symbolic links run the following set
of commands:
    pushd /opt/intel/mic/perf/micp/micp
    for mod in common info kernel offload params run stats
    do sudo ln -s ${mod}.py micp_${mod}.py; done
    popd

Changed test for correct card IP address to require that password-less
ssh is enabled and that "ssh IPADDRESS uname -a | grep k1om" gives a
zero return code.  Also clean up the error message printed in the case
where this test fails.

Added an option to micpcsv output to create a single table for all
data by putting all parameters into a single field.  This is accessed
with the --short or -s options to micpcsv.

Now including INSTALL.txt with the python package in addition to putting
it in /opt/intel/mic/perf/docs.

MPSS license is no longer distributed with micperf.  The MPSS license
still applies to micperf (a.k.a. The OEM Workload Package), but now
the the path to the license is referenced in the python package
(/opt/intel/mic/LICENSE/license.txt) instead including the file.

The optimal category for stream now tries number of cores minus ten
through number of cores threads to search for highest performance from
stream.

Shortened the "long description" in the python package to the include
just the introduction from README.txt.

Integrated changes to python scripts for windows port, although we are
not releasing a windows port with Gold Update 3.


================================================================================
                                   2013-1-31
                                 Gold Update 2
================================================================================
Python source distribution is now installed to
"/opt/intel/mic/perf/micp" not
"/opt/intel/micp/perf/micp-VERSION"

Created an INSTALL.txt and removed installation instructions from the
README.txt.

Cleaned up help messages for micp scripts.  micpinfo got a significant
overhaul.  All micp scripts now use the getopt module for command line
parameter parsing and have more robust checking of input.

Now piping python ERROR and WARNING messages to standard error.

Updated SHOC benchmark to transfer larger payloads, display latency
information, aligned memory to 2MB boundaries and free up memory at
end of execution.

Return codes for micprun have changed.  Used to always return -1 on
failure, but now there are several handled exceptions that cause
different return codes.  In particular, if the workload process
returns a non-zero return code this code is also returned by micprun.
The return codes are documented in micprun's help message.  The
function micp.run.run() no longer has a return value, but rather
raises exceptions which are caught by micprun.  Stack trace has been
suppressed by micprun for common known errors.

Added a few different attempts to get the ip address of the card.
First it looks for it in the ifcfg on the card image (this used to be
the only way the address was found), if that fails it looks in
/etc/hosts, if that fails it looks miccfg.

Added documentation about how to download publically released MKL
Linpack benchmark package when the Linpack binary is not found.

Filter tag to exclude non-alphanumeric characters and replace them
with the dash character.

Removed "confidential" watermarks from the plots.

micinfo errors out for non-existent --app requests instead of failing
silently.

More robust error messages.

Better code documentation especially in kernel.py and offload.py.

Removed trailing white space in python source files.

Some clean up of micp library interfaces.

Added check to make sure that setup.py is run in the correct
directory.

Removed unused source files from SHOC benchmark and unused option in
pragma version.

Added user input checking for gemm benchmark.


================================================================================
                                   2012-12-4
                     Gold Update and Integration into MPSS
================================================================================
WARNING: With this release several externally facing interfaces have
changed, and the installation procedure is significantly different.

Distributed as two Redhat Package Manager (RPM) files which install to
"/opt/intel/mic/perf".  These files are called "intel-mic-perf*.rpm"
and "intel-mic-perf-data*.rpm".  The reference data stored in pickle
file form is distributed in the "intel-mic-perf-data*.rpm".

Uses standard Python packaging system for distribution of python
automation infrastructure.  The rpm installs a source distribution of
the package called micp (formerly within the micperf/automation
folder) into "/opt/intel/mic/perf/micp-VERSION".

There are instructions in the README.txt in the "Setup" section on how
to incorporate the scripts (like micprun) into your environment.

Changed the names specified for the -k parameter (kernels):
sgemm_mkl -> sgemm
dgemm_mkl -> dgemm
linpack_dp -> linpack
stream_mccalpin -> stream

MKL SMP Linpack binary no longer distributed with the package.  Now in
order to run the Linpack benchmark Intel (R) Composer XE must be
installed and the compilervars script must be sourced.

Changed the default tag to include the MIC card SKU in place of the
hardware hash.

Significantly extended command line --help documentation to supporting
micp applications: micpcsv, micpplot, micpprint, micpinfo.

Added --version command line option to micprun.

Default parameter values for the micprun -p option are now the optimal
values, so now calling:
  micprun -k dgemm -p ' '
is equivalent to calling
  micprun -k dgemm


