Create framework for ISTEP 10, 12, 13

istep framework for istep 10 (sbe_centaur_init)
istep 12( mss_volt, etc).
istep 13 ( mss_draminit, etc )

Commented out testHWP, not used anymore.
Fixed bug in hb-istep for simics

fixed review comments
Added section in genIstep.pl to generate include/usr/isteps/istepNlist.H
	( istep 13 generated using script)

NOTE:  10, 11, 12 were partially generated manually, that is why they are
	not consistent.

Change-Id: I28ed8d3e60d2d0438ebe7ca3ed2053c781bc72ed
Reviewed-on: http://gfw160.austin.ibm.com:8080/gerrit/661
Tested-by: Jenkins Server
Reviewed-by: Van H. Lee <vanlee@us.ibm.com>
Reviewed-by: A. Patrick Williams III <iawillia@us.ibm.com>

1 files changed, 1124 insertions, 0 deletions

diff --git a/src/build/tools/genIStep.pl b/src/build/tools/genIStep.pl
new file mode 100755
index 000000000..2cfe2eb7d
--- /dev/null
+++ b/src/build/tools/genIStep.pl
@@ -0,0 +1,1124 @@
+#!/usr/bin/perl
+#  IBM_PROLOG_BEGIN_TAG
+#  This is an automatically generated prolog.
+#
+#  $Source: src/build/tools/genIStep.pl $
+#
+#  IBM CONFIDENTIAL
+#
+#  COPYRIGHT International Business Machines Corp. 2012
+#
+#  p1
+#
+#  Object Code Only (OCO) source materials
+#  Licensed Internal Code Source Materials
+#  IBM HostBoot Licensed Internal Code
+#
+#  The source code for this program is not published or other-
+#  wise divested of its trade secrets, irrespective of what has
+#  been deposited with the U.S. Copyright Office.
+#
+#  Origin: 30
+#
+#  IBM_PROLOG_END
+
+#
+# Author:   Mark Wenning    wenning@us.ibm.com
+#
+# Usage:
+#   genIStep.pl --tag-file <path>   ( required: file containing tag block )
+#               [ --help ]          ( prints usage message )
+#               [ --dry-run ]       ( prints all steps without doing anything )
+#               [ --import-hwp ]    ( import new HWP source from Gerrit )
+#
+# Purpose:
+#   Read in a tag file and generate a new istep (or update the existing istep)
+#   based on the tags.
+#
+#   To set up to run a new HWP, follow these directions
+#        ( or have your perlscript do it from the tag block )
+#
+#   Make up a new directory  src/usr/hwpf/hwp/<@istepname>
+#   cd to that directory.  
+#
+#   Make up a blank file src/usr/hwpf/hwp/<@istepname>/<@istepname.H>    
+#           (use src/usr/hwpf/hwp/template.H as a template)
+#   - add the tag block file detailed below.  
+#
+#   1. [x]  Update the src/usr/hwpf/hwp/<@istepname>/<@istepname.H>   
+#           with the prototypes, etc. from the istep/substep.
+#     
+#   2. [x]  Create a new file src/usr/hwpf/hwp/<@istepname>/<@istepname.C>    
+#           (use src/usr/hwpf/hwp/template.C as a template)
+#
+#   3. [ ]  Make a new istep<@istepnum>list.H file in /usr/include/isteps/
+#           Add the new istep<@istepnum>list.H file to 
+#           src/include/usr/istepmasterlist.H in the correct place in the 
+#           master istep list.
+#
+#   4. [ ]Make up new makefile src/usr/hwpf/hwp/<@istepname>/makefile to compile 
+#           the HWP and wrapper
+#   Add makefile support for the new HWP:
+#   - Scan src/usr/hwpf/hwp/@substepname/makefile for the line:
+#       ##  NOTE: add a new EXTRAINCDIR when you add a new HWP
+#   - Add new line just after it:
+#       EXTRAINCDIR += ${ROOTPATH}/src/usr/hwpf/hwp/@istepname/@substepname
+#   - Scan further for the line:
+#       ##  NOTE: add a new directory onto the vpaths when you add a new HWP
+#   - Add new line just after it:
+#       VPATH += ${ROOTPATH}/src/usr/hwpf/hwp/@istepname/@substepname
+#   - Scan further for the line:
+#       OBJS = ??
+#   - Append $substepname.o on to the end of it.  May have to wrap at 80 chars  
+#
+#        Make sure you add the lines
+#            ## pointer to common HWP files
+#            EXTRAINCDIR += ${ROOTPATH}/src/usr/hwpf/hwp/include
+#        to the makefiles.
+#
+#   * Update all the other makefiles:
+#       src/usr/hwpf/hwp/makefile   ( add SUBDIR )
+#       src/usr/hwpf/makefile       ( add to HWP_ERROR_XML_FILES, see below )
+#       src/usr/makefile            ( add to EXTENDED_MODULES )
+#
+
+#   Make a new istep<@istepnum>list.H file in /usr/include/isteps/
+#   Add the new istep<@istepnum>list.H file to src/include/usr/istepmasterlist.H
+#       in the correct place in the master istep list.
+#
+#   Create a tag block, usually in src/usr/hwpf/hwp/<@istepname>/<@istepname.H>
+#       At present this is optional, but the (coming) genIstep.pl script will 
+#       not be able to maintain your istep without it. 
+#
+#   The tag block keywords, with explanations, are as follows:
+#   *   @tag isteplist
+#       - should be at the beginning of the block to tell the (mythical) perl
+#           script that this will generate an IStep wrapper for an HWP
+#   *   @docversion     (version # of Dean's IPL document)
+#       - adds a comment to istep<@istepname>list.H
+#   *   @istepname      ( istep name from Dean's IPL document )
+#       - creates a namespace ISTEP_NAME, i.e. uppercased <@istepame>
+#           in <@istepname>.C and <@istepname>.H
+#       - creates a new component id in src/include/usr/hbotcompid.H
+#       - creates a new module id in src/include/usr/initsvcreasoncodes.H
+#       - creates a modulename string "<@istepname>.so" for istep<@istepnum>list.H
+#       - ?
+#   *   @istepnum       (istep number from Dean's IPL document)
+#       - creates a new istep<@istepnum>list.H file in /usr/include/isteps/
+#       - adds the new istep<@istepnum>list.H file to src/include/usr/istepmasterlist.H
+#           in the correct place in the master istep list.
+#       - sets the istep number in the ISTEPNAME() macro in istep<@istepnum>list.H
+#   *   @istepdesc      ( description of istep from Dean's document )
+#       - creates comments in istep<@istepnum>list.H file
+#   -- one or more substep blocks:
+#   *   @substepname     (substepname from Dean's document)
+#       - creates a prototype for <@substepname>
+#   *   @substepnum     ( number of substep from Dean's document )
+#       - sets the istep number in the ISTEPNAME() macro in istep<@istepnum>list.H
+#           @target_sched  ( serial or parallel )
+#           - will attempt to run each target either serially or in parallel
+#       --  0 or more target types to be used as parameters to HWP
+#           TBD needs work
+#           @target_type    (type or class of targets that this HWP should run under)
+#           - adds code to find the targets used in TARGETING
+#
+#
+#   Make up a new directory  src/usr/hwpf/hwp/<@istepname>/<@substepname>
+#   Copy code for new HWP to src/usr/hwpf/hwp/<@istepname>/<@substepname>. using git.
+#       For example, to set up for istep 11.7, proc_gen_framelock :
+#       ## cutNpaste the fetch comand from Gerrit.  See the webpage at
+#       ##  http://gfw160.austin.ibm.com:8080/gerrit/#change,597
+#       git fetch ssh://wenning@gfw160.austin.ibm.com:29418/hwp_review_centaur refs/changes/97/597/3
+#       ##  then run the git command to put the code in the right directory:
+#       git diff FETCH_HEAD FETCH_HEAD~1 -R | git apply --directory=src/usr/hwpf/hwp/dmi_training/proc_gen_framelock
+#
+#   Add makefile support for the new HWP:
+#   - Scan src/usr/hwpf/hwp/@substepname/makefile for the line:
+#       ##  NOTE: add a new EXTRAINCDIR when you add a new HWP
+#   - Add new line just after it:
+#       EXTRAINCDIR += ${ROOTPATH}/src/usr/hwpf/hwp/@istepname/@substepname
+#   - Scan further for the line:
+#       ##  NOTE: add a new directory onto the vpaths when you add a new HWP
+#   - Add new line just after it:
+#       VPATH += ${ROOTPATH}/src/usr/hwpf/hwp/@istepname/@substepname
+#   - Scan further for the line:
+#       OBJS = ??
+#   - Append $substepname.o on to the end of it.  May have to wrap at 80 chars  
+#       
+#   Part of the HWP source should (may??) be a <@substep>.xml file .
+#   - Update hwpf/makefile to process the xml file  in the
+#       Source XML files section:
+#       #------------------------------------------------------------------------------
+#       # Source XML files
+#       #------------------------------------------------------------------------------
+#       HWP_ERROR_XML_FILES = ...
+#
+
+
+#------------------------------------------------------------------------------
+# Specify perl modules to use
+#------------------------------------------------------------------------------
+use strict;
+use warnings;
+use POSIX;
+use Getopt::Long;
+## use Getopt::Long qw(GetOptionsFromString) ;
+use File::Basename;
+use lib dirname (__FILE__);
+
+
+#------------------------------------------------------------------------------
+# Constants
+#------------------------------------------------------------------------------
+use constant    ERR_INVALID_START_TAG   =>  1;
+use constant    ERR_DUPLICATE_TAG       =>  2;
+use constant    ERR_NO_TAG_FILE         =>  3;
+use constant    ERR_NO_ISTEP_DIR        =>  4;
+use constant    ERR_NO_TAG_BLOCK        =>  5;
+use constant    ERR_NO_ISTEP_LIST_DIR   =>  6;
+
+
+#------------------------------------------------------------------------------
+# Forward Declaration
+#------------------------------------------------------------------------------
+sub printUsage;
+sub extractTagBlock;
+sub processBlock;
+sub storeTagInHash;
+sub createIstepHFile;
+sub createIstepCFile;
+sub createIstepListFile;
+
+#------------------------------------------------------------------------------
+# Globals
+#------------------------------------------------------------------------------
+my  %Hash       =   ();
+my  $Tag_Block   =   "";
+
+#####################################################################
+#####   begin   templateHFileHdr    #################################
+my  $templateHFileHdr   =
+"
+#ifndef  __\@\@istepname_\@\@istepname_H
+#define  __\@\@istepname_\@\@istepname_H
+
+/**
+ *  \@file \@istepname.H
+ *
+ *  \@istepdesc
+ *
+ *  All of the following routines are \"named isteps\" - they are invoked as
+ *  tasks by the \@ref IStepDispatcher.
+ *
+ *  *****************************************************************
+ *  THIS FILE WAS GENERATED ON \@timestamp
+ *  *****************************************************************
+ *
+ */
+
+/*@ 
+\@tag_block
+ */
+/******************************************************************************/
+// Includes
+/******************************************************************************/
+#include    <stdint.h>
+
+namespace   \@\@istepname
+{
+";
+#####   end     templateHFileHdr    #################################
+#####################################################################
+
+#####################################################################
+#####   begin   templateHFileSubStep    #############################
+my  $templateHFileSubStep   =
+"
+/**
+ *  \@brief   \@substepname
+ *
+ *  \@istepnum.\@substepnum : \@substepdesc
+ *
+ *  param[in,out] io_pArgs  -   (normally) a pointer to a TaskArgs struct,
+ *                              or NULL.
+ *  return  none
+ *
+ */
+void    call_\@substepname( void * io_pArgs );
+";
+#####   end     templateHFileSubStep    #############################
+#####################################################################
+    
+
+#####################################################################
+#####   begin   templateHFileTrailer   ##############################
+my  $templateHFileTrailer    =
+"
+};   // end namespace
+
+#endif
+";
+#####   end templateHFileTrailer    #################################
+#####################################################################
+
+
+#####################################################################
+#####   begin   templateCFileHdr    #################################
+my  $templateCFileHdr   =
+"   
+/**
+ *  \@file \@istepname.C                                                
+ *
+ *  Support file for IStep: \@istepname                                                    
+ *   \@istepdesc
+ *
+ *  *****************************************************************
+ *  THIS FILE WAS GENERATED ON \@timestamp
+ *  *****************************************************************
+ *
+ */
+
+/******************************************************************************/
+// Includes
+/******************************************************************************/
+#include    <stdint.h>
+
+#include    <trace/interface.H>
+#include    <initservice/taskargs.H>
+#include    <errl/errlentry.H>
+
+#include    <initservice/isteps_trace.H>
+
+//  targeting support
+#include    <targeting/attributes.H>
+#include    <targeting/entitypath.H>
+#include    <targeting/target.H>
+#include    <targeting/targetservice.H>
+#include    <targeting/iterators/rangefilter.H>
+#include    <targeting/predicates/predicatectm.H>
+#include    <targeting/predicates/predicatepostfixexpr.H>
+#include    <targeting/predicates/predicateisfunctional.H>
+
+//  fapi support
+#include    <fapi.H>
+#include    <fapiPlatHwpInvoker.H>
+
+
+//  --  prototype   includes    --
+//  Add any customized routines that you don't want overwritten into
+//      \"\@istepname_custom.C\" and include the prototypes here.
+//  #include    \"\@istepname_custom.H\"
+
+#include    \"\@istepname.H\"          
+                                  
+//  Uncomment these files as they become available:
+";
+#####   end templateCFileHdr    #####################################
+#####################################################################
+
+
+#####################################################################                                                      
+#####   begin templateCFileNSHdr    #####################################
+my  $templateCFileNSHdr  =
+"
+namespace   \@\@istepname                                              
+{
+
+using   namespace   TARGETING;
+using   namespace   fapi;
+";      
+#####   end templateCFileNSHdr    #####################################
+#####################################################################
+
+
+#####################################################################
+#####   begin   templateCFileSubStep    #############################
+my $templateCFileSubStep =
+"
+//
+//  Wrapper function to call \@istepnum.\@substepnum : \@substepname
+//
+void    call_\@substepname( void *io_pArgs )
+{
+    //  \@todo   remove when join() merged
+    INITSERVICE::TaskArgs *pTaskArgs =
+            static_cast<INITSERVICE::TaskArgs *>( io_pArgs );
+    fapi::ReturnCode    l_fapirc;
+
+    TRACDCOMP( ISTEPS_TRACE::g_trac_isteps_trace, \"call_\@substepname entry\" );
+        
+#if 0
+    // \@\@\@\@\@    CUSTOM BLOCK:   \@\@\@\@\@    
+    //  figure out what targets we need
+    //  customize any other inputs
+    //  set up loops to go through all targets (if parallel, spin off a task)
+    
+    //  print call to hwp and dump physical path of the target(s)
+    TRACFCOMP( ISTEPS_TRACE::ISTEPS_TRACE::g_trac_isteps_traces_trace,
+                    \"=====  \@substepname HWP(? ? ? )\",
+                    ?
+                    ?
+                    ? );
+    //  dump physical path to targets
+    EntityPath l_path;
+    l_path  =   l_\@targetN_target->getAttr<ATTR_PHYS_PATH>();
+    l_path.dump();
+    TRACFCOMP( g_trac_mc_init, \"===== \" );   
+
+    // cast OUR type of target to a FAPI type of target.                         
+    const fapi::Target l_fapi_\@targetN_target(
+                    TARGET_TYPE_MEMBUF_CHIP,
+                    reinterpret_cast<void *>
+                        (const_cast<TARGETING::Target*>(l_\@targetN_target)) );
+                    
+    //  call the HWP with each fapi::Target
+    l_fapirc  =   \@substepname( ? , ?, ? );
+
+    //  process return code.
+    if ( l_fapirc== fapi::FAPI_RC_SUCCESS )
+    {
+        TRACFCOMP( ISTEPS_TRACE::ISTEPS_TRACE::g_trac_isteps_traces_trace,
+                \"SUCCESS :  \@substepname HWP(? ? ? )\" );
+    }
+    else
+    {
+        /**
+         * \@todo fapi error - just print out for now...
+         */
+        TRACFCOMP( ISTEPS_TRACE::g_trac_isteps_trace,
+                \"ERROR %d:  \@substepname HWP(? ? ?) \",
+                static_cast<uint32_t>(l_fapirc) );
+    }
+    // \@\@\@\@\@    END CUSTOM BLOCK:   \@\@\@\@\@    
+#endif
+
+    TRACDCOMP( ISTEPS_TRACE::g_trac_isteps_trace, \"call_\@substepname exit\" );
+
+    //  end the task.
+    pTaskArgs->waitChildSync();     // \@todo remove when join() merged
+    task_end();
+}
+";
+#####   end templateCFileSubStep    ################################# 
+#####################################################################
+
+
+#####################################################################
+#####   begin   templateCfileTrailer    #############################
+my  $templateCFileTrailer    =  
+"
+};   // end namespace
+";
+#####   end     templateCFileTrailer    #############################
+#####################################################################
+
+
+
+#####################################################################
+#####   begin   templateListFileHdr1   #############################
+my  $templateListFileHdr1 =   
+"
+#ifndef __ISTEPS_ISTEP\@istepnumLIST_H
+#define __ISTEPS_ISTEP\@istepnumLIST_H
+
+/**
+ * \@file    istep\@istepnumlist.H
+ *
+ *  IStep \@istepnum    \@istepdesc
+ *  IPL FLow Doc        \@docversion
+ *
+";
+ #####   end     templateListFileHdr1    #############################
+#####################################################################
+
+ 
+#####################################################################
+#####   begin   templateListFileHdr2   #############################
+ my $templateListFileHdr2    =   
+" *
+ *  *****************************************************************
+ *  THIS FILE WAS GENERATED ON \@timestamp
+ *  *****************************************************************
+ *
+ *  Please see the note in initsvcstructs.H for description of
+ *      the ISTEPNAME macro.
+ *
+ */
+
+#include    <initservice/initsvcstructs.H>
+#include    <initservice/initsvcreasoncodes.H>
+
+//  include prototypes file
+#include    \"../../../usr/hwpf/hwp/\@istepname/\@istepname.H\"
+
+namespace   INITSERVICE
+{
+    const   TaskInfo    g_istep\@istepnum[]  =   {
+        // NOTE:  IStep indexes start with 0
+";
+#####   end     templateListFileHdr2    #############################
+#####################################################################
+
+
+#####################################################################
+#####   begin   templateListFileSS  #################################
+my  $templateListFileSS  =   
+"        {
+                ISTEPNAME(\@istepnum,\@-substepnum,\"\@substepname\"),
+                \@\@istepname::call_\@substepname,
+                {
+                        START_FN,
+                        EXT_IMAGE,
+                        ISTEP_ERRL_ID,
+                }
+        },      
+";        
+#####   end     templateListFileSS    #############################
+#####################################################################
+
+
+#####################################################################
+#####   begin   templateListFileTrailer  ############################
+my  $templateListFileTrailer =
+"  
+        //  END OF LIST!
+};
+
+// make a struct from the above with the number of items included
+const   ExtTaskInfo g_istep\@istepnumTaskList    =   {
+        &(g_istep\@istepnum[0]),
+        ( sizeof(g_istep\@istepnum)/sizeof(TaskInfo) ),
+        NULL    //  later, depModules struct
+};
+
+};  // end namespace
+
+#endif
+";
+#####   end     templateListFileTrailer    #############################
+#####################################################################
+
+
+#==============================================================================
+# MAIN
+#==============================================================================
+my  $pgmDir  =   `dirname $0`;
+chomp( $pgmDir );
+
+my $hbDir = $ENV{'HBDIR'};
+if ( ! defined( $hbDir) || ( $hbDir eq "" ) )
+{
+    $hbDir = $pgmDir;               ##  Set to tool directory
+}
+
+
+## print   $#ARGV;
+if ( $#ARGV < 0 )
+{
+    printUsage();
+    exit    0 ;
+}
+#------------------------------------------------------------------------------
+# Parse optional input arguments
+#------------------------------------------------------------------------------
+my  $opt_help       =   0;
+my  $opt_tag_file   =   "";
+my  $opt_dry_run    =   0;
+my  $opt_debug      =   0;
+my  $istepDir       =   "";
+my  $istepListDir   =   "src/include/usr/isteps";
+
+#####
+##  This should work, but doesn't.
+##  my  %optHash    =   (     'help|?'        => \$opt_help,
+##                            'tag-file=s'    => \$opt_tag_file,
+##                            'dry-run'       => \$opt_dry_run,
+##                            'debug'         => \$opt_debug,
+##                            );
+##  GetOptionsFromArray( \%optHash, \@ARGV,
+##            'help|?',
+##            'debug',
+##            'tag-file=s',
+##            'dry-run'
+##            );
+#####
+
+GetOptions( 'help|?'            => \$opt_help,
+            'tag-file=s'        => \$opt_tag_file,
+            'istep-dir=s'       => \$istepDir,
+            'istep-list-dir=s'  =>  \$istepListDir,
+            'dry-run'           => \$opt_dry_run,
+            'debug'             => \$opt_debug,
+            );
+            
+if  ( $opt_debug )
+{
+    print   STDERR  "help       =   $opt_help\n";
+    print   STDERR  "debug      =   $opt_debug\n";
+    print   STDERR  "tag-file   =   $opt_tag_file\n";
+    print   STDERR  "dry-run    =   $opt_dry_run\n";
+    print   STDERR  "istepDir   =   $istepDir\n";
+}
+
+
+##  check for required options
+if ( $opt_tag_file  eq  "" )
+{   
+    print   STDOUT  "No tag file specified\n";
+    printUsage();
+    exit    ERR_NO_TAG_FILE;
+}
+
+if ( $istepDir  eq  "" )
+{
+    print   STDOUT  "No istep-dir specified.\n";
+    exit    ERR_NO_ISTEP_DIR;
+}
+
+if ( $istepListDir  eq  "" )
+{
+    print   STDOUT  "No istep-list-dir specified.\n";
+    exit    ERR_NO_ISTEP_LIST_DIR;
+}
+
+if ( ! -e $opt_tag_file )
+{
+    print STDOUT    "Tag file $opt_tag_file doesn't exist\n";
+    exit ERR_NO_TAG_FILE;
+}
+
+if (    ( ! -e $istepDir )
+     || ( ! -d $istepDir )
+    )
+{
+    print STDOUT    "dir $istepDir doesn't exist.\n";
+    exit    ERR_NO_ISTEP_DIR;
+}
+
+if (    ( ! -e $istepListDir )
+     || ( ! -d $istepListDir )
+    )
+{
+    print STDOUT    "dir $istepListDir doesn't exist.\n";
+    exit    ERR_NO_ISTEP_LIST_DIR;
+}
+
+##  extract tag block
+if ( extractTagBlock( $opt_tag_file )  != 0 ) 
+{
+    print   STDOUT  "No Tag block in $opt_tag_file.\n";
+    exit    ERR_NO_TAG_BLOCK;
+}
+
+##  strip comment junk  from Tag Block
+$Tag_Block =~ s/^(\*|\s)*//gmo;
+
+##  split cleaned up lines from Tag_block into an array
+my  @tag_lines  =   split /^/, $Tag_Block;
+ 
+## print STDERR    "@tag_lines";
+  
+##  check to make sure this is the correct tag file
+if ( $opt_debug )   {   print "--$tag_lines[0]\n";    }
+if (    ( !defined $tag_lines[0] )    
+     || ( ! ($tag_lines[0] =~ m/^(\*|\s)*\@.*tag\s+isteplist/) )
+    )
+{
+    print   STDOUT  "ERROR: The first line of the tag block MUST be \"\@tag isteplist\"\n";  
+    exit    ERR_INVALID_START_TAG;    
+}
+    
+##  OK, start storing tag values
+while ( $_ = shift( @tag_lines ) )
+{
+    if ( ! defined $_ ) 
+    {   
+        if ( $opt_debug )   {   print STDERR    "Done.\n";  }
+        last;  
+    }
+    
+    ##  strip junk at the beginning
+    s/^(\*|\s)*//;
+    
+    chomp;
+    if ( $opt_debug )   {   print   "-$_\n";    }   
+    
+    if  ( m/\@\{/ )
+    {
+        ##  process the tag block
+        processBlock( \@tag_lines );    
+    } 
+    
+    if  ( m/\@docversion/ )
+    {
+        s/^\@docversion\s+//;
+        storeTagInHash( "docversion", $_ );
+    }
+    
+    if  ( m/\@istepname/ )
+    {        
+        s/^\@istepname\s+//;
+        storeTagInHash( "istepname", $_ );
+    }
+    
+    if  ( m/\@istepnum/  )
+    {
+        s/^\@istepnum\s+//;
+        storeTagInHash( "istepnum", $_ );
+    }
+       
+    if  ( m/\@istepdesc/ )
+    {        
+        s/^\@istepdesc\s+//;
+        storeTagInHash( "istepdesc", $_ );   
+    }
+}
+
+##  -----   Begin writing the files.    ---------------------------------
+
+#   Make up (or modify) src/usr/hwpf/hwp/<@istepname>/<@istepname.H>    
+#       (use src/usr/hwpf/hwp/template.H as a template)
+createIstepHFile( );
+
+#   Make up a new file src/usr/hwpf/hwp/<@istepname>/<@istepname.C>
+#      (use src/usr/hwpf/hwp/template.C as a template)
+createIstepCFile( );
+       
+createIstepListFile( );
+       
+print   STDOUT  "Done.\n";
+
+#==============================================================================
+# SUBROUTINES
+#==============================================================================
+
+##
+##  Print the usage (help) message
+##  
+sub printUsage()
+{
+    print   STDOUT  "genIStep.pl\n";
+    print   STDOUT  "   --tag-file <path>           ( required: file containing tag block )\n";
+    print   STDOUT  "   --istep-dir <path>          ( required: directory where istep code will be generated )\n";
+    
+    print   STDOUT  "   [ --istep-list-dir <path> ] ( directory where istepNlist.H will be generated\n"; 
+    print   STDOUT  "                               ( this is usually src/include/usr/isteps )\n";
+    print   STDOUT  "   [ --help ]                  ( prints usage message )\n";
+    ## print   STDOUT  "    [ --dry-run ]       ( prints all steps without doing anything )\n";
+}
+
+
+##
+##  extract tag block from the passed-in file and put in the global $Tag_Block
+##
+sub extractTagBlock( $ )
+{
+    my  ( $in_tag_file )    =   @_;
+    my  $data   =   "";
+    
+    open( TAGFH, "< $in_tag_file") or die " $? : can't open $in_tag_file : $!";
+    read( TAGFH, $data, -s TAGFH ) or die "Error reading $in_tag_file: $!";
+    close TAGFH;
+
+    # =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+    # Capture everything from opening '/* @tag isteplist' to end of tags '*/'
+    #
+    # Example:
+    #   /*@
+    #    *  @tag    isteplist
+    #    *  ...
+    #    */
+    # =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+    ##  Extract Tag block
+    while ($data =~ /\/\*\@((.|\n)+?)\*\//mgo )
+    {
+        $Tag_Block = $1; 
+    }    
+    
+    if ( $Tag_Block eq  "" )
+    {
+        return  1;
+    }
+
+
+    
+    if ( $opt_debug )   
+    { 
+        print STDERR "debug: Extracted Tag Block: \n$Tag_Block\n"; 
+    }
+    
+    return  0;
+}
+
+##
+##  Store a tag in the hash table, given a key and value
+##      @param  $key    -   key
+##      @param  $value  -   value   
+##
+sub storeTagInHash( $$ )
+{
+    my ( $key, $value ) =   @_;
+    my  $rc =   0;
+ 
+    if  ( exists  $Hash{ $key } )
+    {
+        print   STDOUT  "ERROR: duplicate tag \"$key\" \n";
+        $rc =   ERR_DUPLICATE_TAG;
+    }
+    else
+    {
+        $Hash{ $key } =   $value;
+    }
+    
+    if ( $opt_debug )   {   print STDERR "storetag: $key = $Hash{ $key }\n";  }
+    
+    return  $rc;
+}    
+
+
+##
+##  process a tag block from the caller
+##  Note that this is passed a reference to the 
+##  original array so that we can shift the array 
+##  as we use up lines.
+sub processBlock( $ )
+{
+    my  (@tag_block)    =   @{$_[0]};               # this is actually a copy
+    my  %localhash      =   ();
+    
+    while ( $_  =   shift( @{$_[0]} ) )             ##@tag_block)  )
+    {
+        chomp;
+        if ( $opt_debug )   {   print   "process:   $_\n";  }
+        if ( m/\@}/ )
+        {
+            if ( $opt_debug )   {   print   "$_ : done.\n"; }
+            last;
+        }
+        
+        if  (   m/\@substepnum/  )
+        {
+            s/^\@substepnum\s+//;
+            #storeTagInHash( \%localhash, "substepnum", $_ );
+            $localhash{'substepnum'}    =   $_;
+        }
+                
+        if  (   m/\@substepname/ )
+        {
+            s/^\@substepname\s+//;
+            #storeTagInHash( \%localhash, "substepname", $_ );
+            $localhash{'substepname'}    =   $_;
+        }        
+        
+        if  (   m/\@substepdesc/ )
+        {
+            s/^\@substepdesc\s+//;
+            #storeTagInHash( \%localhash, "substepdesc", $_ );
+            $localhash{'substepdesc'}    =   $_;
+        } 
+        
+                      
+        if  (   m/\@target_sched/    )
+        {
+            s/^\@target_sched\s+//;
+            #storeTagInHash( \%localhash, "target_sched", $_ );
+            $localhash{'target_sched'}  =   $_;
+        }        
+    }
+    
+    ##  Store results in %Hash using keys like "<key>:<substepnum>"
+    ##      Keep it easy and flat.  
+    if (    ( exists $localhash{'substepname'} )
+         && ( exists $localhash{'substepnum' } )
+        )
+    {
+        my  $num    =   sprintf( "%2.2d", int($localhash{'substepnum'}) ); 
+        $Hash{ "substepname:$num"}= $localhash{'substepname'};
+        $Hash{ "substepnum:$num"}= $localhash{'substepnum'};
+        
+        if (exists $localhash{'substepdesc'} )
+        {
+            $Hash{ "substepdesc:$num"}= $localhash{'substepdesc'};
+        }
+                
+        if (exists $localhash{'target_sched'} )
+        {
+            $Hash{ "target_sched:$num"}= $localhash{'target_sched'};
+        }
+    }
+    else
+    {
+        print   STDOUT  "Incomplete tag block for $localhash{'substepname'}\n";
+           
+    }  
+}
+
+##
+##  Back up old file before we start modifying it, if it exists.
+##
+sub backupOldFile( $ )
+{
+    my  $backupFileName  =   shift;
+    
+    if ( $opt_debug )   
+    {   
+        print   STDERR  "backing up $backupFileName, if necessary...\n";    
+    }
+    
+    if ( -e $backupFileName )
+    {
+        my  $ts  =   `date +%Y-%m-%d.%H%M`;
+        chomp   $ts;
+        my  $old_file   =   "$backupFileName.org_$ts";
+        print   STDOUT  "   $backupFileName exists, renaming to $old_file\n"; 
+        rename( $backupFileName, "$old_file" );
+    }
+}
+
+##  
+##  Apply all the tags that belong to the istep to a multiline string
+##      @docversion
+##      @istepname
+##      @istepnum
+##      @istepdesc
+##
+##  param[in,out]   -   ref to a multiline string
+##
+##  Assumes that the istep tag values stored in the correct place in %Hash
+##
+sub applyIstepTags
+{   
+    my  $str_ref    =   shift;
+    my  $istepname  =  $Hash{'istepname'};  
+    my  $istepnum   =   $Hash{'istepnum'};
+    my  $docversion =   $Hash{'docversion'};
+    my  $istepdesc  =   $Hash{'istepdesc'};
+    my  $upCaseistepname =   toupper( $istepname );
+    my  $timestamp  =   `date +%Y-%m-%d:%H%M`;
+    chomp   $timestamp;
+    
+    ${$str_ref}    =~  s/\@timestamp/$timestamp/gmo;
+    #   replace "@@istepname"
+    ${$str_ref}    =~  s/\@\@istepname/$upCaseistepname/gmo;
+    #   replace "@istepname"
+    ${$str_ref}    =~  s/\@istepname/$istepname/gmo;
+    #   replace "istepnum"
+    ${$str_ref}    =~  s/\@istepnum/$istepnum/gmo;    
+    #   replace "@istepdesc"
+    ${$str_ref}    =~  s/\@istepdesc/$istepdesc/gmo; 
+    #   replace "@docversion"
+    ${$str_ref}    =~  s/\@docversion/$docversion/gmo; 
+    
+}
+
+##
+##  Make up a new file src/usr/hwpf/hwp/<@istepname>/<@istepname.H>
+##   (use src/usr/hwpf/hwp/template.H as a template)Create the IstepHFile( )
+##  This creates a new file, it will not carry anything over from an old file
+##  Instead, it will rename the old file to <file>.org_YYYY.MM.DD:HHDD
+##
+sub createIstepHFile( )
+{
+    my  $istepname  =  $Hash{'istepname'};
+    my  $istepHfile =   "$istepDir/$istepname.H";
+    
+    print STDOUT  "Create file $istepHfile...\n";
+    
+    ## @todo sanity check - $istepDir should be src/usr/hwpf/hwp/<@istepname>/
+    
+    backupOldFile( $istepHfile );
+    
+    open( HFH, "> $istepHfile") or die " $? : can't open $istepHfile : $!";
+    
+    ##  apply all the istep tags to the header
+    applyIstepTags( \$templateHFileHdr );
+    
+    ##  add the original tag block as comments.
+    my  $cleaned_up_tag_block   =   $Tag_Block;
+    chomp   $cleaned_up_tag_block;
+    $cleaned_up_tag_block   =~  s/^/ * /gmo;
+    $templateHFileHdr   =~  s/\@tag_block/$cleaned_up_tag_block/gmo;
+    
+    print   HFH "$templateHFileHdr\n";
+    
+    ##  generate substeps
+    my  @substepnames   =   sort grep /substepname/,    ( keys %Hash );
+    my  @substepnums    =   sort grep /substepnum/,     ( keys %Hash ); 
+    my  @substepdescs   =   sort grep /substepdesc/,    ( keys %Hash ); 
+        if ( $opt_debug )
+    {
+        
+        print   "$istepname.H file: @substepnames\n";
+        print   STDERR  "substeps last index = $#substepnames.\n";
+    }
+    
+    ##  write each substep section 
+    for ( my $i=0; $i<=$#substepnames; $i++ ) 
+    {
+        ##  make a local copy to modify
+        my  $templateHSS =   $templateHFileSubStep;
+        applyIstepTags( \$templateHSS );
+        
+        #   replace "@substepname"
+        $templateHSS    =~  s/\@substepname/$Hash{$substepnames[$i]}/gmo;
+        #   replace "substepnum"
+        $templateHSS    =~  s/\@substepnum/$Hash{$substepnums[$i]}/gmo;    
+        #   replace "@substepdesc"
+        $templateHSS    =~  s/\@substepdesc/$Hash{$substepdescs[$i]}/gmo; 
+        
+        print   HFH "\n$templateHSS\n";
+    }
+    
+    print   HFH "$templateHFileTrailer\n";  
+    
+    
+    close   HFH;
+}
+
+
+##
+##  Make up a new file src/usr/hwpf/hwp/<@istepname>/<@istepname.C>
+##      (use src/usr/hwpf/hwp/template.C as a template)
+##  This creates a new file, it will not carry anything over from an old file
+##  Instead, it will rename the old file to <file>.org_YYYY.MM.DD:HHDD
+##
+sub createIstepCFile( )
+{    
+    my  $istepname  =  $Hash{'istepname'};  
+    my  $istepCfile =   "$istepDir/$istepname.C";
+    
+    print STDOUT  "Create file $istepCfile...\n"; 
+    
+    ## sanity check - $istepDir should be src/usr/hwpf/hwp/<@istepname>/
+    
+    backupOldFile( $istepCfile );
+
+    open( CFH, "> $istepCfile") or die " $? : can't open $istepCfile : $!";
+     
+    applyIstepTags( \$templateCFileHdr );
+    print   CFH "$templateCFileHdr";
+    
+    ##  generate substeps
+    my  @substepnames   =   sort grep /substepname/,    ( keys %Hash );
+    my  @substepnums    =   sort grep /substepnum/,     ( keys %Hash ); 
+    my  @substepdescs   =   sort grep /substepdesc/,    ( keys %Hash ); 
+    if ( $opt_debug )
+    {
+        
+        print   "$istepname.C file: @substepnames\n";
+        print   STDERR  "substeps last index = $#substepnames\n";
+    }
+   
+    ##  Write the lines to include the hwp h file
+    for ( my $i=0; $i<=$#substepnames; $i++ ) 
+    {
+        ##  Write the line to include the hwp h file
+        print   CFH "// #include    \"$Hash{$substepnames[$i]}/$Hash{$substepnames[$i]}.H\"\n"; 
+    } 
+    
+    applyIstepTags( \$templateCFileNSHdr );
+    print   CFH "$templateCFileNSHdr\n"; 
+    
+    ##  write each substep section 
+    for ( my $i=0; $i<=$#substepnames; $i++ ) 
+    {
+        ##  make a local copy to modify
+        my  $templateCSS =   $templateCFileSubStep;
+        applyIstepTags( \$templateCSS );
+        
+        #   replace "@substepname"
+        $templateCSS    =~  s/\@substepname/$Hash{$substepnames[$i]}/gmo;
+        #   replace "substepnum"
+        $templateCSS    =~  s/\@substepnum/$Hash{$substepnums[$i]}/gmo;    
+        #   replace "@substepdesc"
+        $templateCSS    =~  s/\@substepdesc/$Hash{$substepdescs[$i]}/gmo; 
+        
+        print   CFH "\n$templateCSS\n";
+    }
+    
+    print   CFH "$templateCFileTrailer";
+    
+    close( CFH );
+}
+
+##
+##  3. [ ]  Make a new istep<@istepnum>list.H file in /usr/include/isteps/
+##          Add the new istep<@istepnum>list.H file to 
+##          src/include/usr/istepmasterlist.H in the correct place in the 
+##          master istep list.
+##
+sub createIstepListFile( )
+{
+
+    my  $istepname  =   $Hash{'istepname'};
+    my  $istepnum   =   $Hash{'istepnum'};  
+    my  $istepLfile =   $istepListDir . "/istep" . $istepnum . "list.H";
+    
+    print STDOUT  "Create file $istepLfile...\n"; 
+    
+    ## sanity check - $istepListDir should be src/include/usr/isteps
+    
+    backupOldFile( $istepLfile );
+    
+    open( LFH, "> $istepLfile") or die " $? : can't open $istepLfile : $!";
+     
+    applyIstepTags( \$templateListFileHdr1 );
+    print   LFH "$templateListFileHdr1";
+    
+    ##  generate substeps
+    my  @substepnames   =   sort grep /substepname/,    ( keys %Hash );
+    my  @substepnums    =   sort grep /substepnum/,     ( keys %Hash ); 
+    my  @substepdescs   =   sort grep /substepdesc/,    ( keys %Hash ); 
+    if ( $opt_debug )
+    {
+        
+        print   "$istepname.C file: @substepnames\n";
+        print   STDERR  "substeps last index = $#substepnames\n";
+    }
+    
+    ##   write the documentation lines in the istepNlist file
+    for ( my $i=0; $i<=$#substepnames; $i++ ) 
+    {
+        print   LFH " *  $istepnum.$Hash{$substepnums[$i]}\t  $Hash{$substepnames[$i]}\n";
+        print   LFH " *  \t$Hash{$substepdescs[$i]}\n";   
+    }
+    
+    applyIstepTags( \$templateListFileHdr2 );
+    print   LFH "$templateListFileHdr2";
+    
+   
+    ##  write each substep section 
+    for ( my $i=0; $i<=$#substepnames; $i++ ) 
+    {
+        ##  make a local copy to modify
+        my  $templateLSS =   $templateListFileSS;
+        applyIstepTags( \$templateLSS );
+        
+        #   replace "@substepname"
+        $templateLSS    =~  s/\@substepname/$Hash{$substepnames[$i]}/gmo;
+        #   replace "substepnum"
+        $templateLSS    =~  s/\@substepnum/$Hash{$substepnums[$i]}/gmo;    
+        #   replace "@substepdesc"
+        $templateLSS    =~  s/\@substepdesc/$Hash{$substepdescs[$i]}/gmo;
+  
+        ## @todo - the substep indices have to start with 0, but of course
+        ##          the substeps start at 1.  We have to compensate for this
+        ##          with a special tag...
+        ##          This needs to be fixed by modifying lookupTask, etc., in the
+        ##          istepDispatcher
+        #   replace "@-substepnum"
+        my  $hackedSSnum =   $Hash{$substepnums[$i]} - 1; 
+        $templateLSS    =~  s/\@-substepnum/$hackedSSnum/gmo;  
+              
+        print   LFH "\n$templateLSS\n";
+    }
+    
+    applyIstepTags( \$templateListFileTrailer );
+    print   LFH "$templateListFileTrailer";
+    
+    
+    close   LFH;
+}
+
+
+__END__