================================================================================
 Intel(R) Xeon Phi(TM) Coprocessor Performance Workloads:  micp
================================================================================
Micperf Version:  3.1 for Windows
MPSS Version:  3.1 for Windows

Disclaimer and Legal Information:

INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH INTEL PRODUCTS.
NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL
PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT. EXCEPT AS PROVIDED IN INTEL'S
TERMS AND CONDITIONS OF SALE FOR SUCH PRODUCTS, INTEL ASSUMES NO LIABILITY
WHATSOEVER AND INTEL DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO
SALE AND/OR USE OF INTEL PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING
TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY
PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT.

A "Mission Critical Application" is any application in which failure of the
Intel Product could result, directly or indirectly, in personal injury or
death. SHOULD YOU PURCHASE OR USE INTEL'S PRODUCTS FOR ANY SUCH MISSION
CRITICAL APPLICATION, YOU SHALL INDEMNIFY AND HOLD INTEL AND ITS SUBSIDIARIES,
SUBCONTRACTORS AND AFFILIATES, AND THE DIRECTORS, OFFICERS, AND EMPLOYEES OF
EACH, HARMLESS AGAINST ALL CLAIMS COSTS, DAMAGES, AND EXPENSES AND REASONABLE
ATTORNEYS' FEES ARISING OUT OF, DIRECTLY OR INDIRECTLY, ANY CLAIM OF PRODUCT
LIABILITY, PERSONAL INJURY, OR DEATH ARISING IN ANY WAY OUT OF SUCH MISSION
CRITICAL APPLICATION, WHETHER OR NOT INTEL OR ITS SUBCONTRACTOR WAS NEGLIGENT
IN THE DESIGN, MANUFACTURE, OR WARNING OF THE INTEL PRODUCT OR ANY OF ITS
PARTS.

Intel may make changes to specifications and product descriptions at any time,
without notice. Designers must not rely on the absence or characteristics of
any features or instructions marked "reserved" or "undefined". Intel reserves
these for future definition and shall have no responsibility whatsoever for
conflicts or incompatibilities arising from future changes to them. The
information here is subject to change without notice. Do not finalize a design
with this information.

The products described in this document may contain design defects or errors
known as errata which may cause the product to deviate from published
specifications. Current characterized errata are available on request.

Contact your local Intel sales office or your distributor to obtain the latest
specifications and before placing your product order.

Copies of documents which have an order number and are referenced in this
document, or other Intel literature, may be obtained by calling
1-800-548-4725, or go to: http://www.intel.com/design/literature.htm

Intel's compilers may or may not optimize to the same degree for non-Intel
microprocessors for optimizations that are not unique to Intel
microprocessors. These optimizations include SSE2, SSE3, and SSE3 instruction
sets and other optimizations. Intel does not guarantee the availability,
functionality, or effectiveness of any optimization on microprocessors not
manufactured by Intel.

Microprocessor-dependent optimizations in this product are intended for use
with Intel microprocessors. Certain optimizations not specific to Intel
microarchitecture are reserved for Intel microprocessors. Please refer to the
applicable product User and Reference Guides for more information regarding
the specific instruction sets covered by this notice.

Notice revision #20110804

Intel, the Intel logo, Intel Xeon, and Intel Xeon Phi are trademarks of
Intel Corporation in the U.S. and/or other countries.

*Other names and brands may be claimed as the property of others.

Copyright (C) 2013 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.

================================================================================

Introduction
---------------------

This README describes the setup for micperf and the micp run
infrastructure for Windows.  The README content corresponds with the
Intel Manycore Platform Software Stack 3.1 Release for Windows.


What is micperf?
---------------------

micperf is a collection of binaries that demonstrate performance for a
handful of Intel Xeon Phi enabled offload workloads.

	
What is micp?
---------------------

micp is a set of python scripts that provide a run environment for
micperf, and potentially similar Intel Xeon Phi workloads. It is
intended to help with performance data tracking and comparison.  It's
highly recommended to run micperf through micp.

	
Requirements for micperf
---------------------
        -Windows 7 x64 or Windows Server 2008 R2 x64

        -Intel Xeon Phi Co-processor

        -Visual Studio 2012 C++ Runtime Installed. The redistributable
         is available from Microsoft:
         http://www.microsoft.com/en-us/download/details.aspx?id=30679

        -Manycore Platform Software Stack (MPSS) 3.1 for Windows

        -Installation of the Intel(R) Xeon Phi(TM) coprocessor essentials msi file. 

        -PuTTY tools plink.exe and pscp.exe must be installed to a
         directory in your path, e.g. C:\Program Files\Intel\MPSS\bin:
         http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html
		 
	-Intel Composer 14.0 offload runtimes:
         http://software.intel.com/en-us/articles/redistributable-libraries-for-intel-c-and-visual-fortran-composer-xe-2013-for-windows
	 NOTE:  As of 8/29/13 not yet publically distributed.  


Requirements for micp
----------------------
	-Python 2.7 for Windows x64:
         http://www.python.org/ftp/python/2.7.5/python-2.7.5.amd64.msi

        -Numpy, a run-time requirement for matplotlib:
         http://sourceforge.net/projects/numpy/files/NumPy/1.7.1/numpy-1.7.1-win32-superpack-python2.7.exe/download

        -The python package matplotlib to enable plotting:
         https://downloads.sourceforge.net/project/matplotlib/matplotlib/matplotlib-1.2.1/matplotlib-1.2.1.win-amd64-py2.7.exe
		 
	-The python intepreter must also be added to your path. An
         explanation on how to find the interpreter and add it to your
         path is here:
         http://docs.python.org/2/using/windows.html#finding-the-python-executable

    The micperf and micp were built and tested against MPSS 3.1 for
    Windows


