/*
Copyright (c) 2017, Intel Corp.
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

    * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
    * Neither the name of Intel Corporation nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/

*******************************************************************************
iommap TEST DRIVER			version_number = 2.09.1.0528			 07/22/2017
*******************************************************************************

OVERVIEW

    Iommap is a driver for accessing PCI, IO, CMOS and physical memory address. 

  
INSTALLATION FILE REQUIREMENTS

    For Intel x86, iommap requires the following files:
        iommap-2.07.1.0525-00.src.rpm (rpm source)
        libiommap.so (dynamic linking binary)
        libiommap.so.2.i386
        libiommap.so.2.15.i386

    For Intel EM64T, iommap require the following files:
        iommap-2.07.1.0525-00.src.rpm (rpm source)
        libiommap.so (dynamic linking binary)
        libiommap.so.2.x86_64        
        libiommap.so.2.15.x86_64


QUICK INSTALLATION STEPS
        
    1. Login as root.
        
    2. Enter the command:    rmmod iommap

    3. On a RedHat* system enter the command:    
            rpmbuild --rebuild iommap*.src.rpm
       On a SuSE* system enter the command:
            rpm --rebuild iommap*.src.rpm

    4. Copy all three libiommap.so files to the installation directory
       where CTC/T is installed.


QUICK UNINSTALL STEPS

    Enter the command:    rmmod iommap
    

FULL INSTALLATION STEPS FOR SYSTEM ADMINISTRATORS

    1. First install the rpm source:
       rpm -vi --force iommap-<ver>-<release>.src.rpm           
    
    2. After install iommap rpm source, rebuild rpm binary from rpm source:
       RedHat    : rpmbuild -ba /usr/src/redhat/SPECS/iommap.spec
       SuSE      : rpm -ba /usr/src/packages/SPECS/iommap.spec
    
    3. To install iommap rpm binary files:
       RedHat    : rpm -vi --force /usr/src/redhat/RPMS/<platform>/
                   iommap-<ver>-<release>.<platform>.rpm
       SuSE      : rpm -vi --force /usr/src/packages/RPMS/<platform>/
                   iommap-<ver>-<release>.<platform>.rpm
    
    4. Other common RPM option include:
       Query RPM        : rpm -ql iommap-iommap-iommap-<ver>-<release>
       Uninstall RPM    : rpm -ve --force iommap-iommap-<ver>-<release>
       Search for RPM   : rpm -qa | grep iommap
    
    NOTE: <ver> is the version number 2.06.1.0523, 
          <release> is the release number 01, 
          <platform> is the plaform architeture. You could get the 
          platform information by type in "uname -i". 
          Root access is required for all the installation.

    After iommap installation, below files are released to local path:
          /lib/modules/`uname -r`/iMTA/iommap/2.06.1.0523/iommap.ko (ELF binary for Linux Kernel 2.6)
          /lib/modules/`uname -r`/iMTA/iommap/2.06.1.0523/iommap.txt (help file)
          /lib/modules/`uname -r`/iMTA/iommap/iommap.ko (softlink to driver ELF binary for 2.06.1.0523)
          /lib/modules/`uname -r`/iMTA/iommap/iommap.txt (softlink to driver help for 2.06.1.0523)
          /etc/init.d/iommapd (service file)
          /etc/iommapd.conf (configuration file)
          /dev/iommap (device file)    
    
    After iommap installation, below existing files are removed from local path:
          /usr/bin/iommap.o (ELF binary for Linux Kernel 2.4)
          /usr/bin/iommap.ko (ELF binary for Linux Kernel 2.6)    
          /usr/bin/iommap.txt (help file)
          /usr/bin/iommap.chm (help file)          
        
    Note: Once the iommap driver is successfully installed, the library 
          files (libiommap.so, etc) will need to be manually copied into
          directory containing CTC, T and test module binaryies. 
          Otherwise, even though the driver is installed, if the library
          is not located in the current directory the modules will not
          try to use the driver.


    List of services:
    
          From Red Hat command prompt:
          /sbin/service iommapd start 
          (start the driver service)

          /sbin/service iommapd stop
          (stop the driver service)

          /sbin/service iommapd restart
          (restart the driver service)

          /sbin/service iommapd reload 
          (reload the driver service)

          /sbin/service iommapd link 
          (install the driver service to rc3 and rc5)

          /sbin/service iommapd unlink 
          (uninstall the driver service from rc3 and rc5)

          From SuSE or Gentoo command prompt:
          /etc/init.d/iommapd start 
          (start the driver service)

          /etc/init.d/iommapd stop 
          (stop the driver service)

          /etc/init.d/iommapd restart 
          (restart the driver service)

          /etc/init.d/iommapd reload 
          (reload the driver service)

          /etc/init.d/iommapd link 
          (install the driver service to rc3 and rc5 for SuSE, 
          default rc for Gentoo)

          /etc/init.d/iommapd unlink 
          (uninstall the driver service from rc3 and rc5 for SuSE, 
          default rc for Gentoo)


FULL UNINSTALL STEPS FOR SYSTEM ADMINISTRATORS

    1.  rmmod iommap

    2.  rpm -ve --force iommap-iommap-<ver>-<release>


IOMMAP FAQ (FREQUENTLY ASKED QUESTIONS)

    Q. Who developed this driver?
    A. The Iommap driver was developed by Intel®.

    Q. Who should I contact for technical difficulties with this driver?
    A. Send an email to imta.diag.support@intel.com.

    Q. Can I still run test modules with CTC and T if the driver doesn't load?
    A. Yes, the test executives "CTC" & "T" themselves do not rely 
       on this driver.  Only the USB and Memory test modules need this driver.
       The test executives will automatically lower test coverage or bypass
       IOMMAP-dependent tests if this driver is not available.
 
    Q. Why can't I get the SRC RPM to install on a RedHat AS 4 system?
    A. RedHat AS 4 does not install the kernel source by default.
        
    Q. How do I install the kernel source?
    A. See your system administrator or refer to 
       http://www.linuxselfhelp.com/HOWTO/PPP-HOWTO/kernel-configuration.html.

    Q. Which Linux(TM) OS are officially supported for "CTC" & "T"? 
    A. The following operating systems are supported:

        Redhat AS 4.0 for UP, SMP and EM64T (Linux Kernel 2.6.9-5.EL)
        Redhat AS 4.0 Update 2 for UP, SMP and EM64T (Linux Kernel 2.6.9-22.EL)
        Redhat AS 4.0 Update 3 for UP, SMP and EM64T (Linux Kernel 2.6.9-30.EL)
        Redhat AS 4.0 Update 4 Beta for UP, SMP and EM64T (Linux Kernel 2.6.9-39.EL)
                                
        SuSE 9 Patch 3 for UP, SMP and EM64T (Linux Kernel 2.6.5-7.244-default) 
        SuSE 10.0 for UP, SMP and EM64T (Linux Kernel 2.6.13-15-default)
        SuSE 10.0 for UP, SMP and EM64T (Linux Kernel 2.6.16.21-0.8)
 	        
    Q. Which Linux(TM) OS are officially removed for "CTC" & "T"? 
    A. The following operating systems are removed from the support:
            
        Redhat 9.0 for UP and SMP (Linux Kernel 2.4.20-6)
        Redhat AS 3.0 for UP, SMP and EM64T (Linux Kernel 2.4.21-20.ELsmp)
        Redhat AS 4.0 for UP, SMP and EM64T (Linux Kernel 2.6.8-1.528.2.10)
    
        SuSE 9.0 for UP and SMP (Linux Kernel 2.4.21-99-default)
        SuSE 9.1 for UP, SMP and EM64T (Linux Kernel 2.6.4-52) 
        SuSE 9.2 for UP, SMP and EM64T (Linux Kernel 2.6.8-22-smp)        



Version Notes
07/22/17 CLS   Support Kernel 4.4 RHEL7.3, SLESH12, CentOS7.3 & Ubuntu16.4.
10/12/15 CLS   Support 64-bit addressing.
12/27/14 CLS   Support Kernel 3.10.0-123.EL for RHEL7.
05/23/12 HKL   Support Kernel 3.0.13-0.27-default for SuSE 11 SP2.
07/05/11 HKL   Support Kernel 2.6.32 for RHEL6.
09/08/09 HKL   Support Kernel 2.6.30 for Moblin.
09/07/08 HKL   Support IA64.
11/03/07 HKL   Support EM64T for SUSU10 2.6.16.21-0.8.
02/08/07 HKL   Update BSD license.
08/03/06 HKL   Update driver to support iMTA 2.0.
01/25/06 HKL   Updated /etc/init.d/iommapd.
01/07/06 HKL   Change driver debug message level in PCI.
02/04/05 BKL   Reworked to add new user feedback.
01/24/05 HKL   Add debug help details.
01/07/05 HKL   Add MVL CGE 3.1 support.
11/30/04 HKL   Update ioctl32 function call.
11/16/04 HKL   Add RH4.0 Beta 1 and EM64T support.
09/15/04 HKL   Add SuSE9.1 SuSE9.2 Kernel 2.6 support.
07/02/04 HKL   Update the driver version.
06/22/04 HKL   Update the build.txt file.
06/16/04 HKL   Update the build.txt file.
04/23/04 HKL   Initial release.

*All other brands and names are property of their respective owners.
