Intel(R) Manycore Platform Software Stack (Intel(R) MPSS)

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

Intel(R) MPSS 3.4 Software Release
Driver Revision: 3.4-1
Flash Revision: 2.1.02.0390
SMC Firmware Version: 1.16.5078
SMC Boot Loader Version: 1.8.4326
Coprocessor OS Version: 2.6.38.8+mpss3.4

September 18, 2014

Part Number:  Intel(R) Xeon Phi(TM) MPSS 3.4 README
Export Compliance: ECCN = 5D992a; ECCN = EAR99

Notes:
  o This document pertains to systems containing Intel(R) Xeon Phi(TM) 
    coprocessor.
  o Detailed configuration information and procedures appear in the 
    Intel(R) MPSS User's Guide (MPSS_Users_Guide.pdf).
  o In this document, lines preceded by: 
	- "[host]$" at the beginning of a line denotes a command entered on the
	            host with user privileges.
	- "[host]#" at the beginning of a line denotes a command entered on the host
 	      	    administrative (root) privileges.
	
DISCLAIMER:

This document makes reference to products developed by Intel. This section 
highlights restrictions on how these products may be used, and what 
information may be disclosed to others. Contact your Intel field representative
for more information.

Intel is making no claims of usability, efficacy or warranty. The license.txt 
contained herein completely defines the license and use of this software except
in the cases of the GPL components. This document contains information on 
products in the design phase of development. The information here is subject 
to change without notice. Do not finalize a design with this information.

The code contained in these modules may be specific to the Intel(R) Xeon Phi(TM)
coprocessor and is not backward compatible with other Intel(R) products.
Additionally, Intel makes no commitments for support of the code or instruction
set in future products.

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


===============================================================================
 Table of Contents
===============================================================================
  1.   Overview
  1.1  Software Revision Numbers  
  2.   Installing Intel(R) MPSS
  2.1  Requirements
  2.2  Steps to Install Intel(R) MPSS
  2.3  Steps to Uninstall Intel(R) MPSS  
  2.4  Intel(R) Xeon Phi(TM) Coprocessor Flash & SMC Update
  2.5  SSH Access and Configuration for the Intel(R) Xeon Phi(TM) Coprocessor
  2.6  Enable Large Base Address Registers Support (BAR) in the platform BIOS

===============================================================================
1.  Overview
===============================================================================

This README is for the Intel(R) Manycore Platform Software Stack (Intel(R) MPSS)
build revision 3.4.

Intel(R) MPSS 3.4 encompasses the Linux* driver and supporting tools from 
gold_update_3 forward.

1.1  Software Revision Numbers

The revision numbers of the Intel(R) MPSS 3.4 Linux* Package software 
components are listed below:

Intel(R) MPSS 3.4 Linux* host Driver and run time: 
3.4

===============================================================================
2.  Installing Intel(R) MPSS
===============================================================================

Note:
  o The build process creates an empty directory /home/root on the file
    system. Please do not use this directory. Micctrl will create the root 
    entry with root's home at /root and place root's ssh keys in /root/.ssh.

2.1 Requirements

  1) Super-user privileges are required to install the Intel(R) MPSS 3.4
     release.

  2) Valid SSH keys are required for users (including "root" user) that need
     SSH access to each Intel(R) Xeon Phi(TM) coprocessor. To set SSH access,
     see Section 2.5, "SSH Access and Configuration for the Intel(R) Xeon Phi(TM)
     Coprocessor".

  3) Supported hardware platform with at least one Intel(R) Xeon Phi(TM)
     coprocessor installed.

  4) Linux* host operating system (default configuration).
 ________________________________________________________________
|                                       |                       |
| Supported Host OS Versions            | Kernel Version        |
|---------------------------------------|-----------------------|
| Red Hat* Enterprise Linux* 64-bit 6.3 | 2.6.32-279            |
|---------------------------------------|-----------------------|
| Red Hat* Enterprise Linux* 64-bit 6.4 | 2.6.32-358            |
|---------------------------------------|-----------------------|
| Red Hat* Enterprise Linux* 64-bit 6.5 | 2.6.32-431            |
|---------------------------------------|-----------------------|
| Red Hat* Enterprise Linux* 64-bit 7.0 | 3.10.0-123            |
|---------------------------------------|-----------------------|
| SUSE* Linux* Enterprise Server 11 SP2 | 3.0.13-0.27-default   |
|---------------------------------------|-----------------------|
| SUSE* Linux* Enterprise Server 11 SP3 | 3.0.76-0.11-default   |
|_______________________________________|_______________________|

    
WARNING: Host OS kernel updates beyond the "officially supported" initial 
release versions specified in the table above, may prevent the pre-built 
Intel(R) MPSS 3.4 driver modules from loading.  Most Linux distributions 
provide minor kernel updates and patches.  To ensure compatibility,      
disable kernel updates on your host OS.                                  
                                                                              
