12345678901234567890123456789012345678901234567890123456789012345678901234567890
         1         2         3         4         5         6         7         8
----+----|----+----|----+----|----+----|----+----|----+----|----+----|----+----|



Additional Release Notes for Iometer (2003.02.08 and above)

  ------------------------------------------------------------------------

Table of Contents

Iometer Developer's Guide

   * 1     Introduction

   * 2     Building Iometer
   * 2.1   Makefile issues

   * 3     Testing Iometer (coming later)

   * 4     Porting Iometer (coming later)
   * 4.1   To another OS (coming later)
   * 4.2   To another CPU (coming later)

   * 5     Extending Iometer (coming later)
   * 5.1   By other Storage targets (coming later)
   * 5.2   By other Network targets (coming later)

   * A     File descriptions
   * A.1   Iometer
   * A.2   Dynamo 

  ------------------------------------------------------------------------

Iometer Developer's Guide

  ------------------------------------------------------------------------

1 Introduction

Starting with the development of Iometer you first have to have access to
the source code. Best is to use the CVS server provided by sourceforge.
If you do not have a change to get this done (restrictive firewall etc.)
you can download the nightly tarball of the CVS respository from:

http://cvs.sourceforge.net/cvstarballs/iometer-cvsroot.tar.bz2

  ------------------------------------------------------------------------

2.1 Makefile issues

For each of the different supported Unix operating system we have a
independent makefile. You can identify the appropriate one by its name
(the makefile for Linux is named Makefile-Linux and so on).

The most important part is the CFLAGS variable which defines the flags
used while compilation of the sources. Beside the compiler flags you will
find important global defines (-D<key>[=<value>]):

 o IOMTR_OSFAMILY_...
 
   This are global defines to identify the Operating System family:

   IOMTR_OSFAMILY_UNIX      Any UNIX, currently Linux and Solaris
   IOMTR_OSFAMILY_WINDOWS   Any Windows based Operating System

   Note: The Operating System family could be autodetected by mapping the
         given IOMTR_OS_... value. But this implies, that every code- and
	 headerfile includes IOCommon.h which is not given at this time.

 o IOMTR_OS_...

   This are global defines to identify the Operating System itself: 
   IOMTR_OS_FREEBSD         FreeBSD, 32 bit *
   IOMTR_OS_LINUX           Linux, 32 bit   
   IOMTR_OS_LINUX64         Linux, 64 bit *
   IOMTR_OS_SOLARIS         Sun Solaris (64 bit)
   IOMTR_OS_WIN32           Microsoft Windows, 32 bit
   IOMTR_OS_WIN64           Microsoft Windows, 64 bit
   
   * = Not yet implemented / supported.

 o IOMTR_CPU_...

   This are global defines to identify the Processor / CPU itself: 
   IOMTR_CPU_ALPHA          Alpa CPU (Digital->Compaq->HP) *
   IOMTR_CPU_AMD64          AMD x86 with 64 bit extention (Opteron) *
   IOMTR_CPU_I386           Intel x86 processors (32 bit)
   IOMTR_CPU_IA64           Intel Itanium family (64 bit)
   IOMTR_CPU_MIPS           MIPS CPU (used in SGI machines etc.) *
   IOMTR_CPU_SPARC          Sun Sparc processor (64 bit)
   
   * = Not yet implemented / supported.
   
 o _DEBUG

   This is the global "switch" to activate the debugging code.  
   
   Note: We can not change its name to DEBUG for instance, because
         the MFC Library (Windows only) gets into debugging mode when
	 _DEBUG is defined, so we have to stick with it. Another option
	 is to use our own DEBUG define and then activate _DEBUG using
	 a #ifdef statement (something for the IOCommon.h file).

 o _GALILEO_ / _PULSAR_

   This are two global defines to distinguish Iometer (_GALILEO_) from
   Dynamo (_PULSAR_) parts in the code. For instance this "switches" are
   used to define if error messages are prompted as Message Box or
   directly printed to the console.
   
 ...

  ------------------------------------------------------------------------

