[CPU Counter for Linux]
=======================================================
Lee Jung-Hoon (jhlee94@sidae.uos.ac.kr)
Current version : 0.9.6
MDS Patch file by Oh Young-Eun (iceize@venus.uos.ac.kr)

Intel corporation released the program which can detect and support a
Hyperthreading capable processor called "cpu counting utility". 
But that "cpu counting utitlity" can only run on a Microsoft Windows
operating system, not on Linux. But lots of people need that function or
an example of Linux based implementation, so Lee Jung-Hoon (HPC 
Laboratory at the University of Seoul, Korea) made a program based upon Linux 
named "cpucounter4linux". With this small program, you will be able to know 
how to identify Hyper-Threading Technology processors and associate logical 
processors to physical processors on Linux.
The implementation of "cpucounter4linux" is similar to "cpu counting
utility (for Windows which is made by Intel corp.)", hence you can easily figure 
out how to implement that program on the Linux. Refer to Intel's Application
Note AP-485 titled "Intel Processor Identification and the CPUID
Instruction" and the article titled "Detecting Support for Hyper-Threading 
Technology Enabled Processors".
Over the version 0.9.6, cpucounter4linux can support GRID environment. With
this version, GRID become aware of hyperthreading capable processors, and
can handle it appropriately.


0. Features
  1) Detect a Hyper-Threading Technology enabled processor.
  2) Identify the number of logical processors per physical processor.
  3) Associate logical processors to the individual physical processors.
  4) Support for GRID/MDS(Monitoring and Discovering Service).
  

1. Installation
 The most recently released version of cpucounter4linux is 0.9.6, is 
fully functional like Intel's. To install the cpucounter4linux 0.9.6 on your
Linux box, do the following :
  1) Download the "cpucounter4linux.tar.gz" file. if you don't know where it is,
     just e-mail me (jhlee94@sidae.uos.ac.kr).
  2) Uncompress that tarball with this command; 
      # tar xvfz cpucounter4linux.tar.gz
  3) Move to the appropriate directory which is named to the specific version number, 
     compile the source files like this;
      # make
     If you don't have an Intel processor, you will see compile error 
	 message. Don't worry about that. To my knowledge, your processor is
	 not capable of "Hyper-Threading Technology", and you do not need to use
	 this program.
	 When you see error message like this,
     "undefined reference to `sched_getaffinity'"
	 please refer to section "2. Requirements".

  4) After compiling the source code, you can see the binary file "cpucounter4linux". 
     Just execute it. And, I strongly recommend to use this program with
	 "-v" option because it will generate very important and useful messages.


Optionally, If you want to use this program in GRID environment, you have to patch your
globus toolkit 2.0 which is intalled in the same machine as this one:

  1) Just move to your globus directory. Typically, $GLOBUS_LOCATION is
  "/usr/local/globus"
      # cd $GLOBUS_LOCATION
  2) Move mds.patch file to this directory, and patch.
      # patch -p1 < mds.patch
  3) Copy cpucounter4linux binary file to $GLOBUS_LOCATION/libexec
  directory.
      # mv cpucounter4linux $GLOBUS_LOCATION/libexec
  4) Just for confirmation,
      # $GLOBUS_LOCATION/bin/grid-info-search -x | grep Mds-Cpu-Smt



2. Requirements
 cpucounter4linux can run on any flavor of Linux. just compile its source
code, and execute it. but there is just one restriction to use this program.
if your Linux kernel version is less than 2.4.16, it will show you just
restricted informations with this error message - "error, function not
implemented". It comes from the absence of specific system calls related
to cpu affinity in your Linux kernel. if your Linux kernel version is
between "2.4.16" and "2.5.8-pre3", you have to patch your Linux kernel, 
otherwise just do nothing.  Refer to 
http://www.kernel.org/pub/linux/kernel/people/rml/cpu-affinity/README-cpu-affinity.
From this URL, you can get the appropriate kernel patch file.


3. Options
 cpucounter4linux has some options like these.  
  1) -h, --help ; 
     Display command usage and exit.
  2) -V, --version ;
     Display version information and exit.
  3) -v, --verbose ;
     Enable verbose output. This is very important option because this will
	 generate very important and useful messages.
  4) -m, --mds ;
     Enable mds output. This option is conflicted with verbose option. If
	 you once patch your globus 2.0 (http://www.globus.org) with the patch file 
	 in this cpucounter4linux package, your GRIS will automatically use your
	 cpucounter4linux with this option. and you can handle the
	 hyperthreading information in the GRID environment.


4. Execution examples
 Here I can provide some execution examples.

 1) with Pentium III processor DUAL (of course, it cannot support
	 Hyper-Threading Technology).

	=======================================================================
    # cpucounter4linux
       Hyper-Threading capable processr : Not Capable
	   Number of physical processors : 2
	   Logical processors per physical : 0
	   Hyper-Threading technology : Disabled
	=======================================================================


 2) with Intel Xeon CPU 2.4GHz, DUAL. when Hyper-Threading is "ON" by BIOS.

	=======================================================================
    # cpucounter4linux -v
       CPU vendor : GenuineIntel
	   Processor brandname : Intel Xeon processor or Intel Xeon
	                         processor MP
	   Hyper-Threading capable processor : Capable
	   OS Affinity ID: 00000001, APIC ID: 0, PHY ID: 0, LOG ID: 0
	   OS Affinity ID: 00000002, APIC ID: 1, PHY ID: 0, LOG ID: 1
	   OS Affinity ID: 00000004, APIC ID: 6, PHY ID: 3, LOG ID: 0
	   OS Affinity ID: 00000008, APIC ID: 7, PHY ID: 3, LOG ID: 1
	   Number of physical processors : 2
	   Logical processors per physical : 2
	   Hyper-Threading technology : Enabled
	=======================================================================

	This result shows you that the number of processors are 2, and each
	physical processor has 2 logical processors.


 3) The same processors as previous except Hyper-Threading is "OFF" by BIOS.

	=======================================================================
    # cpucounter4linux -v
       CPU brand signature : GenuineIntel
	   Processor brandname : Intel Xeon processor or Intel Xeon
	                         processor MP
	   Hyper-Threading capable processor : Capable
	   OS Affinity ID: 00000001, APIC ID: 0, PHY ID: 0, LOG ID: 0
	   OS Affinity ID: 00000002, APIC ID: 6, PHY ID: 3, LOG ID: 0
	   Number of physical processors : 2
	   Logical processors per physical : 2
	   Hyper-Threading technology : Not Detected
	=======================================================================


5. Miscellaneous
 cpucounter4linux is freely distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY. Without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
 Public License for more details.
 Thanks to free software which is very helpful, especially for "kernel
 patch" for cpu affinity which is made by Robert Love, "cpuid" which 
 is made by Phil Karn and "eject" which is made by Jeff Tranter, "si" 
 which is made by Joe Turgeon.
 and special thanks to Oh young-Eun who made MDS patch file for
 cpucounter4linux.

If you have any problems or suggestions, drop me a line. 
I'm particularly interested in hearing if it has any problems.


Lee Jung-Hoon.
jhlee94@sidae.uos.ac.kr