If the host system must run with an updated kernel, use the following    
steps to re-build the MPSS modules for the updated kernel version prior   
to installing MPSS.  If using Infiniband as an interconnect, refer to    
section 9.1 of the MPSS User's guide, "Recompiling the Intel(R) MPSS    
RPM specifically for OFED".                                              
                                                                              
  O To recompile the MPSS host kernel modules:                            
    1) Ensure the prerequisites are installed:                           
       a. For Red Hat* Enterprise Linux                                  
          [host]#  yum install kernel-headers kernel-devel                
       b. For SUSE* Linux Enterprise Server                              
          [host]# zypper install kernel-default-devel rpm                
                                                                              
    2) Regenerate the Intel(R) MPSS driver module package:               
          [host]$  cd <path to extracted MPSS-3.x.-Linux.tar>/src/        
          [host]$  rpmbuild --rebuild mpss-modules-*.rpm                  
                                                                              
    3) The newly built mpss-modules and mpss-modules-dev rpms will be    
       located at:                                                       
       a. Red Hat* Enterprise Linux                                      
          $HOME/rpmbuild/RPMS/x86_64/                                    
       b. SUSE* Linux Enterprise Server                                  
          /usr/src/packages/RPMS/x86_64/                                 
                                                                              
    4) Copy the re-built mpss-modules and mpss-modules-dev RPMs from the 
       respective directory specified in step 3 into the /modules        
       directory of the extracted MPSS tar file. Continue to section 2.2 
       to install MPSS.                                                  
      
2.2  Steps to Install Intel(R) MPSS

Note:
  o In SUSE*, entering "sudo micctrl --<option>", will return the message 
    "command not found." If using sudo, the full path of the command is 
     required (or run as root):
        [host]# /usr/sbin/micctrl --<option>

    Add /usr/sbin and /sbin to the path to avoid entering the full path of 
    the command:
        export PATH=$PATH:/usr/sbin:/sbin

    Optionally, add /usr/sbin and /sbin to the user's .bashrc file to eliminate
    the need to set the path in each session.

