Add Perl Debug-Framework.

Change-Id: Idc3ba97083a64616a2f3b9e73b4c4c9e1ee1c710
Reviewed-on: http://gfw160.austin.ibm.com:8080/gerrit/473
Tested-by: Jenkins Server
Reviewed-by: A. Patrick Williams III <iawillia@us.ibm.com>

6 files changed, 922 insertions, 0 deletions

diff --git a/src/build/debug/Hostboot/DebugFramework.pm b/src/build/debug/Hostboot/DebugFramework.pm
new file mode 100755
index 000000000..5bdedd4df
--- /dev/null
+++ b/src/build/debug/Hostboot/DebugFramework.pm
@@ -0,0 +1,372 @@
+#!/usr/bin/perl
+
+# DebugFramework.pm
+#
+# This module is a set of utility functions for the debug framework, which 
+# should be common across all debug framework environments.
+#
+# The module provides the functions listed below in @EXPORT.
+#
+# A debug framework environment is expected to implement the following
+# functions:
+#     * getIsTest() - Is the image loaded a test image or normal?
+#     * getImgPath() - Path to the .../img/ directory containing debug files.
+#     * readData(addr,size) - Read a blob of memory.
+#     * userDisplay(varargs-of-mixed) - Display things to the user.
+#
+
+use strict;
+
+package Hostboot::DebugFramework;
+use Exporter 'import';
+
+our @EXPORT = ( 'callToolModule', 'callToolModuleHelp',
+                'parseToolOpts', 'determineImagePath',
+                'findSymbolAddress', 'findSymbolByAddress',
+                'findModuleByAddress',
+                'littleendian',
+                'read64', 'read32', 'read16', 'read8', 'readStr'
+              );
+
+our ($parsedSymbolFile, %symbolAddress, %addressSymbol, %symbolSize);
+our ($parsedModuleFile, %moduleAddress);
+our (%toolOpts);
+
+BEGIN
+{
+    $parsedSymbolFile = 0;
+    %symbolAddress = ();
+    %addressSymbol = ();
+    %symbolSize = ();
+
+    $parsedModuleFile = 0;
+    %moduleAddress = ();
+
+    %toolOpts = ();
+}
+return 1;
+
+# @sub callToolModule
+# 
+# Executes the 'main' function of the requested tool module.
+#
+# @param string - Tool to call.
+#
+# @pre Must have previously called parseToolOpts.
+#
+sub callToolModule
+{
+    my $tool = shift;
+    my $package = "Hostboot::$tool";
+
+    eval("use lib '.'; use $package; return 1;") or 
+            die "Couldn't load tool \"$tool\"";
+    eval("$package->main(\\%toolOpts);");
+}
+
+# @sub callToolModuleHelp
+#
+# Executes the 'help' function of the requested tool module to display 
+# tool usage.
+#
+# @param string - Tool to call.
+#
+sub callToolModuleHelp
+{
+    my $tool = shift;
+    my $package = "Hostboot::$tool";
+
+    eval("use lib '.'; use $package; return 1;") or 
+            die "Couldn't load tool \"$tool\"";
+    eval("$package->help(\\%toolOpts);");
+}
+
+# @sub parseToolOpts
+#
+# Parses a space deliminated string of options for use by the tool.
+#
+# @param string - Tool option list.
+#
+# Example: "foo bar=/abcd/efg" --> { "foo" => 1 , "bar" => "/abcd/efg" }
+#
+sub parseToolOpts
+{
+    my $toolOptions = shift;
+    foreach my $opt (split / /, $toolOptions)
+    {
+        if ($opt =~ m/=/)
+        {
+            my ($name,$value) = split /=/, $opt;
+            $toolOpts{$name} = $value;
+        }
+        else
+        {
+            $toolOpts{$opt} = 1;
+        }
+    }
+}
+
+# @sub determineImagePath
+#
+# Utility function to search for the .../img/ directory from a few well known
+# places.
+#
+# @param string - Path passed by user to the image directory.
+#
+# @returns Found path to the .../img/ directory.
+#
+sub determineImagePath
+{
+    my $imgPath = shift;
+
+    if ($imgPath eq "")
+    {
+        if ((::getIsTest() and (-e "hbicore_test.syms")) or
+            (not ::getIsTest() and (-e "hbicore.syms")))
+        {
+            $imgPath = "./";
+        }
+        else
+        {
+            $imgPath = $ENV{"HOSTBOOTROOT"} . "/img/";
+        }
+    }
+    
+    return $imgPath;
+}
+
+# @sub parseSymbolFile <INTERNAL ONLY>
+#
+# Parses through a .syms file and populates a hash.
+#
+sub parseSymbolFile
+{
+    if ($parsedSymbolFile) { return; }
+
+    my $symsFile = ::getImgPath();
+    if (::getIsTest()) 
+    { 
+        $symsFile = $symsFile."hbicore_test.syms";
+    }
+    else
+    {
+        $symsFile = $symsFile."hbicore.syms";
+    }
+    
+    open(FILE, "< $symsFile") or die;
+    while (my $line = <FILE>)
+    {
+        $line =~ m/(.*?),(.*?),(.*?),(.*?),(.*)/;
+        my $name = $5;        
+        my $addr = hex $2;
+        my $tocAddr = hex $3;
+        my $size = hex $4;
+        
+        $symbolAddress{$name} = $addr;
+        $symbolSize{$name} = $size;
+        $addressSymbol{$addr} = $name;
+        $addressSymbol{$tocAddr} = $name;
+    }
+    close(FILE);
+
+    $parsedSymbolFile = 1;
+}
+
+# @sub findSymbolAddress
+#
+# Searchs a syms file for the address of a particular symbol name.
+#
+# @param string - Symbol to search for.
+# @return array of (address, size) or (not-defined, not-defined).
+#
+sub findSymbolAddress
+{
+    my $name = shift;
+
+    parseSymbolFile();
+
+    return ($symbolAddress{$name}, $symbolSize{$name} );
+}
+
+# @sub findSymbolByAddress
+#
+# Searchs a syms file for the symbol name at a particular address.
+#
+# @param integer - Address to search for.
+# @return string name of symbol or not-defined.
+#
+sub findSymbolByAddress
+{
+    my $addr = shift;
+
+    parseSymbolFile();
+
+    return $addressSymbol{$addr};
+}
+
+# @sub parseModuleFile <INTERNAL ONLY>
+#
+# Parses through a .modinfo file and populates a hash.
+#
+sub parseModuleFile
+{
+    if ($parsedModuleFile) { return; }
+
+    my $modFile = ::getImgPath();
+    if (::getIsTest())
+    {
+        $modFile = $modFile."hbicore_test.bin.modinfo";
+    }
+    else
+    {
+        $modFile = $modFile."hbicore.bin.modinfo";
+    }
+
+    open(FILE, "< $modFile") or die;
+    while (my $line = <FILE>)
+    {
+        $line =~ m/(.*?),(.*)/;
+        $moduleAddress{$1} = hex $2;
+    }
+    close(FILE);
+
+    $parsedModuleFile = 1;
+}
+
+# @sub findSymbolByAddress
+#
+# Searchs a modinfo file for the module owning a particular address.
+#
+# @param integer - Address to search for.
+# @return string name of module or "".
+#
+sub findModuleByAddress
+{
+    my $addr = shift;
+
+    parseModuleFile();
+
+    my $addrF = -1;
+    my $modName = "";
+
+    foreach my $mod (keys %moduleAddress)
+    {
+        if (($moduleAddress{$mod} <= $addr) and
+            ($moduleAddress{$mod} > $addrF))
+        {
+            $addrF = $moduleAddress{$mod};
+            $modName = $mod;
+        }
+    }
+
+    return $modName;
+}
+
+# @sub littleendian
+#
+# Utility function to determine if the current machine is little or big
+# endian.
+#
+# @return true if machine is little-endian.
+#
+sub littleendian
+{
+    return (unpack("L", pack("N", 0xabcd1234)) != 0xabcd1234);
+}
+
+# @sub read64
+#
+# Reads a 64-bit unsigned integer from an address.
+#
+# @param Address to read from.
+# @return Value.
+#
+sub read64
+{
+    my $addr = shift;
+
+    my $result = ::readData($addr, 8);
+    if (littleendian()) { $result = reverse($result); }
+
+    return unpack("Q", $result);
+}
+
+# @sub read32
+#
+# Reads a 32-bit unsigned integer from an address.
+#
+# @param Address to read from.
+# @return Value.
+#
+sub read32
+{
+    my $addr = shift;
+
+    my $result = ::readData($addr, 4);
+    if (littleendian()) { $result = reverse($result); }
+
+    return unpack("L", $result);
+}
+
+# @sub read16
+#
+# Reads a 16-bit unsigned integer from an address.
+#
+# @param Address to read from.
+# @return Value.
+#
+sub read16
+{
+    my $addr = shift;
+
+    my $result = ::readData($addr, 2);
+    if (littleendian()) { $result = reverse($result); }
+
+    return unpack("S", $result);
+}
+
+# @sub read8
+#
+# Reads a 8-bit unsigned integer from an address.
+#
+# @param Address to read from.
+# @return Value.
+#
+sub read8
+{
+    my $addr = shift;
+
+    my $result = ::readData($addr, 1);
+    
+    return unpack("C", $result);
+}
+
+# @sub readStr
+#
+# Reads a string from an address.
+#
+# @param Address to read from.
+# @return Value.
+#
+sub readStr
+{
+    my $addr = shift;
+
+    my $result = "";
+    my $byte = 0;
+
+    do
+    {
+        $byte = read8($addr);
+        $addr += 1;
+
+        if ($byte != 0)
+        {
+            $result = $result.pack("C",$byte);
+        }
+    } while ($byte != 0);
+
+    return $result;
+}
+
+__END__
diff --git a/src/build/debug/Hostboot/Example.pm b/src/build/debug/Hostboot/Example.pm
new file mode 100755
index 000000000..25ca61365
--- /dev/null
+++ b/src/build/debug/Hostboot/Example.pm
@@ -0,0 +1,45 @@
+#!/usr/bin/perl
+#  IBM_PROLOG_BEGIN_TAG
+#  This is an automatically generated prolog.
+#
+#  $Source: src/build/debug/Hostboot/Example.pm $
+#
+#  IBM CONFIDENTIAL
+#
+#  COPYRIGHT International Business Machines Corp. 2011
+#
+#  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
+
+use strict;
+
+package Hostboot::Example;
+use Exporter;
+our @EXPORT_OK = ('main');
+
+sub main
+{
+    ::userDisplay "Welcome to the example module.\n";
+    ::userDisplay "Calling 'usage', which will exit...\n";
+    ::usage();
+    ::userDisplay "Should never get here.\n";
+
+    return 0;
+}
+
+sub help
+{
+    ::userDisplay "Tool: Example\n";
+    ::userDisplay "\tDoesn't really do anything special.\n";
+}
diff --git a/src/build/debug/Hostboot/Printk.pm b/src/build/debug/Hostboot/Printk.pm
new file mode 100755
index 000000000..6e76b484c
--- /dev/null
+++ b/src/build/debug/Hostboot/Printk.pm
@@ -0,0 +1,44 @@
+#!/usr/bin/perl
+#  IBM_PROLOG_BEGIN_TAG
+#  This is an automatically generated prolog.
+#
+#  $Source: src/build/debug/Hostboot/Printk.pm $
+#
+#  IBM CONFIDENTIAL
+#
+#  COPYRIGHT International Business Machines Corp. 2011
+#
+#  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
+
+use strict;
+
+package Hostboot::Printk;
+use Exporter;
+our @EXPORT_OK = ('main');
+
+sub main
+{
+    ::userDisplay "------------Kernel Printk Parser------------\n";
+    my ($symAddr, $symSize) = ::findSymbolAddress("kernel_printk_buffer");
+    if (not defined $symAddr) { ::userDisplay "Cannot find symbol.\n"; die; }   
+    ::userDisplay ::readData($symAddr,$symSize);
+    ::userDisplay "--------------------------------------------\n";
+}
+
+sub help
+{
+    ::userDisplay "Tool: Printk\n";
+    ::userDisplay "\tDisplays the printk buffer.\n";
+}
diff --git a/src/build/debug/Hostboot/Ps.pm b/src/build/debug/Hostboot/Ps.pm
new file mode 100755
index 000000000..7077079d1
--- /dev/null
+++ b/src/build/debug/Hostboot/Ps.pm
@@ -0,0 +1,174 @@
+#!/usr/bin/perl
+#  IBM_PROLOG_BEGIN_TAG
+#  This is an automatically generated prolog.
+#
+#  $Source: src/build/debug/Hostboot/Ps.pm $
+#
+#  IBM CONFIDENTIAL
+#
+#  COPYRIGHT International Business Machines Corp. 2011
+#
+#  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
+
+use strict;
+
+package Hostboot::Ps;
+use Exporter;
+our @EXPORT_OK = ('main');
+
+use constant PS_TASKMGR_SYMBOLNAME => 
+                "Singleton<TaskManager>::instance()::instance";
+use constant PS_TASKMGR_TRACKER_LIST_OFFSET => 8 * 4;
+use constant PS_TRACKER_LIST_HEAD_OFFSET => 0;
+use constant PS_TRACKER_LIST_TAIL_OFFSET => 8 + PS_TRACKER_LIST_HEAD_OFFSET;
+use constant PS_TRACKER_LIST_SIZE => 8 * 3;
+
+use constant PS_TRACKER_PREV_OFFSET => 0;
+use constant PS_TRACKER_NEXT_OFFSET => 8 + PS_TRACKER_PREV_OFFSET;
+use constant PS_TRACKER_PARENT_OFFSET => 8 + PS_TRACKER_NEXT_OFFSET;
+use constant PS_TRACKER_CHILDREN_LIST_OFFSET => 8 + PS_TRACKER_PARENT_OFFSET;
+use constant PS_TRACKER_TID_OFFSET => 
+                PS_TRACKER_CHILDREN_LIST_OFFSET + PS_TRACKER_LIST_SIZE;
+use constant PS_TRACKER_TASK_OFFSET => 8 + PS_TRACKER_TID_OFFSET;
+use constant PS_TRACKER_STATUS_OFFSET => 8 + PS_TRACKER_TASK_OFFSET;
+use constant PS_TRACKER_RETVAL_OFFSET => 8 + PS_TRACKER_STATUS_OFFSET;
+use constant PS_TRACKER_WAITINFO_OFFSET => 8 + PS_TRACKER_RETVAL_OFFSET;
+use constant PS_TRACKER_ENTRYPOINT_OFFSET => 8 + PS_TRACKER_WAITINFO_OFFSET;
+
+use constant PS_TASK_STATE_OFFSET => 8*42;
+use constant PS_TASK_STATEEXTRA_OFFSET => 8 + PS_TASK_STATE_OFFSET;
+
+sub main
+{
+    # Find symbol containing kernel list of task objects.
+    #   (Tasks who's parent is the kernel)
+    my ($symAddr, $symSize) = ::findSymbolAddress(PS_TASKMGR_SYMBOLNAME);
+    if (not defined $symAddr) 
+    { 
+        ::userDisplay "Couldn't find ".PS_TASKMGR_SYMBOLNAME; 
+        die;
+    }
+
+    # Pass address of list to 'displayList' function.
+    $symAddr += PS_TASKMGR_TRACKER_LIST_OFFSET;
+    displayList($symAddr,0);
+}
+
+# Display a list of task objects.
+sub displayList
+{
+    my ($listAddr, $level) = @_;
+
+    my $firstDisplayed = 0;
+
+    # Task lists are FIFO, so start from the 'tail'.
+    my $node = ::read64(PS_TRACKER_LIST_TAIL_OFFSET + $listAddr);
+    while (0 != $node)
+    {
+        if ($firstDisplayed)
+        {
+            ::userDisplay makeTabs($level)."\n";
+        }
+        else
+        {
+            $firstDisplayed = 1;
+        }
+
+        # Display tracker object for this node.
+        displayTracker($node, $level);
+        # Follow pointer to the next node.
+        $node = ::read64(PS_TRACKER_PREV_OFFSET + $node);
+    }
+}
+
+sub displayTracker
+{
+    my ($trackAddr, $level) = @_;
+    
+    # Read TID.
+    my $tid = ::read16(PS_TRACKER_TID_OFFSET + $trackAddr);
+
+    # Determine entry-point symbol name / module.
+    my $entryPoint = ::read64(PS_TRACKER_ENTRYPOINT_OFFSET + $trackAddr);
+    my $entryPointName = ::findSymbolByAddress($entryPoint);
+    if (not $entryPointName) { $entryPointName = sprintf "0x%x",$entryPoint; }
+    my $moduleName = ::findModuleByAddress($entryPoint);
+
+    # Find task object, read task state if task is still running.
+    my $taskAddr = ::read64(PS_TRACKER_TASK_OFFSET + $trackAddr);
+    my $state = "";
+    if ($taskAddr)
+    {
+        $state = pack("C",::read8(PS_TASK_STATE_OFFSET + $taskAddr));
+    }
+    else
+    {
+        $state = "Z";
+    }
+    my $stateExtra = "";  # Parse state extra debug info if it exists.
+    if (($state ne "R") and ($state ne "r") and
+        ($state ne "E") and ($state ne "Z"))
+    {
+        $stateExtra = sprintf "(0x%x)", 
+                              ::read64(PS_TASK_STATEEXTRA_OFFSET + $taskAddr);
+    }
+    elsif ($state eq "Z")
+    {
+        # If task has exited, read status and retval.
+        my $status = ::read32(PS_TRACKER_STATUS_OFFSET + $trackAddr);
+        my $retval = ::read64(PS_TRACKER_RETVAL_OFFSET + $trackAddr);
+        if ($status) { $stateExtra = "(Crashed)"; }
+        elsif ($retval) { $stateExtra = (sprintf "(0x%x)", $retval); }
+    }
+    # Map state to an verbose description.
+    my %states = ( "R" => "Running",
+                   "r" => "Ready",
+                   "E" => "Ended",
+                   "f" => "Block on Futex",
+                   "M" => "Block on Message",
+                   "u" => "Block on Userspace Request",
+                   "s" => "Block on Sleeping",
+                   "j" => "Block on Join",
+                   "Z" => "Zombie",
+                 );
+    $state = $states{$state};
+
+    # Display task info obtained.
+    ::userDisplay makeTabs($level)."-+ TID $tid   State: $state$stateExtra\n";
+    ::userDisplay makeTabs($level)." |     $entryPointName [$moduleName]\n";
+
+    # Display list of children tasks.
+    displayList($trackAddr + PS_TRACKER_CHILDREN_LIST_OFFSET, $level + 1);
+}
+
+sub makeTabs
+{
+    my $level = shift;
+
+    my $result = "";
+    while (0 != $level)
+    {
+        $result = $result." |";
+        $level = $level - 1;
+    }
+    
+    return $result;
+}
+
+sub help
+{
+    ::userDisplay "Tool: Ps\n";
+    ::userDisplay "\tDisplays a tree of all tasks and their current state.\n";
+}
diff --git a/src/build/debug/Hostboot/Trace.pm b/src/build/debug/Hostboot/Trace.pm
new file mode 100755
index 000000000..f57676f40
--- /dev/null
+++ b/src/build/debug/Hostboot/Trace.pm
@@ -0,0 +1,100 @@
+#!/usr/bin/perl
+#  IBM_PROLOG_BEGIN_TAG
+#  This is an automatically generated prolog.
+#
+#  $Source: src/build/debug/Hostboot/Trace.pm $
+#
+#  IBM CONFIDENTIAL
+#
+#  COPYRIGHT International Business Machines Corp. 2011
+#
+#  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
+
+use strict;
+
+package Hostboot::Trace;
+use Exporter;
+our @EXPORT_OK = ('main');
+
+use constant MAX_NUM_TRACE_BUFFERS => 24;
+use constant DESC_ARRAY_ENTRY_ADDR_SIZE => 8;
+use constant DESC_ARRAY_ENTRY_COMP_NAME_SIZE => 16;
+use constant TRAC_DEFAULT_BUFFER_SIZE => 0x0800;
+
+use File::Temp ('tempfile');
+
+sub main
+{
+    my ($packName,$args) = @_;
+
+    if (not defined $args->{"fsp-trace"})
+    {
+        $args->{"fsp-trace"} = "fsp-trace";
+    }
+
+    my $traceBuffers = $args->{"components"};
+
+    my ($symAddr, $symSize) = ::findSymbolAddress("TRACE::g_desc_array");
+    if (not defined $symAddr) { ::userDisplay "Cannot find symbol.\n"; die; }
+
+    my ($fh,$fname) = tempfile();
+    binmode($fh);
+
+    my $foundBuffer = 0;
+
+    for (my $i = 0; $i < MAX_NUM_TRACE_BUFFERS; $i++)
+    {
+        my $compName = ::readStr($symAddr);
+        last if ($compName eq "");
+
+        $symAddr += DESC_ARRAY_ENTRY_COMP_NAME_SIZE;
+
+        my $buffAddr = ::read64($symAddr);
+        $symAddr += DESC_ARRAY_ENTRY_ADDR_SIZE;
+
+        if ((not defined $traceBuffers) or ($traceBuffers =~ m/$compName/))
+        {
+            $foundBuffer = 1;            
+            print $fh (::readData($buffAddr, TRAC_DEFAULT_BUFFER_SIZE));
+        }
+    }
+    
+    if ($foundBuffer)
+    {
+        open TRACE, ($args->{"fsp-trace"}." -s ".
+                    ::getImgPath()."hbotStringFile -f $fname |");
+        while (my $line = <TRACE>)
+        {
+            ::userDisplay $line;
+        }
+    }
+    else
+    {
+        ::userDisplay("No matching buffers found.\n");
+    }
+
+    unlink($fname);
+}
+
+sub help
+{
+    ::userDisplay "Tool: Trace\n";
+    ::userDisplay "\tDisplays the trace buffer.\n";
+    ::userDisplay "\n    Options:\n";
+    ::userDisplay "\tfsp-trace=<path> - Path to non-default ".
+                      "fsp-trace utility.\n";
+    ::userDisplay "\tcomponents=<list> - Comma separated list of components\n".
+                  "\t                    to display trace buffers for.\n";
+}
diff --git a/src/build/debug/hb-dump-debug b/src/build/debug/hb-dump-debug
new file mode 100755
index 000000000..b6648b397
--- /dev/null
+++ b/src/build/debug/hb-dump-debug
@@ -0,0 +1,187 @@
+#!/usr/bin/perl
+#  IBM_PROLOG_BEGIN_TAG
+#  This is an automatically generated prolog.
+#
+#  $Source: src/build/debug/hb-dump-debug $
+#
+#  IBM CONFIDENTIAL
+#
+#  COPYRIGHT International Business Machines Corp. 2011
+#
+#  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
+
+use strict;
+
+use Getopt::Long;
+use Pod::Usage;
+use IO::Seekable;
+
+use Hostboot::DebugFramework;
+
+my $tool = "";
+my $dumpfile = "";
+my $testImage = 0;
+my $imgPath = "";
+my $toolOptions = "";
+my $cfgHelp = 0;
+my $cfgMan = 0;
+my $toolHelp = 0;
+
+GetOptions("tool:s" => \$tool,
+           "tool-options:s" => \$toolOptions,
+           "file:s" => \$dumpfile,
+           "test" => \$testImage,
+           "img-path:s" => \$imgPath,
+           "help" => \$cfgHelp,
+           "toolhelp" => \$toolHelp,
+           "man" => \$cfgMan) || pod2usage(-verbose => 0);
+pod2usage(-verbose => 1) if $cfgHelp;
+pod2usage(-verbose => 2) if $cfgMan;
+pod2usage(-verbose => 0) if (($tool eq "") || 
+                             (($dumpfile eq "") && (!$toolHelp)));
+
+if ($toolHelp)
+{
+    callToolModuleHelp($tool);
+}
+else
+{
+    # Open dump file.
+    open(DUMPFILE, "< $dumpfile") or die "Can't open dump file.\n";
+    binmode(DUMPFILE);
+
+    # Determine the full image path.
+    $imgPath = determineImagePath($imgPath);
+
+    # Parse tool options and call module.
+    parseToolOpts($toolOptions);
+    callToolModule($tool);
+}
+
+sub usage
+{
+    pod2usage(-verbose => 2);
+}
+
+# @sub readData
+#
+# Reads a data blob from the dump file.
+#
+# @param integer - Address to read at.
+# @param size - Size (in bytes) to read.
+# 
+# @return The blob of data requested.
+#
+sub readData
+{
+    my $addr = shift;
+    my $size = shift;
+
+    seek DUMPFILE, $addr, SEEK_SET;
+
+    my $result = "";
+    read DUMPFILE, $result, $size;
+
+    return $result;
+}
+
+# @sub userDisplay
+#
+# Display parameters to the user.
+#
+# @param varargs - Items to display to the user.
+#
+sub userDisplay
+{
+    foreach my $value (@_)
+    {
+        print $value;
+    }
+}
+
+# @sub getImgPath
+#
+# Return file-system path to .../img/ subdirectory containin debug files.
+#
+sub getImgPath
+{
+    return $imgPath;
+}
+
+# @sub getIsTest
+#
+# Return boolean to determine if tools should look at test debug files or
+# normal debug files.
+#
+sub getIsTest
+{
+    return $testImage;
+}
+
+
+
+__END__
+
+=head1 NAME
+
+hb-dump-debug
+
+=head1 SYNOPSIS
+
+hb-dump-debug [options] --tool=<module> --file=<dumpfile>
+
+=head1 OPTIONS
+
+=over 8
+
+=item B<--tool>=MODULE
+
+Identify the tool module to execute.
+
+=item B<--tool-options>="OPTIONS"
+
+List of arguments to pass to the tool as options.
+
+=item B<--toolhelp>
+
+Displays the help message for a specific debug tool.
+
+=item B<--file>=FILE
+
+File containing a memory dump of hostboot.
+
+=item B<--test>
+
+Use the hbicore_test.syms file instead of the default.
+
+=item B<--img-path>=PATH
+
+The path to the "img" directory where the syms file, etc is located.
+
+=item B<--help>
+
+Print a brief help message and exits.
+
+=item B<--man>
+
+Prints the manual page and exits.
+
+=back
+
+=head1 DESCRIPTION
+
+Executes a debug tool module against a memory dump file.
+
+=cut