Installing the micp scripts
------------------------

From the command prompt run: 

pushd C:\ProgramFiles\Intel\MPSS\sdk\micperf\micp
python setup.py install
popd

This will situate the micp python scripts appropriately. Next add
C:\Python27\Scripts to your path.  Assuming the default installation
of Python associated file extensions, you should be able to run any of
the micp*.py scripts documented in this README in a shell.  To get
started run:

micprun.py --help

SSH Setup
------------------------
    The micp run scripts use ssh keys for offloading and executing the micperf test content.
	See the MPSS setup guide pdf for more details on generating authorized keys.
	Set the environment variable INTEL_MPSS_USER to the eligible MICUSER you wish to use, e.g. micuser. 
	Set the environment variable INTEL_MPSS_SSH_KEY to the user's corresponding ssh key.
    By default the INTEL_MPSS_USER is the name of
    the Windows user running the micp command, and the
    INTEL_MPSS_SSH_KEY defaults to:

    C:\Program Files\Intel\MPSS\bin\id_rsa.ppk

    Do not include quotes around the path when setting the
    INTEL_MPSS_SSH_KEY, and be sure to use a full absolute path.
    
    To set environment variables in Windows use "set" the command for
    current shell session variables.  To manipulate global user or
    system variables use the "setx" command or alternatively use the
    "Advanced system settings" in

    Control Panel\All Control Panel Items\System

    and click on the "Environment Variables" button.  The help for "set"
    and "setx" can be accessed by passing these commands the /? flag.


COI logging
------------------
    Our recommendation is to disable COI's debug logging feature by
    setting the environment variable COI_SEP_DISABLE to the value
    TRUE.  This will avoid creating COI log files next to the executables.  

	
Running micp
------------------
    Please ensure the Intel Xeon Phi device is booted with 'micctrl --start'
    before running micp. Ensure the Intel Xeon Phi device status is online. See the 
    
    There are five executable scripts distributed with micp:

    micprun.py
    micpinfo.py
    micpcsv.py
    micpprint.py
    micpplot.py

    Each of these scripts accepts the --help flag to print it's
    documentation.
    
    micprun.py:

		The micprun.py script is used to execute the benchmarks.  In
		simple use, micprun.py executes the benchmark and displays the
		standard output from that benchmark.  In its most elaborate use,
		micprun.py repeats a sequence of runs of a benchmark suite
		previously executed by the performance validation team at Intel,
		and then compares the results to the Intel reference data.  In
		this mode, micprun.py returns a non-zero return code if a
		performance regression is detected, and displays gtest styled
		pass/fail output.

		If an output directory is specified during execution, micprun.py
		will produce pickle files containing data collected during the
		run.  Use the micpprint.py, micpcsv.py, micpplot.py, and
		micpinfo.py applications to inspect the pickle files.

	micpprint.py:

		The micpprint.py application prints the performance measurements
		from data stored in one or more pickle files.

	micpplot.py:

		The micpplot.py application plots the performance statistics from
		one or more runs, from pickle files produced during the run.

	micpinfo.py:

		The micpinfo.py application obtains and displays system
		information. When run without parameters, micpinfo.py displays
		information about the current system.  When run with a pickle
		file, it displays information about the system that created the
		pickle file.

	micpcsv.py:

		The micpcsv.py application extracts the performance data from a
		pickle file and prints it to standard output in comma separated
		value (CSV) format.  If it is run without specifying a pickle
		file, micpcsv.py prints a table summarizing the results in the
		reference data included in the distribution.  If an output
		directory is specified with the -o parameter, then a set of csv
		files is created.


Example micperf source
------------------------------
    The source code used to build micperf for Windows is located by default in C:\Program Files\Intel\MPSS\sdk\tutorials\micperf. 
	The included solution file is configured to build Windows x64 host binaries, Intel Composer 14.0 Offload Runtime executables, and native Intel Xeon Phi executables. 
	The Intel Composer 14.0 compiler tools, which are enabled to target Intel Many Integrated Core (MIC) architecture in Windows, must be installed in order to build the offload runtime and native executables. See the Intel Composer 14.0 setup instructions for ensuring the development environment is setup properly.
	
	
micperf test content
------------------------------

    Binary files are installed to:

    %INTEL_MPSS_HOST_SDK%\micperf\libexec.  

    These files are executed by the micprun.py script, but can also be
    executed independently.

    Intel Composer 14.0 Offload Runtime stand-alone executables:
        BusSpeedDownload_pragma.exe
        BusSpeedReadback_pragma.exe
        dgemm_ofl.x.exe
        sgemm_ofl.x.exe

    Intel Xeon Phi Co-processor native stand-alone executables (Intel MIC architecture):
        dgemm_mic.x
        sgemm_mic.x
        stream_mic

    Host SCIF-based executables (Windows x64):
        BusSpeedDownload_scif.exe
        BusSpeedReadback_scif.exe

    Intel Xeon Phi Co-processor SCIF-based native executables (Intel MIC architecture):
        BusSpeed_mic




Last Updated 20130816