Steps:
  1) Remove any previous installations of Intel(R) MPSS. Refer to Section 2.3.
     To check for previous installed version of Intel(R) MPSS package:
            [host]# rpm -qa | grep -e intel-mic -e mpss

     *Note: Both yum and zypper support software upgrades and downgrades. 
            However, it is necessary that Intel(R) MPSS upgrades and downgrades 
            be carried out by complete uninstallation of existing software 
            followed by a clean installation of the replacement software. 
            Section 2.3 describes uninstalls.

  2) Disarm Module security policies:
	a) The SUSE* Linux* Enterprise Server release requires setting the kernel
	to allow non-SUSE* driver modules to be loaded. Edit the file "/etc/modprobe.d
	unsupported -modules" and set the value of "allow_unsupported_modules" to 1. 

	b) If SELinux is installed, disable SELinux before installing Intel(R) MPSS
 	software, to prevent SELinux from overriding standard Linux* permissions settings. 

  3) Download the Linux tar file for this release,
     then untar and install the Intel(R) MPSS package.
            [host]$ tar xvf mpss-3.4-linux.tar

     *Note: At this point a "modules" directory is created containing all 
            kernel specific modules.         

            [host]$ cd mpss-3.4
            [host]$ cp ./modules/*`uname -r`*.rpm .
       
        o Red Hat* Enterprise Linux* 
            [host]# yum install *.rpm

        o SUSE* Linux* Enterprise Server
            [host]# zypper install *.rpm
     
     *Note: yum and zypper are the recommended tools for installing MPSS RPMs.

     *Note: MPSS packages are not GPG signed. If local package GPG check
            (localpkg_gpgcheck) is enabled in yum.conf, the --nogpgcheck option 
            must be used:
            [host]# yum install --nogpgcheck *.rpm

  4) Load the mic.ko driver, and then initialize MPSS Default Settings.
            [host]# modprobe mic
            [host]# micctrl --initdefaults

  4b) Configure MPSS Via .conf Files (optional).
        o The MPSS_Users_Guide.pdf document explains in detail
          how to modify Intel(R) MPSS configuration files.
           
  5) Update Flash & SMC (see Section 2.4). Flash and SMC updates to versions 
     specified in this release are required.

  6) Start Intel(R) MPSS by using the Linux* service command:
         RHEL 6.x and SUSE
            [host]# service mpss start
         RHEL 7.x
            [host]# systemctl start mpss

	 RHEL 6.x and SUSE
        o To configure the Intel(R) MPSS service to start when the host OS boots:
            [host]# chkconfig mpss on

        o To disable the Intel(R) MPSS service to start when the host OS boots:
            [host]# chkconfig mpss off

	 RHEL 7.x, 
	o To enable or disable service start on boot, the command is: 
            [host]# systemctl enable mpss
            [host]# systemctl disable mpss

2.3  Steps to Uninstall Intel(R) MPSS

Note: The uninstall script will not uninstall rebuilt drivers. You must remove them
      manually before running the uninstall.sh script.
      On RedHat: [host]$yum remove <name of rebuilt package rpm>
      On SUSE Linux: [host]$ zypper remove <name of rebuilt package rpm>

  o To uninstall 3.x-based builds:

     1) Unload the MPSS driver using:
        RHEL 6.x and SUSE
            [host]# service mpss unload
        RHEL 7.x
            [host]# systemctl disable mpss
	    [host]# modprobe -r mic

     2) Uninstall:
        a. To uninstall MPSS-3.x:
           [host]$ cd mpss-3.4
           [host]$ ./uninstall.sh

        b. To uninstall MPSS-2.x:
        o Red Hat* Enterprise Linux*
            [host]# yum remove intel-mic\*

        o SUSE* Linux* Enterprise Server
            [host]# zypper remove intel-mic\*

  2.4  Intel(R) Xeon Phi(TM) Coprocessor Flash & SMC Update

********************************************************************************
*  WARNING:  Flash and SMC updates to versions specified in this release are   *
*            required.                                                         *
*                                                                              *
* Using this release with the incorrect Flash and SMC versions is not supported*
* and may lead to erratic behavior.                                            *
********************************************************************************

Note: 
 o These steps will not work if the flash files (ending in .rom.smc) are
    moved to a location other than the default install path.

o PREREQUISITES:
    - Uninstall prior version of MPSS and install new version.
    - Current running version of Flash must be >= 375. If not, contact your
      Intel support representative.

Steps:
  1) Check the status of the coprocessor(s):
            [host]# micctrl -s

     If the status for all of the coprocessors shows 'ready', goto step 2;
     otherwise, set the coprocessor(s) to a 'ready' state:
            [host]# micctrl -rw

  2) Run from the command prompt:
            [host]# /usr/bin/micflash -update -device all smcbootloader

  *NOTE* If using C0 stepping, or 5110P B1 SKUs with a TA of G65758-253 or
         higher, or if the SMC boot loader version is 1.8, use this command 
         in place of step 2:
            [host]# /usr/bin/micflash -update -device all

  3) Reboot the host system for all flash and SMC changes to take effect.

2.5  SSH Access and Configuration for the Intel(R) Xeon Phi(TM) Coprocessor

Communication with the coprocessor Linux* operating system on the Intel(R) Xeon 
Phi(TM) coprocessor is provided by a standard network interface. The interface 
uses a virtual network driver over the PCIe bus. Standard networking tools 
such as SSH are supported. 

The Intel(R) Xeon Phi(TM) coprocessor Linux* OS supports network access using 
SSH keys or password authentication, provided that valid credentials exist on 
the coprocessor. The initial configuration phase of the Intel(R) MPSS creates 
users for each coprocessor based on the current user IDs in the host /etc/passwd 
file. For each user in /etc/passwd (including root), if SSH key files are found 
in the user's ".ssh" directory, those keys are also populated to the Intel(R) 
Xeon Phi(TM) coprocessor's file system. 

The default user credentialing behavior on the coprocessor can be customized 
with the "micctrl --userupdate" option. Administrators who prefer to only 
provide a limited set of user credentials (root, sshd, micuser, nobody and 
nfsnobody) can run the following commands after the initial configuration to 
prevent all users from being propagated: 
         RHEL 6.x and SUSE
            [host]# service mpss stop
            [host]# micctrl --userupdate=none 
            [host]# service mpss start
         RHEL 7.x
            [host]# systemctl disable mpss
            [host]# micctrl --userupdate=none 
            [host]# systemctl enable mpss

In the case where a user did not have a valid SSH key present during the initial
coprocessor configuration process, they can be added as necessary on a per-user 
basis. To generate the SSH key, each user must execute: 
            [host]$ ssh-keygen 

Then, the "micctrl --sshkeys" option is used to allow Intel(R) MPSS to pick up 
the new keys for a specific user. For example, the following updates the 
coprocessor configuration for mic0 to include root's SSH keys: 
          RHEL 6.x and SUSE
            [host]# service mpss stop
            [host]# micctrl --sshkeys=root mic0 
            [host]# service mpss start
          RHEL 7.x
            [host]# systemctl disable mpss
            [host]# micctrl --sshkeys=root mic0 
            [host]# systemctl enable mpss 

See the Intel(R) MPSS User's Guide (MPSS_Users_Guide.pdf) for detailed 
information regarding user authentication and customization options including 
support for LDAP and NIS. 

If after executing 'ssh mic0' the following message appears, then remove the 
mic0 RSA from the SSH 'known_hosts' file typically found at ~/.ssh/ folder. 
    @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ 
    @    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @ 
    @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ 
    IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY! 
    Someone could be eavesdropping on you right now (man-in-the-middle attack)! 

*Note: If running an ssh command in the background, it is preferable to use the 
       "-f" option instead of appending "&" to the command: 
            [host]$ ssh -f hostname "sleep 20; echo complete" 

2.6 Enable Large Base Address Registers (BAR) Support in the Platform BIOS

In order for Intel(R) Xeon Phi(TM) coprocessors to function properly in a
platform, BIOS and OS support for large (8GB+) Memory Mapped I/O Base Address
Registers (MMIO BAR's) above the 4GB address limit must be enabled.

By default, most platform BIOS implementations have this set to disabled, 
therefore it must be enabled manually in the platform BIOS setup.

Contact your platform and/or BIOS vendor to determine whether changing this 
setting applies for the platform being used.