A File descriptions

In the following two subchapters you will find a lists with descriptions
for each file within the source tarball (grouped by there primary job).

One of the few common rules within the Iometer / Dynamo source seems to
be, that once a class is defined and implemented, you will find the class
defintion in foo.h and its implementation in foo.cpp.

  ------------------------------------------------------------------------

A.1 Iometer

 o Central configuration

    - IOCommon.h               (<none>)

      This is THE central header file of the project. It contains basic
      settings for Iometer as well as Dynamo. Limits like MAX_WORKERS
      or MAX_TARGETS are defined here.

    - IOVersion.h              (<none>)

      The primary job of this file is to set the version string
      (IOVER_FILEVERSION) as well as other descriptive stuff.

      Keep in mind, that once you have changed the version string, you
      have to compile both Iometer and Dynamo - otherwise the login (which
      is done at Dynamo startup) will fail.

 o Core code

    - GalileoApp.h             (CGalileoApp)
    - GalileoApp.cpp           (CGalileoApp)

      The CGalileoApp class is THE central class of Iometer - it is simular
      to the main() function of traditional C programs.

    - ManagerList.h 
    - ManagerList.cpp 

      The ManagerList class gets instantited by the CGalileoApp class. It
      represents a list of Manager class instances.

    - Manager.h 
    - Manager.cpp 

      The Manager class represents a single instance of an single manager
      (which is a running instance of the Dynamo executable). Do not get
      confused, due to the fact, that Dynamo has an Manager class as well.
      Both are talking about the same subject, but contains different coding.
      
 o Helping code (User Interface)

    - LegalBox.h               (CLegalBox)
    - LegalBox.cpp             (CLegalBox)

    - GalileoView.h            (CGalileoView)
    - GalileoView.cpp          (CGalileoView)
    
      This class manages and contains the overall GUI stuff. It is a large
      file containing a mixture of GUI handling and core functionality.
      Beside other things, it contains the AddDefaultWorkers() method which
      is responsible to add the number of disk and network workers (the
      numbers are specified in the "Test setup" tab of the Iometer GUI).
    
    - MainFrm.h                (CMainFrame)
    - MainFrm.cpp              (CMainFrame)    

    - PageDisk.h               (CPageDisk)
    - PageDisk.cpp             (CPageDisk)    
    - PageNetwork.h            (CPageNetwork)
    - PageNetwork.cpp          (CPageNetwork)
    - PageTarget.h             (<none>)
    - PageAccess.h             (CPageAccess)
    - PageAccess.cpp           (CPageAccess)
    - PageDisplay.h            (CPageDisplay)
    - PageDisplay.cpp          (CPageDisplay)
      ...

    - PageSetup.h              (CPageSetup)
    - PageSetup.cpp            (CPageSetup)

      Responsible for the "Test Setup" tab of the Iometer GUI. Beside the
      coding for user interaction, you find the default settings within the
      OnInitDialog() method.
      The number of disk and network workers per manager is defined here
      too. The defaults differ between debug code and release code.      

    - AccessDialog.h           (CAccessDialog)
    - AccessDialog.cpp         (CAccessDialog)
    
    - BigMeter.h               (CBigMeter)
    - BigMeter.cpp             (CBigMeter)
    - MeterCtrl.h              (CMeterCtrl)
    - MeterCtrl.cpp            (CMeterCtrl)
    ...
 
 o Helping code (Rest of)

    - GalileoDefs.h            (<none>)
    - GalileoGlobals.cpp       (<none>)

    - GalileoCmdLine.h         (<none>)
    - GalileoCmdLine.cpp       (<none>)
    ...

    - AccessSpecList.cpp
    - GalileoDoc.h
    - GalileoDoc.cpp
    - ICF_ifstream.h
    - ICF_ifstream.cpp
    - ICFOpenDialog.h
    - ICFOpenDialog.cpp
    - ICFSaveDialog.h
    - ICFSaveDialog.cpp
    - IOAccess.h 
    - IOAccess.cpp 
    - IOGlobals.cpp 
    - IOPort.h 
    - IOPort.cpp 
    - IOPortTCP.h 
    - IOPortTCP.cpp
    - IOSTREAM 
    - IOTest.h 
    - IOTime.h 
    - IOTime.cpp 
    - IOTransfer.h 
    - ISTREAM 
    - ManagerMap.h 
    - ManagerMap.cpp 
    - OSTREAM 
    - StdAfx.h 
    - StdAfx.cpp 
    - TextDisplay.h 
    - TextDisplay.cpp
    - vipl.h 
    - WaitingForManagers.h 
    - WaitingForManagers.cpp 
    - Worker.h 
    - Worker.cpp 
    - WorkerView.h 
    - WorkerView.cpp
    ...

    - Galileo.rc              (<none>)
    - resource.h              (<none>)
    - res/Iometer.rc2         (<none>)

      This resource and there header files which are needed to compile the
      executable for Windows.

    - Iometer.dsw             (<none>)
    - Iometer.dsp             (<none>)

      Both Workspace and Project file are used to compile the Iometer code
      with Microsoft Developer / Visual Studio.

    - Iometer/makefile        (<none>)
    - Iometer/sources         (<none>)

      Files needed to build the Iometer GUI executable with the Microsoft
      Driver Development Kit.

  ------------------------------------------------------------------------

A.2 Dynamo

 o Central configuration

    - IOCommon.h               (<none>)

      This is THE central header file of the project. It contains basic
      settings for Iometer as well as Dynamo. Limits like MAX_WORKERS
      or MAX_TARGETS are defined here.

    - IOVersion.h              (<none>)

      The primary job of this file is to set the version string
      (IOVER_FILEVERSION) as well as other descriptive stuff.

      Keep in mind, that once you have changed the version string, you
      have to compile both Iometer and Dynamo - otherwise the login
      (which is done at Dynamo startup) will fail.

 o Core code

    - Pulsar.cpp              (<none>)

      This is THE central code file of Dynamo, housing the essential
      main() function.      

    - IOManager.h             (Manager)
    - IOManager.cpp           (Manager)
    - IOManagerLinux.cpp      (Manager)
    - IOManagerSolaris.cpp    (Manager)      
      
      The Manager class is Dynamo's main class and is instantiated by
      the main() function (see Pulsar.cpp).

      IOManager.cpp implements the platform independent as well as the
      Windows related stuff.
      IOManagerLinux.cpp and IOManagerSolaris.cpp contains coding related
      to that platforms - the differenciation is done by cheating with
      defines.

    - IOGrunt.h               (Grunt)
    - IOGrunt.cpp             (Grunt)

      The Grunt class represents an Worker thread and is instantiated up
      to MAX_WORKERS (see IOCommon.h) times per Manager class object. 

    - IOTarget.h              (Target)
    - IOTarget.cpp            (Target)
    - IOTargetDisk.h          (TargetDisk)
    - IOTargetDisk.cpp        (TargetDisk)
    - IOTargetTCP.h           (TargetTCP)
    - IOTargetTCP.cpp         (TargetTCP)
    - IOTargetVI.h            (TargetVI)
    - IOTargetVI.cpp          (TargetVI)

      The Target class is a virtual class that represents Worker Targets.
      The TargetDisk, TargetTCP and TargetVI classes are based on that
      and covers the target specific implementation.
      They are instantiated up to MAX_TARGETS (see IOCommon.h) times per
      Grunt class object.

    - IOAccess.h              (IOAccess)
    - IOAccess.cpp            (IOAccess)
    
      The Access class represents the current Access Specifications for
      a Worker. An object contains up to MAX_ACCESS_SPECS (see IOAccess.h)
      Access Specification lines (each represented by a ACCESS struct).

    - IOTransfers.h           (<none>)
 
      Within this header file the Transaction structure is defined which
      is used by Grunt as well as Target class objects.

 o Helping code (Communication)

    - IOPort.h                (Port)
    - IOPort.cpp              (Port)
    - IOPortTCP.h             (PortTCP)
    - IOPortTCP.cpp           (PortTCP)

      The job of the Port class is to handle the communication between
      Iometer and Dynamo. PortTCP is implementing the supported to do
      so. Instantiation is done by the Manager class.
 
    - IOMessage.h             (<none>)
    - IOTest.h                (<none>)

      This two header files defines message structs and substructs for
      the communication between Iometer and Dynamo.

    - Network.h               (Network)
    - Network.cpp             (Network)
    - NetTCP.h                (NetAsyncTCP)
    - NetTCP.cpp              (NetAsyncTCP)
    - NetVI.h                 (NetVI)
    - NetVI.cpp               (NetVI)

      The Network class is a virtual class which covers the communication
      between network workers in Dynamo. The NetAsyncTCP and NetVI class
      are based on that and covers the media specific implementation.
      Instantiation is done by one of the Target classes.

    - ByteOrder.cpp           (<none>)

      This code file implements the reorder() function, which is used in
      big endian environments (Sun Sparc processor for example) to swap
      the byte order. 

 o Helping code (Performance)

    - IOPerformance.h         (Performance)
    - IOPerformance.cpp       (Performance)
    - IOPerformanceLinux.cpp  (Performance)

      The Performance class is responsible for providing basic informations
      as the number of CPU's and their speed. But its primary job is the
      collection and calculation of system-wide performance figures as for
      example the CPU utilization.

      The platform independent coding as well as the Windows and Solaris
      related stuff can be found in IOPerformance.cpp, while the Linux
      related coding is kept in IOPerformanceLinux.cpp - the seperation is
      done by cheating with defines.

    - IOTime.h                (<none>)
    - IOTime.cpp              (<none>)
    - rdtsc.c                 (<none>)
    
      This files contains the different implementations for reading the 
      processors high resolution timers. IOTime.h contains the Linux code,
      IOTime.cpp the Windows and rdtsc.c the Solaris part - the seperation
      is done by cheating with defines.
      
 o Helping code (Rest of)

    - IOCQ.h                  (CQ)
    - IOCQAIO.h               (CQAIO)
    - IOCQAIO.cpp             (CQAIO)
    - IOCQVI.h                (CQVI)
    - IOCQVI.cpp              (CQVI)
    - IOCompletionQ.cpp       (<none>)

      The CQ class (Completion Queue) is a virtual class which is used
      to manage completions. The CQAIO class covers the TargetDisk and
      TargetTCP objects, CQVI is used for TargetVI objects.

      IOCompletionQ.cpp houses the UNIX implementation of several
      Windows NT key functions for asynchronous I/O.

    - IOVIPL.h                (VIPL)
    - IOVIPL.cpp              (VIPL)
    - VINic.h                 (VINic)
    - VINic.cpp               (VINic)
    - vipl.h                  (<none>)

      The VIPL class is a wrapper for all the functions of the VI Provider
      Library. It is used by the VINic class to abstracts the VI NIC's.
      The vipl.h header file contains all the VI specific type definitions,
      structs, enums etc.

    - Pulsar.rc               (<none>)
    - PulsarRC.h              (<none>)
    - res/Iometer.rc2         (<none>)

      This resource and there header files which are needed to compile the
      executable for Windows.
      
    - Iometer.dsw             (<none>)
    - Dynamo.dsp              (<none>)
    
      Both Workspace and Project file are used to compile the Dynamo code
      with Microsoft Developer / Visual Studio.

    - Dynamo/makefile         (<none>)
    - Dynamo/sources          (<none>)

      Files needed to build the Dynamo executable with the Microsoft Driver
      Development Kit.

  ------------------------------------------------------------------------


